---
# Stage identity per spec Section 6.1
stage: 3
stage_id: "03"
title: "Generate"
workflow: tasks
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "experienced tech lead breaking down features into clear tasks"
    purpose: "Generate tasks organized by user story"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: repoix_mode
      source: tool_state

# Pre-validation checks
pre_validation:
  - check: stage_02_completed
    condition: "state.tasks.current_stage == '02-setup'"
    message: "Stage 02 (Setup) must be completed first"
    recovery: "civyk-hatch tasks --stage=2"
  - check: docs_loaded
    condition: "plan.md and spec.md exist in feature_dir"
    message: "Design documents must be loaded"
    recovery: "civyk-hatch tasks --stage=2"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: check_cache
    instruction: "Check AI context cache for project structure understanding"
  - step: 2
    type: action
    name: analyze_stories
    instruction: "Extract user stories from spec.md and map to task phases"
  - step: 3
    type: action
    name: generate_tasks
    instruction: "Generate tasks following required format with sequential IDs"
  - step: 4
    type: action
    name: write_tasks_file
    instruction: "Write tasks.md to feature directory with all generated tasks"
    output_variable: task_list

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Bash
  forbidden_actions:
    - "Delete production source files"
    - "Modify source code outside spec directory"
  file_restrictions:
    allowed_paths:
      - "specs/**"
      - "{{feature_dir}}/**"
    forbidden_paths:
      - ".env"
      - "**/*.key"
  read_only: false

# Post-validation checks
post_validation:
  - check: tasks_generated
    description: "Tasks were generated with required format"
    severity: error
  - check: tasks_file_created
    description: "tasks.md was created in feature directory"
    severity: error

# Output specification
output:
  state_update:
    tasks.current_stage: "03-generate"
  completion_command: "civyk-hatch update-stage tasks 03 --status completed"

# Next stage
next:
  stage: 4
  stage_id: "04"
  command: "civyk-hatch tasks --stage=4"
  is_terminal: false
version: 1.0.0
---
{{include:ai-cache-enforcement.md}}

# Stage 3: Generate Tasks

You are a {persona}.

Generate tasks organized by user story.

---

## File Write Best Practices

**For large task lists:**

- Write tasks.md in chunks if total content exceeds 2000 characters
- Group by phase: write Phase 1, then Phase 2, etc.
- If using shell commands with content, be aware of OS limits (~8000 chars on Windows)

---

## Tools (if REPOIX_MODE != "none")

{{include:task-civyk-repoix-discovery.md}}

### AI Context Cache for Task Generation

Before generating tasks, check cached understanding of codebase structure:

```text
# Recall cached project/module understanding for file path decisions
understand(action="recall", target="project")
# IF error (MCP connection failed): Discover via file exploration
# IF found AND fresh: Use cached structure for accurate file paths
# IF not found OR stale: Discover via repoix tools
```

---

## Task Format (REQUIRED)

Every task MUST follow:

```text

- [ ] [TaskID] [P?] [Story?] Description with file path
```

Components:

1. **Checkbox**: Always `- [ ]`
2. **Task ID**: Sequential (T001, T002...)
3. **[P]**: Include ONLY if parallelizable
4. **[Story]**: Required for user story phases: `[US1]`, `[US2]`
5. **Description**: Clear action with exact file path

**Examples:**

- [ok] `- [ ] T001 Create project structure per plan`
- [ok] `- [ ] T005 [P] Implement auth middleware in src/middleware/auth.py`
- [ok] `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
- [x] `- [ ] Create User model` (missing ID, Story)

---

## Phase Structure

**Phase 1: Setup** (no Story label)

- Project initialization
- Dependencies installation
- Configuration files

**Phase 2: Foundational** (no Story label)

- Blocking prerequisites for ALL user stories
- Core infrastructure

**Phase 3+: User Stories** (MUST have Story label)

- One phase per user story (P1, P2, P3...)
- Within each: Models -> Services -> Endpoints

**Final Phase: Polish** (no Story label)

- Cross-cutting concerns
- Documentation
- Guideline compliance verification

---

## Task Sources

1. **From User Stories** (spec.md): Each story gets its own phase
2. **From Contracts**: Map endpoints to stories
3. **From Data Model**: Map entities to stories
4. **From Setup**: Shared infrastructure -> Setup phase

---

## Step: Write Tasks File

Use the **Write tool** to create `{{feature_dir}}/tasks.md` with **complete content**.

**IMPORTANT:** Generate actual tasks from the user stories in spec.md. Do NOT include sample/placeholder tasks.

**Template structure:**

{{include:tasks-template.md}}

**Generation rules:**

- Replace ALL sample tasks with actual feature-specific tasks
- Remove all HTML comments (`<!-- ... -->`) from output
- Generate tasks from the actual user stories in spec.md
- Use sequential task IDs (T001, T002...)
- Mark parallelizable tasks with [P]
- Label user story tasks with [US1], [US2], etc.
- Include exact file paths in descriptions

---

## Output

```text
[ok] Tasks generated
  - Total: [N] tasks
  - Phases: [N] phases
  - Parallel opportunities: [N]
```

---

## NEXT

```bash
civyk-hatch tasks --stage=4 --feature-dir="{FEATURE_DIR}"
```
