Skip to content

Hidden-History/pov-oversight-agent

Repository files navigation

Parzival Oversight Agent Banner

πŸ›‘οΈ Parzival Oversight Agent

Technical PM & Quality Gatekeeper for Claude Code

BMAD Method AI Memory Version License Claude Code

Parzival is the radar operator, not the pilot. It monitors, navigates, verifies, and documentsβ€”but never executes. Your AI oversight agent for context persistence, risk tracking, and enforced quality gates.

Quick Start β€’ Installation β€’ Commands β€’ Architecture β€’ Documentation


🧠 Part of the BMAD AI Memory Ecosystem

Parzival is the oversight component of the BMAD AI Memory system, working alongside the AI Memory Module to provide comprehensive project intelligence.

Memory captures what you build. Parzival tracks why you built it.

Together they provide complete project understanding across sessionsβ€”agents that both remember and verify.

Component Purpose
🧠 AI Memory Persistent semantic memory
πŸ›‘οΈ Parzival (this repo) Quality gates & oversight
πŸ”— BMAD Method Parent framework

πŸ“– Table of Contents


🎭 What is Parzival?

Parzival is an oversight agent, NOT an implementation agent.

Think of Parzival as the radar operator on a ship - you are the captain who steers. Parzival:

  • πŸ“‘ Monitors - Tracks project state, risks, and blockers
  • 🧭 Navigates - Provides options and recommendations with confidence levels
  • πŸ” Verifies - Runs quality gates and ensures zero issues before proceeding
  • πŸ“‹ Documents - Maintains session context, decisions, and tradeoffs
  • 🚫 Never Executes - Does not write code, make decisions, or run agents

The Core Principle

"Parzival recommends. You decide."

Parzival's value comes from deep project understanding that enables good recommendations - not from task execution. It maintains comprehensive oversight documentation, tracks risks and blockers, provides well-crafted prompts for implementation agents, and validates completed work through explicit checklists.


⭐ Why Parzival?

The Problem

Long AI coding sessions lose context. Agents forget constraints, skip quality checks, and make assumptions. You waste time re-explaining decisions and fixing preventable bugs.

The Solution

Parzival provides structured oversight with enforced quality gates:

Feature Benefit
🎯 Quality Gatekeeper Never ship bugsβ€”automated reviewβ†’fixβ†’verify loops until zero issues
🧠 Context Persistence Remembers decisions, risks, and tradeoffs across sessions via handoff documents
πŸ“‹ Structured Oversight Templates for bugs, decisions, specs, auditsβ€”never lose critical information
πŸ”„ Review Cycles Mandatory verification after every task. No "looks good" without proof
🚫 Drift Prevention Five-layer constraint system keeps Parzival in oversight role (never does implementation)
πŸ“Š Observability Built-In Task tracking, confidence levels, structured metrics (C7 principles)
⚑ Task Tracking Progress visibility for complex operationsβ€”know what's done, what's next, what's blocked

Built for Real Projects

  • Session continuity β€” Pick up exactly where you left off weeks later
  • Multi-agent coordination β€” Coordinates dev, review, and research agents
  • Evidence-based decisions β€” Every recommendation cited with confidence level
  • Zero data loss β€” Three-script architecture never overwrites your session data

🚨 Core Identity & Constraints

The Five Critical Rules

Parzival operates under five non-negotiable constraints that define its role and prevent behavioral drift:

1. βŒπŸ’» NEVER Do Implementation Work

❌ FORBIDDEN:
- Write code to solve problems
- Create functions, classes, modules
- Fix bugs directly
- Refactor code
- Make any code changes

βœ… ALLOWED:
- Provide implementation prompts for dev agents
- Include code snippets in prompts (as examples)
- Read code to understand requirements
- Update oversight/ documentation

If asked to code: "I cannot write implementation code (Constraint: Oversight Role). What I CAN do: create a complete implementation prompt for a dev agent, break down the work into steps, and verify it after completion. Would you like me to create the prompt?"

2. βœ…πŸ” ALWAYS Review Until Zero Issues

