---

name: feature-planning description: "Turns work-item context into execution-ready plans and optional handoff prompts. Use for requirements, planning, refinement, and stress-testing. Triggers on: plan, requirements, PRD, feature planning, handoff prompt, stress-test design."

Feature Planning

Manage work-item planning from rough intent through optional context, execution-ready plans, implementation, and explicit handoffs when another thread is useful.

Workflow Overview

Work Item → Context as needed → Plan → Refine → Execute → Record Evidence
                                             └─ Hand off when useful

1. Work item: Use agent-work to create or locate .agents/work/<category>/<work-slug>/.
2. Context: Add research.md for technical facts, research/ for multiple focused notes, or prd.md as a short requirements brief only when needed.
3. Plan: Create or update the active plan file (plan.md by default, or plans/<name>.md for focused plans) with scoped tasks, dependencies, and acceptance criteria.
4. Refine: Validate assumptions against current repo reality before implementation or delegation.
5. Execute: Implement in the current thread by default; use agent-work coordination when delegation helps.
6. Progress: Update active plan task checkboxes, living progress.md when needed, and index.md; record observed verification evidence.

Plan Locations

New plans live inside work items:

.agents/work/<category>/<work-slug>/
├── index.md
├── research.md
├── research/
├── prd.md
├── plan.md
├── plans/
├── progress.md
└── decisions/

Legacy standalone plan and PRD documents are user content. Migrate one at a time into .agents/work/ only when requested. Retired Ralph guidance/templates may be backed up and removed by sync.

Requirements Brief Guidance

Most work does not need a PRD. Create prd.md only when the missing context is requirements alignment: users, behavior, goals, non-goals, acceptance, rollout, or stakeholder decisions. Use the agent-work requirements brief template.

Use research.md or research/ for technical discovery. If acceptance criteria fit naturally in the active plan file, skip prd.md.

Plan Guidance

Use the agent-work plan template. Keep plans implementation-ready:

• Each task has Scope, Depends on, and verifiable Acceptance.
• The next task or phase is obvious.
• Scope limits and verification commands are explicit when not obvious.
• Blockers, manual steps, and risky assumptions are called out.
• Tasks are small enough to review independently.
• Verification is proportional to blast radius and identifies running-system or manual proof when automated checks are insufficient.
• Deployment, migration, ordering, approval, and rollback steps are explicit when the change touches a release surface.

For larger work, prefer an early thin slice that proves the end-to-end path before broad hardening.

Pre-Implementation Refinement

Use this before implementation or handoff when work is multi-phase, ambiguous, or stale.

1. Read the work item's index.md and active plan file (plan.md or plans/<name>.md as linked from index.md).
2. Read relevant research.md, requirements brief (prd.md), and decisions only as needed.
3. Validate key assumptions against current code, dependencies, and test setup.
4. Resolve material open questions with repo evidence where possible; ask the user only for decisions the repo cannot answer.
5. If a planned task is already satisfied, record evidence and update the active plan file instead of creating no-op work.
6. Update the active plan file, living progress.md when it exists, and index.md when refinement changes the next action or known constraints.

Skip the full pass for small, obvious changes where the plan and repo state are already aligned.

New-Thread Handoff Prompt

Use this mode when asked to write a prompt for a new thread, implementation handoff, or continuation. Produce a paste-ready prompt; do not implement the work yourself unless the user explicitly asks.

The prompt should include:

1. Work item path.
2. Files to read first.
3. Goal and current state.
4. Exact task, phase, or slice to implement.
5. Scope limits and non-goals.
6. Artifact update contract for the active plan file, living progress.md when needed, and index.md.
7. Verification commands or manual checks.
8. Stop conditions.
9. Expected final response format.

Use this template:

You are continuing the work item at:

.agents/work/<category>/<slug>/

Read first:
1. .agents/work/<category>/<slug>/index.md
2. <active plan file linked from index.md: .agents/work/<category>/<slug>/plan.md or .agents/work/<category>/<slug>/plans/<name>.md>
3. Relevant artifacts linked from index.md

Goal:
<one-paragraph goal>

Current state:
<what is already done, plus branch/commit/thread anchors if useful>

Implement only this slice:
- <Task N / phase / exact acceptance criteria>

Scope limits:
- Touch only <paths/modules> unless the plan proves the scope is wrong.
- Do not broaden the feature.
- If the plan is stale, update the plan and explain why before implementing.

Progress contract:
- Update completed task checkboxes in the active plan file.
- Keep progress.md current with the active slice, observed verification evidence, blockers, and next action when the work spans sessions or workers.
- Update index.md Status, Updated, Artifacts, and Next Action when they change.

Verification:
- Run <commands>.
- If verification cannot run, record why and what remains unverified.

Stop conditions:
- Stop and report if blocked by missing decisions, credentials, unsafe migrations, unrelated failing tests, or scope expansion.

Expected final response:
- Summary of changes
- Files changed
- Verification results
- Work item updates made
- Remaining next action

Stress-Test Mode

Use this only when the user explicitly asks to stress-test, grill, or walk decision branches.

1. Inspect the existing PRD, plan, repo docs, and relevant code first.
2. Ask one highest-leverage unresolved question at a time.
3. Provide a recommended default answer and brief rationale for each question.
4. Capture outcomes in prd.md, the active plan file, or index.md.
5. Exit once remaining ambiguity no longer materially changes scope, sequencing, or architecture.

Definition Of Done

Planning is done when the work item has a current index.md, required context artifacts, an execution-ready active plan file, and a clear next action. Produce a paste-ready handoff prompt only when another thread will execute the work.