agile-epic-plan

name	agile:epic:plan
description	Interactively refine an epic strategic plan from approved design.md, then generate complete epic structure — epic.md, feature specs, and task lists. After generation, performs cross-artifact consistency analysis to detect misalignments, then auto-remedies findings before commit. Use when planning a new epic after brainstorm approval.
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, Skill, TaskCreate, TaskList, TaskGet, TaskUpdate, AskUserQuestion, SlashCommand

Epic Plan

Interactively refine an epic strategic plan from an approved design.md, then generate the complete epic artifact structure. The plan phase is collaborative — propose a draft, refine with the user, then generate artifacts.

Invocation

• /agile:epic:plan -- Auto-detect epic with approved design.md
• /agile:epic:plan 119 -- Target specific epic number
• /agile:epic:plan agile/epics/119-skill-consolidation -- Target specific epic path

Context

• Current branch: !git branch --show-current
• Existing epics: !ls agile/epics/ 2>/dev/null | sort | tail -5
• Design.md preview: !head -20 $ARGUMENTS 2>/dev/null || echo "no argument provided"

Hard Gate

Do NOT generate any artifacts until design.md is validated. The file must exist in the resolved epic directory, have status APPROVED, and contain a `## Feature Candidates` section with at least one feature. This applies to EVERY invocation regardless of user instructions. If any prerequisite fails, report the specific error and exit.

Identification Format

This skill uses the hierarchical ID system:

Level	Format	Example	Max
Epic	NNN	121	999
Feature	NNN-XX	121-01	99 per epic
User Story	NNN-XX-U{n}	121-01-U1	9 per feature
Task	NNN-XX-T{nn}	121-01-T03	99 per feature

Feature directories: New epics use 2-digit format: NNN-XX-feature-name (e.g., 121-01-loan-restructuring). Old epics (created before this format) use 3-digit: NNN-###-feature-name (e.g., 120-001-nuclear-import-strip).

Phases

• Phase 1: Validate prerequisites and load context
• Phase 2: Interactive planning — propose and refine epic plan with user
• Phase 3: Write plan.md to epic root
• Phase 4: Checkpoint — ask user to proceed (offer context window clear option)
• Phase 5: Generate epic.md
• Phase 6: Generate feature folders with spec.md + tasks.md
• Phase 7: Cross-artifact consistency analysis
• Phase 8: Remedy misalignments
• Phase 9: Commit and present results

Phase 1: Validate Prerequisites & Load Context

1. Resolve the epic directory (EPIC_DIR):

• If $ARGUMENTS is a 3-digit number (e.g., 119): search agile/epics/ for a directory starting with that number
• If $ARGUMENTS is a path: use it directly
• If no argument: scan agile/epics/ for directories containing design.md with status APPROVED but no plan.md
• If exactly one candidate found, use it. If multiple, use AskUserQuestion to let the user choose (list epic names as options). If none, report error and stop.

2. Validate prerequisites (hard gates — exit if any fail):

• EPIC_DIR/design.md exists
• design.md contains **Status**: APPROVED
• design.md contains ## Feature Candidates section with >= 1 feature

If design.md not found: "Error: design.md not found at [path]. Run /agile-epic-brainstorm first." Stop. If status is not APPROVED: "Error: design.md status is [status], expected APPROVED." Stop. If Feature Candidates missing: "Error: design.md has no Feature Candidates section. Run /agile-epic-brainstorm to add features." Stop.

3. Advisory: warn if Feature Candidates count > 30 (suggest splitting the epic)

4. Read design.md thoroughly — extract all sections:

• Problem Statement, Success Criteria, Constraints & Risks
• Dependencies, Chosen Approach + rationale, Technical Direction
• Feature Candidates table (ID NNN-XX, name, description)

5. Load constitutions:

• .agile/rules/constitution.md (master)
• Domain constitutions based on detected modules (e.g., services, workers, frontend)

6. Load CLAUDE.md from project root for conventions

Phase 1.5: Verify Design Accuracy (CRITICAL)

This phase verifies the design.md accurately reflects the current codebase state. This prevents generating epic artifacts for problems that no longer exist.

Pre-Flight Verification Steps

