## Workspace Preflight

Before doing stage/helper work:

1. Resolve the repository root.
2. Check the core Gofer sentinels:
   - `.specify/.gofer-version`
   - `.specify/commands/0_business_scenario.md`
   - `.specify/templates/spec-template.md`
   - `.specify/scripts/bash/create-new-feature.sh`
   - `.specify/scripts/node/parse-stage-command.mjs`
   - `.specify/scripts/hooks/post-tool-use.mjs`
   - `.specify/scripts/powershell/install-optional-tools.ps1`
   - `.specify/templates/gofer-model-policy.yaml`
   - `.specify/memory/gofer-model-policy.yaml`
   - `.specify/specs/`
   - `.specify/memory/`
3. Check host-specific repo-owned files when relevant:
   - Claude: `AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`
   - Codex: `AGENTS.md`
   - Copilot: `.github/copilot-instructions.md`
   - VS Code extension mirrors Claude/Copilot/Gemini resources itself and should still keep the core scaffold healthy
4. If the repo already has the workspace checker script, prefer running:
   - `node .specify/scripts/node/gofer-workspace-check.mjs --host gemini --json`
5. If the workspace is missing or stale, ask exactly:
   - **"This repo is missing or stale for Gofer. Initialize/update it now?"**
6. If the user says yes, run the Gofer workspace bootstrap helper and then resume this command from the top.
7. If the user says no, stop and explain that Gofer stage/helper work depends on the repo-owned scaffold.

---
description: Generate actionable task breakdown from implementation plan
---

# Gofer Tasks

## Token And Cost Policy
<!-- gofer:token-cost-policy:start -->

Before spawning agents, calling tools, or loading large files:

1. Treat `.specify/memory/gofer-model-policy.yaml` as the repo-owned source of truth for simple, medium, hard, and arbiter model routing. If it is missing, run `/gofer:bootstrap-workspace` before continuing.
2. Use the cheapest capable model first.
   - Claude: Haiku for scouting/extraction; Sonnet for normal implementation, synthesis, validation, and security; Opus for high-risk arbitration or release-critical failures.
   - Codex/OpenAI: GPT mini for simple coding; GPT nano only for locate/classify/summarize/mechanical work; GPT-5.3-Codex or flagship GPT for tool-heavy coding, architecture, and release-critical validation.
   - Gemini: Flash-Lite for cheap large-context scan/summarize; Flash for default research synthesis; Pro for large-context architecture or high-risk arbitration.
   - Copilot: prefer Auto for simple and default work; ask the user before choosing a paid/high-tier picker model for hard security, architecture, or release gates.
3. Keep raw tool output out of the main conversation context. Save stable findings to `.specify/specs/{feature}/context-bundle.md`, then work from summaries.
4. Use provider prompt/context caching only for stable, non-secret prefixes: Gofer scaffold, AGENTS/CLAUDE/Copilot instructions, constitution, repo map, stage contracts, and validation rubric.
5. Before continuing after large research, planning, implementation, or validation bursts, checkpoint the durable artifacts and compact/clear/resume context when the host supports it.
6. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality.
<!-- gofer:token-cost-policy:end -->

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Execution Profile And Task Sizing

Preserve the selected depth from earlier stages:

- **fast**: for `docs-only` or very small low-risk changes, generate a short
  task list with only the work needed to deliver the change and its
  verification.
- **standard**: generate normal dependency-ordered tasks with tests and
  traceability.
- **full**: add tasks for contract compatibility, security review, migration or
  config safety, rollout/rollback, and blast-radius verification.
- **dynamic**: require `workflow-dag.md`, then generate shard-aligned tasks,
  reducer tasks, verifier/refuter tasks, budget/stop-condition checks, and a
  resumable progress ledger before implementation starts.

Every task should name a real file or directory when known. If ownership or
files are unknown, mark that as `unknown` and add a discovery task instead of
fabricating a path. Keep optional artifacts out of the plan unless they support
the selected risk label. Do not convert dynamic shard tasks into implementation
work until the DAG confirmation gate is resolved.

## Prerequisites

This command expects in `.specify/specs/{feature}/`:

