🪜 codeViber

A Claude Code scaffold system — shape · build · validate

codeViber drives software delivery end-to-end — from a raw requirement to validated, production-shaped code — by orchestrating a roster of specialist subagents through a fixed delivery state machine. The root conversation stays lean and acts as a controller; the work happens in bounded subagent dispatches, and progress persists across sessions in .claude/state/.

---

• Explore — What it is · Quick start · How it works · Architecture · Specialist subagents · State machine · Lifecycle hooks · Configuration · Docs

---

What it is

codeViber is a drop-in .claude/ configuration that turns a single Claude Code session into a disciplined delivery pipeline. Instead of one model improvising a whole build, codeViber breaks delivery into sequential stages, hands each stage to a purpose-built specialist subagent, and gates every advance behind a read-only validator.

Two ideas hold it together:

• A persistent state machine. Mode, current stage, decisions, the artifact index, the gap queue, and the latest validator result all live as files in .claude/state/ — so a run survives compaction and can be resumed in a fresh session rather than restarted.
• A lean controller thread. An operating policy (CLAUDE.md) keeps the root conversation under a context budget, holding only control state and delegating detailed implementation to subagents.

It is a scaffold/orchestration layer, not an application — there is nothing to deploy. You install it into a project and drive it with slash commands.

Quick start

codeViber is configuration, not a package — there's no install step beyond placing the .claude/ directory in your project. Requirements: Claude Code and python3 on PATH (the lifecycle hooks are stdlib-only Python 3).

Start a run from a requirement:

/scaffold build a task management API with auth and PostgreSQL

codeViber detects the execution mode from context:

Mode	When used
greenfield	No existing codebase — building from scratch
brownfield	Existing codebase — adding or modifying features
repair	Existing codebase — fixing broken behavior

Then steer the run with the commands below.

Command	Purpose
/scaffold <requirement>	Start a new orchestration run
/resume-scaffold	Resume from saved state at the active stage
/continue-stage	Continue the active stage from its checkpoint
/validate	Run the delivery validator (the gate between stages)
/fix-gap <id | all-blockers>	Route a gap to its owner and re-validate
/plan-product <requirement>	Shape requirements with product-designer
/decide-stack <constraints>	Choose a stack with tech-strategist
/plan-seo <context>	Run seo-expert for public-facing web products

A full walkthrough of each command and the stage flow lives in the scaffold user guide.

How it works

Delivery is broken into sequential stages, each owned by a specialist subagent:

product → [seo] → stack → architecture → implementation → validation

The SEO stage is optional — codeViber skips it for internal tools and APIs, and runs it (between product and stack) only for public-facing web products. Validation runs automatically after each stage; when it finds problems it writes them to a gap queue, assigns each gap a primary owner, dispatches remediation, and re-validates. The root thread tracks stage, decisions, and open gaps — never raw code or logs.

Architecture

The root conversation is a controller. It reads control state, dispatches one specialist subagent at a time for a bounded task, records the returned artifact, and advances only after the validator passes. State persists to disk so the controller can be rebuilt after compaction or in a new session.

flowchart LR
  Op["You · slash commands"]
  Root["Root controller<br/>(lean thread)"]
  State[("`.claude/state/`<br/>state machine")]
  Sub["Specialist<br/>subagents"]
  Val["delivery-validator<br/>(read-only gate)"]

  Op -- "/scaffold, /validate, /fix-gap" --> Root
  Root -- "dispatch bounded task" --> Sub
  Sub -- "decisions · artifact · risks · handoff" --> Root
  Root -- "persist stage / gaps / artifacts" --> State
  State -- "re-entry summary (hooks)" --> Root
  Root -- "run gate after each stage" --> Val
  Val -- "blocking / conditional gaps" --> State

Loading

Repository layout:

.
├── .claude/
│   ├── agents/        # 13 specialist subagent definitions
│   ├── commands/      # 8 slash commands (the operator surface)
│   ├── scripts/       # Python 3 lifecycle hooks
│   ├── state/         # the persistent state machine (JSON + markdown)
│   └── settings.json  # wires the hooks into Claude Code
├── docs/adr/          # architecture decision records (written at runtime)
├── CLAUDE.md          # scaffold-first operating policy for the root thread
├── scaffold_readme.md # the scaffold user guide
└── LICENSE

Specialist subagents

Each stage and each gap is routed to the agent built for it. Every subagent returns the same structured contract — decisions, artifact, risks, next_steps, handoff, done_criteria — so the controller can record outcomes without absorbing the reasoning.

Agent	Handles
product-designer	Requirements shaping, actors, flows, acceptance criteria
tech-strategist	Stack selection with rationale, recorded as ADRs
solution-architect	System shape, contracts, module boundaries
frontend-engineer	UI, components, state, routing
backend-engineer	APIs, schema, jobs, auth
platform-engineer	CI/CD, Docker, deployment, secrets
test-architect	Test strategy, coverage, test scaffolding
security-reviewer	Auth, authz, secrets, data exposure
ux-optimizer	Flow friction, error states, task efficiency
design-system	Tokens, typography, component consistency
seo-expert	Search intent, technical SEO audit, action plan
delivery-validator	Read-only — validates readiness, never patches
bug-fixer	Root-cause diagnosis and targeted fixes

State machine

All durable state lives in .claude/state/ so a run can be resumed rather than restarted:

File	Contents
scaffold-state.json	Current mode, stage, active plan, open gap IDs, next action
project-summary.md	Compact, human-readable summary of the run
artifact-index.json	Pointers to all produced artifacts (specs, ADRs, schemas…)
gap-queue.json	Open gaps with severity and owner assignments
validator-status.json	Latest validation result and timestamp
stage-checkpoints/	Per-stage snapshots for resume / continue

Lifecycle hooks

Four stdlib-only Python 3 scripts in .claude/scripts/, wired through .claude/settings.json, keep the controller and the state machine in sync:

Hook	Script	Role
SessionStart	session_start.py	On startup / resume / compact, emits a concise re-entry summary (mode, stage, validator status, open gaps, next action) into the session
PreCompact	pre_compact.py	Preserves control state before context compaction
SubagentStop	subagent_stop.py	Captures a subagent's outcome as it finishes
Stop	stop_guard.py	Fails closed — warns if blocking validator gaps are still unresolved, otherwise refreshes the summary

Configuration

The system ships ready to run; there is no .env. Behavior is defined declaratively in the repo:

• .claude/settings.json — registers the four lifecycle hooks.
• .claude/agents/*.md — each subagent's name, dispatch description, and allowed tools.
• .claude/commands/*.md — the slash-command surface.
• CLAUDE.md — the operating policy (context budget, delegation, validation, resume rules).

Docs & decisions

• User guide: scaffold_readme.md — commands, stages, resuming, fixing gaps.
• Operating policy: CLAUDE.md — the scaffold-first rules the root thread follows.
• Architecture decisions: docs/adr/ — populated at runtime by tech-strategist / solution-architect; the committed tree currently holds none.
• License: MIT.