1. Parse design.md for verification triggers:

• Extract mentioned module(s) from Problem Statement, Technical Direction, Feature Candidates
• Extract claimed error counts from Problem Statement
• Extract mentioned file paths from Feature Candidates

2. Run current build to get baseline:

   mvn clean compile -pl <module> 2>&1 | tee /tmp/plan-verify.log
   

   Count errors: grep -c "error:" /tmp/plan-verify.log || echo "0"

3. Verify file existence:

• For each file path mentioned in design.md, use Glob to verify it exists
• If files are missing, note them in the verification report

4. Compare current state to design claims:

| Comparison                           | Action                         |
|--------------------------------------|--------------------------------|
| Build fails with similar error count | PROCEED                        |
| Build fails but error count differs  | Note discrepancy in plan.md    |
| Build passes (no errors)             | STOP - Present options to user |

5. Report to user:

   ## Pre-Flight Verification Report
   
   | Check          | Status                | Details          |
   |----------------|-----------------------|------------------|
   | Build Status   | FAIL / PASS           | X errors found   |
   | Design Claimed | Y errors              | Difference: Z    |
   | File Existence | ALL FOUND / X MISSING | Missing: file.kt |
   
   

   Use AskUserQuestion to present options:

   • Question: "Pre-flight verification complete. How should we proceed?"
   • Options: ["Proceed with planning (scope may need adjustment)", "Stop — re-verify problem exists", "Adjust scope based on current state"]

If build passes entirely: Use AskUserQuestion:

• Question: "Pre-flight check: The module compiles successfully. The epic's stated objectives may already be achieved. Should we verify the scope before proceeding?"
• Options: ["Verify scope — check if epic is still needed", "Proceed anyway — the problem exists beyond build errors", "Abort planning"]

This is the critical defense against Epic 124-style failures.

Phase 2: Interactive Planning

This phase is collaborative — the plan is refined through conversation with the user.

1. Read templates/plan-template.md from this skill's directory

2. Draft a plan.md proposal based on design.md content:

• Strategic Overview: Synthesize from Problem Statement + Chosen Approach
• Architecture Decisions: Extract key technical decisions from design.md Technical Direction
• Phasing: Group Feature Candidates into logical phases based on dependencies
• Dependencies: Map inter-feature dependencies from design.md
• Risk Assessment: Extract from Constraints & Risks, map to specific features
• Constitution Compliance: List applicable master + domain principles
• Service Interaction Flow (optional): If design.md mentions business process logic, workflows, sagas, or references multiple bounded contexts, include a step-by-step interaction table showing API calls, event emissions, and data store interactions for the primary workflow. Omit for scaffold, infrastructure, or single-service epics — mark as "N/A".
• Service Dataflow (optional): If design.md mentions cross-domain data exchange, Kafka events, saga patterns, or complex transformation chains, include an ASCII L1 data flow diagram and flow inventory table documenting source, destination, pattern, payload, and error handling. Omit for simple CRUD or single-domain epics — mark as "N/A".

3. Present the draft plan to the user for review:

• Show the full plan.md content
• Use AskUserQuestion to ask: "Does this plan capture the right strategy? Would you like to adjust phasing, decisions, or risk assessments?"
  • Provide options: ["Approve plan as-is", "Adjust phasing", "Adjust architecture decisions", "Adjust risk assessment", "Other feedback"]

4. Refine based on user feedback:

• Iterate until the user selects "Approve plan as-is"
• Each iteration: apply user feedback, present updated draft, then use AskUserQuestion again with the same options
• Track what changed between iterations

Phase 3: Write plan.md

1. Write the approved plan to EPIC_DIR/plan.md

If write fails: Report the error and stop. Do not proceed to Phase 4.

Phase 4: Checkpoint

1. Use AskUserQuestion to present options:

• Question: "plan.md is ready. How would you like to proceed?"
• Options: ["Continue — generate epic.md and feature artifacts", "Clear context and continue — clear context window first, then re-invoke from Phase 5", "Done for now — commit plan.md and stop here"]

If user selects "Done for now", commit plan.md and exit:

docs(agile): add strategic plan for NNN-epic-name

Phase 5: Generate epic.md

