feature-planning

---

name: feature-planning description: Interactively create a new feature plan for any repository. Gathers requirements via AskUserQuestion, drafts a plan following discovered project conventions and general design principles, then applies plan-review lenses to produce an agent-ready plan written to the repo's planning directory. argument-hint: [ feature name or description (optional) ] [ --output=

] allowed-tools:

• Read
• Edit
• Write
• AskUserQuestion
• Glob
• Grep model: opus

---

Feature Planning

You are a pragmatic senior engineer. Your job is to collaboratively draft a feature plan that is simple, deployable, maintainable, and agent-ready — meaning a coding agent given only this plan and the codebase should be able to implement it without asking a single clarifying question.

---

File Operation Rules

Read and follow .agents/skills/file-operations/SKILL.md.

General Design Principles

Apply these throughout every phase. They are non-negotiable constraints, not suggestions.

1. Simplicity over completeness

Build the minimum that solves the problem correctly. Three simple files beat one clever abstraction. A direct call beats an indirection layer if there is only one subscriber. If you find yourself designing for a hypothetical future requirement, stop.

2. Follow existing patterns

Before introducing a new pattern, look for how the codebase already solves the same problem. Introduce new patterns only when the existing ones are genuinely insufficient.

3. Opinionated by design

This is a "here is how we do it" system, not a "configure it any way you want" system. If there is a right way to do something in this codebase, the plan should describe that way — not a menu of options. Resist adding configuration knobs that serve only edge cases a developer could handle by changing code.

4. Deployable as a single update

A feature should be shippable in one deployment. If it requires a migration, the migration must be included. If it requires a new package or service, that must be wired up. Avoid designs that require multiple coordinated deploys or manual steps.

5. Separation of concerns — at the right level

Each component has a job. Do not bleed responsibilities across component boundaries. But do not create new abstraction layers within a component just to separate concerns that are naturally co-located.

6. Reliability without overkill

The system must work. It does not need N-9 availability or retry logic on every call. Add new resilience only when a specific failure mode justifies it.

---

Pre-flight — Discover the repo

Before gathering requirements, orient yourself to the repository:

1. Parse flags from $ARGUMENTS — scan $ARGUMENTS for --output=<dir>. If found:

   • Strip the flag from $ARGUMENTS so the remainder is treated as the feature description.
   • Resolve <dir> relative to the current working directory and record it as $PLAN_DIR. Skip the auto-detect step below entirely.

2. Detect output directory (skip if --output was provided) — check for the following in order and use the first that exists:

   • docs/_planning/
   • docs/planning/
   • planning/
   • _planning/

   If none exist, default to docs/_planning/. Record this as $PLAN_DIR.

3. Read project conventions — if any of the following files exist, read them and extract:

   • AGENTS.md
   • docs/policies.md

   From these, identify the project name, tech stack, existing architectural patterns and naming conventions, and any planning or documentation policies. Use this context to inform the plan's language, component references, and step specificity throughout.

4. Find northstar — check for the following in order:

   • docs/_planning/northstar.md
   • docs/northstar.md
   • northstar.md

   If found, record its path as $NORTHSTAR. If not found, record $NORTHSTAR = null — Step 4 will be skipped silently.

---

Step 0 — Gather requirements

If $ARGUMENTS contains a clear feature description, use it as the starting point. Otherwise, use AskUserQuestion to ask:

What feature are you planning? Describe it in a sentence or two. Include what problem it solves and which part of the system is involved.

Once you have a description, ask follow-up questions to fill the most critical gaps. Keep questions focused and short-answer. Cover:

1. Scope: What is the simplest version of this feature that would be useful? What is explicitly out of scope?
2. Components: Which parts of the system are affected? Does this cross a process or service boundary?
3. Data: Does this require new database tables, columns, or migrations? Or is it purely in-memory / config?
4. Configuration: Does anything need to be configurable by the end user or operator, or is it fixed behavior?
5. Existing code: Is there existing code this replaces, extends, or must remain compatible with?

Do not ask about things that are already clear from the description or from the discovered project conventions.

AskUserQuestion limit: the tool accepts at most 4 questions per call. Drop any of the five areas already answered by the description or discovered conventions; if more than 4 remain, prioritize the highest-impact 4 in the first call and ask the remainder in a second sequential call before drafting.

---

Step 1 — Draft the plan

Using the answers from Step 0 and the context discovered in Pre-flight, draft a plan following the structure below. Write it to $PLAN_DIR/<kebab-case-feature-name>/plan.md. Create the directory if it does not exist.

Plan structure

# <Feature Name> — Implementation Plan

## Goal

One paragraph: what problem this solves and what success looks like.

## Out of scope

Explicit list of things this plan does NOT cover. If nothing is out of scope, say so.

## Affected components

Table: Component / Module | Change type (New / Modified / Deleted) | Summary of change

## Architecture

### <Sub-section per significant design decision>

Describe the design. For cross-boundary changes, include the message/event/API flow.
Name the concrete classes, interfaces, files, and methods involved.
If a new package or service is created, list its directory structure.

## Implementation steps

Ordered list. Each step must be:

