Claude Skill

writing-plans

The spec-to-plan bridge. Routed to by /feature once the brainstormed spec is approved, and by /sprint before execution. Decomposes the spec into 2–5 minute tasks, each carrying its exact file path(s) and a concrete verification step that maps to a tdd obligation. Writes the plan

LLM Mart · 0 points · 15 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download arbiterForge-codeArbiter-plugins_ca-pi_routines_writing-plans-46c0eb3.zip · 6 KB

arbiterforge/codearbiter 145 7 forks AGPL-3.0 Updated 7d ago

Part of arbiterforge/codearbiter — 238 skills

Install

skills CLI npx skills add https://github.com/arbiterForge/codeArbiter/tree/main/plugins/ca-pi/routines/writing-plans

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install arbiterforge-codearbiter@llmmart

Git git clone https://github.com/arbiterForge/codeArbiter.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole arbiterforge/codearbiter collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

writing-plans

Typed-artifact pilot boundary

For an existing HTML spec/plan or an explicitly requested typed-HTML pilot, load <plugin-root>/includes/artifacts.md before artifact I/O. Its typed ID, binding, readiness, receipt, contextual-read and scope-state rules replace the legacy Markdown parsing and direct status-cell edits below for that pilot only. Keep all other workflow gates, including human checkpoints, unchanged. Missing or invalid HTML capability is a STOP for this path, not a fallback to Markdown. HTML --farm dispatch is blocked in this candidate. Default legacy workflows remain unchanged until native host qualification and cutover approval.

Turn an approved spec into an executable plan. Routed to by /feature (after spec approval) and /sprint.

Pre-flight

Read these, or STOP and surface the gap — never plan against an unapproved or missing spec:

<project-root>/.codearbiter/specs/<slug>.md — the approved brainstorming spec. The single source of acceptance criteria. Absent or unapproved → STOP and route back to /feature.
<project-root>/.codearbiter/CONTEXT.md — the stage: frontmatter (the maturity value) and project context.
<project-root>/.codearbiter/tech-stack.md — file layout, build/test/lint invocations. A verification step cites a real command from here, never a guess.
<project-root>/.codearbiter/coding-standards.md — structure and naming, so a task names the right path.

If --farm was requested: check that FARM_API_KEY is set in the environment of the Pi parent process. If absent, BLOCK immediately — cite <plugin-root>/includes/farm.md for setup instructions. Do not proceed; the farm dispatcher cannot run without an API key. Model selection happens later (at dispatch time in subagent-driven-development), so no model research is needed here.

Phase 1 — Criterion extraction · gate: BLOCK

Lift every acceptance criterion from the spec verbatim and assign each a stable ID (AC-01, AC-02, …). This list is the coverage ledger for the whole plan — Phase 4 checks the task set against it.

A criterion the spec leaves ambiguous is a [CONFIRM-NN] against <project-root>/.codearbiter/open-questions.md — surface it, do not invent the intent.