1. Read templates/epic-template.md from this skill's directory

2. Fill template with content from design.md and approved plan.md:

• Epic metadata: ID, created date, status PLANNING, **DevOps ID**: (empty)
• Overview from Problem Statement
• Business Justification
• Architecture Context from Technical Direction
• Key Decisions from plan.md Architecture Decisions
• Epic Breakdown table — one row per Feature Candidate with NNN-XX numbering (2-digit)
  • Feature IDs from design.md Feature Candidates table (e.g., 121-01, 121-02)
  • If design.md used placeholder NNN-XX, replace NNN with actual epic number
• Parallelization Analysis (Parallelization Opportunities table + Dependency Matrix)
• Risk Mitigation from plan.md Risk Assessment
• Constitution Compliance (master + domain principles)
• Timeline Summary
• Success Criteria

3. Generate the Feature Workflow ASCII DAG (CRITICAL — canonical dependency source for agile:epic:implement)

   Build the Feature Workflow diagram from the dependency data in the Epic Breakdown table and plan.md Dependencies section. This diagram is the canonical dependency source — the implement skill parses it to build execution waves.

   Generation algorithm:

   a. Build a feature dependency graph from the Dependencies column of the Epic Breakdown table. b. Assign features to phases using the Phase groupings from plan.md and the Epic Breakdown table headers. c. Within each phase, identify sequential chains (feature A depends on feature B in the same phase) and parallel groups (features with [P] / Parallel=Yes and no intra-phase dependency). d. Render the ASCII diagram using the template format:

                   ┌──────────┐      ┌──────────┐
   Phase [A]       │NNN-01    ├─────▶│NNN-02    │
                   └─────┬────┘      └────┬─────┘
                         │                │
                   ┌─────▼────┐      ┌────▼─────┐
   Phase [B]       │NNN-03 [P]│      │NNN-04 [P]│
                   └─────┬────┘      └────┬─────┘
                         └───────┬────────┘
                            ┌────▼─────┐
   Phase [C]                │NNN-05    │
                            └──────────┘
   

   Rendering rules:

   • Each feature is a box: ┌──────────┐ │NNN-XX │ └──────────┘
   • Append [P] inside the box for parallel features: │NNN-XX [P]│
   • Sequential dependency: horizontal arrow ├─────▶│ between boxes on the same line
   • Cross-phase dependency: vertical arrow ┬ / ▼ between lines
   • Fan-in: multiple vertical lines converging with └───────┬────────┘ into one ▼
   • Phase labels on the left margin: Phase [A], Phase [B], etc.

   Consistency rule: Every edge in the diagram MUST correspond to an entry in the Dependencies column of the Epic Breakdown table, and vice versa. If a feature lists Dependencies: NNN-01, NNN-02, the diagram must show arrows from both NNN-01 and NNN-02 to that feature.

4. Generate the Dependency Matrix (if epic has cross-phase dependencies or >5 features):

   Build the ## Dependency Matrix table from the same dependency data:

   | Feature | Depends On     | Enables     | Notes       |
   |---------|----------------|-------------|-------------|
   | NNN-01  | None           | NNN-02      | [Any notes] |
   | NNN-02  | NNN-01         | NNN-03      | [Any notes] |
   

   The Enables column is the inverse of Depends On — computed by reversing all edges.

5. Write to EPIC_DIR/epic.md

If write fails: Report the error and stop. Do not proceed to Phase 6.

Phase 6: Generate Feature Specifications & Tasks

For each feature from design.md's Feature Candidates:

Feature Directory & Spec

1. Create feature directory: EPIC_DIR/NNN-XX-feature-name/

• Numbering: 2-digit feature sequence — use the NNN-XX ID from design.md Feature Candidates table
• If design.md doesn't provide explicit IDs, call scripts/next-feature-number.sh --epic NNN for the first feature, then increment sequentially
• Name: kebab-case from Feature Candidate name

2. Read templates/spec-template.md from this skill's directory

3. Fill template with:

