Which skill hands off to which: raw idea to landed commit. The nightly mining pipeline has its own page, Smining.
Hand-offs are the typed pipeline edges in each skill's <leaf>.cue; make skills-check checks both sides agree. These tables are the reader's view. Authoring: Skills, skill model.
Plan-producing skills share context/rules/plan.md: section catalog and plan interface (template via plan-template:), stacked table cells, in-plan Q&A (OPEN decision rows, never popups), changelog, mode-invariant code and visual evidence.
This order is doctrine: violating it has invalidated approved plans.
backlog (optional) → idea (optional) → concept → fexplore → fdesign (+ master and derived routes) → (overlap, optional) → fimplement → its commit skill (commit-skill@1, package-commit by example)
| Step | Skill | Does | Artifact out |
|---|---|---|---|
| −1 | backlog (optional) | Organizes and prioritizes a raw multi-idea brain-dump into the durable epic backlog; re-invocation merges. | <dest>/backlog.json |
| 0 | idea (optional) | Pre-concept stress-test or possibility mapping of a half-formed idea; a dead idea ends the chain. | plan dir idea/idea.md on close (the plan-dir naming rule) |
| 1 | concept | Drafts the concept with user stories, drains its open questions in the same run, deciding itself; asks only redirecting or nuanced ones ([AGENT] / [USER] / [BUSINESS] tags, source-requirements diff). Filters already: reject or partial reject. | plan dir concept/concept.md, Open questions drained into Decisions |
| 3 | fexplore (optional: solution space open or contested) | Surveys all sensible solutions, constraint-first; exactly one enters fdesign, the rest stay documented, discarded. | plan dir design/exploration.md |
| 4 | fdesign | Implementation plan for any request, new feature or change: anchored facts, decisions, diffs, tests, refuted claims, drivers checked against the request. Design-gate widget: TLDR, editable scope and decisions. Grounding corrects docs and context. Familiarity modes unfamiliar | familiar | owned. | plan dir in the feature folder, design/<slug>.md: the one binding plan |
| 4b | fdesign <plan file> | Edits a not-yet-implemented plan: Changelog row, gates passed again. An implemented plan gets a sibling in its feature folder. | design/<slug>.md edited in place, or a new plan dir |
| 4e | fdesign master (optional: one code gate would be unreviewable) | Master plan: decisions, contracts between parts, end-to-end checks, no code gate. A coarse split table names the derived plans, each full-plan size. | design/<slug>.md with role: master, plus the recipe for the derived runs |
| 4f | fdesign derived | A master split row as its own plan, both gates; restates nothing, corrects the master first. In a fleet, code-gate approval hands it to the orchestrator's worker; /fleet playbook: design runs rows as unattended cells. | own plan dir in the master's feature folder, design/<master slug>-<part>.md |
| 5 | fimplement | Executes the approved plan as a binding contract. | working, committed code |
| 6 | package-commit | Commits per package (or per file), dot-notation messages. | per-package commits |
| From | To | Kind | Note |
|---|---|---|---|
| raw requirements (user stories, ideas) | concept | next | plan dir concept/concept.md: questions → decisions |
concept | raw requirements | reject | reject or partial reject; clarified requirements flow back |
concept | fexplore | next | exploration.md |
fexplore | options A, B, C | next | B and C discarded |
| option A | fdesign | next | the implementation plan |
fdesign | fdesign on the plan file | revise | ideas back: version bump + changelog, edited in place |
fdesign on the plan file | itself | revise | another round: version bump + changelog |
fdesign on the plan file | fexplore | reject | |
fdesign on the plan file | concept | reject | |
refactor rounds: fdesign round 1 · layer A, round 2 · layer B, a human refactor | fdesign on the plan file | revise | each round bumps version + changelog |
fdesign round N · final product | fimplement | next | |
fdesign on the plan file | fimplement | approve | |
fimplement | fdesign, a new plan in the feature folder | optional | testing or usage surfaces feature changes |
| that new plan | fimplement | optional | |
fimplement | railroad-review | next | n lanes per direction, station protocol |
railroad-review | fix handoff to a separate agent or session | gate | station review + human gate |
| fix handoff | railroad-review | back | merge-back, clean-slate round + rejection ledger |
railroad-review | package-commit | next | two consecutive clean rounds |
railroad-review | dod-report | optional | handoff to the human reviewer: 4 questions + [DoD] walk |
fdesign covers post-implementation tweaks through full restructurings, migrations and consolidations. The plan classifies impact (behavior-preserving | behavioral | contract-touching | no-change); the user never pre-classifies.fdesign (new plan in the feature folder) → fimplement → its commit skill.overlap (optional, read-only, between steps 4 and 5) lists recent same-repo sessions (via peek-mcp) whose diffs or plans touch the plan's files: collisions show before implementation.No fixed chain position; you invoke them on demand.
| Behaviour | Rule |
|---|---|
| Smartskills | discuss, qq, research: the hook injects the default slice of context-map.json unless a topic:<name> token widens it (smartskill rule, context/rules/skills.md). lane: stays railroad-review's direction token. |
--help | Every repo skill answers /<skill> --help (also -help, -h, --h, en and em dashes) with frontmatter, routing, args, title states, Tests lines and topics, running nothing, via the skillhelp hook (cmd/skillhelp, deployed to ~/.claude/hooks/bin/ with session-helpers). Without it --help reaches the skill and deploy renders no help-test.md. |
| Hook-answered skills | answeredBy: "hook" (smine-help): answered that way on every invocation, with its payload text. |
| Message | Effect |
|---|---|
| #allow Makefile / #deny Makefile | Unlocks or re-locks every make source. |
| #allow settings.local.json | Admits toolpolicy allow rules. |
| #add <absolute dir> | Adds a root. |
| #set <rule> | Adds a rule. |
| #disable <word…> / #enable <word…> | Switches hook effects off or on (rgate, skill, inject, session, hb groups). |
| #reset | Clears them all. |
A plan's design run freezes its rules: Permissions § Approvals, Plan rules.
| Skill | Purpose |
|---|---|
| diagnose-debug | Verified root-cause diagnosis before any fix. |
| spec-drift | Read-only drift report: a doc set vs the code (doc mode), or every consumer of one changed contract classified, with a fix order (contract mode). |
| railroad-review | Multi-agent station-protocol review of any scope (committed range or uncommitted snapshot). |
| dod-report | Reviewer-handoff DoD (Definition of Done) report: why, validated, tested, plus a [DoD]-entry walk. After railroad-review or standalone. |
| code-verdict | Problem-or-fine verdict on scoped existing code; alternatives only for a confirmed problem; feature-level escalates to fexplore. |
| support-decision | Read-only adjudication of an external position against the actual code or spec. |
| fimpact | Per-axis change evaluation (maintainability, security, business impact, …). |
| coverage-increase | Coverage gaps → gated brief → tests; hands off to package-commit. |
| dev-stack | Local e2e dev stacks (docker-compose + Makefile + seeded data). |
| merge-resolve | Resolves all conflicts of diverged branches once, at final-tree level; any conflicted integration (failed cherry-pick chains, mid-rebase) normalizes into it. |
| restack | Replays a branch's unlanded commits onto its target's tip on a work branch, adopted after a green audit, never a merge commit; stops before a retarget would copy the old base's commits. Landing's conflict operation (Heartbeat § Merge strategy). |
| overlap | Read-only file-overlap check against recent sessions' diffs and plans (peek-mcp); optional between fdesign and fimplement. |
| plan-archive | Copies a landing feature's plan dirs into the plans-archive repo (~/GolandProjects/agent-plans) renamed wip → done, commits, removes; /done branch: calls it before its fast-forward. |
| skillroutine-create | Skill authoring and routine scaffolding, one arg-routed skill|routine. |
| skillroutine-eval | Runs one declared configuration from a skill's eval/definition.json as headless replicas; reports time, tokens, cost, step misses, check and scorer or golden scores (Skill tests § Eval layer). |
| skillroutine-ab | Measures one change (model, effort, MCP server, overlay patch or skill version) as baseline vs variant smoke- or eval-layer run records, with spread and a blind compare judge. |
| skillroutine-estimate | Predicts a skill or routine configuration's cost and usage before running: cells, dollars, tokens, wall-clock, window fit. Measured-telemetry pricing, analytic fallback. |
| context-create | One ACDSL context entry from a stated rule, with or without gate (anchor + verifier + fixtures), authored in-session; rules generate + make audit close it. |
| context-bootstrap | EXPERIMENTAL whole-repo context miner: dimensions × chunks Workflow fan-out (optional git-history dimension), verified candidate-entry report; context-create applies accepted candidates. |
| investigate | N independent investigations of one question, primary-source re-verification, merged baseline + refuted-hypotheses register. |
| research | Primary-source answer with citations and confidence, from one agent or subagents: n[model-effort] readers; contested sources escalate to investigate. Smartskill. |
| discuss | Dialogue-only discussion with pushback, no artifact; hands off to idea or concept. Smartskill. |
| One quick question, ≤5-sentence answer, one lookup. Smartskill. | |
| fleet | Runs one heartbeat fleet: judges collisions, fast-forwards delivered members onto its merge branch (a member behind restacks first), syncs the human-named target once through /done, journals every act. Headless worker cells: one implementer (feature playbook) or one designer per master-plan split row (design playbook). |
| join | Joins a heartbeat fleet; heartbeat assigns the member token (T1-MA), the session-title hook writes it into the title. |
| done | Reports the work finished: a joined fleet member is marked delivered for its orchestrator; any other session lands its branch on its landing target (the branch it started from) inside that target's landing turn (restack, fast-forward). A main-based session lands nothing. branch: lands a feature branch on the staging target. Title: DONE. |
| close | End-of-session cleanup: leaves its heartbeat fleet, removes the pool worktree and claude/* branch (safety-gated), sets the title CLOSED, archives the Desktop session. Outside a pool worktree, archive only. |
| runtime | Watches exactly one other session's failed enforce checks and judgment points, with evidence, through heartbeat. report lists them; act answers each once with the skill's recovery or judgment template, or a stop: to a subagent as hook context on its next tool call, to the root as its Stop block reason or on its next prompt. |
| heartbeat-demo | Versioned showcase and smoke test of the gate rules and runtime enforcement (needs the gate and heartbeat components): one short run per scenario, named for its expected answer and violation (pass-clean-run, deny-laundered-workflow, deny-workflow-in-plan-mode, block-stop-before-close, kill-repeated-launder, …). |
| smine-help | Explains the typed session messages with examples; answered by the prompt hook. |
| peek | Shows another session: conversation, plan, diff. |
| watch | Cron-watches one pinned session: heartbeat liveness alerts (waiting, blocked), one delta line per tick incl. subagent tokens, new plan revisions only; stops itself once the session is idle or ended. |
| jq / xlsx | Cheap JSON extraction and spreadsheet work, mainly for agents (the agent-only skill package, rarely human-invoked). |
| caveman | Terse output style (agent-only package), the register skill prose is written in; no skill takes it as an arg. Minimal .md taken from caveman. |
Skills and workflows pipe into each other through three harness-native primitives.
| Primitive | How |
|---|---|
| Skill fronts workflow | SKILL.md resolves intake; the session then calls the Workflow tool on a script in the skill's directory (investigate, smine, skillroutine-eval). |
| Workflow nests workflow | workflow({scriptPath}, args) runs another workflow inline, sharing budget and concurrency; one nesting level only. The pipe primitive. |
| Workflow runs skill | An agent() stage whose prompt invokes the Skill tool and follows it unattended. |
workflows/ dir: it nests A's workflow via workflow(), adapts A's structured return to B's input contract in pure JS, runs B via an agent stage.args: workflow scripts have no filesystem or env access.The nesting primitive is unoccupied: its first instance, skillroutine-parallel-eval, retired with the matrix eval framework. /skillroutine-eval and /skillroutine-ab run headless roots via go run ./cmd/skilleval.