Workflows

Six ways of working, from the first install to a multi-spec initiative. You do not pick one: rules, skill triggers and hooks route the task, and every path ends in a check. Direct work is the default; a spec is earned by size — more than 5 steps or more than 6 files over 2+ subsystems — a larger handoff, an open decision or your request. See Feature.

Autopilot treats typed and transcribed requests alike, explains direct work, Delegate or Wave, and names the chosen harness/provider/model and the next action. See smart routing.

Onboarding

Once per machine and project: devkit install → devkit sync → devkit init → /index.

Step	Result
devkit install	Wires the session hook and runs the first sync.
devkit sync	Downloads and verifies the release, links skills, agents, rules and hooks, installs required tools.
devkit init	Sets up the project checkout: agent-state caches in .gitignore, code graph, seeded .agents/context/; an older setup is brought up to date.
/index	Applies what devkit init has pending after one question — apply and commit, apply only, or not now — then keeps .agents/context/ to what the code cannot tell and fixes stale facts, broken paths and oversized decision entries in it. Run it after every devkit update; commit the result for the team.

devkit status and devkit doctor confirm the setup. New project: /vision sets the north star in .agents/context/VISION.md; /spec, /brainstorm and /challenge check against it.

Daily work

For work below the spec thresholds, with no open requirement or explicit plan request: describe → edit → /test → /review → /commit. The agent runs /test after a coherent change and /review --quick for changes across source files or risky paths. You start /commit; risk alone does not require a spec.

Skill	What happens
/test	Runs the targeted tests; the full suite only on request, at high risk, or when shared test infrastructure changed.
/review	Independent read-only review of the current diff; names /spec and stops when the diff needs a contract.
/commit	Stages only this session's files; a gitleaks finding or a staged agent-state path aborts.
/release	Completes the CHANGELOG, bumps the version, pushes the tag and creates the GitHub release.

Feature

For more than 5 steps or more than 6 files over 2+ subsystems, a larger handoff another session will pick up, an open decision you must make first, or when you want a written plan: /spec → /spec-work → /commit → PR. Small work for a later session becomes a todo for /todo, not a spec. Specs and Todos explains both.

Step	You	The agent
/spec	Describe the outcome and correct the summary. Starting /spec-work approves it. The summary gives the path and ends with /clear, then /spec-work <ID> for a fresh session.	Writes goal, steps, files and checks. Risky or cross-system work gets a fuller plan and model review.
/spec-work	Answer decision questions.	A fresh agent implements and checks the steps; the main session then sends the result to an independent reviewer.
Out of scope	Read the widened plan before continuing.	/spec-update reopens affected steps and dependencies. After completed, follow-up fixes are inline work.
Interrupted	Say /spec-work <ID> again.	Continues from the first open step.

Initiative

For work too big for one spec — at least three specs, an external provider, or a change across system boundaries — plan one slice, finish it, then plan the next: /brainstorm → /spec → /spec-work → next slice.

Skill	Use it when
/brainstorm	The direction is open. Ends with the next small slice or a living plan worked one completed row at a time.
/challenge	You want the case against the idea first.
/wave	Several slices are approved and touch different files: runs them in parallel worktrees, each with its own review.
/workspace	The work spans sibling repositories under one folder: one spec per repository, in order.
/delegate	A bounded review, investigation or implementation benefits from another model. Implementations return automatically; a leftover path stays in that worktree and devkit worktree-gc --apply removes merged ones.
/prime-agent	A long unattended audit or whole spec should run alone in a throwaway worktree — this is what /delegate prime routes to. Rerun the checks here afterwards.

Knowledge and context

Continuously, so no session re-learns the project.

Need	Action
Gotcha, convention or decision	/capture writes it to .agents/context/; critical gotchas also get a prompt trigger.
Related repo (backend, boilerplate, contract partner)	/capture as Related → .agents/context/RELATED.md; a prompt hint reminds you.
Open work	The agent offers a todo, from ~30 tool calls it parks one itself; /todo lists, picks or works the next ready todo.
Question about the past	Memory recall, then memsearch if installed.
Suspected drift	devkit context-drift-check reports broken references.

Maintenance

Nothing to do: each session start activates an update that was verified in the background. devkit sync updates now, devkit doctor diagnoses, devkit rollback goes back — details under how it works and troubleshooting.