Agent skill

phase-enforcement

Evidence-based phase completion enforcement for /dev:feature. Use when orchestrating 8-phase feature development to ensure artifacts exist before phase completion, validation criteria are addressed, outer loops are enforced, and show-your-work requirements are met.

View SKILL.md on GitHub Repository
Stars 248
Forks 27

Install this agent skill to your Project

npx add-skill https://github.com/MadAppGang/claude-code/tree/main/plugins/dev/skills/enforcement

SKILL.md

Phase Completion Enforcement

Version: 1.0.0 Purpose: Mechanical enforcement of phase completion requirements for /dev:feature Status: Production Ready

Overview

This skill provides mechanical enforcement (not just prompt-based instructions) for the 8-phase feature development workflow. It prevents:

  1. Claiming completion without proof - Artifacts must exist
  2. Skipping documentation - Required files per phase
  3. Ignoring validation criteria - Phase 1 criteria must map to Phase 7 results
  4. Bypassing retry logic - Outer loop enforced with state tracking
  5. Shipping without tests - Phase 6 requires test files
  6. Faking completion when blocked - Graceful degradation with honest status
  7. Hiding actual results - Show-your-work requirement
  8. Missing automated checks - Checkpoint verification at boundaries

Enforcement Components

1. Phase Completion Validator

Script: scripts/phase-completion-validator.js

How it works:

  • Runs as PreToolUse hook on TaskUpdate
  • Detects phase from task subject (e.g., "Phase 3: Planning")
  • Checks required artifacts exist for that phase
  • Blocks completion if artifacts missing or empty

Required Artifacts per Phase:

Phase Required Artifacts Custom Checks
1 requirements.md, validation-criteria.md, iteration-config.json Config has required fields
3 architecture.md Plan reviews exist
4 implementation-log.md Git changes detected
5 reviews/code-review/consolidated.md Has PASS/FAIL verdict
6 tests/test-plan.md Test files created
7 validation/result.md Has PASS/FAIL status + evidence
8 report.md Phase 7 PASSED

Usage in orchestrator:

markdown
Before marking any phase complete:

1. Run checkpoint verification:
   ```bash
   ${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH}

  1. If check passes, mark task complete:

    TaskUpdate(taskId: X, status: "completed")

  2. If check fails, DO NOT mark complete. Fix missing artifacts first.


---

### 2. Outer Loop Enforcer

**Script:** `scripts/outer-loop-enforcer.js`

**How it works:**
- Tracks iteration state in session-meta.json
- Blocks Phase 8 unless Phase 7 PASSED
- Detects regression (score getting worse)
- Handles escalation when max iterations reached

**Commands:**

```bash
# Start new iteration (call before Phase 3)
node outer-loop-enforcer.js start-iteration ${SESSION_PATH}

# Record Phase 7 result
node outer-loop-enforcer.js record-result ${SESSION_PATH} PASS "All checks passed" 95

# Check if Phase 8 can proceed
node outer-loop-enforcer.js check-can-complete ${SESSION_PATH}

# Get current status
node outer-loop-enforcer.js get-status ${SESSION_PATH}

Session state tracking:

json
{
  "outerLoop": {
    "currentIteration": 2,
    "maxIterations": 3,
    "mode": "limited",
    "phase7Results": [
      {"iteration": 1, "status": "FAIL", "reason": "Button color mismatch", "score": 78},
      {"iteration": 2, "status": "PASS", "reason": "All checks passed", "score": 94}
    ]
  }
}

Usage in orchestrator:

markdown
OUTER LOOP: Before starting Phase 3

1. Start iteration:
   ```bash
   node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js start-iteration ${SESSION_PATH}
  1. Check exit code:
    • 0: Proceed with iteration
    • 2: Max iterations reached, escalate to user

OUTER LOOP: After Phase 7 completes

  1. Record result:

    bash
    node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js record-result ${SESSION_PATH} <PASS|FAIL> "reason" [score]

  2. If PASS: Proceed to Phase 8

  3. If FAIL: Loop back to Phase 3 (start-iteration will be called again)

OUTER LOOP: Before Phase 8

  1. Verify Phase 7 passed:

    bash
    node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js check-can-complete ${SESSION_PATH}

  2. If exit code 1: BLOCKED - cannot proceed to Phase 8


---

### 3. Validation Criteria Enforcer

**Script:** `scripts/validation-criteria-enforcer.js`

**How it works:**
- Parses validation-criteria.md from Phase 1
- Parses validation/result.md from Phase 7
- Matches criteria to results using fuzzy matching
- Blocks if >20% criteria unaddressed

**Usage in orchestrator:**

```markdown
PHASE 7: After creating result.md

1. Run criteria enforcer:
   ```bash
   node ${PLUGIN_PATH}/scripts/validation-criteria-enforcer.js ${SESSION_PATH}

  1. Review generated report: ${SESSION_PATH}/validation/criteria-mapping.md

  2. If unaddressed criteria found:

    • Update result.md to address them
    • Or document why they couldn't be tested

**Output format:**

```markdown
# Validation Criteria Mapping Report

