Plan Guardian

Plan Guardian Skill

Metadata

• skill_name: plan-guardian
• activation_code: PLAN_GUARDIAN_V1
• version: 1.0.0
• category: monitoring
• phase: all (runs alongside any phase)

Description

Background monitoring agent that runs alongside active development agents to detect drift from the original plan. Samples work-in-progress and compares against a plan digest to catch misalignment early, before significant rework is needed.

Architecture

                    ┌─────────────────────┐
                    │   PLAN DIGEST       │
                    │  (.claude/plan-     │
                    │   digest.json)      │
                    └──────────┬──────────┘
                               │
                               ▼
┌──────────────┐     ┌─────────────────────┐     ┌──────────────┐
│ ACTIVE AGENT │────▶│   WORK STREAM       │────▶│ PLAN GUARDIAN│
│ (any phase)  │     │ (sampled via hook)  │     │ (background) │
└──────────────┘     └─────────────────────┘     └──────┬───────┘
                                                        │
                               ┌────────────────────────┴─────┐
                               ▼                              ▼
                        [OK - continue]              [DRIFT - inject]
                                                          │
                                                          ▼
                                              ┌─────────────────────┐
                                              │ Warning injected to │
                                              │ active agent context│
                                              └─────────────────────┘

Activation

Automatic: Plan Guardian starts automatically when:

• Pipeline begins (PIPELINE_STARTED signal)
• Any phase skill activates
• Explicitly enabled in pipeline config

Manual:

• "Enable plan guardian"
• "Start drift monitoring"
• "Watch for plan drift"

Plan Digest

The guardian operates on a lightweight plan digest created at pipeline start.

Digest Location

.claude/plan-digest.json

Digest Schema

{
  "version": "1.0",
  "created_at": "2025-12-19T10:00:00Z",
  "source_documents": ["PRD.md", ".ideation/ideation-summary.md"],

  "core_problem": {
    "statement": "One-sentence problem description",
    "not_solving": ["Adjacent problems explicitly out of scope"]
  },

  "boundaries": {
    "must_have": ["Essential requirements"],
    "must_not_have": ["Explicit exclusions"],
    "constraints": ["Technical/business constraints"]
  },

  "architecture": {
    "patterns": ["Chosen patterns (e.g., REST API, event-driven)"],
    "stack": ["Technology choices"],
    "anti_patterns": ["Explicitly rejected approaches"]
  },

  "scope_markers": {
    "in_scope": ["Features/capabilities included"],
    "out_of_scope": ["Features explicitly deferred/excluded"],
    "scope_creep_indicators": ["Phrases that suggest scope creep"]
  },

  "key_decisions": [
    {
      "decision": "What was decided",
      "rationale": "Why",
      "alternatives_rejected": ["What was not chosen"]
    }
  ]
}

Sampling Mechanism

Hook Integration

The guardian receives samples via the plan-guardian-hook.sh which fires on:

• File writes (Edit, Write tools)
• Significant bash commands (npm install, docker build, etc.)
• Phase transitions

Sample Payload

{
  "timestamp": "2025-12-19T10:30:00Z",
  "phase": 7,
  "skill": "tdd-implementer",
  "action": {
    "type": "file_write",
    "path": "src/auth/oauth.ts",
    "summary": "Added OAuth2 authentication flow with Google provider",
    "lines_changed": 145
  },
  "context": {
    "recent_actions": ["Last 5 actions summary"],
    "current_task": "Implement user authentication"
  }
}

Sampling Rate

• Default: Every 5 significant actions (writes, major commands)
• High-sensitivity phases: Every 2 actions (Phase 7 implementation)
• Low-sensitivity phases: Every 10 actions (Phase 9 testing)

Configurable via .claude/guardian-config.json:

{
  "sampling_rate": {
    "default": 5,
    "phase_overrides": {
      "7": 2,
      "9": 10
    }
  },
  "sensitivity": "normal"
}

Drift Detection

Assessment Criteria

The guardian evaluates samples against the plan digest using these criteria:

Response Levels

┌─────────┬───────────┬─────────────────────────────────────────┐
│ Level   │ Threshold │ Action                                  │
├─────────┼───────────┼─────────────────────────────────────────┤
│ OK      │ > 0.8     │ Silent, continue                        │
│ NOTICE  │ 0.6 - 0.8 │ Log concern, no interruption            │
│ WARN    │ 0.4 - 0.6 │ Inject reminder to active agent         │
│ DRIFT   │ 0.2 - 0.4 │ Pause, require acknowledgment           │
│ HALT    │ < 0.2     │ Block work, escalate to human           │
└─────────┴───────────┴─────────────────────────────────────────┘

Injection Format

When drift is detected, the guardian injects a message into the active agent's context:

WARN level:

[GUARDIAN:WARN] Potential drift detected.
Concern: Implementation adding OAuth flow.
Plan states: "API-key-only authentication for MVP"
Confidence: 0.55
Action: Review and confirm this is intentional, or adjust approach.

DRIFT level:

