┌─────────────────────────────────────────────────────────────────┐
│                        PLAN.md (you write this)                 │
│  - Feature name and description                                 │
│  - Acceptance criteria                                          │
│  - Any notes or constraints                                     │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      TASK MANAGER                               │
│  - Explores codebase for patterns and conventions               │
│  - Breaks down into 2-5 minute implementation tasks             │
│  - Identifies which files/layers to create or modify            │
│  - Determines task dependencies and execution order             │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
        ┌─────────────────────────────────────┐
        │  For each task (in dependency order) │
        └─────────────────────┬───────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       GO BUILDER                                │
│  - Follows TDD: RED -> GREEN -> REFACTOR                        │
│  - Adheres to hexagonal architecture                            │
│  - Runs build, test, lint, arch-check                           │
│  - Commits with descriptive messages                            │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      GO REVIEWER                                │
│  Stage 1: Spec Compliance                                       │
│  - Does implementation match acceptance criteria?               │
│  - No under-building or over-building?                          │
│                                                                 │
│  Stage 2: Code Quality (only if Stage 1 passes)                 │
│  - 100 Go Mistakes checklist                                    │
│  - Hexagonal architecture compliance                            │
│  - Error handling patterns                                      │
│  - Concurrency safety                                           │
└─────────────────────────┬───────────────────────────────────────┘
                          │
              ┌───────────┴───────────┐
              ▼                       ▼
        ┌──────────┐           ┌─────────────┐
        │ APPROVED │           │ CHANGES     │
        │ Next task│           │ NEEDED      │
        └──────────┘           └──────┬──────┘
                                      │
                                      ▼
                              ┌───────────────┐
                              │  GO BUILDER   │
                              │ (with feedback)│
                              └───────────────┘

# Use default PLAN.md in current directory
/go-team

# Specify a different plan file
/go-team plan="docs/features/user-auth.md"

# Implement only a specific task (after initial planning)
/go-team task=3

Feature: [Short descriptive name]
  As a [role/persona]
  I want [capability]
  So that [benefit]

  Background:
    Given [common precondition for all scenarios]

  Scenario: [Specific behavior being tested]
    Given [initial context/state]
    And [additional context]
    When [action taken]
    And [additional action]
    Then [expected outcome]
    And [additional outcome]

  Scenario: [Another behavior]
    Given [context]
    When [action]
    Then [outcome]

  # Optional: Notes section for implementation hints
  # Note: Use existing domain types from internal/core/domain/
  # Note: Token secret should come from config

Feature: JWT Authentication
  As an API consumer
  I want requests to be authenticated via JWT
  So that only authorized users can access protected endpoints

  Background:
    Given the JWT secret is configured
    And the authentication middleware is enabled

  Scenario: Valid token grants access
    Given I have a valid JWT token for user "alice"
    When I make a request to a protected endpoint
    Then the request should succeed
    And the user context should contain user ID "alice"

  Scenario: Expired token is rejected
    Given I have an expired JWT token
    When I make a request to a protected endpoint
    Then I should receive a 401 Unauthorized response
    And the response body should contain error "token expired"

  Scenario: Malformed token is rejected
    Given I have a malformed JWT token "not-a-valid-jwt"
    When I make a request to a protected endpoint
    Then I should receive a 401 Unauthorized response
    And the response body should contain error "invalid token"

  Scenario: Missing token is rejected
    Given I make a request without an Authorization header
    When I access a protected endpoint
    Then I should receive a 401 Unauthorized response
    And the response body should contain error "missing token"

  Scenario: Health check bypasses authentication
    Given I make a request without an Authorization header
    When I access the "/health" endpoint
    Then the request should succeed

  # Note: Use existing `internal/core/domain/user.go` for User type
  # Note: Token secret should come from config, not hardcoded
  # Note: Consider using godog for BDD test execution

## Task Manager: Plan Feature from {PLAN_FILE}

### Plan File Contents (Gherkin/BDD)
{PLAN_CONTENT}

### Your Mission