## Summary
- Total Criteria: 5
- Matched: 4
- Unmatched: 1
- Coverage: 80%

## Criteria Mapping
| Line | Criterion | Result | Evidence |
|------|-----------|--------|----------|
| 12 | "Navigate to test URL" | PASS | screenshot-before.png |
| 13 | "Fill email field" | PASS | action-log.md line 5 |
| 14 | "Click login button" | PASS | action-log.md line 8 |
| 15 | "Redirect to dashboard" | PASS | screenshot-after.png |

## ⚠️ Unaddressed Criteria
- Line 16: "Show error for invalid password"

4. Checkpoint Verifier

Script: scripts/checkpoint-verifier.sh

How it works:

  • Bash script for fast automated checks
  • Runs at phase boundaries
  • Verifies files exist and have content
  • Checks git state for implementation phase

Usage:

bash
# Before completing Phase 4
./checkpoint-verifier.sh phase4 ${SESSION_PATH}

# Before completing Phase 7
./checkpoint-verifier.sh phase7 ${SESSION_PATH}

Example output:

📋 Checkpoint Verification: phase4
─────────────────────────────────────
Session: ai-docs/sessions/dev-feature-login-20260204-143022

✅ Implementation Log: implementation-log.md (1234 bytes)
✅ Code Changes: 8 files with changes
✅ Implementation Log: Has structured progress

─────────────────────────────────────
✅ Checkpoint passed

Integration with /dev:feature

Phase Transition Protocol

MANDATORY: Before marking ANY phase as completed:

markdown
<phase_completion_protocol>
  **Step 1: Run Checkpoint Verification**

  ```bash
  ${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH}

If exit code != 0: STOP. Fix missing artifacts first.

Step 2: Show Evidence Summary

Display 3-5 lines of actual results:

## Phase {N} Evidence
- Artifact: ${SESSION_PATH}/{artifact}.md (exists, 1234 bytes)
- Key result: {actual output from phase}
- Evidence: {file paths to screenshots, logs, etc.}

Step 3: Map to Original Criteria (for Phase 7)

From validation-criteria.md:
- [x] Criterion 1 → Verified (evidence file)
- [x] Criterion 2 → Verified (screenshot)
- [ ] Criterion 3 → Skipped (reason documented)

Step 4: Mark Task Complete

Only if Steps 1-3 pass:

TaskUpdate(taskId: X, status: "completed")

</phase_completion_protocol>


### Show-Your-Work Requirement

**Anti-pattern (BLOCKED):**

```markdown
I'll run the tests now.
[Task tool call to run tests]
Tests passed! Moving to next phase.

Required pattern:

markdown
Running tests:

$ bun test
✓ auth.test.ts (5 tests)
  ✓ should authenticate valid user (12ms)
  ✓ should reject invalid password (8ms)
  ✓ should expire session after timeout (15ms)
  ✓ should refresh token correctly (10ms)
  ✓ should logout user (5ms)

✗ payment.test.ts (3 tests)
  ✓ should process valid payment (20ms)
  ✓ should reject invalid card (12ms)
  ✗ should handle timeout (FAILED)
    Error: Expected timeout after 30s, got success

Results: 7 passed, 1 failed

The payment timeout test failure needs investigation before Phase 6 can complete.

Graceful Degradation

Three Completion Statuses

COMPLETE: All validation criteria passed

  • All artifacts created
  • All tests pass
  • Full validation executed

PARTIAL: Some validation done, gaps documented

  • Core functionality verified
  • Some criteria couldn't be tested (documented why)
  • Known limitations listed

INCOMPLETE: Blocked, needs user action

  • Critical blocker encountered
  • Cannot proceed without external input
  • Clear description of what's needed

Session Status in session-meta.json

json
{
  "status": "partial",
  "completedCriteria": ["builds", "type-checks", "login-flow"],
  "skippedCriteria": [
    {"criterion": "full-auth-flow", "reason": "requires running server"},
    {"criterion": "token-storage", "reason": "depends on auth flow"}
  ],
  "blockers": []
}

Final Report for PARTIAL Status

markdown
## Feature Status: PARTIAL

### Completed ✓
- SDK implementation
- Type safety
- Build verification

### Not Verified ⚠️
- End-to-end authentication (requires running server)
- Token storage persistence (depends on auth)

### Recommended Before Production
1. Run integration tests with real server
2. Verify token encryption roundtrip

5. Failure Report Generator

Script: scripts/failure-report-generator.js

How it works:

  • Auto-generated when phase completion is blocked
  • Documents what was expected vs what happened
  • Lists all attempted approaches and their errors
  • Provides manual testing steps as fallback
  • Includes workarounds and suggestions

