Paivot - The Leading Software Methodology, Rebuilt for AI Agents

The Problem

AI agents are powerful but undisciplined

Left unconstrained, AI coding agents exhibit predictable failure modes that compound over time.

✗

Superficial Testing

Skip testing entirely or write tests that verify nothing meaningful. Mocks everywhere, no real integration.

␡

Isolated Components

Build components that work alone but never integrate. Vertical slices replaced by horizontal layers.

⊘

Lost Context

Lose context across sessions and compaction. Make contradictory decisions after forgetting earlier constraints.

★

Technical Novelty Bias

Ignore business requirements in favor of technically interesting work. Build what's fun, not what's needed.

⚠

Premature Completion

Mark work as "done" without proof it actually works. Claim success without running real tests against real services.

↺

Repeated Mistakes

Rediscover the same problems every session. No mechanism to retain what was learned, so the same errors recur at full cost.

Paivot solves this by applying proven balanced-team engineering practices through specialized AI agents with strict role boundaries, enforced workflows, and hard quality gates. An Obsidian vault serves as an evolving knowledge graph where decisions, patterns, and methodology survive across sessions and compound over time. Three purpose-built Go binaries power the system: pvg (scope guard and lifecycle hooks), nd (git-native issue tracker), and vlt (vault CLI). They sit outside the LLM, so the orchestrator cannot "forget" or be "convinced" to skip steps.

Cognitive Architecture

Three layers, one flywheel

Agents operate across identity, knowledge, and execution. Each layer feeds the others, compounding value with every session.

Identity

AGENTS.md / CLAUDE.md

Your constitution. Principles, values, hard rules. Loaded every session. Rarely changes. Defines coding philosophy, testing requirements, and communication style.

Knowledge

Obsidian Vault

Your brain. Everything learned across all projects. Methodology, conventions, patterns, decisions, and debugging knowledge. Grows continuously via vlt.

Execution

nd

Your hands. Work items, blockers, dependencies for the current project. nd is a git-native issue tracker that stores issues as Obsidian-compatible markdown.

You (Human)

Business Owner

Discovery & Framing

Business outcomes

Designer

User experience

Architect

Technical approach

Optional adversarial review (specialist_review)

BA Challenger

APPROVED / REJECTED

Design Challenger

APPROVED / REJECTED

Arch Challenger

APPROVED / REJECTED

Sr. PM

Creates backlog

→ backlog → ← gaps found ←

Anchor

Adversarial review

Execution Phase

Orchestrator + Vault

Dispatches all work, never writes code

Developer

Implements + proves

→ delivered → ← rejected ←

PM-Acceptor

Evidence-based review

Retro

Harvests learnings

Traditional Balanced Teams	Paivot
Persistent human teams	Ephemeral agents, spawned per task
Pair programming	Orchestrated dispatch with PM review
Implicit shared context	Self-contained stories with ALL context embedded
Trust-based review	Evidence-based delivery with recorded proof
Centralized project tracker	nd (git-native, CLI-first, Obsidian-compatible)
INVEST stories for team clarity	INVEST stories as structural requirement (Independence enables parallel agent execution)
Organic learning through pairing	Vault-captured knowledge with governance and promotion workflow
Flexible role boundaries	Strict enforcement (agents lack judgment to flex)
Prompt-based reminders	Structural enforcement via scope guard + vault governance

Specialized Agents

Eleven agents, each with a single job

Agents cannot spawn subagents. Only the orchestrator dispatches work. This ensures a single point of coordination.

Business Analyst opus

Captures business outcomes through iterative questioning. Owns BUSINESS.md. Part of the Balanced Leadership Team. Cannot ask user questions directly; relays through orchestrator.

Designer opus

Captures user needs and DX for all product types: UI, API, CLI, database. Owns DESIGN.md. Part of the Balanced Leadership Team.

Architect opus

Designs system architecture and defines technical constraints. Owns ARCHITECTURE.md. Ensures technical coherence across the system.

Sr. PM opus