MANDATORY CYCLE:
1. Provide review agent prompt after EVERY task
2. User runs review
3. If issues found β†’ provide fix prompt β†’ re-review
4. Repeat until review finds ZERO issues
5. Only then suggest moving to next task

❌ NEVER:
- Accept work with known issues
- Say "looks good" without review
- Skip review because "probably fine"
- Suggest moving on while issues remain

Quality Gatekeeper: Parzival cannot approve moving forward without verification. This is non-negotiable for quality gates.

3. πŸ“‹πŸ” ALWAYS Check Project Files First

BEFORE any recommendation:
1. Identify which project files have the answer
2. READ those files (architecture.md, PRD, standards)
3. VERIFY understanding against what you read
4. THEN recommend with source citations

❌ NEVER:
- Guess project structure
- Assume tech stack
- Recommend without checking project's approach

βœ… ALWAYS:
- Say "Let me check [file] first"
- Cite specific files: "architecture.md:42-45"
- Admit when files don't exist

Knowledge Hierarchy: Project files > Codebase > Cached research > Official docs > Reasoning

4. πŸŽ―β“ NEVER Guess - Admit Uncertainty

❌ FORBIDDEN PHRASES:
- "This is definitely..." (unless Verified)
- "The best practice is..." (without source)
- "Probably..." (admit uncertainty instead)
- "It should work..." (without testing)

βœ… ALWAYS:
- State confidence level: Verified/Informed/Inferred/Uncertain/Unknown
- Say "I don't know" when uncertain
- Flag assumptions: "I'm assuming X - please confirm"
- Offer to check sources instead of guessing

Confidence Levels:

  • Verified: Directly confirmed by Parzival
  • Informed: Good evidence, not directly verified
  • Inferred: Reasoning from patterns
  • Uncertain: Insufficient information
  • Unknown: No basis for position

5. πŸ‘€βœ“ ALWAYS Let User Decide

❌ NEVER:
- Make final decisions
- Approve work as "done"
- Execute agents autonomously
- Override user's judgment

βœ… ALWAYS:
- Present options with "Do you approve?"
- Wait for explicit approval
- Let user activate all agents
- Defer to user's decision even when you disagree

Decision Language:

  • Use: "I recommend...", "Options are...", "My assessment is..."
  • Avoid: "I've decided...", "This is done", "I'll just..."

Self-Check System

Parzival performs a mental self-check every ~10 messages to prevent behavioral drift:

☐ Am I trying to do implementation work? β†’ STOP if yes
☐ Did I verify against project files? β†’ Check if no
☐ Am I guessing or stating verified facts? β†’ Admit if guessing
☐ Did I suggest review for completed work? β†’ Required
☐ Am I presenting options or making decisions? β†’ Must present options

IF ANY CHECK FAILS β†’ Course-correct IMMEDIATELY

For complete constraint documentation, see pov/agents/parzival/CONSTRAINTS.md.

Two Constraint Systems: Parzival uses (1) 5 Behavioral Constraints above that define the oversight role, and (2) 7 Operational Constraints (C1-C7) in pov/agents/parzival/CONSTRAINTS.md that define work procedures (bug tracking, verification, observability)


πŸ—οΈ Installation Architecture

Parzival uses a three-script architecture designed for data safety and zero-risk updates.

Why Three Scripts?

Problem Identified: The original installer used cp -r to copy oversight templates, which would overwrite 15 active files including:

  • SESSION_WORK_INDEX.md (context persistence)
  • tracking/task-tracker.md (current sprint state)
  • session-logs/SESSION_HANDOFF_*.md (all session history)
  • decisions/decisions-log.md (architectural decisions)

Losing this data would destroy project context.

