Repo OS — Operator Guide

This is the reference for you, the human operator. It covers how to set up projects, run sessions, and work with AI agents safely. Agents do not read this file — it’s for you.

Decision Navigator

Not sure where to start? Answer a quick question to get the exact action, prompt, and next step.

TL;DR

Repo OS is a governance layer for AI-assisted development. Three things to know:

Setup — New Project

Step 1 — Create repo from template operator only

Go to the template on GitHub. Click Use this template → Create a new repository. Set name, owner, visibility. Click create.

Step 2 — Clone

Step 3 — Build your project spec prompt 0

Start a Claude Code session and paste:

The AI interviews you to fill out every spec file — product, architecture, design system, data models, features, integrations, and boundaries. No code is written. You define everything. Output goes to a versioned directory under docs/spec/compiled/.

When the AI confirms “Spec complete”, move to Step 4.

Step 4 — Initialize Repo OS prompt A

Paste:

Prompt A now runs in three phases: Phase 1 activates the Advisory Board to review your specs (specialists run in parallel). Phase 2 presents a synthesized refinement report for your per-item review. Phase 3 validates the Repo OS (agents, gates, decisions). When it says “Repo OS ready”, move to Step 5.

Step 5 — Start building prompt B

For every development session going forward, paste:

Prompt B enforces the development operating model: plan before code, small changes, gates before commits, session log at close. The compiled spec in docs/spec/compiled/ (active version per manifest.json) is the source of truth for what to build.

Triggers — What to Run and When

Spec Builder — Prompt 0

Prompt 0 is a guided interview that builds your complete project specification before any code is written. The AI asks questions. You answer. Every detail is captured in structured spec files.

The spec files

Design system: three paths

Adding a feature later use Prompt T

Prompt 0 no longer has a Feature mode (Decision 0010). To add a feature to an existing spec, use Prompt T with a significant-feature description — it produces a two-brief task group: Brief 1 writes the feature spec to docs/spec/compiled/{active}/features/brief-{name}.md, Brief 2 builds it. The advisory board (including the conditional specialists triggered by what the feature touches) reviews as part of that flow.

Daily Workflow — The Execution Loop

Every unit of work follows a sequence of phases. This applies to every feature, fix, and change. For work planned via Prompt T, the plan and operator approval are sealed in a handoff bundle at task creation; the build session runs a deterministic drift-check and jumps straight to build (Decision 0038). Sessions with no bundle fall through to the legacy plan → approval flow. See Phase Model for full sequences per session type.

HVST Protocol — when things break

When debugging or instability appears, agents switch from the standard loop to HVST to prevent thrashing:

Phase Model

Every session follows a declared sequence of phases tracked in .claude/.state/phase-state. Hooks enforce phase-appropriate actions automatically — you don’t manage the state file directly. Each phase has an automation tag indicating who acts:

Standard Build

Task Group (Brief N of M)

Hotfix

Loops: verify → build only. No review phase — A5 cohesion skipped for speed.

Editor-Live Decision 0023

Continuous visual-development session type for operator-driven editing workflows. The operator edits files in an external editor; the agent responds to each saved change. No plan gate — the operator’s live edits are the plan. Child mode only.

Experiment

Auto vs Review Mode

The operator chooses a session mode when the work is approved — at the Prompt T brief approval (recorded in the handoff bundle and read by drift-check), or at the legacy plan-approval gate when no bundle exists:

Solo Mode

Solo mode enables direct merge to main at session close. Set per-session in the phase-state file.