1. **Parse the Gherkin Feature File**
   - Extract feature name from `Feature:` line
   - Extract user story from `As a / I want / So that` (if present)
   - Extract `Background:` steps (common preconditions for all scenarios)
   - Extract each `Scenario:` with its Given/When/Then steps
   - Note any `# Note:` comments for implementation hints

2. **Map Scenarios to Implementation**
   - Each Scenario becomes one or more test cases
   - `Background:` steps become test setup/fixtures
   - `Given` = test precondition/setup
   - `When` = action under test
   - `Then` = assertion
   - Consider using godog for BDD test execution

3. **Explore the Codebase**
   - Identify existing patterns and conventions
   - Find related code that this feature will integrate with
   - Understand the current architecture (expect hexagonal/onion)
   - Locate test patterns and helpers

4. **Identify Architectural Layer**
   Determine which layers this feature touches:
   - `internal/core/domain/` - Entities, value objects, domain errors
   - `internal/core/ports/` - Interface definitions
   - `internal/core/services/` - Business logic / use cases
   - `internal/adapters/handlers/` - HTTP/gRPC handlers
   - `internal/adapters/repositories/` - Database implementations

5. **Break Down into Tasks**
   Create tasks that are:
   - 2-5 minutes each
   - Follow TDD (test file created before implementation)
   - Have clear dependencies
   - Include exact file paths
   - Reference specific scenarios they implement

6. **Output Format**

