Imported from tmalcolm-0607/mad-council-claw (.claude/skills/mad-implement/SKILL.md). Install upstream with npx skills add tmalcolm-0607/mad-council-claw --skill mad-implement. Copyright stays with the author.

MAD: Implement

Execute the implementation plan by processing and executing all tasks defined in tasks.md.

Reference Files (load on demand, not by default):

Gate Enforcement (MANDATORY)

⚠️ CRITICAL WORKFLOW - MUST FOLLOW EXACTLY:

1. After EVERY phase completion → Run ALL quality gates
2. After gates pass → Create atomic commit
3. Before next phase → Verify commit exists in git log

DO NOT: Skip gates, batch multiple phases, or proceed without committing.

TDD Requirement (MANDATORY)

For each implementation task:

1. Write test first (if task has testable behavior)
2. Run ONLY that test → Verify it FAILS (proves test works)

   dotnet test tests/<Project>.Tests --filter "FullyQualifiedName~<TestClass>.<TestMethod>"

3. Implement code
4. Run ONLY that test → Verify it PASSES
5. Run the test class → Verify no sibling regressions

   dotnet test tests/<Project>.Tests --filter "FullyQualifiedName~<TestClass>"

DO NOT: Run dotnet test src/consumer-project.sln during TDD cycles. Full solution runs are for phase gates ONLY. DO NOT: Write implementation without corresponding tests, skip failing test verification.

TDD Advisory Hook Integration

The TDD Advisory hook (.claude/hooks/tdd-advisory.js) provides automated reminders when source files are modified without recent test changes. This hook complements the mandatory TDD requirement above.

How it works:

• Monitors Write and Edit tool calls on source files (.cs, .ts)
• Emits a non-blocking advisory if no test file was modified within the last 10 tool uses or 5 minutes
• One advisory per source file per session (no repeated warnings)
• Excludes .tsx files, test files, documentation, and configuration

When following TDD correctly, the advisory never fires because:

1. You write/update the test first (step 1 above) -- this satisfies the recency check
2. You then modify the source file (step 3 above) -- no advisory because test was recently modified

Feature flag: Set TDD_ADVISORY_ENABLED=false in .claude/settings.local.json to disable.

Cross-references:

• Hook: .claude/hooks/tdd-advisory.js
• Rule: .claude/rules/test-discipline.md (TDD workflow and test failure protocol)

Phase Checkpoint Protocol (MANDATORY)

At the END of each phase, you MUST:

1. Mark all phase tasks as [X] in tasks.md
2. Run: [BUILD_COMMAND from CLAUDE.md] → Paste output
3. Run: [TEST_COMMAND from CLAUDE.md] → Paste output (must show pass count)
4. Run: [LINT_COMMAND from CLAUDE.md] → Paste output
5. Create commit: git add . && git commit -m "feat: complete phase N - description"
6. Verify: git log --oneline -n 1 → Paste commit hash
7. Report: Phase N Gate Summary table
8. ONLY THEN proceed to next phase

Gate Commands: Read from project's CLAUDE.md "Quality Gates" section and use the canonical runner entrypoint (powershell -File .claude/scripts/Run-DotnetGates.ps1).

If tests fail: STOP → fix → re-run ONLY the failing test with --filter → after fix passes, run affected test project → then re-run ALL gates once. If build/lint fail: STOP → fix → re-run ALL gates.

Usage

/mad-implement                        # Execute all tasks in tasks.md (auto-detects plan files)
/mad-implement --phase 2              # Execute specific phase only
/mad-implement --dry-run              # Show tasks without executing
/mad-implement --bypass               # Skip permission prompts (quality gates still run)
/mad-implement <plan-file>            # Convert plan mode file and implement
/mad-implement <plan-file> --full     # Convert using full workflow
/mad-implement <plan-file> --bypass   # Convert and implement with bypass mode

Plan Mode Support: Automatically detects and converts plan mode files (from EnterPlanMode) to MAD artifacts before implementation. Simply provide the plan file path as an argument, or call /mad-implement without arguments to auto-detect plan files in .claude/plans/.

Bypass Mode: Use --bypass flag to skip permission prompts for file creation, package installation, and git operations. Quality gates (tests, build, lint) remain mandatory and blocking. Bypass mode streamlines the plan → implementation workflow by reducing interruptions for non-critical decisions.

DAG Execution: Set DAG_EXECUTION_MODE in .claude/settings.local.json to change execution strategy. See "DAG Execution Mode" section below for details.

Overview

This skill orchestrates the complete implementation workflow, executing tasks phase-by-phase with proper dependency management, validation checkpoints, and quality gates. It ensures all tasks are completed according to the plan while maintaining code quality and architecture compliance.

DAG Support: Optionally supports wave-based parallel execution via DAG_EXECUTION_MODE environment variable. Classic phase-by-phase execution remains the default. See "DAG Execution Mode" section for details.

Execution Flow

0. Work Item Check (MANDATORY - enables artifact routing): a. Read .claude/work-items/sessions/${CLAUDE_SESSION_ID:-default} to check for active work item b. If the session pointer is empty or missing:
   • WARN: "No active work item. Agent outputs will go to .mad/scratch/"
   • WARN: "Run /work-item create or /mad-spec to enable tracking"
   • ASK: "Continue without tracking? [y/N]"
   • If user declines, halt execution c. If ACTIVE contains a work item ID:
   • Verify the work item directory exists at .claude/work-items/<ID>/
   • All agent outputs will route to artifacts/ subdirectories:
     • code-investigator → artifacts/investigation/
     • code-implementer → artifacts/implementation/
     • code-reviewer → artifacts/review/
     • feature-verifier → artifacts/verification/ d. When spawning agents, include in prompt:

   **Work Item**: <ACTIVE work item ID>
   **Output**: .claude/work-items/<ID>/artifacts/<type>/<filename>.md
   

0.5. Plan Mode Detection (Automatic Conversion):

Check if user provided a plan mode file instead of MAD artifacts:

a. Check command arguments: - If user provided a file path argument (e.g., /mad-implement .claude/plans/feature.md) - Parse the path to check if it's a plan mode file

b. Detect plan mode file: - Pattern: Path contains .claude/plans/ OR ends with -plan.md - Verify file exists and is readable - If NOT a plan mode file → Continue to Step 1 (normal flow)