- `research.md` - Codebase analysis (from /1_gofer_research)
- `spec.md` - Feature specification (from /2_gofer_specify)
- `plan.md` - Implementation plan (from /3_gofer_plan)
- `goal-ledger.json` - Goal and re-loop contract (from /1 and /2)

If missing, prompt user to run the prerequisite stage.

---

## Outline

1. Context health check
2. Load context (lightweight)
3. Dispatch task generation agents (sub-agents handle heavy generation)
4. Review agent outputs
5. Engineer review gate
6. Optional multi-perspective review
7. Approval gate
8. Output: `tasks.md`, `traceability.md`, `issues.md`

---

## Step 0: Context Health Check

Before generating tasks, assess context window health:

```bash
.specify/scripts/bash/check-context-health.sh
```

- If **< 50%**: Proceed normally
- If **50-70%**: Consider `/compact` before loading all artifacts
- If **> 70%**: Start new session with handoff summary

Task generation dispatches agents — keep main context lightweight.

---

## Step 1: Load Context (Lightweight)

1. **Run setup script**:

   ```bash
   .specify/scripts/bash/check-prerequisites.sh --json
   ```

   Parse JSON for FEATURE_DIR, AVAILABLE_DOCS

2. **Scan available documents** (do NOT load full content — agents read
   directly):
   - Note feature name from FEATURE_DIR
   - Note which optional docs exist: data-model.md, contracts/, quickstart.md
   - Note the tasks template path: `.specify/templates/tasks-template.md`

---

## Step 2: Dispatch Task Generation Agents

**CRITICAL**: You **MUST** launch these agents using the Task tool. Do NOT
perform this work inline in the main context. The main context should only
orchestrate and review agent outputs.

### Agent 1: Task Breakdown Generator

```
Task: subagent_type="general-purpose", model="sonnet"
Prompt: "Generate a complete, dependency-ordered task breakdown for [FEATURE_NAME].

Feature directory: {FEATURE_DIR}

Read these files for full context:
- {FEATURE_DIR}/plan.md — Implementation phases, architecture, file structure
- {FEATURE_DIR}/spec.md — User stories with priorities and acceptance criteria
- {FEATURE_DIR}/data-model.md — Entity definitions (read if exists)
- {FEATURE_DIR}/contracts/ — API contracts (read all .md files if exists)
- {FEATURE_DIR}/research.md — Technology decisions (read if exists)
- .specify/templates/tasks-template.md — Task template structure

Generate tasks.md organized by user story to enable independent implementation:

Task Organization (REQUIRED structure):
1. Phase 1: Setup — Project initialization, shared infrastructure
2. Phase 2: Foundational — Blocking prerequisites for all user stories
3. Phase 3+: User Stories — One phase per story in priority order (P1 first)
4. Final Phase: Polish — Cross-cutting concerns, documentation

Task Format (REQUIRED for every task):
- [ ] [TaskID] [P?] [Story?] Description with exact file path
Where:
- TaskID: Sequential (T001, T002...)
- [P]: Only if parallelizable with other tasks in same phase
- [Story]: [US1], [US2] etc. for user story phases only
- Description: Clear action with the exact file path to create/modify

Each phase MUST include:
- Goal statement
- Independent Test Criteria (for user story phases)
- Verification checklist at the end

Include these sections:
1. YAML frontmatter: feature, spec, plan, status: ready, created (ISO date)
2. Overview: Total tasks, parallel opportunities, user story count
3. Dependencies: Mermaid graph showing phase dependencies
4. All phases with tasks
5. Parallel Execution Guide: Which [P] tasks can run concurrently
6. Implementation Strategy: MVP first, incremental delivery, polish last

Validation checks before writing:
- Every plan phase has at least one task (GAP-02)
- Every plan task item has a corresponding task
- Every acceptance criterion maps to at least one task (GAP-03)
- Every data model entity has implementing tasks
- Every API contract endpoint has implementing tasks
- Task file paths match plan.md File Structure section
- For CLI-driven platform mutations, task order must reflect authoritative
  store setup before orchestrator writes, orchestrator writes before CLI
  consumption, and platform persistence before local mirror patching.

Write the complete task breakdown to {FEATURE_DIR}/tasks.md.

Return a structured summary:
- Total task count
- Tasks per phase
- Parallel opportunity count
- Plan phase coverage: N/N phases covered
- Acceptance criteria coverage: N/N criteria covered
- Any coverage gaps found"
```

