csk-start
Skill1 starsChanged 4 months agoMITView on GitHub
Standalone CSK repository-start and resume routine. Use on every repository open, after context loss, when the user asks what is open or says resume/continue/weiter, when first-use adoption must be classified, or whenever unfinished work must survive into a later session. Manages tracked project onboarding state in .csk/project-state.json and durable local work in tasks/INDEX.md entirely inside the current repository.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- 1-csk-initSkill
- 2-csk-write-specSkill
- 3-csk-architectureSkill
- 4-csk-frontendSkill
- 5-csk-backendSkill
- 6-csk-qaSkill
- 7-csk-deploySkill
- audit-plan-loopSkill
- claude-skill-proxy-syncSkill
- create-worker-worktreeSkill
- csk-adopt-plan-scaffoldSkill
- csk-helpSkill
- csk-refineSkill
- finish-branchSkill
- pull-main-ffSkill
- review-loopSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
45 rules. About 0 are common, 30 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈30
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Run a local, read-first start routine.
- Distinctive: line 35
Do not copy feature status or full specifications into the task index.
- Very specific: line 43
Never push this state to an upstream remote.
- Very specific: line 47
Use scripts/csk_start.py for mechanical validation and mutation.
- Distinctive: line 53
Prefer the bundled launcher so detection and missing-runtime behavior stay consistent:
- Very specific: line 79
Run the helper from the repository root and use --repo <path> when needed.
- Distinctive: line 95
Before choosing an action:
- Distinctive: line 100
Read every applicable skill before using it.
- Distinctive: line 102
Use semantic LLM judgment to choose relevant skills.
- Distinctive: line 105
Use repository copies of CSK skills.
- Very specific: line 116
Use one distinct label per session (for example claude, codex, claude-2): the guard identifies sessions by label, so two sessions sharing …
- Very specific: line 120
If the guard reports SECOND SESSION DETECTED, another session holds this working copy.
- Very specific: line 131
Run state check before reading or creating tasks.
- Very specific: line 135
When state is pending/not-assessed (initial template or explicit recheck), run state inventory, review its candidate files semantically, …
- Very specific: line 145
After consent, run state decide --mode adopt|greenfield.
- Very specific: line 149
Read distribution.origin_role.
- Very specific: line 154
After the state write, offer a selective handoff: commit the approved .csk/project-state.json change (and no unrelated paths), then push …
- Very specific: line 168
Only explicit --recheck-adoption or an equivalent user request may run state recheck and reopen classification.
- Distinctive: line 174
Read, in this order:
- Distinctive: line 180
Only feature specs and source-of-truth files referenced by open task rows.
- Distinctive: line 182
Do not contact a network service or inspect another repository.
- Very specific: line 186
Run tasks check. It verifies the exact table schema, the unique next-ID marker, IDs, allowed states and priorities, required cells, dates, …
- Distinctive: line 193
Use LLM context judgment to:
- Distinctive: line 211
Before the board, give the user one plain-language sentence in the user's language, for example: "Bevor wir arbeiten, prüfe ich den …
- Distinctive: line 216
Use this compact shape:
- Distinctive: line 236
After the board, ask one concise question: continue the recommendation, choose a numbered item, maintain the index, or stop.
- Distinctive: line 239
If no task is open:
- Distinctive: line 255
Use the helper for every mutation.
- Distinctive: line 262
Search semantically for an existing task before invoking the helper.
- Distinctive: line 263
Update the existing row instead of adding a duplicate.
- Distinctive: line 268
Create a task only when the work is still open or blocked, is expected to span a session, is explicitly deferred, or is a verified …
- Very specific: line 274
Keep the row, set status to blocked, and record both the concrete blocker and the next action that could remove it.
- Distinctive: line 279
Verify the outcome against the owning file, acceptance criteria, test, artifact, commit, or explicit user decision.
- Very specific: line 283
Commit, file, and artifact evidence must resolve locally.
- Distinctive: line 290
Check that no dependent open task was orphaned.
- Distinctive: line 292
If evidence is missing, keep the task open or blocked and report the gap.
- Distinctive: line 296
When repository writes are authorized, before ending non-trivial work:
- Distinctive: line 299
Ensure every durable follow-up has exactly one task row.
- Distinctive: line 300
Remove completed rows only with evidence.
- Distinctive: line 301
Leave the index unchanged when no durable follow-up exists.
- Distinctive: line 309
Default start mode is read-only.
- Distinctive: line 310
Do not execute multiple tasks automatically.
- Distinctive: line 311
Do not modify feature status during task maintenance.
- Distinctive: line 312
Do not hide a dirty working tree or unrelated changes.
- Distinctive: line 313
Do not create cross-repository workflow state, external task stores, transport directories, or task archives.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CSK Start
Run a local, read-first start routine. Repository files, not chat memory, decide
what can safely continue. .csk/project-state.json is the source of truth for
project-wide onboarding; tasks/INDEX.md is the source of truth for immediate
durable work.
Supported operations
/csk-start— validate onboarding, inspect the repository, and show the board./csk-start --quick— show the board without deeper feature reconciliation./csk-start --recheck-adoption— explicitly repeat the repository inventory./csk-start --add "<task>"— add or update durable open work./csk-start --block TASK-NNN --reason "<reason>"— record a blocker./csk-start --close TASK-NNN --evidence "<evidence>" [--evidence-record <path>]— close verified work.
Interpret equivalent natural language without requiring exact flag syntax. Do
not start implementation merely because the board was shown. If the user says
weiter, continue, go, or equivalent after the board, continue with the
recommended item and its applicable skill.
State boundaries
.csk/project-state.jsonowns the repository role and adoption decision.tasks/INDEX.mdowns only immediateopenandblockeddurable work.- A feature spec owns feature scope, status, decisions, and acceptance evidence.
features/INDEX.mdis a feature overview, not an open-task queue.Expected branchin a task row is advisory intent. Live Git state is authoritative and must be checked before work or branch completion.- Do not copy feature status or full specifications into the task index.
- Completed work has no open-task row. Preserve evidence in its owning source of truth, a commit, a test result, or another local artifact. Git is the audit trail; create no task archive.
The first-use decision is project-wide, not checkout-local. It becomes
project-wide only when the commit containing .csk/project-state.json is
reachable from origin/<default-branch>. Until then, report its actual scope.
Never push this state to an upstream remote.
Deterministic helper
Use scripts/csk_start.py for mechanical validation and mutation. Python 3.10+
is an explicit CSK tooling runtime, independent of the product stack. Detect it
in this order: python3, python, then Windows py -3. If no compatible
interpreter exists, keep the routine read-only, explain the missing tooling, and
do not hand-edit onboarding or task state.
Prefer the bundled launcher so detection and missing-runtime behavior stay consistent:
PowerShell: powershell -File scripts/csk-start.ps1 <area> <operation> ...
POSIX: sh scripts/csk-start.sh <area> <operation> ...Important commands:
state check
state check-template-distribution [--snapshot HEAD|index]
state inventory
state decide --mode greenfield|adopt
state recheck
state adoption-complete --coverage-report .csk/adoption-coverage.json
state adoption-block --reason <reason>
tasks check
tasks list
tasks add ...
tasks update TASK-NNN ...
tasks block TASK-NNN --reason ...
tasks close TASK-NNN --evidence <typed-evidence>Run the helper from the repository root and use --repo <path> when needed.
The helper owns syntax, invariants, locking, compare-and-swap checks, and atomic
writes. The LLM still owns semantic decisions: whether code or planning evidence
should be adopted, whether tasks are duplicates, which skill applies, and what
the safest next action is.
state check-template-distribution is a maintainer release gate, not a normal
project-start command. It reads HEAD by default and fails unless that Git
snapshot contains the exact initial template/pending/not-assessed state. Use
the explicit --snapshot index only as a pre-commit check of already staged
content. The working-tree file alone can never pass this distribution gate.
Start routine
1. Discover capabilities
Before choosing an action:
- Inspect the skills and tools exposed by the current runtime.
- Inventory repository skills under
.claude/skills/*/SKILL.mdand Codex proxies under.codex/skills/*/SKILL.md. - Read every applicable skill before using it. Explicitly requested skills are mandatory.
- Use semantic LLM judgment to choose relevant skills; do not route by keyword or regex alone.
Use repository copies of CSK skills. Never install or copy them into a user-global Claude or Codex directory. Already available global runtime skills may supplement the workflow but are not an installation target.
Then claim the working copy with the session guard (timestamp lockfile with stale detection; the lock is advisory and gitignored):
python .claude/skills/csk-start/scripts/csk_session_guard.py claim --label <agent>Use one distinct label per session (for example claude, codex,
claude-2): the guard identifies sessions by label, so two sessions sharing
one label would not detect each other.
If the guard reports SECOND SESSION DETECTED, another session holds this
working copy. Warn the user in one plain sentence (two sessions in one folder
share files, index, and HEAD - a known way to corrupt work), recommend
/create-worker-worktree so this session gets its own worktree, and continue
here only after the user confirms no other session is active (then claim with
--takeover). See docs/git-basics.md, "The three levels of parallel work".
A missing Python runtime skips the guard silently; it never blocks the start
routine on its own.
2. Enforce the first-use gate
Run state check before reading or creating tasks.
- Missing, malformed, contradictory, or unsupported state fails closed. Report the exact defect; never infer greenfield state from absence or damage.
- When state is
pending/not-assessed(initial template or explicit recheck), runstate inventory, review its candidate files semantically, then ask exactly one bounded question. Show the evidence and recommended mode, explain both routes, and offer these exact outcomes:adopt and store,greenfield and store, ordo not store yet. Adoption routes tocsk-adopt-plan-scaffold; greenfield routes to normal initialization. This single answer makes both the classification and its permission to write.csk/project-state.jsonunambiguous. - The answer authorizes only that state write and the stated routing. It never authorizes a commit, push, merge, dependency installation, or implementation.
- After consent, run
state decide --mode adopt|greenfield; do not hand-edit the state. The first decision changesrepository_rolefromtemplatetoproject, so the prompt does not recur in later clones after the state commit reaches the default branch. - Read
distribution.origin_role.source-templateis never a project publish target.missing,unconfirmed, orunconfirmed-templaterequires the user to identify or create their own project remote before any push. Recommend renaming a cloned starter-kitorigintoupstreamand adding the project asorigin, but perform remote changes only with explicit authority. - After the state write, offer a selective handoff: commit the approved
.csk/project-state.jsonchange (and no unrelated paths), then push that commit only to the confirmed projectorigindefault branch. Commit and push each require separate explicit authority. If the state lives on a feature branch, route its later integration through/finish-branch. - For
project/adopt/pending, resumecsk-adopt-plan-scaffoldwithout asking the first-use question again. - For
project/adopt/blocked, surface the recorded blocker and propose its next unblock action. - For
project/adopt/complete, verify the recorded scaffold evidence. If it has drifted or disappeared, usestate adoption-block, create/update one durable repair task, and do not repeat the initial interview. - For
project/greenfield/not-applicable, continue normally.
Only explicit --recheck-adoption or an equivalent user request may run
state recheck and reopen classification. Always report whether the current
state is uncommitted, branch/local, or project-wide according to state check.
3. Read local work state
Read, in this order:
tasks/INDEX.mdthrough EOF.git status --short --branch, the current branch, worktree context, and repository operation state when this is a Git repository.features/INDEX.mdunless--quickwas requested.- Only feature specs and source-of-truth files referenced by open task rows.
Do not contact a network service or inspect another repository.
4. Validate mechanically
Run tasks check. It verifies the exact table schema, the unique next-ID marker,
IDs, allowed states and priorities, required cells, dates, advisory branch
format, resume-skill format, and referenced paths. On failure, report the exact
defect and propose the smallest repair. Never silently discard or renumber tasks.
5. Reconcile semantically
Use LLM context judgment to:
- group related tasks by feature or subject;
- identify semantic duplicates despite different wording;
- detect drift between a task and its owning feature/specification;
- determine which available skill best handles each next action;
- validate
Expected branchagainst live Git state; - recommend one next item based on priority, blockers, context, dependencies, value, and switching cost.
A dirty working tree is unowned current work until understood. Surface changed paths before recommending a different workflow. Do not infer that changes are safe, complete, or related to an indexed task. File state beats remembered or conversational state. Report feature/spec conflicts as drift; do not rewrite either side during the read-only start routine.
6. Present the board
Before the board, give the user one plain-language sentence in the user's language, for example: "Bevor wir arbeiten, prüfe ich den gespeicherten Projektstand und die offenen Aufgaben, damit wir genau dort weitermachen, wo die letzte Session aufgehört hat."
Use this compact shape:
CSK START
Repository: <path>
Kit: v<content of the root VERSION file, or "unknown (pre-1.2.0)" when absent>
Onboarding: <mode/status> | Scope: uncommitted/local/project-wide
Origin: <URL or missing> | Role: project/source-template/unconfirmed
Branch: <branch or n/a> | Working tree: clean/dirty
Open: <n> | Blocked: <n>
[1] TASK-NNN [priority/status] <task>
Related: <feature/path/none>
Expected branch: <branch/none>
Next: <next action>
Resume skill: </skill or direct>
Recommendation: <one item and why>After the board, ask one concise question: continue the recommendation, choose a numbered item, maintain the index, or stop.
If no task is open:
- With a dirty working tree, recommend inspecting and attributing those changes first. Offer one durable task only if the work will survive this turn.
- With a clean working tree, derive the normal next action from
.claude/rules/workflow-state.mdthrough/csk-help; do not invent work.
Task mutations
Mutate the index only when the user explicitly requests task maintenance or the
current repository-change task already authorizes continuity for unfinished work
inside that same scope. A newly discovered, deferred, or out-of-scope follow-up
does not inherit that authority: show all proposed rows together as
PENDING-AUTH and ask once whether they should be stored. The read-only start
routine never grants mutation authority.
Use the helper for every mutation. It acquires the repository-local lock, reads and validates current state, checks the input digest, writes atomically, rereads, and verifies. Never bypass a lock, digest mismatch, validation error, or symlink escape with a hand edit.
Add or update
- Search semantically for an existing task before invoking the helper.
- Update the existing row instead of adding a duplicate.
- Otherwise allocate the helper-managed next ID and add one concise row.
- Record
Related, advisoryExpected branch, runtime-neutralResume skill, and an executable next action.
Create a task only when the work is still open or blocked, is expected to span a session, is explicitly deferred, or is a verified interruption/resume point. Do not create and close rows for ordinary work expected to finish in the same turn.
Block
Keep the row, set status to blocked, and record both the concrete blocker and
the next action that could remove it. Never mark uncertainty as completion.
Close
- Verify the outcome against the owning file, acceptance criteria, test, artifact, commit, or explicit user decision.
- Supply typed evidence such as
commit:<sha>,file:<path>,test:<name>,url:<endpoint>, orartifact:<path>to the helper. - Commit, file, and artifact evidence must resolve locally. Test and URL
evidence also require
--evidence-record <relative-path>pointing to a local proof file that contains the test name or URL. Store new proof files under.csk/evidence/<TASK-ID>-<short-name>.mdunless an owning source of truth already holds the evidence. - Preserve evidence in the owning local source of truth when one exists.
- Let the helper remove the row; create no archive.
- Check that no dependent open task was orphaned.
If evidence is missing, keep the task open or blocked and report the gap.
End-of-work continuity
When repository writes are authorized, before ending non-trivial work:
- Identify unfinished, deferred, blocked, or interrupted work.
- Ensure every durable follow-up has exactly one task row.
- Remove completed rows only with evidence.
- Leave the index unchanged when no durable follow-up exists.
For discovered or out-of-scope work, present exact proposed rows as
PENDING-AUTH, state that they are not durably conserved, and request one
consolidated authorization. Never claim chat-only work is durable.
Safety
- Default start mode is read-only.
- Do not execute multiple tasks automatically.
- Do not modify feature status during task maintenance.
- Do not hide a dirty working tree or unrelated changes.
- Do not create cross-repository workflow state, external task stores, transport directories, or task archives.
- On repeated tool failure, report the blocker and stop instead of retrying in a loop.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

