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

json

{
  "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

json

{
  "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:

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:

Criterion	Weight	Description
Scope alignment	0.3	Is this within defined scope?
Constraint compliance	0.25	Does this respect constraints?
Architecture adherence	0.25	Does this follow chosen patterns?
Decision consistency	0.2	Does this align with key decisions?

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

Signal	Trigger	Payload
GUARDIAN_STARTED	Guardian activates	`{phase, digest_hash}`
GUARDIAN_WARN	WARN threshold crossed	`{concern, confidence, suggestion}`
GUARDIAN_DRIFT	DRIFT threshold crossed	`{concern, confidence, options}`
GUARDIAN_HALT	HALT threshold crossed	`{concern, confidence, escalation}`
GUARDIAN_ACKNOWLEDGED	Agent responds to drift	`{response, justification}`

Signals Consumed

Signal	Action
PIPELINE_STARTED	Initialize guardian, create digest if missing
PHASE_CHANGED	Adjust sampling rate for new phase
PLAN_UPDATED	Reload plan digest
GUARDIAN_DISABLE	Temporarily disable monitoring

Drift Log

All assessments are logged for audit:

.claude/guardian-log.jsonl

Format (JSON Lines):

json

{"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:

PRD.md (primary source)
.ideation/ideation-summary.md (if exists)
Architecture decisions in PRD Section 8
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

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:

json

{
  "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:

json

{
  "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:

json

{
  "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

Pipeline Start: Guardian initializes, creates/loads digest
Phase Activation: Guardian adjusts sampling rate
During Execution: Samples work, assesses drift
Phase Completion: Summarizes drift events for phase
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

Search AI Tools

plan-guardian-majiayu000-claude-skill-regist

Install this agent skill to your Project

SKILL.md

Plan Guardian Skill

Metadata

Description

Architecture

Activation

Plan Digest

Digest Location

Digest Schema

Sampling Mechanism

Hook Integration

Sample Payload

Sampling Rate

Drift Detection

Assessment Criteria

Response Levels

Injection Format

Signal Integration

Signals Emitted

Signals Consumed

Drift Log

Creating the Plan Digest

Automatic Generation

Manual Override

Digest Refresh

Configuration

.claude/guardian-config.json

Sensitivity Presets

Usage Examples

Example 1: Catching Scope Creep

Example 2: Architecture Violation

Example 3: Approved Deviation

Integration with Pipeline

Phase Lifecycle

Drift Report (end of pipeline)

Success Criteria

See Also