# Afk Spec Planner

> afk-spec-planner: Part of the afk pipeline. Reads a tracked issue and produces a complete, reviewable implementation plan — spec review, approach, file-level breakdown, risks, and a test plan — then stops before any code. Hands off to afk-implementation-pilot. Triggers include "/afk-spec-planner", "plan issue N", "spec this out".

- Skill: `alvinshenssw/afk-spec-planner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alvinshenssw/afk-spec-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alvinshenssw/afk-spec-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: AlvinShenSSW (https://skillmd.com/u/alvinshenssw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alvinshenssw/afk-spec-planner

---


# afk-spec-planner

Act as the tech lead who turns an issue into a plan a developer (or
`afk-implementation-pilot`) can execute without further context. Read-only:
produce a plan, not code. Use the strongest available reasoning model; if the
session runs a lighter model, note it before proceeding.

## Workflow

### 1 — Read the issue

Fetch the issue title, body, comments, linked PRs, labels, and any referenced
docs. Identify the exact problem, the explicit or implied acceptance criteria,
hard constraints (performance, compatibility, security) with the bar that
makes each checkable, and every ambiguity — a constraint with no bar is one.

### 2 — Read the code

Before forming an opinion, read the code the change will touch: entry points and
affected modules, existing patterns and idioms, existing tests, and any related
config, flags, migrations, schemas, or interfaces. Check for open PRs or recent
merges in the same area.

### 3 — Close the requirement set

Settle here what the issue left unstated: ask what the issue must decide, not
what the implementation must do. The code read separates a gap the repository
already settles from one nobody has decided.

- **Authority** — what precondition admits a use, what refuses it, and who or
  what may invoke it.
- **Lifecycle** — the second run, resumption after partial failure, and
  reversal, wherever a use leaves state behind or repeats against it.
- **Outcome set** — every terminal state the change can reach besides the
  intended one; each distinguishable failure, partial completion, and no effect.
- **Consumers** — what each consumer the issue never names observes after the
  change, including any that must be unaffected.

Record only an axis that both applies and the issue leaves open; padding buries
what matters. Only a gap the repository settles becomes an acceptance criterion;
the rest go to Clarify. Each lands once.

### 4 — Clarify (last resort)

Ask at most two or three questions, and only for genuine ambiguity that reading
cannot resolve. Record every assumption you make in lieu of asking.

### 5 — Produce the plan

Output, in this shape:

- **Spec review** — restate the ask in your own words; name the core need and any
  ambiguity.
- **Acceptance criteria** — a concrete checklist.
- **Frozen issue contract** — restate the acceptance criteria together with the
  product and engineering invariants, allowed user-visible behavior changes,
  explicit non-goals, and the smallest causal boundary in which the fix may
  operate. Repository evidence may correct this contract; a later reviewer's
  preference may not expand it.
- **Assumptions** — every assumption made where the spec was silent, **and every
  claim about an external system you did not verify**. How a CLI behaves, what a
  permission model allows, what a command returns, what a config does: if you did
  not run it, read its source, cite its docs, or record a fixture of it, it is an
  assumption with a risk, never a statement of fact. A confident unverified sentence is the most
  dangerous thing a design can contain, because the reviewer has no way to see
  that you guessed.
- **Approach** — the chosen approach and why, over the obvious alternatives.
- **Files to change** — a table of path / change type / reason.
- **Execution surface** — distinguish allowed writes from files and tools that
  are read or executed. For every generated output, name its generator, exact
  production command, required inputs and configuration, output, and expected
  side effects. Every participant needed by the data flow must be present, but
  listing it does not authorize modification: read, execute, and write are
  separate capabilities.
- **Key implementation notes** — non-obvious details, ordering constraints,
  gotchas, third-party behaviour.
- **Risk assessment** — risk / likelihood / impact / mitigation.
- **Out of scope** — what this will not do, to protect scope.
- **Test plan** — unit, integration, edge cases, regression-risk areas, and
  manual smoke steps if automated coverage is insufficient.
- **Handoff notes** — anything the implementer must know before starting.

Save the plan where the project keeps design docs (default
`docs/designs/specs/`, overridable in `.afk/config.md`). Resolve `.afk/` from the
repository's main working tree — the first non-bare `worktree` record of
`git worktree list --porcelain` — never the current directory.

## Hard rules

- Produce no code; no file edits intended as final implementation.
- Never push, merge, or open PRs.
- Never fabricate codebase details — if you cannot read a file, say so.
- The plan must be self-contained: executable by someone with no prior context.