Backstop the ledger against the spec's own stated intent, mechanically, before trusting it — this runs even when brainstorming already ran the same check, because a hole that survived Phase 3 survives Phase 4's bijection too, silently (#566): run "$PY" "<plugin-root>/hooks/_intentlib.py" uncovered-intent <project-root>/.codearbiter/specs/<slug>.md [--issue-body <scratch-file>] — <scratch-file> holds the linked issue's body when one exists (gh issue view <N> --json body -q .body > <scratch-file>, written outside the working tree), omitted when none does. A non-empty result names an in-scope bullet or an acceptance checkbox the criteria never cited — BLOCK and route back to brainstorming (<plugin-root>/routines/brainstorming/SKILL.md) to add the missing criterion or record a [CONFIRM-NN]; never paper over a missing criterion by authoring a task for it here instead. This is the LAST point before a hole gets laundered through Phase 4's bijection, which only checks the ledger against itself and cannot see past it.

Then ask the half this tool cannot mechanize: if every AC-NN passed and nothing else changed, what would still be broken? A real answer names a criterion the ledger is missing even though every scope bullet and checkbox is technically cited — judgment, not mechanizable, and not satisfied by a rhetorical "nothing." Finding nothing broken is a reportable result, stated in one line, never a silent skip.

Gate: every acceptance criterion in the spec captured as a numbered AC-NN; the uncovered_intent backstop above returns empty or every finding is resolved; and the negative question has been asked and answered. A partial ledger does not pass.

Phase 2 — Task decomposition · gate: BLOCK

Break the work into the smallest honest units. Each task is ~2–5 minutes of work and carries:

id — T-01, T-02, … stable.
path(s) — the exact file(s) the task touches, resolved against coding-standards.md. "Some files" is not a path.
verification — one concrete command or observable that proves the task done (e.g., <test cmd> -k test_token_expiry passes, endpoint returns 401 on missing header). It cites a real tech-stack.md invocation or a directly observable behavior — never "looks right".
maps-to — the tdd obligation this verification corresponds to. The verification maps to a tdd obligation; it does NOT replace tdd's own gates. tdd Phase 1 still derives and Phase 4 still verifies obligations against passing tests.
covers — the AC-NN(s) this task advances.

Split anything that won't fit ~5 minutes or touches unrelated paths. Reject the trap of one monolithic "implement the feature" task — that defeats the plan.

Gate: every task has at least one path AND a verification AND a maps-to. A task missing any of the three blocks the plan.

Phase 3 — Order & MVP slice · gate: BLOCK

Order tasks so each runs only after what it depends on. Flag every dependency explicitly (T-07 depends on T-03). A cycle is a decomposition error — return to Phase 2 and split.

Group the ordered tasks so the MVP slice is identifiable: the minimal contiguous task set that satisfies the spec's core acceptance criteria and is shippable on its own. Everything past the slice is incremental.

Gate: a complete dependency order with no cycle, and an explicitly marked MVP slice.

Phase 4 — Bijection proof & write · gate: BLOCK

Cross the ledger against the task set, both directions. This proves the plan and the ledger AGREE with each other — it does not prove the ledger itself is COMPLETE relative to the spec's stated intent. A criterion missing from the ledger entirely was never a candidate for either check below; that completeness gap is caught earlier, by Phase 1's uncovered_intent backstop (and by brainstorming Phase 3 before that) — never re-derived here, and never implied by this phase's name (#566: a prior version of this gate read "coverage proof", which a bijective check does not earn).

Every AC-NN is covered by at least one task's covers. An uncovered criterion blocks — author the missing task.
Every task advances at least one AC-NN. A task that covers nothing is scope creep — cut it or surface it.

Then write the plan to <project-root>/.codearbiter/plans/<slug>.md — <slug> matching the spec — with the AC-NN ledger, the ordered task table (id · path(s) · verification · maps-to · covers · depends-on · status, initialized PENDING), the marked MVP slice, and any out-of-scope item tagged inline [NEEDS-TRIAGE].

The status column is the pipeline's resume ledger: subagent-driven-development flips a task to ACCEPTED the moment it accepts it, so an interrupted run (crash, compaction, closed session) is re-entered by /feature at the first non-ACCEPTED task instead of restarted from brainstorming.

Gate: bijection proven between the plan and the ledger — no criterion without a task, no task without a criterion — and the plan written to disk. This proves the two are mutually consistent, nothing more; completeness of the ledger itself was Phase 1's gate, not this one. This clears the path to execution: executing-plans (checkpointed, via /feature) or subagent-driven-development (autonomous, via /sprint) — each routes every task through tdd. The plan never hands off to tdd directly.

Phase 4-farm extension (only when `--farm` was requested)

When --farm was requested, after the bijective coverage gate passes and the .md plan is written, produce the farm artifact (plan.json) — one MVP slice at a time — per <plugin-root>/routines/writing-plans/references/farm-plan.md. Load that leaf and follow it; it owns the per-task failing-test + schema-valid plan.json procedure.

Gate: all failing tests written and confirmed failing; plan.json written and schema-valid. Both artifacts exist before handing off to subagent-driven-development (<plugin-root>/routines/subagent-driven-development/SKILL.md).

Hard rules

MUST NOT plan against an absent or unapproved spec — STOP and route back to /feature.
MUST NOT emit a task without an exact path AND a concrete verification step.
MUST NOT let a task's verification stand in for a tdd gate — it maps to a tdd obligation, it does not replace one.
MUST NOT write the plan while any acceptance criterion is uncovered or any task covers nothing.
MUST NOT guess a verification command — cite tech-stack.md or STOP.
MUST NOT resolve an ambiguous criterion by guessing — raise a [CONFIRM-NN].
MUST run the uncovered_intent backstop and ask the negative-judgment question in Phase 1, and MUST NOT treat Phase 4's bijection proof as a substitute — bijection proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
MUST NOT emit plan.json in --farm mode without writing and confirming each failing test first.
MUST NOT set meta.model or meta.apiBaseUrl in plan.json — these belong to the dispatch step.
MUST NOT proceed with --farm if FARM_API_KEY is absent — cite <plugin-root>/includes/farm.md and BLOCK.
MUST, at exit, run the follow-up harvest (<plugin-root>/includes/harvest.md) over any [NEEDS-TRIAGE] out-of-scope items — batch-confirm promoting them to open-tasks.md (work) or open-questions.md (decisions) so they don't die in the plan file.

Files (codearbiter)

references

farm-plan.md 4.9 KB

# writing-plans — `--farm` plan.json extension

Loaded by `writing-plans` Phase 4 only when `--farm` was requested. The base plan (Phases 1–4) is
unchanged; this leaf adds the machine artifact the farm dispatcher needs.

Apply the shared `<plugin-root>/includes/verification-boundary.md`: the slice's narrow RED test and
affected contracts run locally, while exhaustive repository/cross-platform proof remains an
exact-head hosted-CI requirement.

**Rollout gate:** HTML-backed farm use remains disabled until the repository's fresh model-era
qualification matrix, native payload packaging, and real authority adapters are complete. The
projection contract below is implemented so qualification can exercise the real boundary; it is not
permission to use HTML farm dispatch in ordinary work.

After the bijective coverage gate passes and the canonical plan is written, produce the farm artifact —
**one MVP slice at a time, not the whole plan up front.** Front-loading every failing test for the
entire plan would be the waterfall this skill otherwise rejects (Phase 3), and it maximizes the cost
of a mid-flight spec change. So the farm artifact is scoped to the **current slice** (the MVP slice on
the first pass; the next contiguous group on later passes). For each task in the current slice, in
dependency order:

1. Route through `tdd` Phase 1 (derive obligations) + Phase 2 (write the failing test). The test file
   must exist on disk and fail before continuing. Record the test file path for this task.
2. Confirm the test is actually failing (run the gate command from `tech-stack.md`; it must exit
   non-zero). A test that passes before implementation means the obligation is wrong — STOP and revisit
   Phase 2.

For a legacy Markdown plan, retain the existing schema-driven path below unchanged. For an HTML plan,
do **not** hand-write the projection. Construct the minimal candidate in memory and submit it through
the on-demand artifact protocol's `farm-project` operation. That operation atomically writes
`<project-root>/.codearbiter/plans/<slug>.plan.json` and an immutable content-addressed base binding
only after the approved source pair, current input snapshot, selected scope/slice, deterministic ID
mapping, projection bytes, and fresh RED result for every task all agree.

The HTML projection is the current slice's tasks only and is a strict subset of the unchanged farm
runtime schema:

- `meta.name` ← slug
- `meta.model` and `meta.apiBaseUrl` — **leave unset**. These are written by
  `subagent-driven-development`'s model research step at dispatch time. Writing them here would bake in
  a potentially stale selection.
- Per task: `id` ← T-NN (normalized to kebab-case), `description` ← task description,
  `filesInScope` ← path(s) from the task table, `test.path` ← the failing test written above,
  `gate.commands` ← the canonical task verification argv joined without shell reinterpretation;
  `deps` ← dependency ids inside the selected slice (empty array if none). Do not add `repo`,
  `context`, setup, retry, or task-model fields to an HTML projection. A canonical argv token that
  cannot be represented without shell quoting makes the slice unsupported and BLOCKS projection.
- **`gate.commands[0]` MUST be the task's narrow behavioral test** (the command that runs just
  `test.path`), with affected contract tests and lint/typecheck following. The farm's mutation guard re-runs
  `gate.commands[0]` per mutant; if the first command were an exhaustive suite, mutation testing would be
  prohibitively slow.