• Feature metadata: branch name NNN-XX-feature-name, created date, status PENDING, **DevOps ID**: (empty)
• User Scenarios: 2-3 user stories with NNN-XX-U{n} IDs (e.g., 121-01-U1, 121-01-U2)
  • Each story includes metadata: Story Points, Priority, Risk, Effort, and **DevOps ID**: (empty) — left blank for later backfill by /devops-workitem push
  • Each story in Given/When/Then format derived from design.md + feature description
  • Story numbering: start at U1 for each feature, increment sequentially
• Requirements: FR-001, FR-002... from design.md scope
• Success Criteria (checkboxes)
• Constitution Compliance per feature

4. Write to EPIC_DIR/NNN-XX-feature-name/spec.md

Feature Tasks

1. Read templates/tasks-template.md from this skill's directory

2. Fill template with:

• Task IDs using full prefix: NNN-XX-T{nn} (e.g., 121-01-T01, 121-01-T02)
  • Call scripts/next-task-number.sh --epic NNN --feature XX if appending to existing tasks
  • For new features, start at T01
• 6-state markers: All tasks start as [ ] (pending)
• Dependency notation: Use :[NNN-XX-T{nn}] between task ID and description where dependencies exist
• Cross-feature dependency notation: Use :[NNN-YY-T{nn}] (where YY ≠ XX) for tasks that depend on tasks in other features. Also document these in the **Cross-Feature Dependencies**: header field.
• User story references: map tasks to NNN-XX-U{n} story IDs from spec.md
• Organize by phase: Setup → Foundation → User Stories → Polish
• Include Story Point Summary referencing NNN-XX-U{n} IDs

3. Generate the Tasks Workflow ASCII DAG (CRITICAL — canonical task dependency source for agile:epic:implement)

   Build the Tasks Workflow diagram from the task list, showing User Story groupings with sequential gates and intra-story task dependencies. This diagram is parsed by the implement skill to build per-feature execution plans.

   Generation algorithm:

   a. Group all tasks by their User Story label (NNN-XX-U{n}). Tasks without a story label (Setup/Foundation phases) belong to an implicit U0 group. b. Order User Stories sequentially: U0 → U1 → U2 → ... These form sequential gates — all tasks in U{n} must complete before any task in U{n+1} can start. c. Within each User Story, build a mini-DAG from :[deps] markers and [P] flags:

   • Tasks with no deps and no [P] → sequential from top to bottom
   • Tasks with [P] and no deps → parallel (independent, no edges between them)
   • Tasks with :[dep] → edge from dep to this task d. Render the ASCII diagram using the template format:

   ┌─────────────────────────────────────────────────────────────────────────────┐
   │                                  NNN-XX-U0                                  │
   │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐         │
   │ │NNN-XX-T01    │ │NNN-XX-T02 [P]│ │NNN-XX-T03 [P]│ │NNN-XX-T05    │         │
   │ └──────┬───────┘ └──────────────┘ └──────────────┘ └──────┬───────┘         │
   │        │                                                  │                 │
   │ ┌──────▼───────┐                                   ┌──────▼───────┐         │
   │ │NNN-XX-T04    │                                   │NNN-XX-T06    │         │
   │ └──────────────┘                                   └──────────────┘         │
   │                                                                             │
   │ ┌──────────────┐ ┌──────────────┐                                           │
   │ │NNN-XX-T07 [P]│ │NNN-XX-T08 [P]│                                           │
   │ └──────────────┘ └──────────────┘                                           │
   └──────────────────────────────────────┬──────────────────────────────────────┘
                                          │
   ┌──────────────────────────────────────▼──────────────────────────────────────┐
   │                                  NNN-XX-U1                                  │
   │  ...tasks...                                                                │
   └─────────────────────────────────────────────────────────────────────────────┘
   

   Rendering rules:

   • Each User Story is a large box with its ID as the title (centered)
   • Sequential gate between stories: vertical arrow ┬ / ▼ between story boxes
   • Within a story, each task is a small box: ┌──────────────┐ │NNN-XX-T{nn} │ └──────────────┘
   • Append [P] inside the box for parallel tasks: │NNN-XX-T02 [P]│
   • Dependency edges within a story: vertical arrow ┬ / ▼ from source to target
   • Independent parallel tasks: placed side-by-side with no arrows between them
   • Cross-feature deps: NOT shown in the diagram (they are in the header field and :[deps] notation)

   Consistency rules:

   • Every :[dep] marker on a task line MUST have a corresponding arrow in the diagram (and vice versa)
   • Every User Story from spec.md MUST appear as a story box in the diagram
   • The story ordering in the diagram MUST match the priority ordering in spec.md (P1 first)
   • Tasks in Setup/Foundation phases (no story label) are grouped under an implicit U0 box