### Agent 2: Traceability Analyzer

```
Task: subagent_type="general-purpose", model="haiku"
Prompt: "Generate a requirement traceability artifact for [FEATURE_NAME].

Feature directory: {FEATURE_DIR}

Read these files:
- {FEATURE_DIR}/spec.md — User stories, acceptance criteria, functional requirements
- {FEATURE_DIR}/plan.md — Implementation phases, components
- {FEATURE_DIR}/goal-ledger.json — goals, metrics, delivery states, re-loop triggers
- {FEATURE_DIR}/tasks.md — Task breakdown (read after Agent 1 writes it)
- {FEATURE_DIR}/data-model.md — Entity definitions (read if exists)
- {FEATURE_DIR}/contracts/ — API contracts (read if exists)

Generate {FEATURE_DIR}/traceability.md with:

1. Goal → Story → Requirement Mapping:
   | Goal ID | Metric / Target | User Story | Requirement IDs | Task IDs |

2. Requirement Trace Matrix:
   | Requirement ID | Goal ID | Plan Phase | Task IDs | Planned Code | Planned Tests | Status |

3. Acceptance Criteria Detail:
   | ID | Criterion | Task(s) | Planned Code | Planned Tests | Phase |

4. Plan Phase Coverage:
   | Phase | Task Count | Coverage % |

5. Data Entity Coverage (if data-model.md exists):
   | Entity | Implementing Task(s) | Fields Covered? |

6. API Contract Coverage (if contracts/ exists):
   | Endpoint | Contract File | Implementing Task(s) |

7. Coverage Summary:
   - Plan Phases: N/N covered
   - User Stories: N/N covered
   - Acceptance Criteria: N/N covered
   - Requirements with code targets: N/N covered
   - Requirements with test targets: N/N covered
   - Data Entities: N/N covered
   - API Endpoints: N/N covered
   - Status: VALIDATION PASSED or VALIDATION FAILED

Return: overall coverage percentages and any MISSING items"
```

**Run Agent 1 first**, then Agent 2 after tasks.md is written.

---

## Step 3: Review Agent Outputs

After both agents complete:

1. **Review tasks.md** — Verify from Agent 1:
   - Tasks are specific enough for LLM execution
   - File paths reference real locations in the codebase
   - Phase dependencies make sense
   - Every user story phase is independently testable
   - Parallel markers [P] are correct (no dependency conflicts)

2. **Review traceability.md** — Check from Agent 2:
   - If VALIDATION FAILED: identify which coverage gaps exist
   - Add missing tasks for uncovered acceptance criteria
   - Add missing tasks for uncovered plan phases
   - Add missing planned code/test targets for uncovered requirements
   - Re-run Agent 2 if tasks.md was modified

3. **Fix coverage gaps** — Max 3 correction iterations

---

## Step 4: Engineering Review Gate (Up to 5 cycles)

Before proceeding to the approval gate, run an iterative engineering review to
catch misalignment early.

### Review Cycle (repeat up to 5 times)

**You MUST dispatch 3 review agents in parallel** using the Task tool:

**Agent 1**: engineer-review (sonnet) — cross-check spec↔plan↔tasks alignment

```
Task: subagent_type="engineer-review", model="sonnet"
Prompt: "Review alignment between spec.md, plan.md, and tasks.md in {FEATURE_DIR}.
Find every gap, inconsistency, and misalignment. Report Red/Yellow/Gray findings."
```

**Agent 2**: codebase-analyzer (sonnet) — verify file paths and code patterns

```
Task: subagent_type="codebase-analyzer", model="sonnet"
Prompt: "Verify that the tasks at {FEATURE_DIR}/tasks.md reference correct
file paths and follow existing codebase patterns from {FEATURE_DIR}/research.md.
Report Red/Yellow/Gray findings."
```

**Agent 3**: validation-correctness (sonnet) — verify acceptance criteria
coverage