Final gatekeeper for D&F. Creates the backlog from D&F documents. Embeds ALL context into self-contained stories so agents need nothing else.

Anchor opus

Adversarial reviewer in two modes: backlog review (gaps, walking skeletons, integration stories) and milestone review (real delivery, no mocks, skills consulted).

Developer opus

Ephemeral. Implements one story, runs tests, records proof. Supports optional hard-tdd mode: RED phase (tests only) or GREEN phase (implementation only, test files locked by git).

PM-Acceptor sonnet

Reviews one delivered story using evidence-based approach. Accepts (closes) or rejects with structured EXPECTED/DELIVERED/GAP/FIX notes.

Retro sonnet

Harvests learnings from completed epics. Writes actionable insights to .vault/knowledge/ with actionable: pending for future sessions.

BA Challenger sonnet

Adversarial reviewer of BUSINESS.md. Checks for omissions, hallucinations, and scope creep against user context. Returns APPROVED or REJECTED. Only spawned when specialist_review is enabled.

Designer Challenger sonnet

Adversarial reviewer of DESIGN.md. Checks for unmet user needs, hallucinations, and contradictions with BUSINESS.md. Returns APPROVED or REJECTED. Only spawned when specialist_review is enabled.

Architect Challenger sonnet

Adversarial reviewer of ARCHITECTURE.md. Checks for unmet requirements, untraceable decisions, and contradictions across D&F documents. Returns APPROVED or REJECTED. Only spawned when specialist_review is enabled.

Knowledge Governance

Two-tier vault: system and project

Knowledge lives in Obsidian and is accessed at runtime via vlt. System knowledge is shared across projects; project knowledge stays local.

System Vault

Shared across all projects. Contains methodology, conventions, patterns, decisions, and debugging knowledge. Protected by the scope guard. Changes require proposals and triage.

methodology/ Paivot methodology as atomic notes
conventions/ Working conventions (testing, Python, etc.)
decisions/ Architectural decisions with rationale
patterns/ Reusable solutions and idioms
debug/ Problems and their resolutions
_inbox/ Writable directly for proposals and captures

Project Vault

Lives at .vault/knowledge/ in each repo. Contains project-specific knowledge, settings, and session artifacts. Accessed through vlt only; direct file edits are blocked.

Project-specific patterns and decisions
Session operating mode and settings
Local knowledge that doesn't belong in the system vault
Managed via /vault-settings command

Slash Commands

/vault-capture

Deliberate knowledge capture pass. Routes knowledge to the global vault or project vault based on scope.

/vault-evolve

Identifies improvements to vault content. Creates proposals for system notes; edits project notes directly.

/vault-triage

Reviews and accepts/rejects pending proposals for system-scoped vault notes. The approval gate for knowledge changes.

/vault-settings

View and configure project-level settings. Key settings: architecture.c4 (C4 model), workflow.fsm (status machine), project_vault_git (git tracking), default_scope, stack_detection, proposal expiry, and more.

/vault-status

Shows vault health: note counts by folder, project vault status, and pending proposals.

/intake

5-phase feedback-to-backlog pipeline: collect user feedback, gather vault context, detect project stack, delegate to the Sr. PM agent for story creation, then triage into the backlog. The primary entry point for turning ideas into work.

/piv-loop

Unattended execution loop. Dispatches delivered stories to PM-Acceptor, rejected stories back to Developer, and ready stories to Developer. Runs until blocked or protected-main handoff.

/piv-cancel-loop

Cancel the active execution loop. Stops dispatching new work while letting in-flight agents complete.

Skills

vault-knowledge

Teaches agents how to interact with the vault: when to capture, what to capture, how to format notes, and how to search effectively.

vlt-skill

Complete vlt command reference, agentic patterns, and advanced techniques. Fetched from GitHub at install time.

Vault-backed issue tracker storing issues as Obsidian-compatible markdown. Multi-session work, dependency tracking, and persistent context that survives compaction.

