Feature Planner

Feature Planner

When to Use

• Starting a new product from a spec
• Adding a new feature area to an existing product
• Re-planning after scope changes or user feedback
• Triaging unlabeled GitHub Issues (user-created feature requests and bugs)

Workflow

Step 1: Read Context

1. Read AGENTS.md for tech stack and conventions.
2. Read docs/product-spec.md for the product vision, scope boundaries, and feature priority.
3. Read .agents/architecture.md for the data model and system design.
4. List existing GitHub Issues: gh issue list --state all --json number,title,state,labels
5. Identify what's already planned, in progress, or done.

Step 2: Ensure Labels Exist

Create these labels if they don't exist:

gh label create "status:backlog" --color 0E8A16 --force
gh label create "status:in-progress" --color 1D76DB --force
gh label create "status:in-review" --color FBCA04 --force
gh label create "status:done" --color 6F42C1 --force
gh label create "priority:1" --color B60205 --force
gh label create "priority:2" --color FF9F1C --force
gh label create "priority:3" --color 0E8A16 --force
gh label create "feature" --color A2EEEF --force
gh label create "enhancement" --color A2EEEF --force
gh label create "chore" --color FEF2C0 --force
gh label create "bug" --color D73A4A --force
gh label create "performance" --color F9D0C4 --force

Step 3: Decompose into Issues

For each feature, create a GitHub Issue. Each issue must be:

• Single-concern: one independently implementable feature, resulting in one PR
• Ordered by dependency: foundational features first (auth, DB schema, layout)
• Sized for one session: an agent should be able to implement it in a single run

Issue Template

## Description
One paragraph: what this feature does and why a user cares.

## Acceptance Criteria
- [ ] Criterion 1 (user-visible behavior)
- [ ] Criterion 2
- [ ] Criterion 3

## Integration Requirements
How this feature connects to existing components and systems. Include:
- Which existing components this feature must use (not reimplement)
- Layout requirements relative to the page shell (e.g., full-width vs content-width)
- Interaction edge cases (rapid clicks, overlay dismissal, keyboard navigation)
- Data flow: where data comes from, how it's passed to the UI

## Dependencies
Depends on #N, #M (or "None")

## Technical Notes
- Implementation hints, relevant files, patterns to follow
- Reference .agents/conventions.md for component patterns
- Reference .agents/architecture.md for data model

Integration Requirements Guidance

The "Integration Requirements" section prevents a class of bugs where features are implemented correctly in isolation but fail when integrated into the real app. When writing this section, consider:

1. Component reuse: If a registry, factory, or shared component exists for this domain, the issue must explicitly state "use X for Y" (e.g., "use the property type registry for cell editing"). Without this, the implementer may reimplement the behavior inline.

2. Layout context: If the feature renders inside a page layout, specify whether it should respect or break out of the page's content width constraints. Database tables, for example, need full available width — not the editor's max-w-3xl.

3. Interaction edge cases: For interactive UI, list the edge cases that must be handled: rapid double-click (debounce), overlay dismissal before subsequent interactions, keyboard navigation, focus management after dialog close.

4. Cross-component data flow: If the feature involves data flowing between components (e.g., a type picker that configures a cell editor), specify the interface explicitly. Don't assume the implementer will discover the connection.

Labels

Each issue gets exactly 3 labels:

• Status: status:backlog
• Priority: priority:1 (foundation), priority:2 (core features), priority:3 (polish/stretch)
• Type: feature, enhancement, or chore

Priority Guidelines

Step 4: Present the Plan

After creating all issues, present a summary to the user:

## Feature Plan Summary

**Total issues created**: N
**By priority**: P1: X, P2: Y, P3: Z

### Suggested Implementation Order
1. #N — Title (P1, no deps)
2. #M — Title (P1, depends on #N)
3. ...

### Ambiguities / Questions for Human
- [Any unclear requirements from the spec]
- [Any scope decisions that need human input]

Wait for the user to review, reorder, or adjust before the Feature Builder starts picking up issues.

Continuous Improvement: Triaging Unlabeled Issues

After the initial product spec is implemented, the Feature Planner's primary role shifts to triaging incoming issues. Users and automations create GitHub Issues that need to be assessed and labeled before the Feature Builder or Bug Fixer can act.

Triage Workflow

1. Find open issues with NO status:* label and NO needs-human label.
2. For each issue, assess quality:
   • Sufficient detail (clear what/why, testable definition of done):
     • Enrich the body if needed (add Acceptance Criteria, Technical Notes)
     • Add 3 labels: status:backlog + priority:* + type
   • Insufficient detail:
     • Add needs-human label
     • Post a comment with specific questions (what, why, context)
3. Do NOT remove needs-human from issues — the Needs-Human Requeue automation handles that when the user responds.

The needs-human Feedback Loop

1. Feature Planner adds needs-human + questions to an insufficient issue
2. User responds with the requested information
3. Needs-Human Requeue automation (cron, every 30 min) detects the response and removes needs-human
4. Feature Planner re-triages the issue on its next manual run

Issue Quality Checklist

Every issue entering the backlog must have:

• Description: what and why
• Acceptance Criteria: testable checkboxes
• Integration Requirements: component reuse, layout context, interaction edge cases, data flow (for UI features)
• Dependencies: explicit issue refs or "None"
• Technical Notes: relevant files, patterns, edge cases
• 3 labels: status + priority + type

Anti-patterns

• Do NOT create issues that bundle multiple unrelated changes
• Do NOT create issues for infrastructure that already exists (check the codebase)
• Do NOT create overly granular issues (e.g., "add import statement") — each should be a meaningful feature
• Do NOT create issues without acceptance criteria — the Feature Builder needs them to know when it's done
• Do NOT assign priority:1 to non-foundational features — P1 means "blocks other work"
• Do NOT triage issues that already have a status:* label — they're already in the workflow
• Do NOT remove needs-human — that's the re-queue automation's job