```yaml
feature: {{feature}}
user_story: "As a ... I want ... So that ..."
background_setup: "[common test setup from Background:]"

scenarios:
  - name: "[Scenario name]"
    given: ["step 1", "step 2"]
    when: ["action"]
    then: ["outcome 1", "outcome 2"]

architecture_analysis:
  layers_affected:
    - layer: [domain|ports|services|adapters]
      reason: [why this layer is needed]
  existing_patterns:
    - pattern: [pattern name]
      location: [file path]
      relevance: [how it applies]
  integration_points:
    - file: [path]
      description: [what needs to connect]

tasks:
  - id: 1
    name: "[descriptive task name]"
    layer: [domain|ports|services|adapters]
    scenarios_covered:
      - "[Scenario name this task implements]"
    files:
      create:
        - path: [exact/path/to/file.go]
          purpose: [why this file]
        - path: [exact/path/to/file_test.go]
          purpose: test file
      modify:
        - path: [exact/path/to/existing.go]
          changes: [what changes]
    test_cases:
      - scenario: "[Scenario name]"
        test_name: "Test[ScenarioInPascalCase]"
        given_setup: "[how to implement Given steps]"
        when_action: "[how to implement When step]"
        then_assert: "[how to implement Then assertions]"
    dependencies: []  # task IDs this depends on
    tdd_steps:
      - step: "Write failing test for scenario"
        file: [test file path]
        description: [what the test verifies]
      - step: "Implement minimal code"
        file: [implementation file]
        description: [what to implement]
      - step: "Run validation"
        commands:
          - go build ./...
          - go test ./[package]/...
          - golangci-lint run ./[package]/...

  - id: 2
    name: "[next task]"
    scenarios_covered:
      - "[Another scenario]"
    dependencies: [1]  # depends on task 1
    ...

execution_order: [1, 2, 3, ...]  # respecting dependencies

---

## Phase 2: Go Builder Agent

**Purpose:** Implement a single task following TDD and Go best practices.

### Dispatch Template

Dependencies flow INWARD:
  adapters/handlers -> core/services -> core/domain
  adapters/repositories -> core/ports <- core/services

Domain layer has NO external dependencies

// Wrap with context
return fmt.Errorf("operation failed: %w", err)

// Check wrapped errors
errors.As(err, &targetType)
errors.Is(err, sentinelErr)

// Define where used, not where implemented
// Keep small (1-3 methods)
// Name with -er suffix for single method
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
}

func TestFeature(t *testing.T) {
    tests := []struct {
        name    string
        input   Input
        want    Output
        wantErr bool
    }{
        {"valid input", validInput, expectedOutput, false},
        {"empty input", emptyInput, Output{}, true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := Feature(tt.input)
            if (err != nil) != tt.wantErr {
                t.Errorf("error = %v, wantErr %v", err, tt.wantErr)
                return
            }
            if !reflect.DeepEqual(got, tt.want) {
                t.Errorf("got %v, want %v", got, tt.want)
            }
        })
    }
}

task_id: {{task.id}}
task_name: {{task.name}}
status: complete|blocked|needs_clarification

files_created:
  - path: [file path]
    purpose: [why created]
    lines: [line count]

files_modified:
  - path: [file path]
    changes: [summary of changes]

tests_added:
  - name: [test name]
    file: [test file path]
    covers: [what it tests]

validation:
  build: pass|fail
  test: pass|fail
  lint: pass|fail
  arch: pass|fail|skipped

commits:
  - hash: [short hash]
    message: [commit message]

summary: [1-2 sentence summary of what was implemented]

{{#if blocked}}
blockers:
  - [description of what's blocking]
{{/if}}

---

## Phase 3: Go Reviewer Agent

**Purpose:** Two-stage review - spec compliance then code quality.

### Stage A: Spec Compliance Review

review_type: spec_compliance
task_id: {{task.id}}
status: APPROVED|CHANGES_NEEDED

scenario_assessment:
{{#each task.scenarios_covered}}
  - scenario: "{{this}}"
    status: implemented|partial|missing
    test_name: "[test that implements this scenario]"
    given_verified: true|false
    when_verified: true|false
    then_verified: true|false
    notes: "[if not fully implemented]"
{{/each}}

under_building:
  found: true|false
  issues:
    - scenario: "[which scenario is missing/incomplete]"
      severity: critical|major
      suggestion: "[how to fix]"

over_building:
  found: true|false
  issues:
    - description: "[what's extra beyond scenarios]"
      files: "[affected files]"
      recommendation: remove|keep_with_justification

test_quality:
  adequate: true|false
  missing_tests:
    - scenario: "[scenario without test]"
      suggested_test: "[test description with Given/When/Then]"

verdict: APPROVED|CHANGES_NEEDED
changes_required:
  - priority: 1
    description: "[what to fix]"
    scenario: "[which scenario]"
    files: "[which files]"

### Stage B: Code Quality Review (only after Stage A passes)

review_type: code_quality
task_id: {{task.id}}
status: APPROVED|CHANGES_NEEDED

findings:
  critical:
    - issue: [description]
      location: [file:line]
      mistake_ref: [#number from 100 Go Mistakes]
      fix: [how to fix]

  major:
    - issue: [description]
      location: [file:line]
      mistake_ref: [#number if applicable]
      fix: [how to fix]

  minor:
    - issue: [description]
      location: [file:line]
      suggestion: [improvement]

architecture:
  compliant: true|false
  violations:
    - layer: [which layer]
      issue: [what's wrong]
      fix: [how to fix]

testing:
  tdd_followed: true|false
  coverage_adequate: true|false
  issues:
    - [testing issue]

verdict: APPROVED|CHANGES_NEEDED
changes_required:
  - priority: 1  # critical first
    description: [what to fix]
    location: [file:line]

---

## Orchestration Flow

### Main Loop

### Error Recovery

If a task fails repeatedly (3+ review cycles):
1. Stop the loop
2. Report the stuck task
3. Ask for human intervention

---

## Quick Reference

### Dispatch Task Manager

### Dispatch Go Builder

### Dispatch Go Reviewer (Spec)

### Dispatch Go Reviewer (Quality)

---

## Anti-Patterns

- Running code quality review before spec compliance
- Skipping either review stage
- Dispatching multiple builders in parallel (causes conflicts)
- Proceeding with CHANGES_NEEDED status
- Builder reading plan files instead of receiving full context
- Ignoring architecture violations
- Marking task complete with failing tests/lint

---

## Integration with Other Skills

- **writing-plans**: Can be used to create the initial plan that Task Manager refines
- **subagent-driven-development**: Go Team follows the same two-stage review pattern
- **execute-plan**: Can execute Go Team's task output in batch mode