• At close (auto): merge branch to main directly, then seal branch
• At close (review): agent pauses at op-review for operator acceptance, then merges
• Merge failure: git merge --abort, operator notified with conflict details
• Excluded: experiment/* (never merge) and release/* (excluded from solo merge)

Agent Roles

Agents across four teams: Build Team (implementation — 8 agents, incl. the Pragmatist plan-gating reviewer), Audit/Operations (health checks, telemetry — 3 agents), Advisory Board (spec & task review — 9 specialists, see next section), and User Review (persona simulation — 3 tiers). Plus the PM Advisor (spec-fit + build-phase spec-drift) and the UX Design Agent (design, UX review, design-health). All read shared files (_agent-glossary.md, _agent-workflow.md) before operating. Click to expand details.

Advisory Board

Before any code is written, up to 9 specialist agents review your compiled spec (or task brief) for gaps, risks, and opportunities. They run in parallel during Prompt A Phase 1 (and a task-scoped subset runs in Prompt T Brief mode). All findings are advisory — you decide what to act on.

How it works

Activation

Three specialists always run (Lite+ tier — the core group: Architect, Critic, Pragmatist). Exploration and PM Advisory join at Standard+. Four conditional specialists activate at Full tier when trigger keywords are found in the spec or task brief.

The specialists

All advisory agents are read-only. They cannot modify files, run commands, or spawn sub-agents. Click to expand details.

Refinement report

The Orchestrator synthesizes all specialist briefs into a single report, organized by severity:

• Critical Findings — must address before build begins
• Recommendations — you decide, grouped by specialist
• Ideas — from Exploration + nice-to-haves from others
• Activation Summary — which specialists ran and why

You review each item: Accept (integrate into spec), Reject (document reason), or Defer (revisit later). All Critical findings must be addressed before proceeding to build.

Quality Gates

Gates must pass before code moves forward. Three tiers — click to switch:

Decisions

Version-controlled constraints in docs/ai/decisions/. They are laws, not notes. Violations block commits. If one no longer fits, create a new decision — never silently ignore the old one.

Hooks & File Map

What runs automatically

Customizing hooks

Add your project’s lint, format, and build commands to .claude/hooks/pre-commit-gates.sh (A3 stubs). Add test, typecheck, and dependency audit commands to .claude/hooks/pre-push-gates.sh (B2/B3 stubs). Adjust permissions in .claude/settings.json (team-shared, committed) or .claude/settings.local.json (personal, gitignored).

Repository structure

Operating Modes

Three modes control which files an agent can modify. Enforced by write-guard.sh (Decision 0012). The mode is declared in .claude/repo-mode — a single word: template, child, or autonomous.

Mode summary

Mode resolution

Priority (highest first):

1. REPO_OS_MODE environment variable (force any mode)
2. .claude/repo-mode file (committed, single word)
3. Default: child (when file is missing)

Immune paths

write-guard.sh and repo-mode cannot be modified in any mode — no override accepted. This is self-protection against circumvention. To maintain these files: set REPO_OS_SKIP_MODE_GUARD=1 (disables the entire guard, logged in overrides.log).

Overrides

Decision naming convention

Prototyping

Not everything needs a full spec. When you want to test an idea, validate architecture, or explore a feature before committing to it, use Prompt 0.5 on an experiment/* branch. Only the A4 safety gate applies — no process gates, no review chain, no scope warnings.

Prototyping tiers

You choose the tier. The tiers are a menu, not a gate — they determine how much documentation overhead the session carries.

What to say to the Orchestrator

The system maps your natural language to tiers. You don’t need to memorize tier names — just describe what you want to do.

How to start

The system helps you create an experiment/* branch (if needed), fill out a brief (Spike/PoC), and start building immediately. No full spec interview. No plan-before-code requirement.

What happens to the code?

Experiment branches never merge to main. The code is disposable. When you’re done:

• Discard — question answered, delete the branch
• Promote — capture learnings, then rewrite the validated approach into a feature/* branch
• Pivot — start a new experiment with a different hypothesis

Experiment briefs are stored in docs/spec/prototypes/ and survive branch deletion. Prompt B checks this directory for validated learnings before planning new work.

Task Definition — Prompt T

Prompt T facilitates exploration and task planning. Two modes, selected based on operator language — Query mode is conversational and ephemeral; Brief mode produces a copy-paste brief plus a sealed handoff bundle:

Query mode

Conversational Q&A grounded in specs and codebase. No agent dispatch, no structured output. The conversation is the output. If it evolves toward task definition, the system offers to switch to Brief mode.

Brief mode

Four core specialists (Architect, Exploration, Critic, Pragmatist) are dispatched in parallel — plus a conditional PM Advisory (when compiled specs or mvp-scope.yaml exist) and a conditional UX Design agent (for UI work) — to produce a structured task brief:

The operator approves via a structured AskUserQuestion that merges brief approval with auto/review mode selection (Decision 0038). Options: Approve — review (Prompt B pauses at op-review before commit), Approve — auto (Prompt B runs autonomously through merge), Approve & queue (review/auto) (writes the brief + bundle to the automation queue for headless execution), Revise, or Abandon. Splitting into multiple briefs (Narrow) is available via “Other”. The finalized brief is displayed for copy-pasting, and the chosen mode is written into the bundle so the downstream session never re-prompts.

How to start

Task Group Contracts

When Prompt T splits a task into multiple briefs (Narrow path), each brief includes a ### Task Group section. The briefs share a task group contract — a YAML file that coordinates naming, patterns, decisions, and integration points across sessions.

Contract lifecycle

Contract path depends on repo mode: template mode uses .claude/local/task-groups/, child/product mode uses docs/ai/task-groups/. Gate A6 verifies contract compliance when a task group is present. Override: SKIP_CONTRACT_CHECK=1.

Project Audit — Prompt C

On-demand health check that scans for drift, compliance issues, and accumulated problems. Read-only — no file modifications (except when the operator defers findings, which writes to known-issues.md).

Dimension menu

Depth tiers

How it works

Specialist collaboration: Escalation (Auditor tags a finding → specialist follows up), Co-audit (both run in parallel), Workshop (iterative loop, capped at 2 rounds).

How to start

Hotfix & Debug — Prompt H

Reactive debugging and fix session for runtime errors, integration failures, and production incidents. Operates on hotfix/* branches with expedited gates (A2 scope relaxed, A5 cohesion skipped). Structured workflow: diagnose root cause, apply minimal fix, iterate when fixes fail, escalate when diagnosis stalls.

Workflow

Loop: verify → build when the fix doesn’t work. Maximum 3 fix cycles before escalation.

Agent dispatch

Escalation protocol

After 3 failed fix cycles, Prompt H produces a structured Debug Report containing: symptoms observed, hypotheses tested (with results), root causes eliminated (with evidence), remaining candidates, and recommended next steps. The operator may provide new evidence, accept a partial fix, or redirect entirely.

Known patterns

How to start

HVST Review Board

When HVST debugging stalls (2+ consecutive failures) or the operator proactively requests a debug review, the Orchestrator dispatches a 3-agent review board for multi-agent hypothesis analysis.

The board produces ranked hypotheses (not consensus) ordered by evidence strength, falsifiability, and implementation risk. The operator or Builder selects which to validate first. Capped at 1 review board round — if still stuck, escalate to operator.

Branch Categories

Every branch has a category that determines which gates apply and at what strictness. Use the naming convention <category>/<short-description>.

Examples

Multi-Agent Teams

Repo OS is designed for one operator, one session, one branch at a time. But you can scale to parallel agent teams working on separate branches. Here’s how.

When to use parallel teams

• Multiple independent features in flight simultaneously
• Time-sensitive delivery where sequential work is too slow
• Large projects where features have clear ownership boundaries

How it works

Each team is a separate Claude Code session on a separate branch. The Repo OS governance model runs independently in each session — same gates, same agents, same enforcement. No special configuration needed to start.

What you must set up

What Repo OS handles

• Each session independently enforces all gates (A1–A6, B1–B3)
• Secret scanning runs per-session before every commit
• Agent tool boundaries apply identically across all sessions
• Decision compliance is checked per-session

What Repo OS does NOT handle

Practical setup checklist

Template Sync

If your repo was created from a template, you can pull governance updates (workflow rules, agent definitions, gates, prompts) without losing your project-specific specs or decisions.

How it works

A GitHub Actions workflow runs daily (06:00 UTC) and compares your repo against the template. When differences are found, it creates a PR and auto-merges it. Your compiled specs and logs are never touched — protected by .templatesyncignore. Template decisions (t-*) sync from upstream; child decisions (0100+) are untouched. Every sync is recorded as a merged PR for audit.

One-time setup

1. Copy .claude/.automation/templates/template-sync-with-cleanup.yml to .github/workflows/template-sync.yml
2. Replace OWNER/repo-OS-template with your actual template repo path
3. If the template repo is private (required):
   1. Create a Classic PAT on GitHub: Settings → Developer settings → Personal access tokens → Tokens (classic)
   2. Scopes required: repo and read:org (fine-grained PATs are not compatible with git clone in Actions)
   3. Add the PAT as a repository secret named SOURCE_REPO_TOKEN in each child repo (Settings → Secrets and variables → Actions)
   4. In each child repo: Settings → Actions → General → Workflow permissions → enable "Allow GitHub Actions to create and approve pull requests"

   The workflow already references SOURCE_REPO_TOKEN via source_gh_token. If the template repo is public, you can remove that line — the default GITHUB_TOKEN works without extra setup.

Note: The template repo itself should not have this workflow. Only project repos created from the template need it.

Want to review before merge?

Remove the Auto-merge sync PR step from the workflow. Sync PRs will stay open until you merge them from the Pull requests tab on GitHub.

What syncs vs what stays

GitHub prerequisites

The sync workflow uses GitHub Actions. Before setup, confirm these settings on your project repo (not the template):

1. Actions enabled — On by default. Check at Settings → Actions → General.
2. Workflow permissions — Go to Settings → Actions → General → Workflow permissions and select Read and write permissions. The workflow declares its own permissions, but the repo-level setting must allow it.
3. Branch protection (if used) — If main has branch protection requiring PR reviews or status checks, the auto-merge step cannot bypass them. Either allow the github-actions bot to bypass protection rules, or use manual merge mode.

Merge conflicts

If your project has locally modified a governance file that the template also updated (e.g., you customized .claude/hooks/pre-commit-gates.sh and the template changed it too), the auto-merge will fail. The sync PR stays open and you resolve the conflict manually — same as any git merge conflict.

To avoid this for files you always want to customize, add them to .templatesyncignore. The template sync will skip them entirely.

When you need to act

Syncs are automatic. The only time you need to act is if spec templates were updated with new fields:

1. Check the merged PR diff — look for changes in docs/spec/_templates/
2. If templates changed, re-run Prompt 0:
   • It detects existing compiled versions and enters update mode
   • Copies your latest version, highlights new/changed fields, asks what to fill in
   • Output goes to a new version (e.g., v2) — previous version preserved
3. If only governance files changed (agents, gates, prompts) — no action needed, already live

Template version tags

The template repo uses CalVer git tags (format: v2026.02.1 — YYYY.0M.MICRO) to mark meaningful milestones. Tags are applied on main after changes to decisions, agents, hooks, or prompts. Not every commit is tagged. Each tag has a corresponding GitHub Release with a summary of what changed.

To check which template version your child repo synced from, look at the sync PR — git log --oneline in the PR diff shows the tagged commit. You can also compare against the template repo's Releases page to see what's included.

Companion Tools

Repo OS is a governance framework. Companion tools extend the development workflow without modifying the core system. They integrate via MCP servers registered in .claude/settings.json.

Visual Bridge optional

A Chrome extension + MCP server for visually editing live front-end UI and feeding precise change requests back to Claude Code.

What it does

• Operator selects and adjusts elements in the browser (spacing, typography, colors, sizing)
• Edits snap to the project’s design system tokens
• Structured diffs with exact source file and line number are sent to Claude Code
• Claude Code applies the precise edit — no fuzzy matching, no guessing

Setup (per project)

1. Install the dev plugin: npm install -D @visual-bridge/dev-plugin
2. Add to your build config (e.g., import { visualBridge } from '@visual-bridge/dev-plugin' in vite.config.ts)
3. Add the MCP server to .claude/settings.json: "visual-bridge": {"command": "npx", "args": ["@visual-bridge/mcp-server"]}
4. Install the Chrome extension from the Chrome Web Store

Design token discovery: The MCP server auto-reads tokens from your project’s Tailwind config, tokens.json, or docs/spec/compiled/{active}/design-system.md. No additional configuration needed.

Automation Layer

An optional headless runner infrastructure for automated claude -p sessions with full governance parity. Decision 0017. Ships disabled by default — no behavioral change until the operator explicitly opts in.

Runner lifecycle

Queue lifecycle

Enabling and disabling

Prompt D provides a conversational alternative to manual config edits. It runs as a single-purpose ephemeral session that toggles runner.enabled in config.yaml and manages the HALT file — two files only, then closes automatically. Use the Navigator to find it, or paste the Prompt D starter directly.

Phase model integration

Automated sessions use the same phase sequences as interactive sessions (Decision 0014) and run worktree-isolated by default (Decision 0033). When a brief was queued from Prompt T with a handoff bundle (Decision 0038), the session’s drift-check phase reads the bundle and derives plan-approved + pragmatist-signed directly; the runner’s pre-write of plan-approved is the fallback for bundle-absent (legacy) briefs. All hooks fire normally except the Stop hook — the runner replicates Stop hook cleanup (solo merge, registry cleanup, branch sealing) as part of the post-session phase.

Dev Orchestrator

For task groups, the runner invokes a Dev Orchestrator agent between content briefs and before merge briefs. The orchestrator reviews cross-brief coherence, validates contract compliance, detects boundary drift, and produces health reports. Reports are written to .claude/.automation/reports/ (gitignored). All findings are advisory — the runner or operator decides what to act on.

Key files

Session Hygiene

Every session must end with all five satisfied. If they’re not, you’re not done.

Session log format

Glossary