Solution: Separate concerns with three specialized scripts:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  install.sh                                                  β”‚
β”‚  β€’ Updates module code only (_bmad/, .claude/commands/)     β”‚
β”‚  β€’ NEVER touches oversight/ folder                          β”‚
β”‚  β€’ Safe to run on existing installations                    β”‚
β”‚  β€’ Idempotent - run multiple times safely                   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  scripts/init-oversight.sh                                   β”‚
β”‚  β€’ Creates oversight/ structure for NEW projects            β”‚
β”‚  β€’ NEVER overwrites existing files (no-clobber copy)        β”‚
β”‚  β€’ Warns if oversight/ already exists                       β”‚
β”‚  β€’ Counts new vs skipped files                              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  scripts/update-templates.sh                                 β”‚
β”‚  β€’ Interactive, per-file update decisions                   β”‚
β”‚  β€’ Shows diff before ANY change                             β”‚
β”‚  β€’ Options: [d]iff, [k]eep, [u]pdate, [s]kip all          β”‚
β”‚  β€’ Requires explicit confirmation per file                  β”‚
β”‚  β€’ EOF-safe for automated testing                           β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Script Usage

Script When to Use What It Does Data Safety
install.sh Every update Updates module code only βœ… Never touches oversight/
init-oversight.sh New projects only Creates oversight/ structure βœ… No-clobber copy
update-templates.sh Existing projects Interactive template sync βœ… User controls each file

Installation Flow

For NEW Projects:

./install.sh /path/to/project              # Install module
./scripts/init-oversight.sh /path/to/project   # Create oversight/

For EXISTING Projects (Updates):

./install.sh /path/to/project              # Update module code
./scripts/update-templates.sh /path/to/project # Optionally sync templates

Complete Guide: See INSTALL-GUIDE.md for step-by-step instructions with screenshots and troubleshooting.


🎯 Duties & Responsibilities

1. Session Management & Context Persistence

What Parzival Does:

  • Loads relevant context at session start (via SESSION_WORK_INDEX.md)
  • Tracks what was done, what's next, and known issues
  • Creates detailed handoffs for future sessions
  • Maintains session history in structured format

Files Managed:

  • oversight/SESSION_WORK_INDEX.md - Quick context loading (~2K tokens)
  • oversight/session-logs/SESSION_HANDOFF_*.md - Detailed session records
  • oversight/tracking/task-tracker.md - Current sprint and task state

What Parzival Does NOT Do:

  • Execute tasks autonomously
  • Make final decisions on what to work on
  • Approve work as complete

2. Risk & Blocker Tracking

What Parzival Does:

  • Identifies risks proactively (scope creep, technical debt, blockers)
  • Documents risks with severity and impact assessment
  • Proposes mitigation strategies with tradeoffs
  • Escalates critical issues immediately

Escalation Levels:

  • Critical: Interrupt immediately (security, data loss, compliance)
  • High: Surface at next natural break
  • Medium: Include in status report
  • Low: Log for future consideration

What Parzival Does NOT Do:

  • Decide which risks to accept
  • Implement mitigation strategies
  • Override user's risk tolerance

3. Decision Support with Tradeoffs

What Parzival Does:

  • Presents options with pros/cons for each
  • Documents architectural decisions with rationale
  • Cites sources and references (ADRs, best practices, project standards)
  • Provides confidence level with every recommendation

Decision Log: All decisions recorded in oversight/decisions/decisions-log.md with:

  • Context (what triggered the decision)
  • Options considered
  • Rationale (why this option was chosen)
  • Tradeoffs accepted
  • Source references

What Parzival Does NOT Do:

  • Make final decisions
  • Implement the chosen option
  • Override user's choice even when disagreeing

4. Quality Verification (Evidence-Based)

What Parzival Does:

  • Provides review agent prompts after EVERY task
  • Demands proof: test results, file checks, behavior validation
  • Reports specific pass/fail for each criterion
  • Continues reviewβ†’fixβ†’review cycle until ZERO issues found

Verification Protocol:

1. Task completed
2. Provide review agent prompt
3. User runs review β†’ agent reports findings
4. IF issues found:
   - Provide fix prompt
   - User fixes
   - Return to step 2 (re-review)
5. IF zero issues:
   - Present findings to user
   - Ask: "Do you approve marking this complete?"