4. Write to EPIC_DIR/NNN-XX-feature-name/tasks.md

Epic Checklist

1. Read templates/checklist-template.md from this skill's directory

2. Fill template with:

• Epic metadata
• Constitution Compliance items (master + domain)
• Feature Completion Gates table — one row per feature with NNN-XX references
• Cross-Cutting Verification items (build, testing, code quality, documentation)

3. Write to EPIC_DIR/checklist.md

Phase 7: Cross-Artifact Consistency Analysis

After all artifacts are generated, perform a mechanical consistency check across the entire epic structure. This replaces ad-hoc quality scoring with deterministic, cross-referencing analysis that catches misalignments before they propagate into implementation.

7.1 Build Semantic Models

Build internal representations from the freshly generated artifacts. These models drive mechanical detection rather than subjective judgment. Do not include raw model data in the output.

A. Requirements Inventory (from each feature spec.md):

• Extract each functional requirement (FR-XXX) and non-functional requirement (NFR-XXX)
• Generate a stable slug from the imperative phrase (e.g., "Remove Lombok annotations" -> remove-lombok-annotations)
• Tag each with: feature ID, type (functional/non-functional), user story parent (NNN-XX-U{n})

B. Task Coverage Map (from each feature tasks.md):

• Extract each task with its ID, description, phase grouping, and marker state
• Map each task to one or more requirements by:
  1. Explicit FR-XXX references in the task description
  2. Keyword matching against requirement slugs
  3. File-path overlap with plan components
• Flag tasks mapping to zero requirements as "orphan tasks"
• Flag requirements mapping to zero tasks as "uncovered requirements"

C. Constitution Rule Set (from loaded constitutions):

• Extract principle IDs (MASTER:I, SERVICES:II, etc.)
• Classify normative statements as MUST, SHOULD, or MAY
• Build checklist of applicable rules per feature based on domain scope

D. Epic-Wide Composition:

• Merge all per-feature inventories into epic-wide sets for cross-feature detection

7.2 Severity Classification

All findings use deterministic heuristic rules:

Level	Classification Rule
CRITICAL	Constitution MUST violation; missing core artifact; epic requirement with zero feature coverage; circular dependency
HIGH	Duplicate or conflicting requirement; ambiguous security/performance attribute; interface mismatch; constitution SHOULD violation
MEDIUM	Terminology drift between artifacts; missing non-functional task coverage; underspecified edge case; missing constitution principle in checklist
LOW	Style/wording improvements; minor redundancy; cosmetic inconsistency; stale references

Precedence: Constitution violation > Functional gap > Documentation gap > Cosmetic.

7.3 Finding Categories

Each finding gets a category prefix for stable identification:

Prefix	Category	Description
D-	Duplication	Near-duplicate requirements within or across features
A-	Ambiguity	Vague adjectives without measurable criteria; unresolved placeholders
U-	Underspecification	Requirements with verbs but missing object or measurable outcome
G-	Coverage Gap	Requirements with zero task coverage; orphan tasks
I-	Inconsistency	Terminology drift; conflicting definitions; ordering contradictions
K-	Constitution	Principle violations (MUST -> CRITICAL; SHOULD -> HIGH)

Finding cap: 100 findings max. Aggregate overflow as summary count.

7.4 Analysis Passes

Execute these passes sequentially using the semantic models:

Pass 1: Feature Specs vs Epic Plan

• Architecture alignment: feature approach matches epic architecture decisions
• Module boundaries: feature stays within designated modules
• Naming conventions: all identifiers follow MASTER:V (no abbreviations)
• [D-] Near-duplicate requirements across feature specs (same verb+object, different wording)
• [A-] Vague adjectives (fast, scalable, secure) lacking measurable criteria; unresolved placeholders (TODO, TBD)