For the legacy path, validate the JSON against the schema before writing (load the schema from
`<plugin-root>/tools/plan.schema.json` and check). A schema-invalid plan BLOCKS.

`plan.schema.json` is the **authoring** contract. The dispatcher enforces its own **runtime** contract
(`PLAN_SHAPE` / `parsePlan()` in `farm.ts`) on the parsed JSON before it touches a single field, and
that one is authoritative: a plan that fails it exits before any worktree, branch, report, or network
call. The two are kept identical key-for-key and type-for-type by a parity test, so a plan that
satisfies the schema is accepted at runtime — with one deliberate exception, the kebab-case `id`
pattern, which is stricter here than the runtime path-safety rule. Both objects are closed: an
undeclared property is an error, not an ignored extra.

For the HTML path, the existing user/SMARTS workflow must capture a `farm_authorization` receipt whose
payload binds the current spec/plan/input hashes, scope, base projection hash, and each task's source
ID, farm ID, test path, verification-definition hash, command, failing exit, stdout hash and stderr
hash. A digest is correspondence, not approval authentication. Call `farm-project` with that receipt;
do not create a binding file directly.

Gate: all failing tests written and freshly observed failing; the legacy JSON is schema-valid or the
HTML projection and immutable binding were committed together. Both artifacts exist before handoff.

