maestro: Command for Claude Code

---

command: plan-feature version: 1.0.0 description: Plan a feature across the project, creating API contracts first, then milestones and issues with dependency tracking. placeholders:

• INCLUDE
• SUBAGENT_LIST
• VCS_PROVIDER_CMD includes:
• core/premises.md
• core/dependency-graph.md source_provenance: ported_from: .claude/commands/plan-feature.md ported_at: 2026-05-13

---

Plan Feature

Plan a feature across your project, creating API contracts first, then milestones and issues with dependency tracking.

Usage: /plan-feature <description> or /plan-feature

Premises (Canonical Fragment)

Canonical fragment. Do not edit per-provider — render via manifest.toml. Source of truth ported from .claude/CLAUDE.md § CRITICAL PREMISES.

1. YOU ARE THE ONLY AGENT THAT WRITES CODE

The orchestrator is the ONLY agent authorized to:

• Write, edit, or create code files
• Execute bash commands
• Run tests
• Create any files (except documentation - see docs-analyst)

ALL subagents are CONSULTIVE ONLY. They:

• Analyze, research, and plan
• Provide detailed recommendations with exact file paths and code examples
• Return blueprints for YOU to implement

Exception: subagent-docs-analyst can create/edit .md files.

2. Subagent Delegation Depends on MODE

In 🤖 Subagents Orchestrator Mode - You are FORBIDDEN from doing these tasks directly:

• Researching or exploring codebases → delegate to subagents
• Planning implementations → delegate to subagents
• Analyzing code or architecture → delegate to subagents
• Web searches for solutions → delegate to subagents
• Reading documentation to understand how things work → delegate to subagents

Orchestrator Mode workflow is ALWAYS (TDD ENFORCED):

1. Receive user request
2. Pre-check hook (MANDATORY):
   • Run bash .maestro/hooks/implement-gates.sh <issue-number>
   • Abort on any non-zero exit (see exit-code table in /implement)
3. Delegate to Gatekeeper (MANDATORY):
   • subagent-gatekeeper → structured JSON report (DOR, blockers, contracts, task_type)
   • Parse via .maestro/hooks/parse_gatekeeper_report.py
   • On DOR FAIL → by default, orchestrator prints the proposed comment for human review and STOPs (does NOT auto-post); pass --auto-comment to /implement to auto-post the comment and apply needs-info label
   • On blocker/contract FAIL → STOP with reasons from the report
4. Delegate to Architect for blueprint - MANDATORY:
   • subagent-architect - For all architecture decisions
   • NEVER skip architecture step - the architect MUST be called
5. CONTRACT VALIDATION (if task involves API endpoints) - MANDATORY:
   • Run /validate-contracts to check existing models against docs/api-contracts/ schemas
   • If no contract schema exists for the endpoint → STOP and ask user to provide the JSON schema
   • If contract exists but models mismatch → fix models BEFORE proceeding
6. Delegate to QA for test blueprint - MANDATORY (TDD):
   • subagent-qa - Provides test cases, mocks, and expected behaviors
   • Tests are designed BEFORE implementation
7. Write tests FIRST (RED) — verify they fail (enforced by /implement Step 6e bash gate)
8. Implement minimum code (GREEN) — make tests pass (enforced by /implement Step 6g bash gate)
9. Refactor — clean up while tests stay green
10. Delegate to Security for review of implemented code
11. Call docs-analyst at the end