Pass 2: Feature Interdependencies & Dependency Graph Integrity

• Dependency completeness: every dependency in tasks.md acknowledged bidirectionally
• Shared entity consistency: same entities across features have identical definitions
• No circular dependencies: verify the dependency graph is a DAG
• [G-] Epic requirements not covered by any feature; per-feature requirements with zero tasks
• [I-] Terminology drift: same concept named differently across specs
• [U-] Requirements with verbs but no measurable outcome

Pass 2b: Feature Workflow DAG Consistency (NEW — validates diagram-to-table synchronization)

• [I-] Feature Workflow diagram edge not in Dependencies column: diagram shows NNN-01 → NNN-02 but table says "None"
• [I-] Dependencies column entry not in Feature Workflow diagram: table says "NNN-01" but no arrow from NNN-01 in diagram
• [I-] Phase assignment mismatch: feature is in Phase [A] heading but diagram shows it in Phase [B] row
• [I-] Parallel flag mismatch: table says Parallel=Yes but diagram box has no [P] marker (or vice versa)
• [I-] Dependency Matrix Depends On / Enables inconsistency with diagram edges
• [K-] Circular dependency detected in Feature Workflow DAG (CRITICAL — blocks implementation)

Pass 3: Constitution Compliance

• Master principles (MASTER:I through MASTER:V) applied to every artifact
• Domain principles applied based on each feature's module scope
• [K-] Tag each violation with principle ID and MUST/SHOULD classification

Pass 4: Tasks vs Spec Alignment

• User story coverage: every user story (NNN-XX-U{n}) has implementing tasks
• Acceptance criteria coverage: every acceptance criterion has a test task
• Story point consistency: estimates match between spec and tasks summary
• Task ordering: dependencies respected, foundational tasks precede story tasks

Pass 4b: Tasks Workflow DAG Consistency (NEW — validates task diagram-to-markers synchronization)

• [I-] Tasks Workflow diagram shows edge T01→T04 but task T04 has no :[NNN-XX-T01] dep marker (or vice versa)
• [I-] Task in diagram has [P] but task line does not (or vice versa)
• [I-] User Story box in diagram contains task not labelled with that story ID in the task list
• [I-] User Story from spec.md missing from Tasks Workflow diagram
• [I-] Story order in diagram doesn't match priority order in spec.md (P1 should be U1, etc.)
• [G-] Cross-feature dep :[NNN-YY-T{nn}] references a task ID that doesn't exist in feature YY's tasks.md
• [K-] Circular dependency detected within a User Story's task DAG (CRITICAL — blocks implementation)
• [I-] User Story sequential gate violated: task in U{n+1} has no implicit dependency on U{n} completion

Pass 5: Status & Metadata Consistency

• All spec.md Status fields are PENDING (freshly generated)
• Epic.md status is PLANNING
• Feature IDs in epic.md breakdown table match actual feature directory names
• Checklist items reference correct feature IDs
• No duplicate **FieldName**: metadata headers (template copy-paste artifacts)

7.5 Present Analysis Results

Present the analysis summary to the user:

## Analysis Summary

| Severity | Count | Categories |
|----------|-------|------------|
| CRITICAL | N     | [prefixes] |
| HIGH     | N     | [prefixes] |
| MEDIUM   | N     | [prefixes] |
| LOW      | N     | [prefixes] |

## Coverage Summary

| Feature | FRs | Tasks | Coverage % | Uncovered | Orphan Tasks |
|---------|-----|-------|------------|-----------|--------------|
| NNN-01  | N   | N     | N%         | N         | N            |

Then list each finding with its category prefix, severity, location, and description.

If 0 findings: "All artifacts are internally consistent. Proceeding to commit." If findings exist: Proceed to Phase 8 (Remedy). If CRITICAL only: Flag as blocking -- must remedy before commit.

Phase 8: Remedy Misalignments

This phase auto-fixes detected findings from Phase 7. Since all artifacts were just generated by this same skill invocation, the fixes are applied immediately without interactive approval -- the artifacts are fresh and not yet committed, so there is no risk of overwriting user work.

8.1 Fix Strategy by Category