[GUARDIAN:DRIFT] Significant drift from plan detected.
Concern: Adding real-time WebSocket features.
Plan states: "REST-only API, WebSockets deferred to Phase 2"
Confidence: 0.35
Action: PAUSED. Acknowledge one of:
  1. "Continue anyway" - Proceed with deviation (logged)
  2. "Revert approach" - Return to plan-aligned implementation
  3. "Update plan" - Modify plan digest to include this change

HALT level:

[GUARDIAN:HALT] Critical drift - human review required.
Concern: Implementing payment processing.
Plan states: "No payment handling - use third-party Stripe redirect"
Confidence: 0.15
Action: BLOCKED. Awaiting human decision.

Signal Integration

Signals Emitted

Signals Consumed

Drift Log

All assessments are logged for audit:

.claude/guardian-log.jsonl

Format (JSON Lines):

{"ts":"2025-12-19T10:30:00Z","phase":7,"action":"file_write","path":"src/auth/oauth.ts","score":0.55,"level":"WARN","concern":"OAuth not in plan"}
{"ts":"2025-12-19T10:31:00Z","phase":7,"action":"acknowledge","response":"continue","justification":"Product approved OAuth addition"}

Creating the Plan Digest

Automatic Generation

When pipeline starts, guardian creates digest from:

1. PRD.md (primary source)
2. .ideation/ideation-summary.md (if exists)
3. Architecture decisions in PRD Section 8
4. Scope boundaries in PRD Section 3

Manual Override

User can provide custom digest:

"Use this as plan digest: [paste JSON or key points]"

Digest Refresh

Digest can be updated mid-pipeline:

"Update plan digest to include WebSocket support"

This logs the change and adjusts future assessments.

Configuration

.claude/guardian-config.json

{
  "enabled": true,
  "sampling_rate": {
    "default": 5,
    "phase_overrides": {}
  },
  "sensitivity": "normal",
  "thresholds": {
    "notice": 0.8,
    "warn": 0.6,
    "drift": 0.4,
    "halt": 0.2
  },
  "auto_digest": true,
  "log_all_samples": false,
  "phases_to_monitor": [5, 6, 7, 8, 9, 10, 11]
}

Sensitivity Presets

• relaxed: Higher thresholds, fewer interruptions
• normal: Balanced detection
• strict: Lower thresholds, more aggressive detection

Usage Examples

Example 1: Catching Scope Creep

Scenario: TDD Implementer adds caching layer not in PRD.

Sample:

{
  "action": {"type": "file_write", "path": "src/cache/redis-client.ts"},
  "summary": "Implemented Redis caching for API responses"
}

Guardian Assessment:

Plan digest check:
- core_problem: "User management API" - no mention of caching
- boundaries.must_have: No caching requirement
- scope_markers.out_of_scope: "Performance optimizations deferred"

Score: 0.45 (WARN)

Injection:

[GUARDIAN:WARN] Potential scope creep detected.
Concern: Adding Redis caching layer.
Plan states: "Performance optimizations deferred to post-MVP"
Action: Confirm this is essential for MVP functionality.

Example 2: Architecture Violation

Scenario: Implementation uses synchronous file I/O in async codebase.

Sample:

{
  "action": {"type": "file_write", "path": "src/services/data-loader.ts"},
  "summary": "Added fs.readFileSync for config loading"
}

Guardian Assessment:

Plan digest check:
- architecture.patterns: ["Fully async/await", "Non-blocking I/O"]
- architecture.anti_patterns: ["Synchronous file operations"]

Score: 0.30 (DRIFT)

Injection:

[GUARDIAN:DRIFT] Architecture violation detected.
Concern: Using synchronous fs.readFileSync.
Plan states: "Fully async/await, non-blocking I/O required"
Action: PAUSED. Use fs.promises.readFile instead.

Example 3: Approved Deviation

Scenario: Team decided to add feature not in original plan.

Agent Response:

Continue anyway - Product approved adding dark mode support in standup.

Guardian Log:

{
  "ts": "2025-12-19T14:00:00Z",
  "action": "acknowledge",
  "response": "continue",
  "justification": "Product approved adding dark mode support in standup",
  "original_concern": "Dark mode not in PRD scope",
  "logged_by": "agent"
}

Integration with Pipeline

Phase Lifecycle

1. Pipeline Start: Guardian initializes, creates/loads digest
2. Phase Activation: Guardian adjusts sampling rate
3. During Execution: Samples work, assesses drift
4. Phase Completion: Summarizes drift events for phase
5. Pipeline End: Generates drift report

Drift Report (end of pipeline)

.claude/reports/guardian-summary.md

Contains:

• Total samples assessed
• Drift events by phase
• Deviations approved vs reverted
• Recommendations for plan updates

Success Criteria

Guardian is effective when:

• Drift caught within 3 actions of occurrence
• False positive rate < 15%
• No HALT-level issues reach phase completion
• Plan digest accurately reflects intent

See Also

• Pipeline Orchestration skill (starts guardian)
• Signal Manager (guardian signals)
• Hook system (sampling triggers)