writing-plans skill

Routed skill

Turn the selected specification into a maintained implementation plan with clear outcomes, useful tasks, dependencies, and verification steps. Drafting uses the existing authorization and does not require artifact approval codes, reviewer receipts, or a frozen implementation script.

How it is used

The orchestrator routes to this skill from an owning command. It is not a direct user entry point.

What it does

Turns a selected specification into a maintained plan under the existing authorization. Tasks name useful outcomes, relevant paths, criterion IDs, actual dependencies and concrete verification. The feature or sprint caller owns execution; this skill authors and maintains the plan without implementing code.

Draft and readiness

For typed work, reuse the specification’s stable criterion IDs and preserve the selected identity. A draft may be incomplete. Readiness diagnostics identify missing structure and coverage; they do not create another permission request for independent authorized work. A conflicting write or structural failure prevents claiming the plan was saved.

Check coverage in both directions, then ask whether the plan still misses part of the user’s intent. Choose useful task sizes and meaningful batches. Separate observable fact prerequisites from consequential decisions that need their actual owner. Record shared source inputs only where tasks genuinely depend on them; do not claim an exhaustive dependency graph.

Existing Markdown pairs retain their representation and one task ledger.

What to review

Check each task’s outcome, paths, dependencies, criteria and proving check. Use real repository commands with a working directory and expected observation, or an explicitly described observable check. An unavailable named-test parser limits the result claim; it does not justify invented evidence or a command executed merely to author a plan.

Exits

Save through the selected writer, read back the result and return the plan location, useful next work, open decisions and pending checks. In-scope method changes can update the plan with a reason. A changed outcome goes to its decision owner; explicit human pauses remain effective.

A plan or DONE label is not verification or release evidence. Resume at unfinished work without restarting settled interviews. Review specifications and plans and Resume and recover explain inspection and continuation.

Gates

Gate	When	Effect
criterion coverage	assessing plan readiness	every required criterion has planned work and every task serves the agreed outcome; missing requirements and structural failures remain visible

Source

Source — plugins/ca/skills/writing-plans/SKILL.md (v3.7.0)

---
name: writing-plans
description: Turn the selected specification into a maintained implementation plan with clear outcomes, useful tasks, dependencies, and verification steps. Drafting uses the existing authorization and does not require artifact approval codes, reviewer receipts, or a frozen implementation script.
disable-model-invocation: true
---

# writing-plans

Produce the plan for the active feature or sprint, then return it to that caller.
Do not execute implementation from this skill. Use the user's existing direction;
ask only about a consequential unresolved outcome, not permission to maintain the
plan. An explicitly requested human checkpoint still belongs to the caller.

## Select the source and representation

Load `${CLAUDE_PLUGIN_ROOT}/includes/artifacts.md` for artifact I/O. Read the selected
specification's criterion records and retain its artifact ID and normative digest.
For HTML, `_preflight_plan_authoring` checks that identity, structural validity,
and the same-slug target. Create the matching plan as `draft_preview`; use
`plan-bind` when selecting or refreshing its specification binding. Preserve human
edits and stable references in the selected representation.

Read relevant project context and the build/test commands in
`${CLAUDE_PROJECT_DIR}/.codearbiter/tech-stack.md`; use
`${CLAUDE_PROJECT_DIR}/.codearbiter/coding-standards.md` for applicable conventions. In an
HTML-knowledge repository `knowledge.py relevant <paths>` returns both
(`${CLAUDE_PLUGIN_ROOT}/includes/knowledge.md`).
Missing optional orientation is not a new permission gate. Identify a genuinely
missing requirement or command contract instead of guessing it.

## Build useful tasks

Start with the specification's intended outcome and criterion IDs. Check coverage
in both directions: each required criterion has planned work, and each task serves
the agreed outcome. Agreement between a plan and its criterion list does not
prove that either captures every part of the user's intent. Inspect relevant
source and ask what would still be wrong if all listed criteria passed. Record
actual gaps; do not repeat an interview the caller has already resolved.