Category	Fix Strategy
I- (Inconsistency)	Determine authoritative source (plan.md > epic.md for architecture; epic.md > spec.md for scope). Edit non-authoritative artifact to match.
I- (Diagram mismatch)	Regenerate the diagram from the authoritative dependency data (Dependencies column for features, :[deps] for tasks). The diagram must match the data — never edit the data to match a diagram.
G- (Coverage Gap)	For uncovered requirements: add tasks using patterns from sibling tasks in the same file. For orphan tasks: add corresponding FR to spec.md.
G- (Cross-feature ref)	For invalid cross-feature dep references: verify the target feature's tasks.md exists and contains the referenced task ID. If not, remove the dep or fix the task ID.
K- (Constitution)	Add missing principle entries using format of existing entries as template.
K- (Circular dep)	CRITICAL. Cannot auto-fix — report the cycle path. User must restructure dependencies in plan.md and regenerate.
D- (Duplication)	Keep higher-quality phrasing (more specific, measurable). Remove the duplicate.
A- (Ambiguity)	Replace vague adjectives with measurable criteria derived from plan.md context. Fill unresolved placeholders.
U- (Underspecification)	Add missing measurable outcomes from plan.md verification or tasks.md acceptance criteria.

8.2 Apply Fixes

For each finding, in severity order (CRITICAL first):

1. Read the target file
2. Apply the fix using the Edit tool
3. Log: [FIXED] [ID]: [one-line summary]
4. If edit fails: log [FAILED] [ID]: [reason] and continue

8.3 Re-Verify

After all fixes are applied, re-run the analysis passes (Phase 7.4) on the corrected artifacts. If new findings emerge from the fixes, report them but do not enter a second remedy loop.

8.4 Present Remedy Results

## Remedy Summary

Applied: N fixes
Failed: M fixes
Remaining: P findings (if any)

Files modified:
- EPIC_DIR/epic.md
- EPIC_DIR/125-01-feature-name/spec.md
- ...

If CRITICAL findings remain after remedy, use AskUserQuestion to present options:

• Question: "CRITICAL findings remain after auto-remedy. How should we proceed?"
• Options: ["Fix manually — I'll provide guidance for each finding", "Proceed anyway — commit with known issues", "Abort — do not commit, I'll re-run planning"]

Phase 9: Commit & Present

1. Archive design.md: change status from APPROVED to ARCHIVED

2. Git commit all generated artifacts + archived design.md:

   docs(agile): add epic structure for NNN-epic-name
   

3. Present summary:

• Features generated: N features across M phases
• Artifact count: plan.md, epic.md, checklist.md, N×(spec.md + tasks.md)
• Analysis results: N findings detected, M remedied, P remaining
• Coverage: overall requirement-to-task coverage percentage
• Reminder: "Run /devops:workitem push to register work items in Azure DevOps"

4. Use AskUserQuestion to present next-step options:
   • Question: "Epic NNN artifacts are committed. What would you like to do next?"
   • Options: ["Implement — invoke /agile:epic:implement NNN", "Refine — re-generate a specific artifact with feedback", "Done for now — end skill execution"]
   • If user selects "Refine", use AskUserQuestion to ask which artifact to refine (list the feature directories)

Key Principles

