---

name: feature description: Orchestrates complete feature discovery and planning by running specs-writer, frontend-architect, frontend-reviewer, backend-architect, and backend-reviewer agents sequentially to generate comprehensive, rule-compliant architecture documentation. context: fork agent: general-purpose allowed-tools: Task, Read, Write, Bash user-invocable: true

Feature Planning Workflow

This skill orchestrates the complete feature discovery and planning process by sequentially running five specialized agents.

Workflow Overview

You will execute these steps in order:

1. Specs Writer - Gather requirements → create specs.md
2. Frontend Architect - Design frontend → create frontend.md
3. Frontend Reviewer - Review and update frontend.md for rule compliance
4. Backend Architect - Design backend → create backend.md
5. Backend Reviewer - Review and update backend.md for rule compliance

Execution Steps

Step 1: Get Feature Name

Ask the user for the feature name if not provided in the command.

Example:

CopyUser: /feature user-notifications

The feature name should be:

• Lowercase with hyphens (e.g., user-notifications, payment-processing)
• Descriptive and concise
• Used as the directory name under docs/features/

Step 2: Create Feature Directory

Create the directory structure:

Copymkdir -p docs/features/<feature-name>

Verify it was created successfully.

Step 3: Invoke Specs Writer Agent

Use the Task tool to invoke the specs-writer agent:

CopyTask tool with:
- subagent_type: general-purpose
- description: "Gather requirements for <feature-name>"
- prompt: "You are now acting as the specs-writer agent.

Read the agent instructions at .claude/agents/specs-writer.md and follow them precisely.

The user wants to create a feature called '<feature-name>'.

Your task:
1. Ask the user clarifying questions about the feature
2. Read the template at .claude/templates/specs-template.md
3. Create docs/features/<feature-name>/specs.md following the template
4. Ensure all sections are filled with Mermaid diagrams and tables
5. Validate completeness before finishing

Start by asking your first batch of clarifying questions."

Wait for the agent to complete.

After completion, verify docs/features/<feature-name>/specs.md exists.

Step 4: Invoke Frontend Architect Agent

Use the Task tool to invoke the frontend-architect agent:

CopyTask tool with:
- subagent_type: general-purpose
- description: "Design frontend architecture for <feature-name>"
- prompt: "You are now acting as the frontend-architect agent.

Read the agent instructions at .claude/agents/frontend-architect.md and follow them precisely.

The feature is '<feature-name>'. The specs have been created at docs/features/<feature-name>/specs.md.

Your task:
1. Read docs/ai-rules/frontend.md and docs/ai-rules/clean-code.md
2. Read docs/features/<feature-name>/specs.md
3. Explore existing patterns in docs/features/ and the codebase
4. Read the template at .claude/templates/frontend-template.md
5. Create docs/features/<feature-name>/frontend.md with:
   - Mermaid component hierarchy diagram
   - Mermaid data flow diagram
   - Mermaid state diagram (if applicable)
   - Tables for routes, controllers, shadcn/ui components, validation
   - TypeScript interfaces
   - Critical files list
6. Validate completeness

Begin by reading the project rules and specs."

Wait for the agent to complete.

After completion, verify docs/features/<feature-name>/frontend.md exists.

Step 4.5: Invoke Frontend Reviewer Agent

Use the Task tool to invoke the frontend-reviewer agent:

CopyTask tool with:
- subagent_type: general-purpose
- description: "Review frontend architecture for <feature-name>"
- prompt: "You are now acting as the frontend-reviewer agent.

Read the agent instructions at .claude/agents/frontend-reviewer.md and follow them precisely.

The feature is '<feature-name>'. The frontend.md document has been created at docs/features/<feature-name>/frontend.md.

Your task:
1. Read CLAUDE.md, docs/ai-rules/frontend.md, and docs/ai-rules/clean-code.md
2. Read docs/features/<feature-name>/specs.md to understand requirements
3. Read docs/features/<feature-name>/frontend.md - the document to review
4. Use Glob to explore existing frontend patterns in the codebase
5. Review frontend.md against strict architecture rules:
   - Single-action controllers ONLY (no resource controllers)
   - Inertia.js ONLY (no axios/fetch)
   - shadcn/ui components ONLY (no custom UI)
   - TypeScript interfaces for all props
   - Simplicity over complexity (no over-engineering)
6. UPDATE frontend.md directly to fix all violations
7. Report summary of changes made

Begin by reading the project rules and specs."

Wait for the agent to complete.

After completion, the frontend.md should now be compliant with all frontend architecture rules.

Step 5: Invoke Backend Architect Agent

Use the Task tool to invoke the backend-architect agent:

CopyTask tool with:
- subagent_type: general-purpose
- description: "Design backend architecture for <feature-name>"
- prompt: "You are now acting as the backend-architect agent.

Read the agent instructions at .claude/agents/backend-architect.md and follow them precisely.

The feature is '<feature-name>'. The specs have been created at docs/features/<feature-name>/specs.md.

Your task:
1. Read docs/ai-rules/backend.md and docs/ai-rules/clean-code.md
2. Read docs/features/<feature-name>/specs.md
3. Explore existing bounded contexts and patterns
4. Read the template at .claude/templates/backend-template.md
5. Create docs/features/<feature-name>/backend.md with:
   - Mermaid layer architecture diagram
   - Mermaid domain model class diagram
   - Mermaid sequence diagrams (one per use case)
   - Mermaid ERD for database schema
   - Tables for entities, VOs, ports, use cases, bindings
   - PHP code blocks for DTOs
   - Critical files list
6. Validate hexagonal architecture compliance

Begin by reading the project rules and specs."

Wait for the agent to complete.