c. If plan mode file detected: - Display: "Plan mode file detected: [filename]" - Display: "Converting to MAD artifacts before implementation..." - Invoke /made-from-claude-plan <path> (use --full flag if user specified it) - Wait for conversion to complete - Verify MAD artifacts were created in specs/<N>-<feature>/ - Continue to Step 1 with the newly created artifacts

d. If no arguments provided:

  **First**: Check for existing MAD artifacts: `specs/<N>-<feature>/plan.md` and `tasks.md`
  - If artifacts exist → Continue to Step 1 (normal flow)

  **Second**: If no MAD artifacts found, scan `.claude/plans/` for plan files:

  ```javascript
  // Auto-detection function
  function detectCurrentPlanFile() {
    const plansDir = '.claude/plans/';
    if (!fs.existsSync(plansDir)) return null;

    const planFiles = glob.sync(`${plansDir}*.md`);
    if (planFiles.length === 0) return null;
    if (planFiles.length === 1) return planFiles[0];

    // Multiple files - return most recent
    return planFiles.sort((a, b) => {
      const statA = fs.statSync(a);
      const statB = fs.statSync(b);
      return statB.mtime - statA.mtime;
    })[0];
  }
  ```

  **If exactly one plan file found**:
  1. Extract feature name and summary from plan file
  2. Check file age: warn if older than 7 days
  3. Prompt user via AskUserQuestion:
     - Header: "Plan Detected"
     - Question: "Found plan file: `<filename>` (created <date>). Convert to MAD artifacts and implement?"
     - Options:
       - "Yes (auto-start ~30s)" → Invoke `/made-from-claude-plan <path>`
       - "Full workflow (~3-5min)" → Invoke `/made-from-claude-plan <path> --full`
       - "No, provide MAD artifacts manually" → Exit with guidance
  4. After conversion completes → Continue to Step 1

  **If multiple plan files found**:
  1. List all plan files with timestamps and descriptions
  2. Prompt user to select which plan to use:
     - Show: filename, age, first line (description)
     - Allow: select file or cancel
  3. After selection → Same prompt as single file above

  **If no plan files found**:
  - ERROR: "No MAD artifacts or plan files found. Options:"
  - "1. Run /mad-spec to create MAD artifacts"
  - "2. Create plan with EnterPlanMode and save to .claude/plans/"
  - "3. Provide plan file path as argument: /mad-implement <path>"

Example usage:

# Automatic conversion from plan mode
/mad-implement .claude/plans/user-preferences.md

# With full workflow mode
/mad-implement .claude/plans/user-preferences.md --full

# Normal flow (MAD artifacts already exist)
/mad-implement

# With bypass mode (skip permission prompts)
/mad-implement --bypass
/mad-implement .claude/plans/feature.md --bypass

0.6. Bypass Mode Detection (Optional Streamlined Workflow):

Check if --bypass flag was provided as an argument.

If bypass mode enabled:

• Skip permission prompts for:
  • File creation (new source files, test files, configuration files)
  • Package installation (npm install, dotnet add package)
  • Git operations (branch creation, commits, pushes - except destructive operations)
• DO NOT skip:
  • Quality gates (tests, build, lint, coverage) - these remain mandatory and blocking
  • User confirmation for destructive operations (force push, delete branches, rm -rf)
  • Error handling and validation
  • AskUserQuestion for critical decisions (architecture choices, approach selection)

Integration with AskUserQuestion:

• In bypass mode, skip non-critical questions (e.g., "Create this file?", "Install this package?")
• Always prompt for critical decisions (e.g., "Multiple implementation approaches available, which one?")
• Always prompt for destructive operations (e.g., "Delete existing branch?", "Force push?")

Safety notes:

• Bypass mode is designed for streamlined plan → implementation workflow
• Quality remains enforced through mandatory gates
• Use when you trust the plan and want to reduce interruptions
• If unsure, omit --bypass flag and receive prompts for each operation

1. Orientation & Context Loading:

   • Run git status and git log --oneline -n 5 to understand recent changes.
   • Worktree Check (REQUIRED for feature work):
     • Run git worktree list to check if worktrees exist
     • If implementing a feature and NOT in a worktree:
       • WARN: "Feature work should be in a worktree. Create one?"
       • Suggest: git worktree add C:/repos/[project]-[feature] -b feature/[name]
     • If in a worktree, verify ALL subsequent commands use the worktree path
     • CRITICAL: /pr-review and commits MUST run from worktree, not main repo
   • Run .claude/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Check checklists status (if FEATURE_DIR/checklists/ exists):

   • Scan all checklist files in the checklists/ directory

   • For each checklist, count:

     • Total items: All lines matching - [ ] or - [X] or - [x]
     • Completed items: Lines matching - [X] or - [x]
     • Incomplete items: Lines matching - [ ]

   • Create a status table:

     | Checklist | Total | Completed | Incomplete | Status |
     |-----------|-------|-----------|------------|--------|
     | ux.md     | 12    | 12        | 0          | ✓ PASS |
     | test.md   | 8     | 5         | 3          | ✗ FAIL |
     | security.md | 6   | 6         | 0          | ✓ PASS |

   • Calculate overall status:

     • PASS: All checklists have 0 incomplete items
     • FAIL: One or more checklists have incomplete items

   • If any checklist is incomplete:

     • Display the table with incomplete item counts
     • STOP and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
     • Wait for user response before continuing
     • If user says "no" or "wait" or "stop", halt execution
     • If user says "yes" or "proceed" or "continue", proceed to step 3

   • If all checklists are complete:

     • Display the table showing all checklists passed
     • Automatically proceed to step 3

2.5. Determine Execution Strategy (DAG Mode Detection):

Read the DAG execution mode to determine how tasks will be orchestrated:

// Read from settings.local.json env block
const settings = JSON.parse(fs.readFileSync('.claude/settings.local.json', 'utf8'));
const mode = settings?.env?.DAG_EXECUTION_MODE || 'classic';

Mode Resolution (checked in order):

1. If DAG_EXECUTION_MODE env var is set in .claude/settings.local.json under env key -> use that value
2. Otherwise -> default to classic