• Interactive planning — Phase 2 is collaborative: propose a plan draft, refine with the user until approved. This ensures strategic alignment before generating artifacts.
• Plan before epic — The strategic plan (plan.md) is created and approved before epic.md and feature artifacts. The plan guides all downstream generation.
• Design.md is the source of truth — All generated content traces back to decisions made in design.md. Reference with (see design.md).
• Templates are skill-owned — Read from templates/ in this skill's directory, not from .agile/templates/.
• 2-digit feature numbering — New epics use NNN-XX format (e.g., 121-01). Old epics with 3-digit (NNN-###) are not modified.
• Full-prefix task IDs — Every task ID carries the epic+feature prefix: NNN-XX-T{nn}.
• 6-state task markers — [ ] pending, [W] in-progress, [X] completed, [-] partial, [B] blocked, [S] skipped.
• One commit — All artifacts are committed atomically. No partial state (except Phase 4 early exit which commits plan.md alone).
• Analyse before commit — Phase 7 mechanically detects misalignments across all generated artifacts using semantic models and deterministic heuristics. Findings use stable category prefixes (D-, A-, U-, G-, I-, K-) for traceability.
• Auto-remedy fresh artifacts — Phase 8 fixes detected issues immediately since artifacts are not yet committed. No interactive approval needed for freshly generated content.
• Constitution is non-negotiable — MUST violations are always CRITICAL severity. SHOULD violations are HIGH.
• Workflow diagrams are canonical — The Feature Workflow DAG (epic.md) and Tasks Workflow DAG (tasks.md) are the canonical dependency sources for the downstream agile:epic:implement skill. The implement skill parses these diagrams to build execution waves and task execution plans. Therefore:
  • Every edge in a diagram MUST correspond to a dependency in the feature/task table (and vice versa).
  • The diagrams MUST be generated from the same dependency data as the tables — not manually drawn.
  • Phase 7 validates diagram-to-table consistency (Pass 2b and Pass 4b).
• User Story sequential gates — User Stories in tasks.md form sequential gates: all tasks in U{n} must complete before any task in U{n+1} can start. The Tasks Workflow DAG encodes this with arrows between story boxes. The implement skill enforces these gates during execution. Task dependencies (:[deps]) within a story define intra-story ordering; the story boundary defines inter-story ordering.
• Cross-feature task dependencies are explicit — When a task depends on a task in another feature, use the full cross-feature notation :[NNN-YY-T{nn}] and document it in the **Cross-Feature Dependencies**: header. The implement skill tracks these at dispatch time.

Scripts

Script	Location	Purpose	Inputs	Output
next-feature-number.sh	scripts/	Next 2-digit feature XX	--epic NNN	08
next-story-number.sh	scripts/	Next user story digit	--epic NNN --feature XX	3
next-task-number.sh	scripts/	Next 2-digit task nn	--epic NNN --feature XX	04

Skill Integrations

This skill is self-contained — epic directory resolution is handled inline in Phase 1. After completion, suggest the user invoke /agile:epic:implement NNN for implementation.

Templates

Template	File	Purpose
Epic plan	templates/plan-template.md	Epic strategic plan with phasing, dependencies, and decisions
Epic spec	templates/epic-template.md	Epic specification with NNN-XX feature breakdown + Feature Workflow ASCII DAG
Feature spec	templates/spec-template.md	Feature spec with NNN-XX-U{n} user stories
Feature tasks	templates/tasks-template.md	Task list with NNN-XX-T{nn} IDs, 6-state markers + Tasks Workflow ASCII DAG
Epic checklist	templates/checklist-template.md	Standalone epic-level verification gates

Workflow Diagram Templates

The templates contain example ASCII DAG diagrams that this skill MUST generate as part of artifact creation:

• epic-template.md ## Feature Workflow (L261-275): Shows how features connect across phases with dependency arrows, parallel markers, and fan-in points. Generated in Phase 5, Step 3 from the Epic Breakdown dependency data.

• tasks-template.md ## Tasks Workflow (L253-308): Shows how tasks are grouped by User Story with sequential gates (U0 → U1 → U2), intra-story dependency edges, and parallel markers. Generated in Phase 6, Feature Tasks Step 3 from the task list and :[deps] notation.

These diagrams are the canonical dependency sources consumed by agile:epic:implement. The implement skill parses them to build execution waves (feature-level) and task execution plans (task-level). Consistency between diagrams and tables is validated in Phase 7 (Pass 2b and Pass 4b).

Shared References

Module	Location	Purpose
Pre-Flight Verification	agile-epic-shared/verify/verify.md	Build and file verification procedures

Backward Compatibility

This skill generates artifacts in the new format only (2-digit features, full-prefix task IDs). Downstream skills that read these artifacts (agile:epic:implement, agile:epic:progress, etc.) must accept both old format (3-digit features, bare T001 IDs) and new format.

Terminal State

The terminal state is a committed set of epic artifacts (plan.md, epic.md, checklist.md, feature spec.md and tasks.md files). Do NOT invoke any implementation skill, task generation, or analysis skill automatically. The user will manually invoke the next pipeline step (/agile:epic:implement NNN) as suggested in Phase 9.