Architecture-as-code using the C4 model and Structurizr DSL. Teaches agents to maintain workspace.dsl, validate boundaries, and generate diagrams.

Project Settings

All settings are project-local, stored in .vault/knowledge/.settings.yaml, and managed via pvg settings <key>=<value>. Run pvg settings to see current values.

dnf.specialist_review

Enable adversarial Challenger agents to review each D&F document. Default: false

dnf.max_iterations

Max challenger review loops before user escalation. Range 1-5. Default: 3

workflow.fsm

Structural enforcement of nd status transitions (open → in_progress → delivered → closed). Default: false

architecture.c4

Maintain a Structurizr DSL file alongside ARCHITECTURE.md as a machine-checkable twin. Default: false

bug_fast_track

Allow PM-Acceptor to create bugs directly during review instead of routing through Sr. PM. Default: false

project_vault_git

Git tracking for .vault/knowledge/ notes. Options: tracked, ignored, ask. Default: ask

default_scope

Default scope for new vault notes. Options: system, project. Default: system

auto_capture

Automatically capture knowledge notes during work sessions. Default: true

stack_detection

Detect and output tech stack at session start for concurrency limit selection. Default: false

loop.persist_across_sessions

Whether execution loop state persists across sessions. Default: false

proposal_expiry_days

Days before system vault proposals are flagged as stale. Default: 30

session_start_max_notes

Max vault notes summarized per subfolder at session start. Default: 10

Structural Enforcement

"Advisory instructions do not work for subagents."

LLMs can be "convinced" to deviate and lose rules after context compaction. The pvg Go binary implements structural enforcement at the hook level. It sits outside the LLM and cannot be circumvented by prompt manipulation.

Scope guard in action

Agent attempts Edit methodology/Testing Philosophy.md

PreToolUse hook fires pvg guard intercepts Edit call

Protected directory detected BLOCKED: Direct modification of system-scoped vault content

Agent uses correct path vlt vault="Claude" append ... -- ALLOWED

Protected directories

methodology/ conventions/ decisions/ patterns/ debug/ concepts/ projects/ people/ _inbox/ (writable) _templates/ (writable)

System vault directories are protected. Only _inbox/ and _templates/ are writable directly. All other changes require /vault-evolve to create a proposal and /vault-triage to apply it. The vlt CLI always bypasses the guard.

Scope Guard

PreToolUse hook intercepts Edit, Write, and Bash commands. Blocks direct writes to protected vault directories. Exit code 2 = blocked.

vlt-Only Access

Project vault at .vault/knowledge/ requires vlt commands for all access. Direct file edits are blocked. vlt provides locking for concurrent agent safety.

Concurrency Limits