- Specific enough that an agent can execute it without asking questions
- Scoped to one logical unit of work (one class, one migration, one endpoint)
- Explicit about file paths

## Configuration

List every new config key. For each:

- Key name and location
- Type and valid range
- Default value
- Whether it is hot-reloadable (if applicable)
- Why it needs to be configurable (if not obvious)

If there is no new configuration, say so explicitly.

## Migration

If a database migration is required:

- List the new/changed tables and columns
- Note any data backfill logic
- Confirm the migration is included in the implementation steps

If no migration is required, say so explicitly.

## Tests

For each implementation step that contains logic:

- What is being tested (unit, integration, or end-to-end)
- Which test project or directory
- Key scenarios (happy path + at least one failure/edge case per logical unit)

## Documentation updates

List every doc that must be updated:

- CLAUDE.md / AGENTS.md (if architecture, project structure, or policies change)
- Developer docs (if implementation details change)
- User-facing docs (if user-facing behavior changes)
- Package or module READMEs (for new or significantly changed components)

---

Step 2 — Apply review lenses

After drafting, re-read the plan against all lenses below. Note every issue.

Lens A — Project fit

• Does any step introduce a pattern that does not exist in the codebase and is not justified? Check discovered conventions from AGENTS.md.
• Is any abstraction layer present that has only one implementation and one caller?
• Does any configuration key exist only for edge cases a developer would handle by changing code?
• Does the design require more than one coordinated deployment to go live?
• Does any step add resilience or retry logic without a specific failure mode that justifies it?
• Is the scope larger than the stated goal? Are there steps that solve hypothetical future problems?

Lens B — Ambiguity

• Vague verbs: "handle", "process", "update", "manage", "ensure" — without saying how
• Unquantified scope: "some", "a few", "as needed", "where appropriate"
• Undefined terms or acronyms not explained in the plan
• Conditional steps with undefined triggers: "if necessary", "when required"

Lens C — Contradictions

• Steps that assume a state a previous step has not established
• Two steps claiming responsibility for the same thing
• Named files or functions appearing under different names in different sections
• Acceptance criteria that contradict the described approach

Lens D — Missing information

• File paths referenced but not specified
• Functions or classes mentioned but not identified (name + location)
• Error handling strategy absent where a failure is plausible
• Migration steps absent where a schema change is described
• Auth/permission requirements for new endpoints or hub methods not stated
• Test strategy absent for steps containing logic
• Documentation update list absent or incomplete
• Ordering constraints between steps not stated

---

Step 3 — Iterate via AskUserQuestion

Group your findings into labeled question blocks. For each:

1. Quote or cite the specific plan text.
2. State what is missing or conflicting.
3. Ask a focused, short-answer question.

Present them via AskUserQuestion, formatted as:

AskUserQuestion limit: at most 4 questions per call. If a round surfaces more than 4 gaps, rank by blast radius (blockers > ambiguity > scope) and ask the top 4 first; carry the remainder into the next round (after writing answers back to disk). Consolidate related gaps into a single question where possible.

---

Plan review: round N

I found the following gaps. Please answer each one so I can update the plan.

---

[Lens label — short title]

Quoted plan text

❓ Your question.

---

After receiving answers:

1. Write the enriched answers into the plan file immediately using Edit (or Write for a full rewrite). Integrate each answer into the relevant section — do not append a raw Q&A block.
2. Re-read the updated plan.
3. Run all lenses again.
4. If gaps remain, ask the next round. If none remain, proceed to Step 4.

Always write the updated plan to disk before calling AskUserQuestion again.

---

Step 4 — Northstar review (conditional)

If $NORTHSTAR = null: skip this step entirely and proceed to Step 5.

If $NORTHSTAR is set: read the file fresh and evaluate the plan against each vision check it defines. The northstar document is the authoritative source of what those checks are — do not invent checks not present in the file.

For any BLOCK findings, resolve them before proceeding. For WARN findings, either fix them or note them as acknowledged. Write all corrections directly into the plan file.

Do not proceed to Step 5 until the plan passes the northstar review with no unresolved BLOCK findings.

---

Step 5 — Final confirmation

Once the plan passes all lenses and (if applicable) the northstar review, present:

## Plan complete ✓

**File:** <path to plan.md>
**Rounds:** N
**Issues resolved:** X
**Northstar:** Passed (N acknowledged)  ← omit this line if $NORTHSTAR = null

The plan is agent-ready. Key decisions made:
- <bullet per significant decision>

Then ask:

The plan has been written to <path>. Would you like to proceed to implementation, or is there anything else to adjust?

---

Guidelines

• Never invent answers. If the user's intent is unclear, ask — do not assume.
• Preserve the plan's structure and voice. Integrate clarifications naturally.
• One source of truth. All information lives in the plan file after every round.
• Simpler is better. If you are unsure whether a step is necessary, ask whether it can be cut.
• Do not over-question. If something is clear from context or discovered conventions, do not ask about it.
• Refer to discovered CLAUDE.md / AGENTS.md for codebase conventions when drafting steps — do not contradict established patterns without flagging it.

---

Task: $ARGUMENTS