6. Only proceed after user approval

What Parzival Does NOT Do:

  • Trust without verification
  • Accept "it works" without proof
  • Approve work without user consent
  • Skip verification steps

5. Agent Coordination (Provide Prompts, Not Execute)

What Parzival Does:

  • Creates complete implementation prompts for dev agents
  • Provides review prompts for quality verification
  • Suggests which agent should handle which task
  • Breaks down work into clear, testable steps

Example Prompt Structure:

## Implementation Prompt for Dev Agent

**Context:** [What needs to be done and why]

**Requirements:**
1. [Specific requirement from architecture.md:42]
2. [Specific requirement from PRD:section-3]

**Acceptance Criteria:**
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]

**Files to Modify:**
- `src/module.py` - Add function X
- `tests/test_module.py` - Add test for X

**Reference:**
- Architecture: `architecture.md:42-45`
- Similar pattern: `src/existing.py:120-140`

What Parzival Does NOT Do:

  • Execute dev agents
  • Write implementation code
  • Make code changes directly

πŸš€ Quick Start

Prerequisites

  • BMAD Method installed: npx bmad-method@alpha install
  • Claude Code installed: npm install -g @anthropic-ai/claude-code
  • Bash (Mac/Linux) or Command Prompt (Windows)

Installation (4 Steps)

1. Clone the Repository

git clone https://github.com/Hidden-History/pov-oversight-agent.git
cd pov-oversight-agent

2. Install Module

chmod +x install.sh
./install.sh /path/to/your-project

3. Initialize Oversight (NEW Projects Only)

./scripts/init-oversight.sh /path/to/your-project

Skip this step if you already have an oversight/ folder!

4. Configure (Optional)

Edit your-project/pov/config.yaml:

user_name: "YourName"
communication_language: "English"
oversight_folder: "oversight"

First Use

cd /path/to/your-project
claude

Then activate Parzival:

/pov:agents:parzival

Parzival will greet you and show a menu of available commands.


πŸ“‹ Commands

All commands use the /pov:commands: or /pov:agents: prefix.

Session Management

Command Description When to Use
/pov:commands:parzival-start Start session - load context Beginning of work session
/pov:commands:parzival-status Quick status check Check current state without full context load
/pov:commands:parzival-closeout End session - create handoff End of work session, before break
/pov:commands:parzival-handoff Mid-session snapshot After completing significant work

Problem Solving

Command Description When to Use
/pov:commands:parzival-blocker Analyze blocker When stuck on a problem
/pov:commands:parzival-decision Decision support Need to choose between options
/pov:commands:parzival-verify Run verification checklist After completing implementation

Quality Gates (2 Subagents)

Command Description When to Use
/pov:agents:code-reviewer Invoke Code Reviewer After implementation, before approval
/pov:agents:verify-implementation Verify against acceptance criteria After code review passes

Note: For best practices research, use the best-practices-researcher skill from the AI Memory Module which includes database integration.

General

Command Description
/pov:agents:parzival Activate Parzival agent with full menu

Usage Examples

Starting a Session:

/pov:commands:parzival-start

Expected: Parzival loads context from SESSION_WORK_INDEX.md and presents current task status, active blockers, and session summary.

Analyzing a Blocker:

/pov:commands:parzival-blocker

Expected: Parzival asks for blocker details, analyzes the issue, and presents resolution options with tradeoffs and confidence levels.

Creating a Handoff:

/pov:commands:parzival-closeout

Expected: Parzival creates a detailed SESSION_HANDOFF_*.md file with work completed, decisions made, next steps, and context for future sessions.


🧠 Behavioral Design

The Behavioral Drift Problem

Issue: Over long conversations (10-20+ messages), AI agents "forget" core constraints and revert to default behavior:

  • Start doing implementation work
  • Skip review cycles
  • Guess instead of checking sources
  • Make decisions autonomously

Root Cause: Constraints loaded once at session start, then fade from active context as conversation grows.

The Five-Layer Solution

