Planning Workflow

Follow this sequence unless the user asks for a shorter output:

1. Define feature worktree + branch plan using Feature Worktree Policy.
2. Clarify objective and constraints.
3. Discover relevant system context from repository docs and code.
4. Select planning mode using Practical Default Mode Selection.
5. Define scope boundaries (in-scope, out-of-scope, assumptions).
6. Generate one primary implementation approach and optional alternatives.
7. Convert the selected approach into an agent-executable plan with right-sized tasks.
8. Present plan status as Awaiting Confirmation, including the task list and commit strategy.
9. Wait for explicit user confirmation before execution (worktree creation, code edits, tests, or commits).

Feature Worktree Policy

• Treat the current checked-out branch as the source branch unless the user specifies another source.
• For new feature implementation work, create a dedicated worktree and feature branch before code changes.
• Preferred commands:
  • git worktree add -b feature/<concise-feature-name> ../<repo>-<concise-feature-name> <source-branch>
  • cd ../<repo>-<concise-feature-name>
• Use a short, informative kebab-case branch suffix (for example: feature/profile-groups-redesign).
• Include a one-line worktree summary near the top of the plan:
  • Worktree Plan: create ../<repo>-<name> on feature/<name> from <current-branch>
• If only planning is requested and no implementation follows in the same session, still include the branch name to be used at execution time.
• If worktree creation requires a path outside the current project directory, explicitly call out that user confirmation is required before execution.

Parallel Feature Streams

• Worktree isolation is the default for every feature. When the user is running multiple features at the same time, recommend worktree-parallel to orchestrate separate worktrees cleanly.
• Add a one-line parallelization note in the plan when applicable:
  • Parallel Plan: use worktree-parallel to create isolated worktrees per feature branch
• Keep one feature branch per worktree to reduce cross-feature conflicts and simplify review/rollback.

Plan Confirmation Gate

• After presenting a plan, explicitly ask for confirmation before execution (for example: Confirm this plan for execution?).
• Do not start implementation actions until the user gives clear approval (for example: approved, proceed, yes, implement).
• If the user requests changes, revise the plan and re-confirm.
• Confirmation must include the commit strategy choice (task-level commits recommended).

Task Chunking Policy

• Break the feature into clear, relevant tasks that are independently reviewable and testable.
• Target meaningful chunks (typically 2-5 tasks per phase), not micro-steps and not broad "do everything" buckets.
• Each task should include objective, file/module targets, acceptance criteria, and validation commands.
• Prefer coherent vertical slices when possible so each task has visible user or system value.

Implementation Commit Policy

• Recommend one commit per completed task to preserve traceability between plan and code history.
• Include a suggested commit message for every planned task.
• Tiny inseparable follow-up fixes MAY be folded into the same task commit.
• Do not create commits until the user confirms both execution and the commit strategy.
• During implementation, report task completion alongside the corresponding commit SHA.

Practical Default Mode Selection

Choose planning mode using these defaults:

• Use architecture-first for auth, data model, routing, or infrastructure-impacting features.
• Use implementation-tickets-first for contained UI flows, isolated endpoints, and incremental enhancements.
• Use hybrid by default when uncertain: produce a short architecture section (maximum one page), then move to ticket-first execution steps.

Mode behavior:

• architecture-first: expand Proposed Design with boundaries, contracts, and data flow before ticket breakdown.
• implementation-tickets-first: keep Proposed Design concise and prioritize detailed, implementation-ready tickets.
• hybrid: keep architecture concise, then provide full ticketized phases.

Context Discovery Rules

• Start from docs/INDEX.md, then open only docs relevant to the feature.
• Read AGENTS.md and task-specific prompt files before proposing implementation steps.
• Use rg to find existing modules, routes, APIs, schemas, and tests that match the feature.
• Prefer incremental changes that align with current architecture and conventions.

Output Contract

Produce plans in a concrete format with explicit file targets:

1. Feature Summary
2. Goals and Non-Goals
3. Current State
4. Proposed Design
5. Implementation Phases
6. Testing Strategy
7. Rollout and Safety
8. Risks and Mitigations
9. Open Questions
10. Execution Readiness

For Implementation Phases, include:

• Phase name and objective
• Expected files/modules to change
• Ordered, right-sized tasks with acceptance criteria
• Dependencies/blockers
• Definition of done
• Suggested commit message per task

Also include a one-line Planning Mode declaration near the top of every plan. Also include Plan Status: Awaiting Confirmation near the top of every plan.

Quality Bar

• Prefer small, reversible steps over broad rewrites.
• Keep tasks right-sized: avoid overly granular noise and overly broad bundles.
• Call out assumptions explicitly when information is missing.
• Separate mandatory work from optional follow-ups.
• Include validation commands (lint, typecheck, unit/e2e) for each meaningful phase.
• Keep plans actionable enough that another agent can implement without reinterpretation.
• Never start execution until explicit user confirmation is received.

References

• For a reusable plan skeleton, use references/plan-template.md.
• For discovery and risk checks, use references/planning-checklist.md.