Stack-aware defaults. Heavy stacks (Rust, iOS, C#, CloudFlare Workers): 2 dev + 1 PM = 3 total. Light stacks (Python, TypeScript): 4 dev + 2 PM = 6 total. Auto-detected from project files. Users can override these defaults.

Five Lifecycle Hooks

SessionStart loads context. PreToolUse guards scope. PreCompact captures knowledge. Stop checks the capture checklist. SessionEnd logs the session.

Agent Operating Rules

Three rules every agent must follow: invoke skills via the Skill tool (never Bash), never edit vault files directly (SHA-256 integrity verification), and stop immediately on system errors instead of retrying.

Dispatcher Guard

PreToolUse hook blocks the orchestrator from writing D&F files (BUSINESS.md, DESIGN.md, ARCHITECTURE.md) unless a BLT agent is active. Prevents the main agent from bypassing the balanced team.

Advanced Capabilities

Beyond enforcement: built-in intelligence

Machine-checkable architecture, convergence protocols, and unattended execution -- capabilities that make Paivot more than a process framework.

C4 Architecture-as-Code

A Structurizr DSL file lives alongside ARCHITECTURE.md as a machine-checkable twin. Defines containers, components, and their allowed dependencies. The Anchor agent validates that code respects declared boundaries. Generated diagrams keep documentation in sync with reality.

Opt-in via architecture.c4 setting · Structurizr DSL · Auto-generated diagrams

BLT Convergence Protocol

After all three Discovery & Framing documents exist (BUSINESS.md, DESIGN.md, ARCHITECTURE.md), every BLT agent cross-reviews the other two for consistency. Contradictions are surfaced before the backlog is created. The system must reach BLT_ALIGNED status before the Sr. PM begins story creation.

BA + Designer + Architect cross-review · Must reach BLT_ALIGNED

Mandatory Questioning Rounds

BLT agents follow a structural execution sequence: their first output must be QUESTIONS_FOR_USER, never a document. The orchestrator relays questions to the user, then resumes the agent with answers. This ensures requirements are clarified before any document is produced. Light D&F means fewer rounds, not zero rounds.

First output = QUESTIONS_FOR_USER · Relay loop via orchestrator

Execution Loop (`/piv-loop`)

Unattended dispatch loop that runs the full delivery pipeline autonomously. Priority order: accept delivered stories first, fix rejected stories second, implement ready stories third. Concurrency-limited to 2 developer agents + 1 PM-Acceptor (3 total subagents max).

Priority: delivered > rejected > ready · Concurrency defaults by stack type (configurable)

FSM Workflow Enforcement

Optional state machine on nd issue status transitions. pvg guard validates that every status change follows the allowed graph -- for example, you cannot skip from open directly to closed without passing through in-progress and delivered. Invalid transitions are blocked with a clear error message.

Configurable via workflow.fsm setting · pvg guard validates transitions

Dispatcher Mode

When Paivot is engaged, the orchestrator becomes coordinator-only. It spawns agents and relays questions but never writes code, documents, or stories itself. This is enforced structurally by the pvg hook system, not just by prompt instructions. The orchestrator dispatches; agents deliver.

Orchestrator = coordinator only · Enforced by pvg hook · Agents deliver

Specialist Review (Adversarial D&F)

When specialist_review is enabled, each D&F document is adversarially reviewed by a dedicated Challenger agent before proceeding to the next phase. Challengers check for omissions, hallucinations, and contradictions. If rejected, the creator agent revises and resubmits. Up to max_iterations rounds (default 3) before escalating to the user.

Opt-in via dnf.specialist_review · 3 challengers · Binary APPROVED/REJECTED

Hard-TDD Mode

Opt-in per story via the hard-tdd label. Splits development into two phases: RED (write tests only, no implementation) and GREEN (write implementation only, test files locked). Git diff verifies test immutability between phases. The PM-Acceptor adjusts its review criteria based on the current phase.

Opt-in via hard-tdd label · RED/GREEN phases · Git-enforced test lock

Trunk-Based Development

All work happens on short-lived story/<ID> branches off main. No long-lived feature branches. Developer agents create branches, implement, and the orchestrator manages merges back to main after acceptance. Protected-main handoff pauses the loop when human review is needed.

main + story/<ID> branches · Protected-main handoff · No long-lived branches

Delivery Pipeline

Every story follows a strict delivery pipeline

No shortcuts. Verification before review. Evidence before acceptance. Learnings before forgetting.

✍

Implement Developer builds + tests

→

✎

Record Proof Test results, coverage, output

→

✓

Deliver Mark delivered, NOT closed

→

⚙

Verify Integration tests must pass

→

⚲

PM Review Evidence-based acceptance

→

✔

Accept PM closes or rejects

Testing Philosophy

Mocks in integration tests are an automatic rejection. Only real calls prove functionality.

Type	Mocks?	Required
Unit	OK	80% coverage
Integration	Never	Every story
E2E	Never	Milestones

Evidence-Based Review

PM-Acceptor trusts developer proof unless suspicious. Every rejection must include four parts:

Part	Purpose
Expected	Quote the AC
Delivered	What code does
Gap	Where it falls short
Fix	Actionable guidance

Knowledge Lifecycle

AI agents cannot learn implicitly. Knowledge must be captured, stored, and injected deliberately via the vault.

Stage	Actor
Record	Developer notes in story
Harvest	Retro agent extracts
Store	.vault/knowledge/ (actionable: pending)
Promote	/vault-evolve + /vault-triage

Hard-TDD Mode

Opt-in per story via hard-tdd label. Two-phase developer workflow with git-enforced test immutability.

Phase	What happens
RED	Test Author writes tests only
Review	PM verifies tests cover all ACs
GREEN	Implementer writes code (cannot touch tests)
Verify	Git diff confirms test immutability

Intake Pipeline

The /intake command converts raw user feedback into a prioritized backlog through five structured phases.

Phase	What happens
Collect	Gather user feedback and intent
Context	Search vault for related knowledge
Detect	Identify project stack and constraints
Delegate	Sr. PM creates stories from context
Triage	Prioritize and slot into backlog

Vault Integrity

SHA-256 checksums protect vault content from accidental or unauthorized modification. Agents never edit vault files directly.

Mechanism	Purpose
SHA-256 baseline	Detects unauthorized file changes
vlt-only writes	All edits go through the CLI
Scope guard	Blocks direct Edit/Write to vault
Acknowledgement	External changes require explicit ack

Getting Started

Up and running in four steps

Requires vlt 0.9.5+, nd 0.10.5+, an Obsidian vault, and Go 1.26.1+.

Install Prerequisites

Install vlt (vault CLI) and nd (git-native issue tracker). Pre-built binaries are available on each project's GitHub Releases page -- no Go compiler needed. You also need an Obsidian vault named "Claude".

# Option A: Download pre-built binaries from GitHub Releases
# https://github.com/paivot-ai/vlt/releases
# https://github.com/paivot-ai/nd/releases

# Option B: Build from source (requires Go 1.26.1+)
go install github.com/paivot-ai/vlt@latest
go install github.com/paivot-ai/nd@latest

vlt version  # should print vlt 0.9.5+

Install Paivot Graph

Clone the repo and run the installer. This installs the pvg binary (downloaded or built from source), fetches the vlt skill, and registers the plugin with Claude Code.

git clone https://github.com/paivot-ai/paivot-graph.git
cd paivot-graph
make install

Seed the Vault

Populate your Obsidian vault with agent prompts, methodology notes, and behavioral conventions. This is idempotent and safe to run again.

make seed

# Force-update all notes with latest content
make reseed

Start a Session

Restart Claude Code. The SessionStart hook will automatically search your vault for project context, load the operating mode, and display relevant knowledge.

# Start Claude Code in your project
claude

# Check vault health
/vault-status

The leading software methodology,reborn for AI agents

AI agents are powerful but undisciplined

Superficial Testing

Isolated Components

Lost Context

Technical Novelty Bias

Premature Completion

Repeated Mistakes

Three layers, one flywheel

AGENTS.md / CLAUDE.md

Obsidian Vault

nd

Eleven agents, each with a single job

Two-tier vault: system and project

System Vault

Project Vault

Slash Commands

Skills

Project Settings

Scope guard in action

Protected directories

Scope Guard

vlt-Only Access

Concurrency Limits

Five Lifecycle Hooks

Agent Operating Rules

Dispatcher Guard

Beyond enforcement: built-in intelligence

C4 Architecture-as-Code

BLT Convergence Protocol

Mandatory Questioning Rounds

Execution Loop (/piv-loop)

FSM Workflow Enforcement

Dispatcher Mode

Specialist Review (Adversarial D&F)

Hard-TDD Mode

Trunk-Based Development

Every story follows a strict delivery pipeline

Testing Philosophy

Evidence-Based Review

Knowledge Lifecycle

Hard-TDD Mode

Intake Pipeline

Vault Integrity

Up and running in four steps

Install Prerequisites

Install Paivot Graph

Seed the Vault

Start a Session

One methodology, three platforms

The leading software methodology,
reborn for AI agents

Execution Loop (`/piv-loop`)