When generated:

  • Phase completion validator blocks a phase
  • Validation criteria enforcer finds gaps
  • Outer loop reaches max iterations
  • Any enforcement script fails

Report structure:

markdown
# {Phase Name} - Failure Report

**Generated:** 2026-02-04T10:30:00Z
**Session:** ai-docs/sessions/dev-feature-login-20260204
**Phase:** phase7

## Expected Artifacts
- ❌ `validation/result.md`
- ❌ `validation/screenshot-before.png`
- ❌ `validation/screenshot-after.png`

## Attempted Approaches

### Attempt 1: browser_test
**What was tried:** Chrome MCP navigation to localhost:3000
**Error:** Tool mcp__chrome-devtools__navigate_page not available
**Timestamp:** 2026-02-04T10:25:00Z

## Failure Analysis

### Common Failure Reasons
- **chrome_mcp_unavailable**: Chrome MCP tools not available or not responding
- **server_not_starting**: Dev server fails to start
- **page_not_loading**: Test URL not accessible

## Suggestions for Resolution
1. Verify Chrome MCP is properly configured in .claude/settings.json
2. Check if dev server is running: curl http://localhost:3000
3. Try using different browser automation: mcp__claude-in-chrome instead
4. Consider unit tests + manual verification as fallback

## Manual Testing Steps
1. Start dev server: npm run dev (or bun run dev)
2. Open browser to test URL (e.g., http://localhost:3000)
3. Take screenshot of initial state
4. Perform test actions (fill forms, click buttons)
5. Take screenshot of result state
6. Verify expected behavior occurred
7. Document results in validation/result.md

## Workarounds

### If Browser Automation Unavailable
1. Run validation manually in browser
2. Take screenshots with system screenshot tool
3. Save screenshots to `validation/` directory
4. Create `validation/result.md` with manual observations

### Minimal result.md Template
[template provided]

## Next Steps
1. **Fix and Retry**: Address the issues above and re-run the phase
2. **Manual Completion**: Follow manual steps and create artifacts manually
3. **Skip with Justification**: Create `phase7-skip-reason.md` explaining why
4. **Escalate to User**: Ask user for guidance via AskUserQuestion

Usage in orchestrator:

When phase completion is blocked:

markdown
1. Failure report auto-generated at:
   ${SESSION_PATH}/failures/phase{N}-failure-report.md

2. Read report and either:
   a. Fix issues and retry
   b. Follow manual testing steps
   c. Create skip-reason.md with justification
   d. Escalate to user with AskUserQuestion

3. If manually completing:
   - Create required artifacts following templates in report
   - Re-run phase completion validator

Summary Table

Enforcement What It Prevents
Phase completion validator Claiming "done" without proof
Mandatory artifacts Skipping documentation
Validation criteria enforcer Collecting criteria but ignoring them
Outer loop enforcer Skipping retry logic
Phase 6 test check Shipping without tests
Graceful degradation Faking completion when blocked
Show-your-work Hiding actual results
Checkpoint verification Automated sanity checks
Failure report generator Silent failures without guidance

Implementation Priority

  1. HIGH: Evidence-based completion + Show-your-work (fixes core trust problem)
  2. HIGH: Validation criteria enforcement (ensures Phase 1 work is used)
  3. MEDIUM: Phase 6 test enforcement (ensures quality)
  4. MEDIUM: Graceful degradation (enables honest status)
  5. LOW: Checkpoint verification (nice automation, but manual review works)

Scripts Location: ${PLUGIN_ROOT}/plugins/dev/scripts/ Hooks Config: ${PLUGIN_ROOT}/plugins/dev/hooks/feature-enforcement.json

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

MadAppGang/claude-code

test-skill

A test skill for validation testing. Use when testing skill parsing and validation logic.

248 27
Explore
MadAppGang/claude-code

bad-skill

248 27
Explore
MadAppGang/claude-code

claudish-usage

CRITICAL - Guide for using Claudish CLI ONLY through sub-agents to run Claude Code with OpenRouter models (Grok, GPT-5, Gemini, MiniMax). NEVER run Claudish directly in main context unless user explicitly requests it. Use when user mentions external AI models, Claudish, OpenRouter, or alternative models. Includes mandatory sub-agent delegation patterns, agent selection guide, file-based instructions, and strict rules to prevent context window pollution.

248 27
Explore
MadAppGang/claude-code

release

Plugin release process for MAG Claude Plugins marketplace. Covers version bumping, marketplace.json updates, git tagging, and common mistakes. Use when releasing new plugin versions or troubleshooting update issues.

248 27
Explore
MadAppGang/claude-code

claudish-integration

248 27
Explore
MadAppGang/claude-code

openrouter-trending-models

Fetch trending programming models from OpenRouter rankings. Use when selecting models for multi-model review, updating model recommendations, or researching current AI coding trends. Provides model IDs, context windows, pricing, and usage statistics from the most recent week.

248 27
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results