After completion, verify docs/features/<feature-name>/backend.md exists.

Step 5.5: Invoke Backend Reviewer Agent

Use the Task tool to invoke the backend-reviewer agent:

CopyTask tool with:
- subagent_type: general-purpose
- description: "Review backend architecture for <feature-name>"
- prompt: "You are now acting as the backend-reviewer agent.

Read the agent instructions at .claude/agents/backend-reviewer.md and follow them precisely.

The feature is '<feature-name>'. The backend.md document has been created at docs/features/<feature-name>/backend.md.

Your task:
1. Read CLAUDE.md, docs/ai-rules/backend.md, and docs/ai-rules/clean-code.md
2. Read docs/features/<feature-name>/specs.md to understand requirements
3. Read docs/features/<feature-name>/backend.md - the document to review
4. Use Glob to explore existing backend patterns in the codebase
5. Review backend.md against strict hexagonal architecture rules:
   - Domain layer purity (NO framework dependencies)
   - Application returns DTOs (NEVER entities)
   - Infrastructure implements port interfaces
   - Correct dependency flow (Infra → App → Domain)
   - Exception translation included
   - Simplicity over complexity (no over-engineering)
6. UPDATE backend.md directly to fix all violations
7. Report summary of changes made

Begin by reading the project rules and specs."

Wait for the agent to complete.

After completion, the backend.md should now be compliant with all hexagonal architecture rules.

Step 6: Summary & Next Steps

After all documents are created and reviewed, provide the user with:

Paths to generated documents:

• docs/features/<feature-name>/specs.md
• docs/features/<feature-name>/frontend.md (reviewed and updated)
• docs/features/<feature-name>/backend.md (reviewed and updated)

Summary:

CopyFeature planning complete for '<feature-name>'!

Generated and reviewed architecture documents:
✓ specs.md - Requirements and acceptance criteria
✓ frontend.md - Inertia/React architecture (reviewed for compliance)
  - Single-action controllers enforced
  - Inertia.js patterns verified
  - shadcn/ui components only
  - Simplified for clarity
✓ backend.md - Hexagonal architecture (reviewed for compliance)
  - Domain purity enforced (no framework dependencies)
  - DTOs enforced in Application layer
  - Dependency flow verified
  - Simplified for clarity

All documents now strictly follow project rules and are ready for implementation.

Next steps:
1. Review the documentation (optional - already compliance-checked)
2. Run /create-issue to create a GitHub issue with task checklist
3. Begin implementation using the architecture as your guide
4. After implementation, create a pull request with /create-pr

Important Guidelines

Sequential Execution

CRITICAL: Execute agents ONE AT A TIME, in order.

❌ Do NOT run agents in parallel ✅ Run sequentially:

1. specs-writer (creates specs.md)
2. frontend-architect (creates frontend.md)
3. frontend-reviewer (reviews and updates frontend.md)
4. backend-architect (creates backend.md)
5. backend-reviewer (reviews and updates backend.md)

Wait for each agent to fully complete before starting the next.

Error Handling

If any agent fails:

1. Report the specific error to the user
2. Show which agent failed (specs-writer, frontend-architect, or backend-architect)
3. Ask if they want to:
   • Retry the failed agent
   • Skip that agent and continue (not recommended)
   • Cancel the workflow

Do not proceed to the next agent until the current one succeeds.

Verification

After each agent completes, verify the output file exists:

Copyls -lh docs/features/<feature-name>/specs.md
ls -lh docs/features/<feature-name>/frontend.md
ls -lh docs/features/<feature-name>/backend.md

If a file is missing, report it and retry the agent.

Invoking Agents

When using the Task tool to invoke agents:

• Set subagent_type: general-purpose
• Provide clear context in the prompt
• Include the feature name
• Reference the agent's instruction file
• List all tasks the agent should complete
• Specify output file location

Feature Name Validation

Ensure the feature name is:

• All lowercase
• Uses hyphens (not underscores or spaces)
• Descriptive (e.g., user-notifications, not notif)
• Unique (check if docs/features/<feature-name>/ already exists)

If the directory already exists, ask the user if they want to:

• Overwrite existing docs
• Choose a different name
• Cancel

Example Usage

User command:

Copy/feature payment-processing

Your workflow:

1. Create docs/features/payment-processing/
2. Invoke specs-writer agent → creates specs.md
3. Invoke frontend-architect agent → creates frontend.md
4. Invoke frontend-reviewer agent → reviews and updates frontend.md
5. Invoke backend-architect agent → creates backend.md
6. Invoke backend-reviewer agent → reviews and updates backend.md
7. Report completion and next steps

User command:

Copy/feature

Your response:

CopyWhat is the name of the feature you want to plan? (use lowercase with hyphens, e.g., 'user-notifications')

Tone & Style

• Be clear and professional
• Report progress after each agent completes
• Show file paths for generated documents
• Provide actionable next steps
• Use checkmarks (✓) to show completion
• Keep the user informed throughout the process

Success Criteria

The workflow succeeds when:

• Feature directory created
• specs.md created with all sections, Mermaid diagrams, and tables
• frontend.md created with Mermaid diagrams, tables, and TypeScript interfaces
• frontend.md reviewed and updated for strict rule compliance
• backend.md created with Mermaid diagrams, tables, and PHP code blocks
• backend.md reviewed and updated for hexagonal architecture compliance
• All files are readable and valid markdown
• All documentation strictly follows project rules (no violations)
• Architecture is kept simple and focused on specs
• User is informed of completion and next steps

Your role is to orchestrate the agents smoothly and ensure the user ends up with complete, high-quality, rule-compliant architecture documentation that is simple and ready for implementation.