convez.ai
SkillProdutividadeAvançado
vojtech-stas

Project Claude

vojtech-stas/project-claude

Senior engineer + AI agents starter template para projetos auto-gerenciados

Ver no GitHub
InicialPluginScore · de 0 a 100

Template 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-claude

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
287
Contribuidores
1

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:

  1. Clone under your own owner and repo name:
    git clone https://github.com/<your-owner>/<your-repo> my-project
    cd my-project
    
  2. Authenticate with the GitHub CLI:
    gh auth login
    
  3. Run bootstrap — creates all required labels (including needs-human-check), installs git hooks via core.hooksPath, checks that gh, git, and python3 are on your PATH, and applies branch protection R1+R2 to main:
    bash bootstrap.sh
    
  4. Optionally create a project board — bootstrap.sh detects an existing GitHub Project v2 board named "project-claude"; create one via gh 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.
  5. Open in Claude Code — CLAUDE.md auto-loads; the agents are oriented. Start with /grill-me for 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>.md with 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-backlog after a captured-label issue).
  • trivial-lane — fast path (I3) for PRs ≤10 LoC; branch hotfix/<N>-..., label trivial.

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

ColorClassNode typeExamples in the diagram
🟦 BluehumanHuman checkpointUser (input at /grill-me, acceptance at /qa-plan)
🟩 TealskillUser-invocable skill/grill-me, /ship, /to-prd, /to-issues, /qa-plan, /audit-subagents, /promote-to-backlog, /glossary
🟢 GreengenGenerator subagentslicer (single decomposition per ADR-0044), implementer (slice → PR)
🟧 OrangecriticAdversarial critic (≤3-round loop)prd-critic, adr-critic, slicer-critic, glossary-critic, backlog-critic, codebase-critic
🟥 RedreviewerAuto-merge gate (per ADR-0002)reviewer — the only critic that auto-merges on APPROVE
⬜ GrayartifactGitHub artifactPRD 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-written captured-labeled issue and decide whether the autopilot should promote it to backlog or 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:

  1. Pre-commit hook — .githooks/pre-commit checks branch-name regex and refuses commits to main. Install with .githooks/install.sh (idempotent git config core.hooksPath .githooks).
  2. 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.
  3. Reviewer rule R-CLOSES — PRs without Closes #<slice-issue> referencing a valid slice-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):

  1. SessionStart state injection — .claude/hooks/session-start.sh emits additionalContext with branch + divergence vs origin/main + recent commits + open slice/PR/captured counts; mitigates the recurring stale-worktree false-alarm (#173) at the moment of session start.
  2. PreToolUse rule-#10 escalation — PreToolUse(Edit|MultiEdit|Write) emits permissionDecision: "ask" when the main agent (not a subagent) writes a tracked file; preserves trivial-lane I3 ergonomics over hard-deny.
  3. PreToolUse dangerous-git deny — PreToolUse(Bash) emits permissionDecision: "deny" on git push ... origin main (any flavor), mechanically enforcing rule #4.
  4. UserPromptSubmit grill-suggestion — feature-request-shaped prompts get a non-blocking nudge toward /grill-me before /ship if the prompt does not already invoke a pipeline command.
  5. Stop reviewer-signoff gate — ADR-0029 stop-reviewer-gate.sh: blocks session-stop if any in-flight PR lacks a reviewer APPROVE comment; STOP_GATE_BYPASS=1 env-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 reviewer APPROVE; STOP_GATE_BYPASS=1 override.
  • ADR-0030 — Windows Git Bash hardening: bootstrap.sh adds idempotent jq install; the Playwright-MCP install was later deprecated per ADR-0049 D1 (Claude_Preview is harness-provided); pre-tool-edit.sh allowlist 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

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-check scope-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 add for single-term interactive entry flow; /glossary fold for bulk-fold of skill-local vocabulary sections. Both flows gate through glossary-critic before opening a PR. Use /glossary add when the user wants to land a new vocabulary term; use /glossary fold to 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 single captured-labeled GitHub issue. Invoked INLINE by whatever agent (subagent, skill, or main Claude) just wrote the capture via gh issue create --label captured, per ADR-0008 D3. Calls backlog-critic; on APPROVE swaps labels captured → backlog and 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 the slicer and slicer-critic subagents 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-written captured-labeled issue and decide whether the autopilot should promote it to backlog or leave it in the captured tier. Use immediately after an agent runs gh issue create --label captured (per ADR-0008 D3, inline firing in same agent context). On APPROVE, the invoking context performs the label swap captured → 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-prd skill (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 via gh 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 after slicer has 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 single slice-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 with Closes #<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 (/ship or /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 hook
  • session_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:

  • ## Glossary in 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.

Ver o original no GitHub

Bom para

Relacionados