Valid Modes: classic, dag-parse-only, dag-validate, dag-execute

Branch on Mode:

If mode is classic: No DAG library is loaded, no overhead. Proceed directly to Step 3.

If mode is NOT classic: After tasks are parsed in Step 5, execute Step 5.1 (DAG Orchestration) before proceeding to Step 6.

3. Load and analyze the implementation context:
   • REQUIRED: Read tasks.md for the complete task list and execution plan
   • REQUIRED: Read plan.md for tech stack, architecture, and file structure
   • IF EXISTS: Read data-model.md for entities and relationships
   • IF EXISTS: Read contracts/ for API specifications and test requirements
     • CRITICAL: If contracts exist, all generated modules MUST match defined interfaces exactly
     • Mock implementations MUST export the same methods as real implementations
     • Method names are case-sensitive and must match contracts
   • IF EXISTS: Read research.md for technical decisions and constraints
   • IF EXISTS: Read quickstart.md for integration scenarios

3.5. Load Applicable Patterns (Pattern Templates):

Before implementation begins, load patterns as code templates:

a. Read Pattern Compliance from plan.md: - Locate "## Pattern Compliance" section - If missing, check spec.md for "## Applicable Patterns" section - If neither exists, skip with note "No patterns specified"

b. Load Pattern Files: - For each pattern file referenced: - Read the pattern file from .claude/rules/patterns/ - Extract "## Correct" code examples as templates - Extract "## Anti-Patterns" as things to avoid - If pattern file not found, WARN and continue

c. Pattern Usage During Implementation: - When generating code, reference pattern "Correct" examples - Add comments linking to pattern file: // Per dotnet-architecture.md - Check generated code against "Anti-Patterns" before committing

Note: Pattern loading failures are WARNings, not errors. Implementation continues without patterns if files are missing.