Each task should describe a coherent unit of work: stable ID, intended result,
relevant paths, referenced criteria, an implementation approach, dependencies,
and the appropriate check or observable completion condition. Choose task size
for useful implementation and review, not a compulsory two-to-five-minute limit.
A small related change does not need its own author/reviewer lifecycle. Split
work when it has separate outcomes, dependencies, or independently useful progress.

**Design-drift guard.** Decomposition splits decided work; it never designs. If splitting surfaces a
material solution choice the spec does not decide — two or more materially plausible approaches the
spec leaves open, or a step that would contradict the spec's recorded SMARTS rationale — STOP and
never pick, score or SMARTS-evaluate it here. Route the undecided choice back to the owning design
workflow, `brainstorming` (`${CLAUDE_PLUGIN_ROOT}/skills/brainstorming/SKILL.md`), and resume planning only
once the spec records the decision. A choice the spec already decides, or a trivial local
implementation detail with no material solution choice, is not drift.

Use real repository commands or an explicitly described observable check. A test
file or case that this task will create may not exist yet. An unsupported named
result parser is not a reason to reject the plan or invent test outcomes; a
command-level result must not be claimed as proof of individual named tests.
Read relevant command definitions without executing anything merely to author a
plan. Runner support and actual execution are checked when that check is needed.

Separate prerequisites that can be observed from choices only the user can make.
For typed prerequisites, use `kind: fact` or `kind: decision` and explicit
`task_refs` for affected tasks. Do not guess that an old unscoped prerequisite
applies to every task, or narrow a real shared dependency to hide it. Observable
facts use ordinary authorized tools and the engine's reported-observation path.
A consequential unresolved choice gets a clear normal-language question, not an
approval digest or a certification code.

For source impact without a repository-wide dependency analysis, record
`shared_inputs` only where the task genuinely depends on a common source
interface, fixture, schema or unusual build configuration. These must be
portable repository-relative paths to actual source, not generated artifact
state; a directory path includes its bounded descendants. A known shared
input change should refresh the affected check, not every unrelated review.
Do not invent references or claim an exhaustive dependency graph; missing
or unbounded inputs remain honestly `unassessed` in task context.

Order tasks by their actual dependencies. Remove cycles by fixing the plan, not
by pretending a required predecessor is complete. Group meaningful batches with
clear outcomes; checkpoints organize implementation and do not independently
create user approval requests. Keep genuinely blocked work visible while allowing
independent work to proceed. Identify the smallest useful delivery outcome without
splitting a promised atomic migration or compatibility change across releases.

## Save, inspect, and maintain

For HTML, use typed `create` and `apply` operations with current identity and CAS.
Preserve the specification's criterion IDs, task references, reasons, and history.
Drafts may be incomplete. Use `validate` with `gate: ready` to discover omissions;
its diagnostics describe the plan, not whether an already-authorized agent may
continue useful work. Structural errors or a conflicting write remain actual
operation failures. Do not fill missing fields with fabricated evidence to make
validation green.

Maintain the plan under existing authorization without extra artifact approvals
or freezing each method or check as another decision. Update in-scope steps,
tasks, checks and valid dependencies with a reason; material outcome changes
go to their actual decision owner.

Read back the saved identity and affected symbols. Return the plan location,
useful next work, actual unresolved choices, and outstanding checks to the active
caller. Distinguish implemented progress from verified behavior; a plan or a
`DONE` label is not test, review, or release evidence. Keep unrelated progress
when correcting the plan, and do not restart brainstorming after an interruption.

Existing Markdown retains one ledger and its original representation.
Never infer a passing check from an old status or duplicate approval prompts.

## Explicit farm requests only

For a user-selected Markdown `--farm` workflow, use
`${CLAUDE_PLUGIN_ROOT}/includes/farm.md` and
`${CLAUDE_PLUGIN_ROOT}/skills/writing-plans/references/farm-plan.md`. Preserve the
requested provider/budget and actual credential boundaries. Do not read
credential contents or trigger model spending during ordinary authoring.
HTML farm is disabled; never silently change backends.

Retain real out-of-scope follow-ups using `${CLAUDE_PLUGIN_ROOT}/includes/harvest.md`
when relevant. Do not turn routine drafting into an additional audit program,
mandatory reviewer chain, or repeated approval interview.

View in repo