Plan Feature

Plan Feature (router)

One door to turn anything — an idea, an issue, or a scoped slug — into a planned, roadmap-registered feature. Routes to a focused internal step so only the work you need runs (no fat single skill). Docs only — no code, no branch.

Turn contract — verify before ending the turn

✓ SPEC + artifacts written and the roadmap entry registered (number, order, deps verified)
✓ The dependency & blocker check was RUN and its result decides which closing block is printed
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed, then the machine envelope (fenced ```json — see ## Machine envelope) as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

Step 0 — Discover the project (always first)

Per the agent guide's Workflow conventions + documentation map, then read what THIS skill needs: the roadmap (docs/features/ROADMAP.md), so routing and roadmap registration match the project's real layout.

Routing

Pick the mode — first match wins:

1. Flag forces it (skip detection): --interview, --from-issue ,

--scaffold , --next.

1. Issue — an issue number or issue URL → plan-feature-from-issue.
2. Scoped — an existing roadmap slug or a filled SPEC.md → plan-feature-scaffold.
3. Raw idea — a vague description → plan-feature-interview.
4. --next / no input — read the roadmap, take the next planned entry; if

it's a thin line → plan-feature-interview, if scoped → plan-feature-scaffold.

1. Ambiguous — ask one question, then route.

Example (routing)

| You run | Detected | Routes to | Then | |---|---|---|---| | plan-feature "add CSV export" | raw idea | plan-feature-interview → plan-feature-scaffold | execute-phase NN P1 | | plan-feature 131 | issue #131 | plan-feature-from-issue → plan-feature-scaffold | PR carries Closes #131 | | plan-feature 14-csv-export | scoped slug | plan-feature-scaffold | execute-phase 14 P1 | | plan-feature --next | next planned roadmap entry | scaffold (interview if thin) | execute-phase NN P1 |

Process

1. Route per above. The interview / from-issue internals produce a **filled,

sized SPEC**; then invoke plan-feature-scaffold, which scales the artifacts to the SPEC's size (XS/S → SPEC-only; M/L → full set) and registers the roadmap. The scoped path runs plan-feature-scaffold directly.

1. Confirm roadmap. Verify the feature is registered in

docs/features/ROADMAP.md with the right number, ordering, and dependencies; if any of the three is missing or wrong, fix the entry now — never leave registration for later.

1. Dependency & blocker check (always, before recommending execution).

• Walk the feature's Depends on: closure (transitively): every dependency

must be done and merged. Any unmet → the closing block recommends building the deepest unmet dependency first, NOT this feature.

• Check the fix index + open issues (forge CLI) for fix-now items touching

the same modules this SPEC names. Any hit → the closing block recommends /plan-fix before execution ("building on a known defect bakes it in").

• Planning itself never blocks on either — the SPEC/artifacts are still

written; only the recommended next step changes.

1. Print the next step per the check above (see Done when).

Guardrails

• Docs only — no code, no branch (that is execute-phase).
• Don't re-ask what a flag, the issue, or the docs already settle.
• Surface conflicts (numbering clashes, dependency cycles, scope overlap) before

writing, not after.

• Otherwise per the project's Workflow conventions (docs-language).

Internal steps (not user-invocable)

• plan-feature-interview — interview a raw idea into a SPEC.
• plan-feature-from-issue — issue → scoped SPEC, Closes #N.
• plan-feature-scaffold — SPEC → full artifact set + roadmap entry.

These run within this same conversation (that's what "composing" means) — on any agent, just follow their SKILL.md inline as the routed step.

Machine envelope

Every invocation ends with the machine envelope — schema, field rules and placement per the installed orchestration-envelope skill: one fenced

``json block, printed **after** the closing block above, as the **absolute last output** of the turn (external orchestrators parse the LAST fenced json block; see docs/workflow/ORCHESTRATION.md`). All top-level keys always present; values only from verified command output, never invented.

This skill emits:

• state: OK (planned — artifacts written, roadmap registered),

BLOCKED (the dependency check found unmet deps: dependencies.unmet + build_order filled, blockers[] kind dependency), or NEEDS_INPUT (interview path question — needs_input filled, nothing guessed).

• Fields: unit = the planned feature (type: "feature", id, branch from

the SPEC); phase.total = planned phase count (null for XS/S single-pass); next.recommended = /execute-phase P1 (or single-pass) with tier: "cheap" — or the deepest unmet dependency's command when BLOCKED, tier: "strong".

• detail: {"size": "XS|S|M|L", "artifacts": [paths]}.

Portability (agents other than Claude Code)

The workflow is the contract; Claude Code features are conveniences. On an agent that lacks one, apply the fallback — never skip the step the feature enables:

• No slash-command menu — where this skill says /, open that

skill's SKILL.md (wherever your agent installed the skills) and follow it literally, in a fresh conversation: hand-offs assume a clean context. The internal steps above are the exception — they run inline, in this one.

• No per-skill model:/effort: — on the #claude branch the frontmatter pins these tiers; here, pick tiers yourself:

planning is judgment work — run it on your strongest model. The execution it hands off to may run cheaper.

Relationship to other skills

• triage-issue routes here to promote an issue to a feature.
• execute-phase executes the phases afterward (audit-docs audits anytime).

Done when

• A planned feature with its full artifact set exists and is roadmap-registered.
• The dependency & blocker check ran, and **the closing → Next: block matches

its result** — clean:

`` → Next: /execute-phase P1 — start phase 1 (M/L, phased) · XS/S feature → /execute-phase (single-pass) · adjust scope first → re-run /plan-feature · audit the planning docs → /audit-docs ``

unmet dependency and/or blocking fix-now issue:

`` → Next: /plan-feature (or /execute-phase …) — build the dependency chain first: · blocking fix-now issue # in the same area → /plan-fix before executing · proceed anyway → /execute-phase P1 --force (the gate logs the override) ``

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gtrabanco
• Source: gtrabanco/agentic-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.