4. Project Setup Verification:

   • Detect project type from marker files (*.csproj/*.sln → .NET, package.json → Node.js, pyproject.toml/requirements.txt → Python, go.mod → Go, Cargo.toml → Rust)
   • Verify toolchain available, restore dependencies (e.g., dotnet restore, npm install)
   • Check for Azure Artifacts feeds or private registries requiring authentication

   Ignore File Setup (REQUIRED):

   • Detect which ignore files are needed based on actual repo setup:
     • Git repo? → .gitignore
     • Docker? → .dockerignore
     • ESLint/Prettier? → respective ignore files or config ignores
     • Terraform/Helm? → .terraformignore/.helmignore
   • If exists: verify essential patterns present, append missing
   • If missing: create with technology-appropriate patterns

   Patterns: See ignore-patterns.md for full language and tool-specific pattern lists.

5. Parse tasks.md structure and extract:

   • Task phases: Setup, Tests, Core, Integration, Polish
   • Task dependencies: Sequential vs parallel execution rules
   • Task details: ID, description, file paths, parallel markers [P]
   • Execution flow: Order and dependency requirements

5.1. DAG Orchestration (non-classic modes only):

Skip this step entirely if mode is classic (determined in Step 2.5).

After parsing tasks in Step 5, apply the DAG execution strategy based on the mode.

Step 5.1a: Load DAG Executor

The DAG executor library at .claude/lib/dag-executor.js provides the executeDagWorkflow function:

const { executeDagWorkflow, ContextBudgetExceededError } = require('./.claude/lib/dag-executor.js');

Step 5.1b: Call executeDagWorkflow

Invoke the executor with parsed tasks and config:

const config = {
  mode,                    // From Step 2.5: 'dag-parse-only' | 'dag-validate' | 'dag-execute'
  contextThreshold: 0.85,  // Read from DAG_CONTEXT_THRESHOLD env var or use default
  dryRun: false,           // Set true for validation without execution
  taskExecutor: async (taskId) => {
    // Custom task execution logic
    // Return { taskId, success: boolean, duration: number, error?: string }
  },
  onWaveComplete: (waveNumber, waveResult) => {
    // Optional callback after each wave completes
    // Use for progress tracking, logging, phase gate checks
  }
};

try {
  const result = await executeDagWorkflow(tasks, config);
  // Handle result based on mode (see Step 5.1c)
} catch (err) {
  // Handle errors (see Step 5.1d)
}

Step 5.1c: Mode-Specific Behavior

dag-parse-only:

Result format:
{
  success: true,
  mode: 'dag-parse-only',
  message: 'dag-parse-only: DAG validated but not executed',
  waves: <number of waves>,
  conflicts: <number of file conflicts>,
  criticalPath: [array of task IDs on critical path]
}

Action:
1. Log wave count, conflicts, and critical path to user
2. Display: "DAG parse complete: {waves} waves, {conflicts} file conflicts"
3. Display critical path: "Critical path: {tasks} ({estimated duration})"
4. Continue to Step 6 with CLASSIC phase-by-phase execution

dag-validate:

Result format:
{
  success: true,
  mode: 'dag-validate',
  message: 'dag-validate: DAG validated but not executed',
  waves: <number of waves>,
  conflicts: <number of file conflicts>,
  criticalPath: [task IDs],
  resolutions: { serialize: {...}, moveToNext: {...} }
}

Action:
1. Display validation summary
2. If conflicts > 0:
   - Log each conflict with file path and affected task IDs
   - Display suggested resolutions (serialize or moveToNext)
3. Continue to Step 6 with CLASSIC phase-by-phase execution

dag-execute:

Before execution - dry run:
1. Call executeDagWorkflow(tasks, { ...config, dryRun: true })
2. Review result.waves array to see wave structure
3. Display: "{totalWaves} waves, {totalTasks} tasks, {conflicts} conflicts"
4. If conflicts detected, log serialization strategy

Real execution:
1. Call executeDagWorkflow(tasks, { ...config, dryRun: false })
2. Executor handles:
   - Wave-by-wave execution
   - File conflict serialization
   - Context budget checks after each wave
   - Agent Teams integration (if enabled)
3. Result format:
   {
     success: true,
     mode: 'dag-execute',
     totalWaves: <number>,
     completedWaves: <number>,
     totalTasks: <number>,
     completedTasks: <number>,
     failedTasks: [...],
     waveTimings: [{ waveNumber, duration, tasksExecuted }],
     duration: <total milliseconds>
   }
4. After all waves complete: proceed to Step 5.1c (Phase Gates)
5. Skip Step 6 (classic execution) — wave execution replaces it

Step 5.1c: Phase Gates with DAG Execute

When using dag-execute mode, phase gates run at phase boundaries (not after individual tasks):

Phase Detection:

• Parse task IDs to extract phase number (e.g., T010 → Phase 1, T020 → Phase 2)
• Or read phase annotations from tasks.md (if present)
• Group completed waves by phase

Gate Execution:

After all waves in Phase N complete:
1. Mark all tasks in Phase N as [X] in tasks.md
2. Run quality gates (build, test, lint) — same commands as classic mode
3. If gates pass:
   - Create atomic commit: "feat: complete Phase N - {description}"
   - Verify commit exists: git log --oneline -n 1
4. If gates fail:
   - STOP execution
   - Fix failures
   - Re-run gates before continuing to next phase
5. Proceed to next phase's waves

Example:

Phase 1 (Setup): Waves 1-2
  -> After Wave 2 completes: Run Phase 1 gates

Phase 2 (Implementation): Waves 3-5
  -> After Wave 5 completes: Run Phase 2 gates

Phase 3 (Integration): Waves 6-7
  -> After Wave 7 completes: Run Phase 3 gates

Gate commands are identical to classic mode (read from project CLAUDE.md "Quality Gates" section). Only the timing changes.

Step 5.1d: DAG Error Handling

Handle DAG-specific errors using try-catch around executeDagWorkflow call:

1. Cycle Detection:

catch (err) {
  if (err.message.includes('Cycle detected')) {
    // Parse cycle from error message
    // Display: "Cycle detected: T005 -> T008 -> T005"
    // Offer to fix tasks.md:
    //   - Remove one dependency edge
    //   - Or merge cyclic tasks into single task
    // If user declines: fall back to classic mode
    // If user accepts: re-parse and retry from Step 5.1b
  }
}

2. Context Budget Exceeded:

catch (err) {
  if (err instanceof ContextBudgetExceededError || err.name === 'ContextBudgetExceededError') {
    // HALT execution immediately
    // Generate handoff document:
    const handoffPath = `.claude/work-items/${workItemId}/PENDING_HANDOFF`;
    const handoffContent = `
    # DAG Execution Handoff

    ## Resume Point
    - Mode: dag-execute
    - Completed Waves: ${err.details.completedProgress.completedWaves}/${err.details.completedProgress.totalWaves}
    - Remaining Waves: ${err.details.remainingWaves}
    - Remaining Tasks: ${err.details.remainingTasks}

    ## Context Status
    - Usage: ${(err.details.usage * 100).toFixed(1)}%
    - Threshold: ${(err.details.threshold * 100).toFixed(1)}%

    ## Next Steps
    1. Start new session
    2. Run /resume-handoff
    3. Continue from Wave ${err.details.completedProgress.completedWaves + 1}
    `;
    // Write handoff to disk
    // Write PENDING_HANDOFF pointer
    // Tell user: "Context budget exceeded at {usage}%. Handoff created at {path}. Start new session with /resume-handoff"
  }
}

3. Wave Execution Failure:

catch (err) {
  if (err.message.includes('Wave') && err.message.includes('failed verification')) {
    // Parse failed wave and task IDs from error message
    // Display: "Wave N failed: tasks {taskIds}"
    // For each failed task:
    //   - Display error message from task result
    //   - Suggest targeted fix
    // Offer to re-run from failed wave (not from beginning)
  }
}

4. File Conflicts (dag-execute mode):

// Handled automatically by dag-executor.js
// Conflicts trigger serialize resolution
// Log which tasks were moved to later waves
// No user intervention needed unless serialization fails

5. Invalid Mode:

catch (err) {
  if (err.message.includes('Unknown execution mode')) {
    // Display: "Invalid DAG_EXECUTION_MODE: {mode}"
    // Valid modes: classic, dag-parse-only, dag-validate, dag-execute
    // Fall back to classic mode
  }
}

5.5. Investigation & Research Protocol (use when needed during implementation):

Rule: DO NOT implement directly when facing unknowns. Spawn agents instead.

Spawn code-investigator when: modifying unfamiliar code, task is vague about location, debugging unexpected behavior.

Spawn research pipeline (scout → curator → reviewer) when: domain questions arise, choosing between approaches, best practices unclear.

Agent output routes to artifacts/<type>/ under the active work item directory.

Agent Teams mode: If running under a team lead, spawn investigators as teammates using prompts from mad-full/spawn-prompts.md (Code Investigator / Research Scout sections). Multiple investigations on different topics can run in parallel.

Single-session mode: Spawn subagents sequentially via Task tool.

6. Execute implementation following the task plan:

   6.0. Parallel Implementation Mode Detection (Agent Teams):

   1. Read .claude/agent-teams-config.json
   2. Check: config.enabled == true AND config.phases["implement-parallel"] == "teams"
   3. Read .claude/settings.local.json → check env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS == "1"
      - If key missing → WARN: "Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.local.json env block. Add it to enable parallel implementation."
   4. Check: [P]-marked tasks exist in current phase
   5. IF all true → Execute TEAM VARIANT (6.0a below) for [P] tasks
   6. ELSE → Execute SEQUENTIAL VARIANT (6.0b below)
   7. ON FAILURE (team creation) → Log "WARN: Agent Teams unavailable for implement-parallel, falling back to sequential execution" → Execute sequential variant
   

   6.0a. Team Variant — Parallel Implementation for [P] tasks:

   When teams are enabled and [P]-marked tasks exist:

   Team Name: "implement-{feature-slug}"
   Teammates: 1 code-implementer per file-ownership group
   Plan Approval: YES (lead reviews plans before code changes)
   Lead: Coordinates file ownership, runs gates
   

   File Ownership Protocol:

   1. Parse [P] tasks from current phase in tasks.md
   2. Extract file paths from each task description
   3. Group tasks by disjoint file sets
   4. Verify no file appears in multiple groups
   5. If overlap detected → Log "WARN: File conflict between task groups, executing conflicting groups sequentially" → Execute overlapping groups sequentially, parallel groups in parallel

   Lead Responsibilities:

   • Review and approve/reject each teammate's implementation plan
   • Monitor for file ownership violations
   • Run quality gates after each teammate completes
   • When all teammates done: run full gate suite across all changes
   • If quality gates fail: identify which teammate's changes caused failure, re-execute sequentially

   After team variant completes → Proceed to phase checkpoint below.

   ---

   6.0b. Sequential Variant (existing behavior):

   • Phase-by-phase execution: Complete each phase before moving to the next
   • Respect dependencies: Run sequential tasks in order, parallel tasks [P] can run together
   • Within-phase parallelization (Agent Teams mode): If Agent Teams available AND phase has 2+ tasks marked [P] on different files: Spawn one teammate per parallel task group using the Phase Worker prompt from mad-full/spawn-prompts.md. Each teammate owns specific files (no overlapping file edits). Collect results before proceeding to dependent tasks.
   • Within-phase parallelization (Single-session mode): Execute [P] tasks sequentially — the [P] marker documents that they could run in parallel but won't in single-session.
   • TDD MANDATORY for service/API tasks:
     1. Before implementing a service method → Write unit test
     2. Run ONLY that test → Verify FAILS (no implementation yet)
     3. Implement the method
     4. Run ONLY that test → Verify PASSES
     5. Run the test class → Verify no sibling regressions
   • File-based coordination: Tasks affecting the same files must run sequentially
   • Phase checkpoint: Follow the Phase Checkpoint Protocol (see top of this skill)
   • DO NOT proceed to next phase until commit verified

6.1. Progressive Test Validation (Phase 5.5 — after task completion, before phase checkpoint):

Trigger: After all tasks in the current phase are marked [X] in tasks.md, BEFORE running the Phase Checkpoint Protocol.

Purpose: Invoke the test-selector agent to determine the minimum test scope needed, execute targeted tests for fast feedback, and log the checkpoint. This reduces phase validation time by up to 99% (1 second vs 1m 30s) for changes limited to Domain/Application layers.

Step 1: Spawn test-selector agent

Task tool: {
  "subagent_type": "general-purpose",
  "description": "Analyze changed files and select minimum test scope",
  "prompt": "You are the test-selector agent. Follow the protocol in .claude/agents/test-selector.md.

**Context**:
- Work Item: <ACTIVE work item ID>
- Phase just completed: Phase <N>
- Changed files since last commit: Run `git diff --name-only HEAD` to identify
- Output: Write your analysis to .claude/work-items/<ACTIVE>/artifacts/test-selections/<YYYYMMDD-HHMMSS>.md

**Your task**:
1. Run `git diff --name-only HEAD` to identify all changed files
2. Map changed files to test projects using the Test Impact Heuristic
3. Apply the 3-layer selection algorithm (naming convention, project reference, safety fallbacks)
4. Determine the appropriate validation tier (Tier 1-4)
5. Generate the recommended `dotnet test` command
6. Assign a confidence score (HIGH/MEDIUM/LOW)
7. Write your full analysis to the output path above

**Output format**: Follow the log template in .claude/agents/test-selector.md exactly."
}

Step 2: Read test-selector output

After the agent completes, read the markdown log from:

.claude/work-items/<ACTIVE>/artifacts/test-selections/<timestamp>.md

Parse the following fields:

• Recommended Command: The dotnet test command to execute
• Confidence: HIGH, MEDIUM, or LOW
• Tier: Which validation tier was selected (1-4)
• Estimated Time: Expected execution duration

Step 3: Execute recommended tests

Execute the selected command and capture output (examples: Tier 1: dotnet test tests/Domain.Tests tests/Application.Tests | Tier 3: add Infrastructure.Tests and Integration.Tests).

Step 4: Log the checkpoint

Record the progressive validation result in the implementation report:

### Progressive Validation Checkpoint — Phase <N>

| Field | Value |
|-------|-------|
| Phase | <N> |
| Tier | <1-4> |
| Confidence | <HIGH/MEDIUM/LOW> |
| Command | `<executed command>` |
| Execution Time | <actual time> |
| Test Results | <X passed, Y failed, Z skipped> |
| Fallback Used | <Yes/No — reason if yes> |

Step 5: Determine next action

Important: Progressive Test Validation does NOT replace the Phase Checkpoint Protocol. It runs BEFORE the checkpoint to provide fast feedback. The Phase Checkpoint Protocol still runs the build, lint, and commit steps. However, when progressive validation passes, the Phase Checkpoint Protocol step 3 (test execution) MAY use the same tier instead of the full suite, provided the test-selector confidence was HIGH.

Anti-Patterns:

6.1.5. Code Review Gate (Phase 5.55 — after progressive validation, before E2E):

Reference: See .claude/rules/review-gate-protocol.md for the canonical review gate pattern.

Trigger: After Progressive Test Validation passes (step 6.1), BEFORE E2E generation (step 6.2).

Config Check:

1. If --skip-review passed → SKIP (log: "Code review skipped by user flag")
2. Read .claude/settings.local.json → check env.AUTO_REVIEW_ENABLED
   - If false → SKIP (log: "Reviews disabled globally")
3. Check env.AUTO_REVIEW_IMPLEMENT
   - If false → SKIP (log: "Implementation review disabled")
4. Check env.AUTO_REVIEW_IMPLEMENT_FREQUENCY (default: "major"):
   - "every" → Run at every phase checkpoint
   - "major" → Run only at phase boundaries (Phase N → Phase N+1), skip within-phase checkpoints
   - "final" → Run only at the last phase checkpoint before validation
5. If frequency check passes → Proceed with review gate

Reviewer Dispatch (subagent fallback):

Spawn 2 domain-reviewer agents in a SINGLE message (synchronous parallel):

For each domain in [code-quality, security]:
  Task({
    subagent_type: "domain-reviewer",
    model: REVIEW_AGENT_MODEL (default: sonnet),
    prompt: "You are a domain-reviewer specializing in {domain}.
             Review the code changes in the current phase using: git diff HEAD~1
             Cross-reference against: plan.md (architecture decisions), spec.md (requirements).
             Classify findings as CRITICAL/MAJOR/MINOR.
             Focus on:
             - code-quality: SOLID violations, code duplication, missing error handling,
               test coverage gaps, naming conventions, architecture layer violations
             - security: Input validation, injection risks, auth/authz gaps, sensitive data exposure,
               insecure defaults, missing rate limiting on public endpoints"
    // NOTE: spawn ALL domains in a SINGLE message with multiple Task blocks
    // NEVER use run_in_background: true
  })

Process Findings:

1. Collect findings from both reviewers
2. Write to {FEATURE_DIR}/reviews/implement-phase-{N}-review.md
3. Apply severity rules:
   • CRITICAL findings (security vulnerabilities, data loss risks) → BLOCK: Fix before proceeding to next phase
   • MAJOR findings (architecture violations, missing tests) → WARN: Present to user, may proceed
   • MINOR findings (style, naming) → LOG: Record only

Auto-Debate Trigger:

If CRITICAL findings ≥ AUTO_DEBATE_THRESHOLD (default: 2):

1. Run a 1-round devils-advocate debate on the proposed fixes
2. Persist to {FEATURE_DIR}/reviews/implement-phase-{N}-debate.md

Performance Note: At ~30K tokens per review, this adds ~1 minute per phase boundary (with "major" frequency). Use "final" frequency to reduce to a single review at the end.

Output: {FEATURE_DIR}/reviews/implement-phase-{N}-review.md, optional debate file

6.2. E2E Test Generation & Smoke Test Validation (Phase 5.6 — UI features only):

Trigger: After Phase 5.5 (Progressive Test Validation), BEFORE Phase Checkpoint Protocol, IF any files in frontend/ were modified.

Purpose: Auto-generate missing E2E tests for UI features and validate smoke tests (100% pass required).

Step 1: Check if E2E coverage needed

# Check if frontend files changed
git diff --name-only HEAD | grep '^frontend/'

If no frontend files changed → SKIP Phase 5.6 entirely, proceed to Phase Checkpoint Protocol.

Step 2: Read E2E Test Coverage Matrix from spec.md

Load <FEATURE_DIR>/spec.md and extract the "E2E Test Coverage" section → "Critical User Journeys" table.

For each journey with Status = "To Implement":

• Journey ID (e.g., J-001)
• User Story reference (e.g., US-001)
• Journey Description (complete user flow)
• Priority (P0/P1/P2/P3)
• E2E Test File path (e.g., e2e/campaigns/create-campaign.spec.ts)

Step 3: Auto-generate missing E2E test files

For each test file that does NOT exist:

a. Extract journey details from spec: - Parse User Story acceptance scenarios (Given/When/Then) - Extract component names from Presentation field - Identify page object class needed

b. Generate Page Object (if not exists):

  Check if `frontend/e2e/pages/[category]-page.ts` exists.

  If NOT, create it:
  ```typescript
  import { Page } from '@playwright/test';

  export class [Category]Page {
    constructor(private page: Page) {}

    async [actionMethod]([params]) {
      // Auto-generated based on journey description
      // Example: await this.page.click('button:has-text("Save")');
    }

    async verify[Entity]([criteria]) {
      // Auto-generated verification methods
      // Example: return this.page.locator('.success-message').isVisible();
    }
  }
  ```

c. Generate E2E test file:

  ```typescript
  import { test, expect } from '@playwright/test';
  import { [Category]Page } from '../pages/[category]-page';

  test('[journey description from spec] @[priority]', async ({ page }) => {
    const [pageName] = new [Category]Page(page);

    // Auto-generated test steps based on Given/When/Then from spec
    // Step 1: Given - Setup preconditions
    await page.goto('/[initial-route]');

    // Step 2: When - Execute actions
    await [pageName].[actionMethod]([params]);

    // Step 3: Then - Verify outcomes
    expect(await [pageName].verify[Entity]()).toBeTruthy();
  });
  ```

  Use the journey description and acceptance scenarios to populate test steps.
  Extract route from Presentation field or infer from journey.

d. Update E2E Test Coverage table in spec.md:

  Change Status from "To Implement" → "Generated (needs validation)"

Step 4: Run Smoke Tests (P0 only)

Execute smoke tests to validate critical paths:

cd frontend && npm run test:e2e -- --grep @p0

Pass Criteria: 100% of smoke tests MUST pass (blocking).

Step 5: Log E2E Generation & Validation

Record in implementation report:

### E2E Test Generation & Smoke Validation — Phase <N>

| Field | Value |
|-------|-------|
| E2E Tests Generated | <count> test files created |
| Page Objects Generated | <count> page object files created |
| Smoke Tests Executed | <count> P0 tests run |
| Smoke Test Pass Rate | <percentage>% (100% required) |
| Execution Time | <actual time> |
| Flaky Tests | <count> tests marked as flaky |

Step 6: Update spec.md Component Audit

For each generated Page Object, update the "Component Audit" table:

| Component | Page Object Method | Accessibility (WCAG 2.1) | E2E Coverage | Notes |
|-----------|-------------------|--------------------------|--------------|-------|
| CampaignForm | CampaignPage.createCampaign() | [ ] AA Compliant | [x] Covered | Generated - needs accessibility review |

Mark "E2E Coverage" as checked, but leave "Accessibility" unchecked for manual review.

Anti-Patterns:

7. Implementation execution rules:

   • Setup first: Initialize project structure, dependencies, configuration
   • Tests before code: If you need to write tests for contracts, entities, and integration scenarios
   • Core development: Implement models, services, CLI commands, endpoints
   • Integration work: Database connections, middleware, logging, external services
   • Polish and validation: Unit tests, performance optimization, documentation

8. Progress tracking and error handling:

   • Report progress after each completed task
   • Halt execution if any non-parallel task fails
   • For parallel tasks [P], continue with successful tasks, report failed ones
   • Provide clear error messages with context for debugging
   • Suggest next steps if implementation cannot proceed
   • IMPORTANT For completed tasks, make sure to mark the task off as [X] in the tasks file.

9. Completion validation:

   • Verify all required tasks are completed
   • Check that implemented features match the original specification
   • Run actual tests - builds passing is NOT verification (see Verification Protocol)
   • Confirm the implementation follows the technical plan
   • Report final status with summary of completed work

10. Feature Verification (if verification spec exists in plan.md):

    After all implementation phases complete and gates pass:

    a. Check for verification spec: Read plan.md and look for "Verification Spec" section

    b. If verification spec exists:

    • Gather baseline metrics (from earlier test runs or documented baselines)
    • Gather post-change metrics (from current test output)
    • Spawn feature-verifier agent with:
      • Path to plan.md (contains verification spec)
      • Baseline metrics
      • Post-change metrics
    • Wait for verification outcome

    c. Handle verification outcome:

    Outcome	Action
    VERIFIED	Proceed to commit/PR
    VERIFIED_WITH_NOTE	Proceed with documentation of notes
    NEEDS_INVESTIGATION	Pause, investigate before proceeding
    STRUCTURAL_FAILURE	Do NOT proceed, address structural issues
    MECHANICAL_FAILURE	Do NOT proceed, fix runtime errors

    d. Document outcome: Add verification result to commit message or PR description

11. Quality Gates (MANDATORY - BLOCKING after each phase):

    Run ALL applicable gates. Paste ACTUAL output as proof. See gate-definitions.md for detailed definitions and paste-box templates.

    Gate	Applies When	Blocking
    1. Build	Always	Yes
    2. Tests	Always	Yes
    3. Coverage	Coverage configured	Yes
    4. Deploy Health	Docker/deployment exists	Yes
    5. E2E Tests	UI phases	Yes
    6. Code Quality	Lint/analysis configured	No
    7. API URL Consistency	Frontend+backend	No
    8. Environment/CORS	Deployment config exists	No
    9. Test Plan Verification	.mad/test-plans/{project}/verify-{slug}.sh exists	Conditional

    Gate 9 Logic:

    • Slug derivation: Read .claude/work-items/ACTIVE → manifest.json → spec_directory → last path segment
    • If no verify script found: WARN "No verify script at .mad/scratch/verify-{slug}.sh — Gate 9 skipped" → NON-BLOCKING
    • Phase 1 (first implementation phase): Run script; FAIL = NON-BLOCKING — document failure count as expected baseline; continue
    • Phase 2+: Run bash .mad/scratch/verify-{slug}.sh; any FAIL = BLOCKING — report count, halt phase, require fix before proceeding
    • Tip: verify scripts generated by /testplan --source spec live at .mad/scratch/verify-{feature-slug}.sh

    If test gate ❌: STOP → Fix failing test(s) using --filter → Verify fix with targeted run → Then re-run ALL gates once. If other blocking gate ❌: STOP → Fix → Re-run ALL gates. If ALL ✅: Trust-But-Verify (see gate-definitions.md) → Atomic Commit.

12. Comprehensive Validation (MANDATORY after ALL phases complete):

    CRITICAL: After all implementation phases are done and all quality gates pass, you MUST run comprehensive validation BEFORE creating a PR.

    Invoke /mad-validate using Skill tool:

    Skill tool: { "skill": "mad-validate" }
    

    Purpose: mad-validate runs 6+ validation lenses:

    • Contract traceability (API contracts match implementation)
    • Spec lint (no template placeholders remaining)
    • Test coverage (all requirements have tests)
    • Living documentation (READMEs match reality)
    • Pattern compliance (architecture rules followed)
    • Staleness detection (no outdated dependencies)

    DO NOT:

    • Skip validation and proceed directly to PR
    • Ask user "Should I create a PR?" without running validation first
    • Assume quality gates are sufficient (they test code, not completeness)

    Validation Outcomes:

    Outcome	Action
    ✅ PASS (all lenses green)	Proceed to PR creation
    ⚠️ WARN (non-blocking issues)	Document warnings, proceed with caution
    ❌ FAIL (blocking issues)	Do NOT create PR - fix issues first, re-run validation
    ⏭️ SKIP (incomplete spec/plan)	Do NOT proceed - complete prerequisites first

    After validation passes: Ask user if they want to create a PR, providing summary of validation results.

Investigation Protocol

When debugging: check actual behavior, not code assumptions. Check logs first (docker logs, test output). Verify by running code. Report observations with evidence: "Logs show X" not "This code would do X".

LLM Trust Boundary

When processing LLM output: Application code handles LOGICAL verification. LLM handles SEMANTIC judgment.

Required Logical Gates (in application code): Verify files exist after LLM claims, verify actual changes via git status, call injected validators.

Anti-Patterns: Graceful degradation hiding bugs, mock/placeholder data in production code, // TODO: use real API comments.

DAG Execution Mode

The /mad-implement skill supports four execution modes via the DAG_EXECUTION_MODE environment variable. This system enables progressive adoption of wave-based parallel execution without breaking existing workflows.

Mode Reference

Configuration

Set in .claude/settings.local.json under the env key:

{
  "env": {
    "DAG_EXECUTION_MODE": "dag-execute",
    "DAG_CONTEXT_THRESHOLD": "0.85"
  }
}

Related flags:

• DAG_CONTEXT_THRESHOLD (default 0.85): Context budget threshold for halting execution
• DAG_VISUALIZATION_ENABLED (default false): Enable /dag-visualize skill
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS (default unset): Required for parallel wave execution

See .claude/docs/dag-feature-flags.md for complete configuration documentation and recommended adoption path.

Execution Flow by Mode

Classic (default):

Step 1 -> Step 2 -> Step 2.5 (detect classic, skip DAG) -> Step 3 -> Step 5 -> Step 6 (phase-by-phase) -> Gates

dag-parse-only:

Step 1 -> Step 2 -> Step 2.5 (detect mode) -> Step 3 -> Step 5 -> Step 5.1b (call executeDagWorkflow with mode='dag-parse-only') -> Log waves -> Step 6 (phase-by-phase) -> Gates

dag-validate:

Step 1 -> Step 2 -> Step 2.5 (detect mode) -> Step 3 -> Step 5 -> Step 5.1b (call executeDagWorkflow with mode='dag-validate') -> Log conflicts -> Step 6 (phase-by-phase) -> Gates

dag-execute:

Step 1 -> Step 2 -> Step 2.5 (detect dag-execute) -> Step 3 -> Step 5 -> Step 5.1b (call executeDagWorkflow with mode='dag-execute') -> Waves execute -> Step 5.1c (phase gates) -> Skip Step 6 (waves replace phase-by-phase)

DAG Executor Integration

When DAG_EXECUTION_MODE is NOT classic, Step 5.1 calls the executeDagWorkflow function from .claude/lib/dag-executor.js:

Function signature:

const { executeDagWorkflow, ContextBudgetExceededError } = require('./.claude/lib/dag-executor.js');

const result = await executeDagWorkflow(tasks, config);

Config object:

{
  mode: 'dag-parse-only' | 'dag-validate' | 'dag-execute',
  contextThreshold: 0.85,  // Read from DAG_CONTEXT_THRESHOLD env var
  dryRun: false,           // Set true for validation without execution
  taskExecutor: async (taskId) => {
    // Custom task execution logic
    // Return { taskId, success: boolean, duration: number, error?: string }
  },
  onWaveComplete: (waveNumber, waveResult) => {
    // Optional callback after each wave completes
  }
}

Return value (varies by mode):

• dag-parse-only: { success, mode, waves, conflicts, criticalPath }
• dag-validate: { success, mode, waves, conflicts, criticalPath, resolutions }
• dag-execute: { success, mode, totalWaves, completedWaves, totalTasks, completedTasks, failedTasks, waveTimings, duration }

Error types:

• Cycle detected: Thrown if task dependencies form a cycle
• ContextBudgetExceededError: Thrown when context usage exceeds threshold during dag-execute
• Wave execution failure: Thrown when one or more tasks fail verification

See Step 5.1d for complete error handling patterns.

Backward Compatibility

• Default mode is classic: Zero changes to existing behavior
• All existing invocations work identically: No configuration required for existing workflows
• DAG modes are strictly opt-in: Must explicitly set DAG_EXECUTION_MODE env var
• DAG library only loaded when needed: No import overhead in classic mode (mode check happens before require)
• Phase gates apply identically in all modes: Gates run after phases (classic) or after phase's waves (dag-execute)
• TDD requirements unchanged: Red-green-refactor cycle applies in all modes
• Checkpoint protocol unchanged: Commit after gates pass, regardless of mode

Interaction with Agent Teams

DAG execution and Agent Teams are complementary, not competing:

How they integrate:

1. Agent Teams check (Step 6.0a) is independent of DAG mode
2. In dag-execute mode, dag-executor.js checks checkAgentTeamsEnabled() before wave execution
3. If teams available AND wave has 2+ tasks → calls executeWaveWithAgentTeams()
4. If teams unavailable OR single task → calls executeWaveSequential()
5. File ownership protocol applies in both modes (prevents conflicts)

Phase 2 Status: ✅ COMPLETE - Agent Teams integration, file conflict detection, phase gates, and context budget monitoring are fully implemented and tested (147/147 tests passing).

Testing DAG Modes

Test classic mode (default):

# Ensure no DAG_EXECUTION_MODE is set (or set to "classic")
/mad-implement
# Expected: No DAG output, no wave assignments, traditional phase-by-phase execution

Test dag-parse-only:

# In .claude/settings.local.json:
{ "env": { "DAG_EXECUTION_MODE": "dag-parse-only" } }

/mad-implement
# Expected: Shows wave assignment summary after parsing tasks.md, then executes classically
# Look for: "DAG parse complete: N waves, N conflicts, critical path: [T001, T010, ...]"

Test dag-validate:

# In .claude/settings.local.json:
{ "env": { "DAG_EXECUTION_MODE": "dag-validate" } }

/mad-implement
# Expected: Shows warnings for cycles/conflicts, suggests resolutions, then executes classically
# Look for: "[dag-validate] File conflict in wave N: src/file.cs owned by tasks T020, T021"

Test dag-execute:

# In .claude/settings.local.json:
{ "env": { "DAG_EXECUTION_MODE": "dag-execute", "DAG_CONTEXT_THRESHOLD": "0.85" } }

/mad-implement
# Expected: Executes waves in dependency order, runs phase gates after each phase's waves
# Look for: Wave timing output, file conflict serialization logs, context budget checks
# Context budget check after each wave: "Wave N complete. Context usage: 45.2%"

Verify backward compatibility:

# Remove all DAG_* entries from .claude/settings.local.json (or set mode to "classic")
/mad-implement
# Must behave identically to pre-DAG implementation (no wave output, no DAG library loaded)

Error Handling Examples

Cycle detection:

Error: "Cycle detected in task dependencies: [T010 -> T020 -> T030 -> T010]"
Action: Display cycle, offer to fix tasks.md, retry after fix or fall back to classic

Context budget exceeded:

ContextBudgetExceededError: "Context budget exceeded (87.5% > 85.0%). 3 waves remaining."
Action: HALT immediately, generate handoff with completed wave progress, tell user to start new session

Wave execution failure:

Error: "Wave 2 failed verification. Failed tasks: T020, T021"
Action: STOP, display task errors, suggest fixes, offer to re-run from failed wave

DAG Anti-Patterns

Phase 2: Smart Parallelization (COMPLETE)

Phase 2 enhances dag-execute mode with intelligent wave execution, file conflict management, context budget monitoring, and quality gates. All features are fully implemented and tested (147/147 unit tests passing).

File Conflict Detection and Resolution

Automatic Detection: The system detects when multiple tasks in the same wave attempt to modify the same files, which would cause merge conflicts or race conditions.

Resolution Strategy (Serialize):

• First task in conflict group: Remains in parallel wave
• Subsequent conflicting tasks: Moved to sequential execution
• Non-conflicting tasks: Stay parallel (maximum parallelism)

Configuration (.claude/agent-teams-config.json):

{
  "dag": {
    "fileConflicts": {
      "detectionEnabled": true,
      "resolutionStrategy": "serialize",
      "warnOnConflicts": true
    }
  }
}

Example:

Wave 1: [T1, T2, T3] all modify shared.js
Result after conflict detection:
  Parallel: [T1] (first task keeps position)
  Serial: [T2, T3] (moved to sequential execution)

Implementation: .claude/lib/file-ownership.js provides detectConflicts(), resolveConflicts(), and `splitWaveB

Truncated - read the full file at https://github.com/tmalcolm-0607/mad-council-claw/blob/5e87a82fbd139875fdd5fe81040e4ce29bb57271/.claude/skills/mad-implement/SKILL.md.