```
Task: subagent_type="validation-correctness", model="sonnet"
Prompt: "Verify that every acceptance criterion in {FEATURE_DIR}/spec.md
is covered by at least one task in {FEATURE_DIR}/tasks.md.
Report Red/Yellow/Gray findings with coverage gaps."
```

**After agents return:**

1. Classify findings: Red (blocking) / Yellow (should fix) / Gray
   (informational)
2. If NO Red or Yellow findings → PASS → proceed to approval gate
3. If Red or Yellow findings exist: a. Fix findings directly in tasks.md (Red
   first, then Yellow) b. Increment cycle counter c. If cycle <= 5 → re-run
   review agents d. If cycle > 5 → log remaining findings, proceed with warnings

---

## Step 5: Multi-Perspective Task Review (Optional)

After task validation, optionally run multi-perspective strategies. **Skip if
time-constrained.**

### Strategy #14: Cross-Cutting Concern Scanner

Spawn 5 agents scanning for missing cross-cutting concerns:

```
Task: subagent_type="tasks-cross-cutting-scanner", model="haiku"
Prompt: "Scan tasks.md at [FEATURE_DIR]/tasks.md for missing cross-cutting concerns.
Dimension [1-5]:
1: Logging/observability  2: Accessibility  3: Internationalization
4: Backward compatibility  5: Documentation
Spec: [FEATURE_DIR]/spec.md"
```

Run all 5 in parallel, then synthesize with judge:

```
Task: subagent_type="multi-perspective-judge", model="opus"
Prompt: "Judge verdict type: cross-cutting concern gap analysis.
Identify which missing concerns should be added as tasks before implementation.
[paste all 5 agent outputs]"
```

Add HIGH priority missing tasks to tasks.md if the judge recommends them.

### Strategy #18: Rollback Strategy Planner

Plan rollback for each implementation phase:

```
Task: subagent_type="tasks-rollback-planner", model="haiku"
Prompt: "Analyze tasks.md at [FEATURE_DIR]/tasks.md.
For each phase, design a rollback plan. Identify irreversible steps that need checkpoints."
```

Include rollback notes in the task document's "Implementation Strategy" section.

---

## Step 6: Generate GitHub Issues

Run the issues generator:

```bash
node .specify/scripts/node/generate-issues.js "$FEATURE_DIR"
```

This creates `{FEATURE_DIR}/issues.md` with GitHub-ready issue definitions.

---

## Step 7: Approval Gate

**IMPORTANT**: Tasks MUST be reviewed and approved before implementation begins.

### 7.1 Update Task Status

Set the frontmatter status to `review`:

```yaml
---
feature: [Feature Name]
spec: spec.md
plan: plan.md
status: review # Changed from 'draft' to 'review'
created: [ISO date]
---
```

### 7.2 Present for Approval

Display the task summary and request explicit approval:

```
════════════════════════════════════════════════════════════════
  TASKS READY FOR REVIEW: [Feature Name]
════════════════════════════════════════════════════════════════

  Task Summary:
  - Total tasks: [N]
  - Tasks by story:
    - US1 (P1): [N] tasks
    - US2 (P2): [N] tasks
    - ...
  - Parallel opportunities: [N] tasks
  - MVP scope: Phase 1-3 (Setup + Foundation + US1)

  Files created:
  - {FEATURE_DIR}/tasks.md
  - {FEATURE_DIR}/traceability.md
  - {FEATURE_DIR}/issues.md ([N] GitHub issues)

════════════════════════════════════════════════════════════════
  APPROVAL REQUIRED BEFORE IMPLEMENTATION
════════════════════════════════════════════════════════════════

  Please review tasks.md and confirm:
  1. Task breakdown is complete and accurate
  2. Protected files list is correct
  3. Phase dependencies make sense
  4. Scope boundaries are appropriate

  Reply with:
  - "approved" or "lgtm" to proceed to implementation
  - "modify [feedback]" to request changes
  - "stop" to halt the pipeline

════════════════════════════════════════════════════════════════
```

### 7.3 Handle Approval Response

| Response                    | Action                                                       |
| --------------------------- | ------------------------------------------------------------ |
| `approved` / `lgtm` / `yes` | Update status to `approved`, proceed to `/5_gofer_implement` |
| `modify [feedback]`         | Update tasks based on feedback, re-present for approval      |
| `stop`                      | Halt pipeline, document reason in tasks.md                   |