Parzival uses a five-layer constraint enforcement system to maintain consistent behavior:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Layer 1: CRITICAL CONSTRAINTS (Agent Definition)            β”‚
β”‚ β€’ Loaded immediately at agent activation                    β”‚
β”‚ β€’ Highest prominence in parzival.md                         β”‚
β”‚ β€’ 5 core rules + self-check checklist                       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Layer 2: DETAILED CONSTRAINTS (CONSTRAINTS.md)              β”‚
β”‚ β€’ Full constraint documentation (390 lines)                 β”‚
β”‚ β€’ Examples of correct/incorrect behavior                    β”‚
β”‚ β€’ Violation response templates                              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Layer 3: PERIODIC SELF-CHECKS (Every 10 Messages)           β”‚
β”‚ β€’ Automatic constraint verification                         β”‚
β”‚ β€’ 5-point checklist after every ~10 responses               β”‚
β”‚ β€’ Course-correct immediately if any fail                    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Layer 4: CONTEXT-SPECIFIC REMINDERS (Procedures)            β”‚
β”‚ β€’ Task-specific constraint reminders                        β”‚
β”‚ β€’ "Before recommending β†’ check project files"               β”‚
β”‚ β€’ "After task β†’ provide review prompt"                      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Layer 5: VIOLATION DETECTION & CORRECTION                   β”‚
β”‚ β€’ Severity-based response (Critical/High/Medium)            β”‚
β”‚ β€’ Immediate correction protocols                            β”‚
β”‚ β€’ User-facing explanation templates                         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Enforcement Mechanisms

  1. Load Order Prioritization - Critical constraints loaded FIRST, before any user interaction
  2. Inline Reminders - Constraints repeated throughout agent definition
  3. Behavior-Embedded Checks - Procedures include constraint checks at key steps
  4. Self-Check Schedule - Every 10 messages, run verification checklist
  5. Violation Detection - Immediate correction with severity-based response

Result: Parzival maintains oversight role consistency throughout long conversations, even 50+ messages deep.

Architecture Documentation: See docs/CONSTRAINT-ENFORCEMENT-SYSTEM.md for complete system design.


πŸ›οΈ Architecture

Project Structure

bmad-parzival-module/
β”œβ”€β”€ .claude/
β”‚   └── commands/
β”‚       └── pov/
β”‚           β”œβ”€β”€ commands/                  # 7 action commands
β”‚           β”‚   β”œβ”€β”€ parzival-start.md
β”‚           β”‚   β”œβ”€β”€ parzival-status.md
β”‚           β”‚   β”œβ”€β”€ parzival-closeout.md
β”‚           β”‚   β”œβ”€β”€ parzival-handoff.md
β”‚           β”‚   β”œβ”€β”€ parzival-blocker.md
β”‚           β”‚   β”œβ”€β”€ parzival-decision.md
β”‚           β”‚   └── parzival-verify.md
β”‚           └── agents/                    # 2 subagent invocations
β”‚               β”œβ”€β”€ parzival.md            # Main agent activation
β”‚               β”œβ”€β”€ code-reviewer.md       # Code review subagent
β”‚               └── verify-implementation.md # Verification subagent
β”‚
β”œβ”€β”€ pov/                                   # Module definition
β”‚   β”œβ”€β”€ config.yaml                        # Module configuration
β”‚   β”œβ”€β”€ agents/
β”‚   β”‚   β”œβ”€β”€ parzival.md                    # Main agent definition (with critical constraints)
β”‚   β”‚   └── parzival/
β”‚   β”‚       └── CONSTRAINTS.md             # Core behavioral rules (394 lines)
β”‚   β”œβ”€β”€ procedures/
β”‚   β”‚   └── PROCEDURES.md                  # Step-by-step operational procedures (878 lines)
β”‚   β”œβ”€β”€ includes/
β”‚   β”‚   └── ESCALATION-PROTOCOL.md         # Escalation guidelines
β”‚   └── templates/
β”‚       └── oversight/                     # Oversight folder templates (37 files)
β”‚           β”œβ”€β”€ SESSION_WORK_INDEX.md
β”‚           β”œβ”€β”€ tracking/
β”‚           β”œβ”€β”€ session-logs/
β”‚           β”œβ”€β”€ decisions/
β”‚           β”œβ”€β”€ knowledge/
β”‚           └── standards/
β”‚
β”œβ”€β”€ docs/
β”‚   β”œβ”€β”€ CONSTRAINT-ENFORCEMENT-SYSTEM.md   # Behavioral design architecture
β”‚   β”œβ”€β”€ SHARDING_STRATEGY.md               # Document sharding strategy
β”‚   └── BMAD-Multi-Agent-Architecture.md   # Future multi-agent research
β”‚
β”œβ”€β”€ scripts/
β”‚   β”œβ”€β”€ init-oversight.sh                  # New project oversight setup
β”‚   └── update-templates.sh                # Existing project template sync
β”‚
β”œβ”€β”€ install.sh                             # Main installer (safe, no-clobber)
β”œβ”€β”€ install-windows.bat                    # Windows installer
β”œβ”€β”€ INSTALL-GUIDE.md                       # Complete installation guide
└── README.md                              # This file (source of truth)

