Project Claude
vojtech-stas/project-claude
Senior engineer + AI agents starter template para projetos auto-gerenciados
Ver no GitHubTemplate starter para projetos AI-coded que replica o fluxo de trabalho de um engenheiro sênior supervisionando um time de agentes de IA. Combina práticas clássicas de engenharia de software (small slices, fast feedback, git tracking, PR review) com automação inteligente de desenvolvimento, eliminando a necessidade de aprovação humana em cada estágio através de críticos adversariais de IA.
Instalação
npx convez-ai vojtech-stas/project-claude1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Prototipagem rápida de features com ciclos autônomos de dev
- Projetos pequenos/médios onde você quer velocidade sem perder rastreabilidade
- Aprender fluxo de engineering moderno com agentes Claude
Veredito

Projeto ambicioso que traz automation real ao fluxo git+PR, não apenas um wrapper. Exige CLI setup (gh, git, Python) e integração profunda com GitHub; recomendado para quem já domina Git e quer experimentar autonomia controlada em dev.
README
A tradução para o português deste README ainda está na fila.
project-claude
A clone-as-template starter for AI-coded projects, replicating the workflow of a senior engineer overseeing a small team of developers — but with AI agents instead of humans. Built on 20-year-old software engineering practices (small slices, fast feedback, git-tracked changes, PR review, scope discipline) and heavy borrowing from Matt Pocock's skills repo.
New here? Start here → Jump to the 5-Minute Quickstart for a literal first-use cycle. Skim the Concepts cheat sheet for one-line definitions. Hit the FAQ for common newcomer questions. For deep theory, scroll to What's the idea; for the architecture, see CLAUDE.md.
Using this repo as a template
This repo is designed to be cloned under your own owner/name and run as-is — no find-and-replace needed. All repo identity (GraphQL queries, PR links, escalation mentions) is derived at runtime from git remote and gh.
One-time setup checklist:
- Clone under your own owner and repo name:
git clone https://github.com/<your-owner>/<your-repo> my-project cd my-project - Authenticate with the GitHub CLI:
gh auth login - Run bootstrap — creates all required labels (including
needs-human-check), installs git hooks viacore.hooksPath, checks thatgh,git, andpython3are on your PATH, and applies branch protection R1+R2 tomain:bash bootstrap.sh - Optionally create a project board —
bootstrap.shdetects an existing GitHub Project v2 board named "project-claude"; create one viagh project create --title "project-claude"if you want the Backlog/Captured columns. The pipeline works without it, but the board gives you a visual queue. - Open in Claude Code —
CLAUDE.mdauto-loads; the agents are oriented. Start with/grill-mefor your first feature.
Runtime identity — nothing to configure. dashboard/collector.py resolves the repo slug via gh repo view --json nameWithOwner (with a git remote get-url origin parse fallback). Every API payload, PR link, and escalation mention derives from that single source at runtime. For unusual multi-remote or CI setups, set the DASH_REPO_SLUG environment variable (e.g. DASH_REPO_SLUG=my-org/my-repo) to override resolution.
Assumption: a single origin remote pointing to github.com. SSH and HTTPS origins both parse correctly; GitHub Enterprise is not supported.
What's the idea
You play senior engineer. AI agents play the team. The template ships an autonomous pipeline with exactly two human-touch points:
- Start —
/grill-me— the agent interviews you about the idea until both of you share the same picture of what's being built. - End —
/qa-plan— after every slice of the PRD has merged, the agent produces a human-runnable acceptance checklist. You verify; you sign off.
Everything in between — PRD authoring, slice decomposition, implementation, review, merge — is autonomous, gated by adversarial AI critics rather than per-stage human approval.
The middle is glued together by one command: /ship. After /grill-me, you invoke /ship and the pipeline chains to-prd → prd-critic → slicer → slicer-critic → implementer → reviewer → merge per slice until the PRD is done. Stage 4 (implementation) is autonomous via the implementer subagent — /ship auto-invokes it on each posted slice with DAG-aware parallel batching, no manual implementation trigger needed (per ADR-0010). See ADR-0003 D2 for the 5-stage pipeline and ADR-0003 D4 for why there are no human gates in the middle.
QA stage (Tier 1, ADR-0020 — runnable end-to-end via /qa-plan). The terminal /qa-plan checkpoint is a writer/executor split: the writer (skill, main-agent context) LLM-extracts each PRD §2 acceptance criterion into a mechanical bash check or a JUDGMENT flag, persists the plan as a PRD comment for audit + re-runnability, then dispatches the qa-tester generator subagent (tools: Read/Bash/Grep only) to execute the plan and return a per-criterion verdict table. Judgment rows and EXTRACT_FAILED rows are surfaced to you via AskUserQuestion; on all-PASS + all-judgment-ACCEPT the PRD auto-closes. Shipped through the autonomous pipeline as the QA writer/executor split per ADR-0020. Per ADR-0020 D9 + ADR-0046 D1 the critic-parsimony principle is honored — qa-tester is the 3rd generator (alongside slicer and implementer), not a critic.
Forward queue. Future-PRD ideas live as backlog-labeled GitHub Issues + a "Backlog" column on the project board (per ADR-0006). Browse with gh issue list --label backlog. Promotion to a PRD: gh issue edit <N> --remove-label backlog --add-label prd + /grill-me #<N>.
Captured → backlog autopilot. Per ADR-0008, any agent that surfaces a deferred-work idea writes it as a captured-labeled issue and invokes the /promote-to-backlog skill inline. The backlog-critic subagent gates the promotion against a 4-criterion rubric (actionable / scoped / not duplicate / clear); on APPROVE the autopilot swaps labels captured → backlog, on BLOCK the item stays in the captured tier as a graveyard for lazy human review (default-conservative per ADR-0008 D4).
Why two tiers? captured is a low-bar safety net — agents capture deferred work indiscriminately (CLAUDE.md rule #11) so nothing gets lost; the autopilot's backlog-critic filters them down to the curated backlog queue you actually pick PRDs from. BLOCKed captures stay in the captured-tier graveyard for lazy human review — three options per item: cull (close), rescue (manually relabel captured → backlog), or restructure-and-recapture.
Session continuity. New Claude Code sessions reconstruct state from live state (git log, gh issue list, gh pr list, project board) — no formal handoff document. See the "Session continuity" section in CLAUDE.md for the canonical procedure.
5-Minute Quickstart
A literal walkthrough of the first full feature cycle. Pick something tiny — e.g., a /say-hello skill that prints a greeting. (Real PRDs are bigger; we use /say-hello here purely to make the example fit in 5 minutes.)
1. Clone + bootstrap (one-time, ~30 seconds):
git clone https://github.com/<your-owner>/<your-repo> my-new-project
cd my-new-project
./bootstrap.sh # creates labels, installs git hooks, applies branch protection
2. Open the repo in Claude Code. CLAUDE.md auto-loads; the agents are oriented.
3. Grill the idea (~2 minutes). Run /grill-me I want a /say-hello skill that prints a friendly greeting. The agent interviews you one question at a time:
Agent: 1. Should /say-hello take an optional name argument, or always greet "world"?
Recommendation: 1B (optional argument) — slightly more useful, same LoC.
1A. always "Hello, world!" pros: dead simple; cons: not personalizable
1B. optional name argument pros: useful; cons: trivially more code
1C. read name from git config pros: zero-arg + personal; cons: edge cases
You: 1B
Agent: 2. Should output go to stdout, or use AskUserQuestion?
...
After 3-5 questions the agent confirms the settled design and returns.
4. Ship it (autonomous, ~2 minutes wall-clock for a trivial example). Run /ship. The orchestrator chains: to-prd → prd-critic (≤3 APPROVE/BLOCK rounds) → slicer → slicer-critic → posts the PRD + slice issues → implementer writes the code per slice → reviewer audits the PR → auto-merges on APPROVE. You watch; you don't touch.
5. Verify (~30 seconds). When the last slice merges, run /qa-plan <PRD-number>. The qa-tester subagent walks each acceptance criterion mechanically; subjective ones surface via AskUserQuestion. On all-PASS the PRD auto-closes.
That's the full loop. Two human commands (/grill-me, /qa-plan), one orchestration command (/ship), and the rest is autonomous.
Concepts cheat sheet
One-line definitions of the load-bearing terms. For the full canonical glossary (with authority citations), see CLAUDE.md ## Glossary.
- PRD — feature-sized GitHub issue (label
prd); top of the PRD → Slice → PR hierarchy. - slice — INVEST-shaped sub-issue of a PRD (label
slice); one PR; ≤300 LoC diff. - skill — user-invocable command at
.claude/skills/<name>/SKILL.md(e.g.,/ship). - subagent — specialist at
.claude/agents/<name>.mdwith isolated context + restricted tools. - critic — adversarial subagent judging a stage's output with APPROVE/BLOCK (≤3 rounds).
- generator — subagent producing output (decompositions, code, test plans); paired with a critic.
- autopilot — inline-firing mechanism (e.g.,
/promote-to-backlogafter a captured-label issue). - trivial-lane — fast path (I3) for PRs ≤10 LoC; branch
hotfix/<N>-..., labeltrivial.
Frequently asked questions
Do I have to use /grill-me?
Recommended for any new feature. Skippable for the trivial lane (I3 — PRs ≤10 LoC, no behavior change, branch hotfix/<N>-...). The /to-prd skill also accepts a clear pre-written spec if you'd rather draft offline. The autopilot enforces no hard requirement today, though a future PRD may make /grill-me mechanically required for new features.
Why is Claude asking permission to edit every file?
The PreToolUse(Edit|MultiEdit|Write) hook (ADR-0023 D3) emits permissionDecision: "ask" when the main agent (not a subagent) writes a tracked file. This is the mechanical enforcement of CLAUDE.md rule #10 — main-agent meta-output discipline. Subagent edits (e.g., implementer shipping a slice) skip the prompt entirely. If you see prompts on every edit including untracked / gitignored files, you may be hitting captured issue #222 — make sure jq is installed and on your PATH.
What if I want to skip critics?
You can't via the pipeline. The joint-APPROVE gate (ADR-0004 D1) is non-negotiable, and reviewer is the sole gate per PR (ADR-0002). You CAN, however, escalate a round-3 BLOCK to a needs-human label and apply your own judgment in a manual PR — that's the designed escape valve.
How do I add a new subagent?
Author .claude/agents/<name>.md per ADR-0001 D6; declare tool boundaries in the frontmatter; write the body per ADR-0001 D6 and the embedded standards in the subagent's own file (the quality rubric is inlined directly in each subagent's body). If your new subagent is a critic, honor the critic-parsimony principle (ADR-0046 D1) — minimize critics; each must earn its place against a distinct concern; a new ADR must justify why an existing critic's rubric can't absorb the concern.
Why so many ADRs?
Each ADR is one architectural decision frozen at its moment per decisions/README.md "What an ADR is". The count reflects the template's walking-skeleton evolution — superseded decisions live on for audit + history, never edited in place. If you fork the template and decide differently for your project, you write new ADRs; the originals remain as the historical record.
What does it mean if I see a needs-human label?
The reviewer applies needs-human on round-3 BLOCK (ADR-0003 I5) — three rounds of generator/critic disagreement is the autonomy ceiling. A human needs to decide. Find them at session start with gh pr list --label needs-human and gh issue list --label needs-human. The reviewer also posts a summary to the parent PRD issue so you don't have to guess what's stuck.
Pipeline diagram
The whole autonomous composition at a glance: the human enters at /grill-me and exits at /qa-plan, with everything in between — PRD authoring, slice decomposition, implementation, review, merge — chained by /ship and gated by adversarial critic loops (≤3 rounds each). The joint prd-critic + adr-critic gate, the reviewer auto-merge red-gate, and the needs-human forward-block paths are all shown; side workflows (/audit-subagents, /glossary, captured→backlog autopilot) live in their own subgraph or fire transparently around the main pipeline.
flowchart TD
subgraph S1["Stage 1: Idea capture"]
user["User"]
build["/build"]
grill_me["/grill-me"]
ship["/ship"]
end
subgraph S2["Stage 2-3: PRD + slice decomposition"]
to_prd["/to-prd"]
to_issues["/to-issues"]
prd_critic{{prd-critic}}
adr_critic{{adr-critic}}
slicer[slicer]
slicer_critic{{slicer-critic}}
prd_issue[(PRD issue)]
slice_issue[(Slice issue)]
end
subgraph S3["Stage 4: Implementation"]
implementer[implementer]
reviewer{{reviewer}}
pr[(Pull Request)]
merge[(Merge)]
closed_prd[(Closed PRD)]
needs_human[(needs-human)]
end
subgraph S4["Stage 5: Acceptance"]
qa_plan["/qa-plan"]
qa_review["/qa-review"]
qa_tester[qa-tester]
verify_verdict[(verify verdict)]
end
subgraph SS["Side workflows"]
glossary["/glossary"]
promote_to_backlog["/promote-to-backlog"]
audit_meta["/audit-meta"]
audit_subagents["/audit-subagents"]
glossary_critic{{glossary-critic}}
backlog_critic{{backlog-critic}}
codebase_critic{{codebase-critic}}
captured_issue[(captured issue)]
backlog_issue[(backlog issue)]
glossary_pr[(glossary PR)]
end
user -->|/build| build
user -->|/ship| ship
user -./grill-me.- grill_me
build --> ship
grill_me -.settled design.- ship
ship --> to_prd
to_prd --> prd_critic
to_prd -.if ADR.- adr_critic
prd_critic -->|joint APPROVE| prd_issue
adr_critic -->|joint APPROVE| prd_issue
prd_critic -.BLOCK.- to_prd
prd_issue --> to_issues
to_issues --> slicer
slicer -->|decomposition| slicer_critic
prd_issue -->|sub-issue| slice_issue
slicer_critic -.BLOCK.- slicer
slice_issue --> implementer
slice_issue --> pr
pr --> reviewer
reviewer -->|APPROVE| merge
merge --> closed_prd
reviewer -.BLOCK.- implementer
reviewer -.round-3 BLOCK.- needs_human
pr -.trivial.- merge
merge --> qa_plan
qa_plan --> qa_tester
qa_tester -->|PASS/FAIL| verify_verdict
merge -.residual.- qa_review
merge -.per-PRD gate.- codebase_critic
codebase_critic -.per-PRD.- reviewer
ship -.whole-repo bg.- codebase_critic
user -./glossary.- glossary
glossary --> glossary_critic
glossary_critic -->|APPROVE| glossary_pr
glossary_pr --> reviewer
user -.- audit_subagents
audit_subagents -.per-PRD.- reviewer
user -.- audit_meta
audit_meta -.per-PRD.- reviewer
orchestrator -.capture.- captured_issue
user -.- promote_to_backlog
captured_issue --> promote_to_backlog
promote_to_backlog --> backlog_critic
backlog_critic -->|APPROVE| backlog_issue
backlog_critic -.BLOCK.- captured_issue
classDef human fill:#3b82f6,color:#fff
classDef skill fill:#14b8a6,color:#fff
classDef gen fill:#22c55e,color:#fff
classDef critic fill:#f97316,color:#fff
classDef reviewer_cls fill:#ef4444,color:#fff
classDef artifact fill:#9ca3af,color:#fff
class user human
class audit_meta,audit_subagents,build,glossary,grill_me,orchestrator,promote_to_backlog,qa_plan,qa_review,ship,to_issues,to_prd skill
class implementer,qa_tester,slicer gen
class adr_critic,backlog_critic,codebase_critic,glossary_critic,prd_critic,slicer_critic critic
class reviewer reviewer_cls
class backlog_issue,captured_issue,closed_prd,glossary_pr,merge,needs_human,pr,prd_issue,slice_issue,verify_verdict artifact
Legend
| Color | Class | Node type | Examples in the diagram |
|---|---|---|---|
| 🟦 Blue | human | Human checkpoint | User (input at /grill-me, acceptance at /qa-plan) |
| 🟩 Teal | skill | User-invocable skill | /grill-me, /ship, /to-prd, /to-issues, /qa-plan, /audit-subagents, /promote-to-backlog, /glossary |
| 🟢 Green | gen | Generator subagent | slicer (single decomposition per ADR-0044), implementer (slice → PR) |
| 🟧 Orange | critic | Adversarial critic (≤3-round loop) | prd-critic, adr-critic, slicer-critic, glossary-critic, backlog-critic, codebase-critic |
| 🟥 Red | reviewer | Auto-merge gate (per ADR-0002) | reviewer — the only critic that auto-merges on APPROVE |
| ⬜ Gray | artifact | GitHub artifact | PRD issue, slice issues, PR, merged commit, needs-human / backlog labels |
Hierarchy — PRD → Slice → PR
Per ADR-0003 D1, the unit-of-delivery hierarchy is exactly three tiers:
- PRD — GitHub Issue (label
prd). One feature per PRD. - Slice — GitHub sub-issue under the PRD (label
slice). One INVEST-shaped vertical, fits in one PR. - PR — one merged change, closes one slice via
Closes #<slice-issue>in the PR body.
No feature label, no slice-N-foo branch names. Branches use Conventional Commits prefixes — <type>/<issue-number>-<kebab-summary>. See CLAUDE.md "Hierarchy" and "Operational git workflow" for the full operational logic.
Adversarial critics
Per ADR-0003 D2, every generation stage in the pipeline is paired with an adversarial critic running a ≤3-round APPROVE/BLOCK loop. The project applies the critic-parsimony principle per ADR-0046 D1 — minimize critics; each must earn its place against a distinct concern; adding one requires an ADR that makes that justification explicitly. Today's critics (auto-generated from .claude/agents/):
adr-critic— Audit a draft ADR for quality against ADR conventions and the adr-critic rubric.backlog-critic— Audit a freshly-writtencaptured-labeled issue and decide whether the autopilot should promote it tobacklogor leave it in the captured tier.codebase-critic— Two modes: (1) per-PRD — audit cumulative PRD change for codebase-level coherence (CRITIC trailer); (2) whole-repo (WHOLE_REPO:true) — map+seam-spot-read for cross-subsystem drift, emits FINDINGS list + GENERATOR trailer.glossary-critic— Audit a draft glossary entry for quality against ADR-0007 D5's rubric (as partially superseded by ADR-0012 D4).prd-critic— Audit a draft PRD (and any macro-ADRs drafted alongside it) for quality against the 6-section template and the PRD-critic rubric.reviewer— Audit a pull request (or local unpushed changes) for scope drift, missing tests, YAGNI violations, commit-format violations, and other code-review concerns.slicer-critic— Review the slicer's single decomposition of a PRD against the quality rubric.
The loop convention (generator proposes → critic challenges against explicit rubric → generator revises → ≤3 rounds → APPROVE or escalate) is the canonical pattern from ADR-0003 D2.
Workflow enforcement
Per ADR-0004 D3, three independent failure-domain defenses prevent the pipeline from being bypassed:
- Pre-commit hook —
.githooks/pre-commitchecks branch-name regex and refuses commits tomain. Install with.githooks/install.sh(idempotentgit config core.hooksPath .githooks). - Branch protection R1 + R2 — live on
main: no direct push (R1), require pull request (R2). R4 (required CI status checks) is live per ADR-0042; R3 (required approving reviews) remains deferred to a future PRD that adds bot identity. - Reviewer rule R-CLOSES — PRs without
Closes #<slice-issue>referencing a validslice-labeled issue are BLOCKed at review time.
The workflow is no longer "discipline-only convention" — these three layers enforce it mechanically.
Per ADR-0046, a fourth layer is the codebase-critic — an adversarial post-PRD critic dispatched by /ship once per PRD at the last slice. It judges semantic reference currency, CLAUDE.md rule consistency, and structural drift that mechanical checks cannot see (supersedes the per-PR reviewer rule from ADR-0018).
The pipeline is complemented at the Claude Code session level by hooks (.claude/settings.json) configured per ADR-0015 for logging / validation / notification (no skill auto-invocation; that requires session interaction). Current count (derived from .claude/settings.json): 13 outer hook entries (2 SessionStart + 1 UserPromptSubmit + 4 PreToolUse + 4 PostToolUse + 2 Stop) → 14 inner hook commands → 8 scripts (session-start.sh, dashboard-autostart.sh, user-prompt-submit.sh, pre-tool-edit.sh, pre-tool-bash.sh, log-event.sh, log-tool-event.sh, stop-reviewer-gate.sh per ADR-0029).
Layer 4 — Claude Code session hooks (per ADR-0023, extending ADR-0015 D6; 5 hooks across the full ADR-0015 → ADR-0023 → ADR-0028 → ADR-0029 → ADR-0030 wave):
- SessionStart state injection —
.claude/hooks/session-start.shemitsadditionalContextwith branch + divergence vsorigin/main+ recent commits + open slice/PR/captured counts; mitigates the recurring stale-worktree false-alarm (#173) at the moment of session start. - PreToolUse rule-#10 escalation —
PreToolUse(Edit|MultiEdit|Write)emitspermissionDecision: "ask"when the main agent (not a subagent) writes a tracked file; preserves trivial-lane I3 ergonomics over hard-deny. - PreToolUse dangerous-git deny —
PreToolUse(Bash)emitspermissionDecision: "deny"ongit push ... origin main(any flavor), mechanically enforcing rule #4. - UserPromptSubmit grill-suggestion — feature-request-shaped prompts get a non-blocking nudge toward
/grill-mebefore/shipif the prompt does not already invoke a pipeline command. - Stop reviewer-signoff gate — ADR-0029
stop-reviewer-gate.sh: blocks session-stop if any in-flight PR lacks a reviewerAPPROVEcomment;STOP_GATE_BYPASS=1env-var override.
Recent hook wave (ADR-0028–ADR-0030):
- ADR-0028 — PreToolUse spec-existence gate (spec-gate): artifact-gated enforcement of rule #10; BLOCKs tracked-file edits when no in-flight PRD/slice issue + matching branch exist; extends ADR-0023 D3 with a deny-layer before the existing ask fallback; trivial-lane (
hotfix/) carveout preserved. - ADR-0029 — Stop reviewer-signoff gate (
stop-reviewer-gate.sh): the 5th.claude/hooks/script in the wave hooks sequence; blocks session-stop without reviewerAPPROVE;STOP_GATE_BYPASS=1override. - ADR-0030 — Windows Git Bash hardening:
bootstrap.shadds idempotent jq install; the Playwright-MCP install was later deprecated per ADR-0049 D1 (Claude_Preview is harness-provided);pre-tool-edit.shallowlist restructured for/and\portability.
Workflow event log. Per ADR-0016, three additional hooks (PostToolUse(Agent), PostToolUse(Bash), Stop) append JSONL events to .claude/logs/workflow-events.jsonl for run-time observability — which subagents fired, which bash commands ran, where session boundaries fell. Greppable from any session (grep '"event":"agent_complete"' .claude/logs/workflow-events.jsonl) and read by future audit-meta tooling.
Output-shape standard
The critics and the output-emitting skills (slicer, qa-plan, ship) conform to a canonical output shape. The canonical verdict template and the CRITIC / GENERATOR trailer schemas are defined in ADR-0005 D1 and restated in the subagent/skill prompts themselves (DRY per CLAUDE.md rule #9).
Use it
git clone https://github.com/<your-owner>/<your-repo> my-new-project
cd my-new-project
./bootstrap.sh # one-time: labels, git hooks, branch protection (idempotent)
# open in Claude Code — CLAUDE.md auto-loads, the agents are oriented
bootstrap.sh is the canonical fresh-clone setup per ADR-0008 D6: it creates the 6 repo labels (prd, slice, backlog, captured, trivial, needs-human), installs the pre-commit hook via core.hooksPath, detects the GitHub Project v2 board, and applies branch protection R1+R2 to main. Every step is idempotent (safe to re-run) and best-effort (single-step failures warn-and-continue).
Then: /grill-me to start a new feature, /ship to hand off to the autonomous pipeline, /qa-plan to verify when the last slice merges.
What's inside
- CLAUDE.md — auto-loaded operating system; canonical home for cross-cutting rules + Map + Glossary INDEX.
.claude/skills/and.claude/agents/— pipeline skills and subagents. See the Map table in CLAUDE.md for what lives where.decisions/— Architecture Decision Records. Seedecisions/README.mdfor the index, conventions, and the strict immutability rule.
All operational content lives in skills + subagents + CLAUDE.md + ADRs; no separate KB layer per ADR-0032.
bootstrap.sh— fresh-clone setup script (labels, git hooks, branch protection); see ADR-0008 D6..githooks/— workflow-enforcement pre-commit hook.- This README.
Dashboard
Dashboard auto-starts on session start via the dashboard-autostart.sh SessionStart hook (per ADR-0033). Visit http://localhost:8765 — Architecture, Live, and Health tabs. Architecture shows the pipeline diagram and auto-discovered component graph (skills, agents, hooks, ADRs) with click-to-view file content. Live shows two lanes: Lane A polls /api/live-progress (~25s) to render the most recent open PRD's per-slice run progress from the artifact trail (hook-independent); Lane B polls /api/live-poll?cursor=N with a byte-cursor against workflow-events.jsonl for an incremental chat transcript (O(delta), session picker, user/assistant bubbles, tool-beat rows, expand-on-click, All/Chat/Tools filter chips, APPROVE/BLOCK verdict badges). A status pill reports hook freshness and collector health honestly. Health shows pass/fail grids for DOCS-1..DOCS-10 and AS-* checks. Python stdlib only — no pip install needed. Manual start: python dashboard/server.py. See dashboard/README.md for configuration and cross-platform notes.
Component map
Skills
User-invocable commands under .claude/skills/:
/audit-meta— Periodic mechanical audit of codebase structure + doc-currency. Subcommand architecture —/audit-meta(no-args = both),/audit-meta --structure,/audit-meta --docs. Sibling skill to /audit-subagents per ADR-0017. Mechanical/grep-only rubric; emits a single Markdown PASS/WARN/FAIL report. Advisory output only (no auto-capture, no PR, no critic gate). Use when you suspect structural bloat or doc drift, after merging a convention-changing ADR, or on the cadence backlog #47 will eventually define./audit-subagents— Periodic mechanical audit of subagent-prompt quality. Scans every file under.claude/agents/*.md, classifies each as critic or generator, applies the 11-checkscope-tagged grep rubric, and emits a single Markdown PASS/FAIL report. No-args invocation; advisory output only (no auto-capture, no PR, no critic gate). Use when you suspect subagent drift, after merging a convention-changing ADR, or on the cadence backlog #47 will eventually define./build— Full-lifecycle orchestrator — one command from idea to merged + verified PR. Use when user says "/build", "build this", "implement this", "let's ship", or wants to drive a feature all the way through from idea to production-verified done. Chains dashboard-autostart → grill (conditional) → /ship → doc-regeneration → production-verify gate (mandatory, blocking per ADR-0037 D1). Thin conductor per ADR-0034 D1; sub-skills remain standalone./glossary— Glossary management skill with two subcommands —/glossary addfor single-term interactive entry flow;/glossary foldfor bulk-fold of skill-local vocabulary sections. Both flows gate through glossary-critic before opening a PR. Use/glossary addwhen the user wants to land a new vocabulary term; use/glossary foldto scan and promote skill-local vocabulary entries to CLAUDE.md. Per ADR-0038 D3 (consolidation of former /glossary-add + /glossary-fold skills)./grill-me— Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me"./promote-to-backlog— Run the captured→backlog autopilot on a singlecaptured-labeled GitHub issue. Invoked INLINE by whatever agent (subagent, skill, or main Claude) just wrote the capture viagh issue create --label captured, per ADR-0008 D3. Callsbacklog-critic; on APPROVE swaps labelscaptured→backlogand posts the verdict as an audit-trail comment; on BLOCK posts the verdict and leaves the captured label in place./qa-plan— Writer/orchestrator for QA automation per ADR-0020 + ADR-0040. Takes a PRD number (defaults to the most-recently-merged PRD), LLM-extracts each §2 acceptance criterion into a bash check or JUDGMENT flag, persists the plan as a PRD comment, dispatches qa-tester, collects PROVISIONAL residuals, posts each as a needs-human-check GitHub issue (writer posts, not qa-tester), reports the single top headline, and auto-closes the PRD on machine-PASS alone (ADR-0040 D2 — no longer waits on all-judgment-ACCEPT). Also the production-verify executor dispatched by /build (step 5) and /ship (step 6 standalone) per ADR-0037 D1./qa-review— Main-agent clearing skill for QA residuals (ADR-0040 D4). Lists open needs-human-check issues, presents each as an AskUserQuestion card (recommendation + PRO/CON inferred from the criterion), and records the verdict — accept closes the issue as verified; reject relabels and captures a defect. Tools: Read, Bash, AskUserQuestion only (NO Write/Edit/Agent). Emits a GENERATOR trailer./ship— Run the autonomous pipeline from grilled context to posted PRD-and-slices on GitHub. Use after /grill-me when the user says "ship it", "/ship", "turn this into a PRD and slices", or otherwise asks to hand off the grilled idea to the autonomous pipeline./to-issues— Break a PRD into independently-grabbable vertical-slice issues on GitHub. Delegates to theslicerandslicer-criticsubagents under the hood. Invocation shape preserved — use when the user says/to-issues, asks to break a PRD into slices, or convert a plan into implementation tickets./to-prd— Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
Subagents
Specialist agents under .claude/agents/:
Critics (adversarial gates):
adr-critic— Audit a draft ADR for quality against ADR conventions and the adr-critic rubric. Use when/to-prd(or any generator) has produced a draft ADR and needs a critic verdict before publishing. On APPROVE, the generator commits the ADR. On BLOCK, the generator revises and re-invokes, up to 3 rounds.backlog-critic— Audit a freshly-writtencaptured-labeled issue and decide whether the autopilot should promote it tobacklogor leave it in the captured tier. Use immediately after an agent runsgh issue create --label captured(per ADR-0008 D3, inline firing in same agent context). On APPROVE, the invoking context performs the label swapcaptured→backlog. On BLOCK, the captured item stays put and the user reviews on whatever cadence they prefer.codebase-critic— Two modes: (1) per-PRD — audit cumulative PRD change for codebase-level coherence (CRITIC trailer); (2) whole-repo (WHOLE_REPO:true) — map+seam-spot-read for cross-subsystem drift, emits FINDINGS list + GENERATOR trailer. Read-only; does not merge or file issues.glossary-critic— Audit a draft glossary entry for quality against ADR-0007 D5's rubric (as partially superseded by ADR-0012 D4). Use when/glossary add(or any generator) has produced a draft entry and needs a critic verdict before opening the PR. On APPROVE, the generator opens the trivial-lane PR. On BLOCK, the generator revises and re-invokes, up to 3 rounds.prd-critic— Audit a draft PRD (and any macro-ADRs drafted alongside it) for quality against the 6-section template and the PRD-critic rubric. Use when the/to-prdskill (or/ship) has produced a draft PRD and needs a critic verdict before publishing. On APPROVE, the generator posts the PRD. On BLOCK, the generator revises and re-invokes, up to 3 rounds.reviewer— Audit a pull request (or local unpushed changes) for scope drift, missing tests, YAGNI violations, commit-format violations, and other code-review concerns. Use when a PR has been opened by an implementer subagent and needs review. On APPROVE, the reviewer auto-merges viagh pr merge --squash --auto(queued merge-when-checks-pass per ADR-0042 D3). On BLOCK, the PR returns to the implementer. Use this proactively when the user asks to "review the PR", "check the changes", or after any implementation work that's been pushed.slicer-critic— Review the slicer's single decomposition of a PRD against the quality rubric. Run a standard APPROVE/BLOCK iterate loop (≤3 rounds). Use afterslicerhas produced its decomposition and before slices are posted to GitHub. Final output is one approved decomposition ready for issue creation.
Generators (output-producing agents):
implementer— Implement a singleslice-labeled GitHub issue end-to-end — read the slice + parent PRD + relevant ADRs, create a branch per CLAUDE.md naming, write code/edits per scope discipline, commit per Conventional Commits, open a PR withCloses #<slice>, hand off to reviewer. Per ADR-0010, the orchestrator (/ship) invokes this subagent on each posted slice after stage 3.qa-tester— Executor subagent: bash-mode (QA-plan row-by-row), ui-mode (headless Playwright/Chrome click-recipe driver), and production-verify mode (auto-routes by change type — browser/hook/skill/static — per ADR-0037 D2, ADR-0050 D1-D5). bash-mode (per ADR-0020 D3): given a structured QA-plan table, walks rows, returns verdicts + GENERATOR trailer. ui-mode (per ADR-0025 D1, driver updated per ADR-0050 D2): headless Playwright/Chrome dogfood self-test then click recipes via Bash-written Python scripts, LLM-judges inner_text/screenshot results, PROVISIONAL_PASS is the RESIDUAL signal (ADR-0040 D1) — returned to the writer, never auto-resolved. production-verify mode (per ADR-0037 D2, extended by ADR-0050): given PRD body + Production check line + merged diff, routes by changed-path glob and exercises the feature in its real running context; emits PASS/FAIL/PROVISIONAL + proof. Dispatched by/qa-plan,/build(step 5), and/ship(standalone gate).slicer— Given a PRD (GitHub issue body or markdown text), produce ONE well-justified vertical-slice decomposition of the work. Use when the autonomous pipeline (/shipor/to-issues) needs a decomposition for the slicer-critic to review. Output is the decomposition with rationale, NOT GitHub issues — posting is downstream.
Hooks
Claude Code session hooks configured in .claude/settings.json (scripts in .claude/hooks/):
session-start(SessionStart) — SessionStart hook — inject live workflow state per ADR-0023 D2.dashboard-autostart(SessionStart) — .claude/hooks/dashboard-autostart.sh — SessionStart tooling-spawn hooksession_start(SessionStart) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).user-prompt-submit(UserPromptSubmit) — UserPromptSubmit hook — nudge feature-request prompts toward /grill-me per ADR-0023 D5.user_prompt(UserPromptSubmit) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).pre-tool-edit(PreToolUse · Edit|MultiEdit|Write) — PreToolUse(Edit|MultiEdit|Write) hook — extended per ADR-0028 with spec-gate;pre-tool-bash(PreToolUse · Bash) — PreToolUse(Bash) hook — block dangerous git ops per ADR-0023 D4.agent_start(PreToolUse · Agent) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).skill_invoke(PreToolUse · Skill) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).log-event(PostToolUse · Edit|MultiEdit|Write) — log-event.sh — canonical event-log appender (ADR-0016 / PRD #467 / slice #468).agent_complete(PostToolUse · Agent) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).bash_complete(PostToolUse · Bash) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).grill_qa(PostToolUse · AskUserQuestion) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).session_stop(Stop) — log-tool-event.sh — parameterized python3-based hook logger (PRD #668 slice #669).stop-reviewer-gate(Stop) — Stop event hook — block session-stop if in-flight PR lacks reviewer subagent APPROVE per ADR-0029.
Architecture Decision Records
decisions/ holds 57 ADR(s). See decisions/README.md for the full index.
Subagent-quality maintenance
Per ADR-0011, subagent prompts drift silently between slices (the 2026-05-19 audit demonstrated: 5 subagent files unchanged for multiple PRDs still instructed --label backlog instead of --label captured, bypassing the autopilot). The /audit-subagents skill (.claude/skills/audit-subagents/SKILL.md) is the mechanical drift-detector: no-args invocation globs .claude/agents/*.md, applies an 11-check scope-tagged grep rubric (frontmatter, tool boundaries, references, surfacing convention, mandatory-reading-order, default-BLOCK clause, adversarial mindset, CRITIC trailer, 5-section verdict, GENERATOR trailer, skill-vs-agent placement), and emits a single Markdown PASS/FAIL report. The skill is a GENERATOR per ADR-0005 D1c — advisory only, no auto-capture, no PR, no critic gate. Honors the critic-parsimony principle per ADR-0046 D1 (skill ownership, not a critic). Invoke periodically or after merging a convention-changing ADR.
Per ADR-0017, the sibling /audit-meta skill (.claude/skills/audit-meta/SKILL.md) covers the adjacent meta-quality concerns: codebase structure (file-counts, file-sizes, depth, naming conventions) and documentation currency (dangling refs, supersession notes, concrete drift detectors). Subcommand architecture: /audit-meta (no-args = both), /audit-meta --structure, /audit-meta --docs. Same advisory-only contract.
Shared vocabulary
Per ADR-0007 (consolidated to single-tier per ADR-0012 D1), the project anchors load-bearing terms (e.g., slice, critic, trivial, PRD) in a single-tier glossary so agents and humans share the same definitions:
## Glossaryin CLAUDE.md — auto-loaded by Claude Code on every session. Soft cap ~35 entries per ADR-0012 D5.
To add a term, run /glossary add — it interviews you for the entry shape (definition, scope category, authority) and gates the addition through the glossary-critic subagent's 5-rule rubric (including ADR-0012 D2's ≥3-citations-across-≥2-directories inclusion threshold) before opening a trivial-lane PR. To bulk-promote skill-local vocabulary entries, run /glossary fold. Both subcommands live in .claude/skills/glossary/SKILL.md per ADR-0038 D3.
Status
Walking-skeleton phase. The pipeline is being built incrementally on the project itself — dogfooding from day one. The autonomous loop now ships PRDs end-to-end with all five stages live: /grill-me → to-prd+critics → to-issues+slicer-critic → implementer+reviewer (per slice, DAG-batched) → /qa-plan at acceptance. All operational content lives in skills + subagents + CLAUDE.md + ADRs per ADR-0032.
Auto-generated component counts (as of last generator run): 11 skill(s), 7 critic(s) + 3 generator(s), 15 hook(s), 57 ADR(s).
License
MIT — use it, fork it, ship it. A shoutout is appreciated.
Credits
Inspired by Matt Pocock's skills repo and the senior-engineer-overseen-agents workflow pattern.