### 7.4 Record Approval

When approved, update frontmatter:

```yaml
---
feature: [Feature Name]
spec: spec.md
plan: plan.md
status: approved
approvedBy: '[user]'
approvedAt: '[ISO timestamp]'
created: [ISO date]
---
```

---

## Step 8: Continue to Implementation

After approval received:

```
✓ Tasks APPROVED: {FEATURE_DIR}/tasks.md

Engineering Review: PASSED (cycle [N] of 5)
```

**AUTO-CHAIN (MANDATORY)**: You MUST immediately invoke the next pipeline stage
by calling the Skill tool with skill="/5_gofer_implement". Do NOT ask the user
for confirmation. Do NOT output "Ready for next stage". Just invoke the skill
NOW.

---

## Ordered Runnable Task-Generation Guidance

The standard Gofer workflow is the public default. EnterpriseAI task generation
is migration-only and used only when `workflowProfile` is explicitly
`enterpriseai`.

When the workflow profile is explicitly `enterpriseai`,
`tasks.md` MUST emit deployment
tasks in the following ordered chain. Each task is independently runnable and
the ordering enforces scaffold before deployment so that configuration and
manifest artifacts exist before any deploy command runs.

0. **EAI readiness unblock -> `eai-preflight.md`**
   - If `{FEATURE_DIR}/eai-preflight.md` is missing, stale, or blocked, emit
     only the smallest runnable unblock tasks before normal build tasks:
     install/update `eai`, run `eai login`, run `eai tenant select`, confirm a
     tenant-admin membership with `eai tenant list --format json`, initialize
     the EAI app template with `eai init <app-name> --skip-prompts
     --company-tenant <tenant-id>` when confirmed, and confirm app enrollment
     with `eai vertical list/create/select`.
   - Do not emit object-type, UI, implementation, deployment, or service-fit
     tasks until EAI readiness is `ready` or explicitly deferred by the user.
   - Never invent tenant IDs, app keys, app URLs, or platform capabilities.
     Use `eai --describe`, public EAI docs, and the user's confirmed tenant/app
     selection as evidence.
   - Do not emit tasks that establish a non-EAI primary runtime, database,
     hosting platform, or app framework. Non-EAI technologies can appear only as
     approved integration/migration/exception tasks after the EAI Platform/Azure
     fit is recorded.
1. **EAI App Template scaffolding -> `eai init`**
   - Command: `eai init <app-name> --skip-prompts --company-tenant <tenant-id>`
   - Produces the working directory, `manifest.yml`, and `config.json` expected
     by subsequent tasks.
2. **Local validation -> `eai verify`**
   - Command: `eai verify`
   - Confirms manifest/config correctness before any deploy attempt.
3. **Pinned `eai major.minor` deployment tasks -> `eai deploy`**
   - Command: `eai deploy trigger --repo <org/repo>`
   - Inherits the `major.minor` pin recorded in `plan.md`.

<!-- prettier-ignore -->
The ordering above is non-negotiable: tasks.md MUST instruct the pipeline to scaffold before deployment, validate before deploy, and only then invoke pinned `eai major.minor` deployment tasks. Breaking the order causes deployment preflight gating in `/5_gofer_implement` to fail.

### App-Delivery Preconditions Inside Shared Stages

For **application delivery**, task generation MUST treat the UI-first gate as a
precondition to downstream implementation tasks:

- If `{FEATURE_DIR}/ui-approval.md` does not exist or is not approved, emit
  only the blocking preview/approval tasks needed to reach approval; do **not**
  emit downstream implementation tasks as if the UI were already settled.
- If `{FEATURE_DIR}/service-fit-matrix.md` is missing or does not distinguish
  accessible now vs purchasable vs unavailable platform capabilities, emit a
  blocking service-fit task group before normal build tasks.
- The first normal build tasks must use the EAI app template, EAI CLI, EAI
  platform services, and Azure-compatible deployment/supporting services before
  any custom or third-party implementation task.