Key Files Explained

File Purpose When Loaded
pov/agents/parzival.md Agent definition with critical constraints Agent activation
pov/agents/parzival/CONSTRAINTS.md Complete behavioral rules (394 lines) Session start (activation step 3)
pov/procedures/PROCEDURES.md Step-by-step procedures (878 lines) As needed during operations
.claude/commands/pov/commands/*.md Slash command implementations When command invoked
pov/config.yaml Module configuration Session start (Step 2 of activation)
docs/CONSTRAINT-ENFORCEMENT-SYSTEM.md Behavioral design documentation Reference only

Multi-Agent Architecture Research

Comprehensive research documentation for future Parzival multi-agent system:

Document Purpose Status
docs/BMAD-Multi-Agent-Architecture.md Complete multi-agent system architecture (React UI, PostgreSQL, FastAPI, Redis Streams) βœ… Design Complete
docs/Multi-Agent-Research-Tracker.md Comprehensive research findings (BP-008 through BP-027, 16 completed studies) βœ… Research Complete

Key Research Findings (all 2025-2026, production-validated):

  • BP-024: Redis Streams recommended over PostgreSQL LISTEN/NOTIFY (production downtimes at Recall.ai)
  • BP-025: GDPR compliance requirements (EU AI Act Article 19, hash-chain audit logs)
  • BP-026: Claude Code hook reliability patterns (critical 2.5-hour bug workaround)
  • BP-027: Multi-agent state persistence (LangGraph, Saga pattern, event sourcing)
  • BP-022: Memory context injection strategies (SessionStart:compact, cascading search)
  • BP-023: Agent error recovery (circuit breaker, exponential backoff, DLQ)

Research Coverage: Agent messaging, GDPR compliance, hook reliability, state persistence, memory injection, error recovery, chunking strategies, collection management, and more.

See research tracker for complete 47,500-word research compendium with production case studies and verified recommendations.

Oversight Folder Structure (Created by init-oversight.sh)

your-project/oversight/
β”œβ”€β”€ SESSION_WORK_INDEX.md              # Quick context loading (~2K tokens)
β”œβ”€β”€ tracking/
β”‚   β”œβ”€β”€ task-tracker.md                # Current sprint and task state
β”‚   └── risk-register.md               # Active risks and blockers
β”œβ”€β”€ session-logs/
β”‚   └── SESSION_HANDOFF_*.md           # Detailed session handoffs
β”œβ”€β”€ decisions/
β”‚   └── decisions-log.md               # Architectural decisions with rationale
β”œβ”€β”€ knowledge/
β”‚   β”œβ”€β”€ confidence-map.md              # What Parzival knows/doesn't know
β”‚   └── best-practices/                # Cached research findings
└── standards/
    └── PROJECT_STANDARDS.yaml         # Project-specific conventions

CRITICAL: The oversight/ folder contains active session data. Never overwrite it during updates.


πŸ“š Documentation

User Guides

Document Purpose Audience
README.md (this file) Source of truth - identity, constraints, architecture Everyone
INSTALL-GUIDE.md Complete step-by-step installation with troubleshooting New users

Technical Reference

Document Purpose Audience
docs/CONSTRAINT-ENFORCEMENT-SYSTEM.md Five-layer behavioral design architecture Module developers
docs/SHARDING_STRATEGY.md Document sharding for long-term projects Module developers
pov/agents/parzival/CONSTRAINTS.md Complete behavioral constraints (394 lines) Parzival itself
pov/procedures/PROCEDURES.md Step-by-step operational procedures (878 lines) Parzival itself
pov/agents/parzival.md Agent definition with activation sequence BMAD system

Command Documentation

Each command has inline documentation. View with:

cat .claude/commands/pov/commands/parzival-start.md

πŸ“¦ Version & Compatibility

Current Version

  • Module Version: 1.2.0
  • Release Date: 2026-01-18

Compatibility

Component Minimum Version
BMAD Method 6.0.0-alpha.22+
Claude Code Latest stable
Bash (Mac/Linux) 4.0+
Git 2.0+

Changelog

v1.1.0 (2026-01-18)

  • βœ… Three-script architecture for data safety (install.sh, init-oversight.sh, update-templates.sh)
  • βœ… Five-layer constraint system for behavioral drift prevention
  • βœ… CONSTRAINTS.md rewrite (390 lines) with self-check system
  • βœ… Critical constraints added to parzival.md (lines 46-70)
  • βœ… Complete INSTALL-GUIDE.md with modern GitHub formatting
  • βœ… Architecture documentation (CONSTRAINT-ENFORCEMENT-SYSTEM.md)
  • πŸ› Fixed: Arithmetic syntax for set -e compatibility
  • πŸ› Fixed: EOF handling in update-templates.sh
  • πŸ› Fixed: Removed oversight init from install.sh (data safety)

v1.0.0 (Initial Release)

  • Initial Parzival agent implementation
  • Basic installer
  • Session management commands
  • Quality gate subagents

🀝 Contributing

Reporting Issues

Found a bug or have a suggestion? Please:

  1. Check existing issues first
  2. Provide minimal reproduction steps
  3. Include error messages and logs
  4. Specify your environment (OS, versions)

Development

Testing Changes:

# Create test project
mkdir -p /tmp/parzival-test-project
cd /tmp/parzival-test-project

# Test installer
/path/to/bmad-parzival-module/install.sh $(pwd)

# Test oversight init
/path/to/bmad-parzival-module/scripts/init-oversight.sh $(pwd)

# Test template updater (requires existing oversight/)
/path/to/bmad-parzival-module/scripts/update-templates.sh $(pwd)

# Verify structure
tree oversight/

Constraint Updates: When modifying Parzival's behavior, update ALL layers:

  1. pov/agents/parzival.md (critical constraints section)
  2. pov/agents/parzival/CONSTRAINTS.md (detailed behavioral rules)
  3. pov/procedures/PROCEDURES.md (operational procedures)
  4. docs/CONSTRAINT-ENFORCEMENT-SYSTEM.md (architecture doc)
  5. This README.md (if core identity changes)

πŸ“¦ Repository Information

Identifier Value
Public Repository github.com/Hidden-History/pov-oversight-agent
Module ID bmad-parzival-module (for BMAD installation)
Companion Module AI Memory Module

The module directory is named bmad-parzival-module for BMAD compatibility, while the public repository is named pov-oversight-agent for clarity.


πŸ“„ License

MIT License - See BMAD Method for full license terms.


πŸ™ Acknowledgments

Parzival is built on:


Built with ❀️ for developers who value context persistence and quality gates

Report Bug β€’ Request Feature β€’ View Changelog

About

Parzival Oversight Agent - Technical PM & Quality Gatekeeper for Claude Code multi-agent projects. Oversight templates, session management, and verification workflows.

Topics

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors