---

name: review-backend description: Reviews and updates backend.md documentation to strictly follow hexagonal architecture rules and ensure simplicity. Typically runs automatically after backend-architect in the /feature workflow. context: fork agent: general-purpose allowed-tools: Task, Read, Write, Glob user-invocable: true

Review Backend Architecture Documentation

This skill invokes the backend-reviewer agent to review and update the backend.md architecture document, ensuring it strictly follows hexagonal architecture rules and stays simple.

When to Use This

This skill typically runs automatically during the /feature workflow after the backend-architect generates backend.md.

You can also run it manually to re-review documentation:

Copy/review-backend payment-processing

Workflow Steps

Step 1: Get Feature Name

If provided with the command:

Copy/review-backend payment-processing

If not provided:

1. Check recent feature directories
2. Ask the user which feature to review

Step 2: Verify Documentation Exists

Check that both documents exist:

• docs/features/<feature-name>/specs.md
• docs/features/<feature-name>/backend.md

If missing:

• Report the issue
• Instruct user to run /feature <feature-name> first
• Do not proceed

Step 3: Invoke Backend Documentation Reviewer Agent

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

CopyTask tool with:
- subagent_type: general-purpose
- description: "Review backend documentation 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>'.

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 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.

Step 4: Report Success

After the agent completes, relay its summary to the user.

Example output:

CopyBackend architecture review complete for '<feature-name>'.

Updated: docs/features/<feature-name>/backend.md

Changes applied:
  ✓ Removed Eloquent Model from Feature entity (pure domain now)
  ✓ Changed GetFeatureUseCase to return FeatureDto instead of entity
  ✓ Added FeatureName and FeatureStatus value objects
  ✓ Moved FeatureRepositoryInterface to Domain/Ports
  ✓ Added exception translation in EloquentFeatureRepository

Architecture compliance:
✓ Domain layer is framework-free
✓ All use cases return DTOs
✓ Infrastructure implements port interfaces
✓ Correct dependency flow (Infra → App → Domain)
✓ Exception translation included
✓ Simple, focused implementation

The documentation now strictly follows hexagonal architecture rules and is ready for implementation.

Error Handling

Missing Documents

If specs.md or backend.md don't exist:

CopyError: Required documentation not found.

Missing: docs/features/<feature-name>/[specs.md|backend.md]

Please run: /feature <feature-name>

This will generate all architecture documents.

Feature Name Not Provided

If user doesn't provide feature name:

CopyWhich feature's backend documentation would you like to review?

Recent features:
- payment-processing
- user-notifications

Specify: /review-backend <feature-name>

Success Criteria

The workflow succeeds when:

• specs.md and backend.md verified to exist
• backend-reviewer agent invoked
• backend.md updated with hexagonal architecture compliance
• Summary of changes reported to user

Tone & Style

• Be clear about changes made
• Show what violations were fixed
• Confirm architecture compliance
• Keep messages concise and actionable

Your role is to ensure the backend documentation strictly follows hexagonal architecture patterns, maintains clean layer separation, and keeps implementation simple before coding begins.