- Use the EAI App Template already scaffolded by `eai` as the default UI
  lego-block source. Any create-new UI concept must appear as an explicit
  exception task with rationale.
- Add a block-catalog task before any UI implementation task. It MUST run
  `eai --describe`, `eai blocks list`, `eai blocks describe <id>` for selected
  blocks, and `eai resources schema --format json`; task notes must cite block
  IDs, resource fields, data/action bindings, package lane, coupling status,
  Storybook story IDs, theme override points, and approved custom-block
  exceptions.
- Add package-profile tasks that lock the external/internal/hybrid profile
  choice and the package lane before any public, shared, or app-local block
  implementation begins.
- Add block-porting tasks for every selected EAI App Template block that must
  move into a reusable package lane, including Storybook story ID coverage,
  theme override points, exports, and compatibility checks.
- Add source-platform decoupling tasks whenever a block or package lane is not
  restricted-source and still depends on source-platform internals; the task must define the
  resource-schema or adapter boundary and the regression proof that source-platform coupling is no
  longer required by the public surface.
- Add public-readiness tasks for external and hybrid profiles covering public
  exports, docs/examples where already part of the package surface,
  accessibility/theming contracts, consumer smoke tests, and unsupported
  custom-block exceptions.
- For **non-app work**, keep the shared numbered stages but skip these
  preview/approval/service-fit prerequisites.

### EnterpriseAI Contract, Reuse, and Red/Green Tasks

`tasks.md` MUST also include:

- Contract-pack coverage tasks for actors, object types, workflows/journeys,
  permissions/tenant boundaries, APIs/events, deployment assumptions, and
  acceptance tests.
- AI-augmented journey tasks for app delivery: one task group for each of the
  four-or-fewer journey steps covering user experience, chatbot/voice/
  accessibility/translation support, contextual prefill, completion validation,
  human review, audit trail, and fallback/escalation.
- App-delivery preview/approval tasks that:
  - build the first MVP from EAI App Template blocks
  - select only known `eai blocks` IDs unless a custom-block exception exists
  - preserve package lane, external/internal/hybrid profile choice, coupling
    status, Storybook story IDs, and theme override points from the approved
    preview brief
  - apply approved branding/logo work when in scope
  - collect screenshot or Playwright-style self-review evidence
  - update `ui-review-log.md`
  - block downstream work until `ui-approval.md` is approved
- App-delivery service-fit tasks that update `service-fit-matrix.md` using
  tenant-aware evidence from `eai --describe`, `eai whoami`, `eai tenant
  select`, `eai resources schema --format json`, `eai workflow readiness
  --format json`, `eai verify calls --format json`, or equivalent approved
  platform evidence.
- A scope-control task that checks whether any user-facing app process exceeds
  four steps and either combines/automates extra steps or records the approved
  exception and rationale.
- Reuse-before-create tasks before any new EnterpriseAI object type, API/event,
  workflow, module, or spec concept is created.
- Test-first red/green tasks: generate spec-derived tests, verify they fail
  against missing or incomplete implementation, implement in a separate task,
  then re-run validation.
- Audit-history tasks that preserve stable finding IDs, recurring findings,
  accepted exceptions, owner, expiry, and review cadence.

### CLI-Driven Platform State Ordering

When a command-line workflow is expected to update platform state, `tasks.md`
MUST order work like this unless the plan proves a different authoritative
dependency:

1. Define or extend the authoritative storage model.
2. Implement platform-side orchestrator writes into those stores.
3. Implement secret/config persistence if secrets or environment state are part
   of the success contract.
4. Implement CLI or UX consumption of the new platform response.
5. Add regression tests for create, repair, recovery, and failure gates.

The CLI must not be treated as the source of truth when the plan says the
platform owns persistence.

---

## Observability Logging

At stage completion, log metrics:

```bash
.specify/scripts/bash/log-stage.sh 4_tasks --complete --tokens [N] --compactions [N]
```

Logs to: `.specify/logs/pipeline.jsonl`

---

## Key Rules

- Use absolute paths for all file references
- Every task must have a file path
- Tasks must be specific enough for LLM execution
- Each user story phase must be independently testable
- Tests are OPTIONAL - only include if specified in requirements
- Log stage completion for observability tracking