SKILL.md 10.1 KB

---
name: writing-plans
description: The spec-to-plan bridge. Routed to by /feature once the brainstormed spec is approved, and by /sprint before execution. Decomposes the spec into 2–5 minute tasks, each carrying its exact file path(s) and a concrete verification step that maps to a tdd obligation. Writes the plan to .codearbiter/plans/<slug>.md, ordered with dependencies flagged and an MVP slice identifiable. Nothing executes until every task has a path and a verification and the task set covers every acceptance criterion.
disable-model-invocation: true
---

# writing-plans

## Typed-artifact pilot boundary

For an existing HTML spec/plan or an explicitly requested typed-HTML pilot, load
`<plugin-root>/includes/artifacts.md` before artifact I/O. Its typed ID, binding,
readiness, receipt, contextual-read and scope-state rules replace the legacy
Markdown parsing and direct status-cell edits below for that pilot only. Keep
all other workflow gates, including human checkpoints, unchanged. Missing or
invalid HTML capability is a STOP for this path, not a fallback to Markdown.
HTML `--farm` dispatch is blocked in this candidate. Default legacy workflows
remain unchanged until native host qualification and cutover approval.


Turn an approved spec into an executable plan. Routed to by `/feature` (after spec approval) and `/sprint`.

## Pre-flight

Read these, or STOP and surface the gap — never plan against an unapproved or missing spec:

- `<project-root>/.codearbiter/specs/<slug>.md` — the approved brainstorming spec. The single source of acceptance criteria. Absent or unapproved → STOP and route back to `/feature`.
- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
- `<project-root>/.codearbiter/tech-stack.md` — file layout, build/test/lint invocations. A verification step cites a real command from here, never a guess.
- `<project-root>/.codearbiter/coding-standards.md` — structure and naming, so a task names the right path.

**If `--farm` was requested:** check that `FARM_API_KEY` is set in the environment of the Pi parent process. If absent, BLOCK immediately — cite `<plugin-root>/includes/farm.md` for setup instructions. Do not proceed; the farm dispatcher cannot run without an API key. Model selection happens later (at dispatch time in `subagent-driven-development`), so no model research is needed here.

## Phase 1 — Criterion extraction · gate: BLOCK

Lift every acceptance criterion from the spec verbatim and assign each a stable ID (`AC-01`,
`AC-02`, …). This list is the coverage ledger for the whole plan — Phase 4 checks the task set
against it.

A criterion the spec leaves ambiguous is a `[CONFIRM-NN]` against
`<project-root>/.codearbiter/open-questions.md` — surface it, do not invent the intent.

**Backstop the ledger against the spec's own stated intent, mechanically, before trusting it — this
runs even when `brainstorming` already ran the same check, because a hole that survived Phase 3
survives Phase 4's bijection too, silently** (#566): run `"$PY" "<plugin-root>/hooks/_intentlib.py"
uncovered-intent <project-root>/.codearbiter/specs/<slug>.md [--issue-body <scratch-file>]` —
`<scratch-file>` holds the linked issue's body when one exists (`gh issue view <N> --json body -q
.body > <scratch-file>`, written outside the working tree), omitted when none does. A non-empty
result names an in-scope bullet or an acceptance checkbox the criteria never cited — BLOCK and route
back to `brainstorming` (`<plugin-root>/routines/brainstorming/SKILL.md`) to add the missing criterion or record a `[CONFIRM-NN]`; never paper over a
missing criterion by authoring a task for it here instead. This is the LAST point before a hole gets
laundered through Phase 4's bijection, which only checks the ledger against itself and cannot see
past it.

Then ask the half this tool cannot mechanize: **if every `AC-NN` passed and nothing else changed,
what would still be broken?** A real answer names a criterion the ledger is missing even though
every scope bullet and checkbox is technically cited — judgment, not mechanizable, and not satisfied
by a rhetorical "nothing." Finding nothing broken is a reportable result, stated in one line, never a
silent skip.

Gate: every acceptance criterion in the spec captured as a numbered `AC-NN`; the `uncovered_intent`
backstop above returns empty or every finding is resolved; and the negative question has been asked
and answered. A partial ledger does not pass.

## Phase 2 — Task decomposition · gate: BLOCK

Break the work into the smallest honest units. Each **task** is ~2–5 minutes of work and carries:

- **id** — `T-01`, `T-02`, … stable.
- **path(s)** — the exact file(s) the task touches, resolved against `coding-standards.md`. "Some files" is not a path.
- **verification** — one concrete command or observable that proves the task done (e.g., `<test cmd> -k test_token_expiry passes`, `endpoint returns 401 on missing header`). It cites a real `tech-stack.md` invocation or a directly observable behavior — never "looks right".
- **maps-to** — the `tdd` obligation this verification corresponds to. The verification *maps to* a tdd obligation; it does NOT replace tdd's own gates. `tdd` Phase 1 still derives and Phase 4 still verifies obligations against passing tests.
- **covers** — the `AC-NN`(s) this task advances.

Split anything that won't fit ~5 minutes or touches unrelated paths. Reject the trap of one
monolithic "implement the feature" task — that defeats the plan.

Gate: every task has at least one path AND a verification AND a `maps-to`. A task missing any of the
three blocks the plan.

## Phase 3 — Order & MVP slice · gate: BLOCK

Order tasks so each runs only after what it depends on. Flag every dependency explicitly
(`T-07 depends on T-03`). A cycle is a decomposition error — return to Phase 2 and split.

Group the ordered tasks so the **MVP slice** is identifiable: the minimal contiguous task set that
satisfies the spec's core acceptance criteria and is shippable on its own. Everything past the slice
is incremental.

Gate: a complete dependency order with no cycle, and an explicitly marked MVP slice.

## Phase 4 — Bijection proof & write · gate: BLOCK

Cross the ledger against the task set, both directions. **This proves the plan and the ledger AGREE
with each other — it does not prove the ledger itself is COMPLETE relative to the spec's stated
intent.** A criterion missing from the ledger entirely was never a candidate for either check below;
that completeness gap is caught earlier, by Phase 1's `uncovered_intent` backstop (and by
`brainstorming` Phase 3 before that) — never re-derived here, and never implied by this phase's name
(#566: a prior version of this gate read "coverage proof", which a bijective check does not earn).

- Every `AC-NN` is covered by at least one task's `covers`. An uncovered criterion blocks — author the missing task.
- Every task advances at least one `AC-NN`. A task that covers nothing is scope creep — cut it or surface it.

Then write the plan to `<project-root>/.codearbiter/plans/<slug>.md` — `<slug>` matching the
spec — with the `AC-NN` ledger, the ordered task table (id · path(s) · verification · maps-to ·
covers · depends-on · **status**, initialized `PENDING`), the marked MVP slice, and any out-of-scope
item tagged inline `[NEEDS-TRIAGE]`.

The status column is the pipeline's resume ledger: `subagent-driven-development` flips a task to
`ACCEPTED` the moment it accepts it, so an interrupted run (crash, compaction, closed session) is
re-entered by `/feature` at the first non-`ACCEPTED` task instead of restarted from brainstorming.

Gate: bijection proven between the plan and the ledger — no criterion without a task, no task without
a criterion — and the plan written to disk. This proves the two are mutually consistent, nothing more;
completeness of the ledger itself was Phase 1's gate, not this one. This clears the path to execution:
`executing-plans` (checkpointed, via `/feature`) or `subagent-driven-development` (autonomous, via
`/sprint`) — each routes every task through `tdd`. The plan never hands off to `tdd` directly.

### Phase 4-farm extension (only when `--farm` was requested)

When `--farm` was requested, after the bijective coverage gate passes and the `.md` plan is written,
produce the farm artifact (`plan.json`) — **one MVP slice at a time** — per
`<plugin-root>/routines/writing-plans/references/farm-plan.md`. Load that leaf and follow it;
it owns the per-task failing-test + schema-valid `plan.json` procedure.

Gate: all failing tests written and confirmed failing; `plan.json` written and schema-valid. Both
artifacts exist before handing off to `subagent-driven-development` (`<plugin-root>/routines/subagent-driven-development/SKILL.md`).

## Hard rules

- MUST NOT plan against an absent or unapproved spec — STOP and route back to `/feature`.
- MUST NOT emit a task without an exact path AND a concrete verification step.
- MUST NOT let a task's verification stand in for a `tdd` gate — it maps to a tdd obligation, it does not replace one.
- MUST NOT write the plan while any acceptance criterion is uncovered or any task covers nothing.
- MUST NOT guess a verification command — cite `tech-stack.md` or STOP.
- MUST NOT resolve an ambiguous criterion by guessing — raise a `[CONFIRM-NN]`.
- MUST run the `uncovered_intent` backstop and ask the negative-judgment question in Phase 1, and MUST NOT treat Phase 4's bijection proof as a substitute — bijection proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
- MUST NOT emit `plan.json` in `--farm` mode without writing and confirming each failing test first.
- MUST NOT set `meta.model` or `meta.apiBaseUrl` in `plan.json` — these belong to the dispatch step.
- MUST NOT proceed with `--farm` if `FARM_API_KEY` is absent — cite `<plugin-root>/includes/farm.md` and BLOCK.
- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any `[NEEDS-TRIAGE]` out-of-scope items — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so they don't die in the plan file.