convez.ai
SkillAutomaçãoAvançado
pillip

Claude Dev Kit

pillip/claude-dev-kit

Pipeline completo PRD→código com 33 agentes e guardrails de engenharia

Ver no GitHub
BomPluginScore · de 0 a 100

Kit de automação que transforma um PRD (Product Requirements Document) em código pronto para produção usando 33 agentes de engenharia especializados e 23 skills. Executa todo o ciclo de vida do desenvolvimento — desde análise de requisitos até review e deploy — mantendo qualidade, testes e conformidade com requisitos.

Instalação

$npx convez-ai pillip/claude-dev-kit

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
11
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 dias
Versão
—
Issues abertas
5
Contribuidores
1

Casos de uso

  • Desenvolvimento de produtos completos a partir de PRDs
  • Automação do ciclo de implementação, review e deploy
  • Geração de workflows de vendas e descoberta (pack opcional)
  • Captura de decisões técnicas e rastreabilidade de requisitos

Veredito

Ferramenta robusta para times que já usam Claude Code e buscam estrutura industrial. O foco em pipeline determinístico (spec→implement→review→ship) e checkpointing de estado a torna confiável para ciclos de desenvolvimento real. Requer Python 3.11+ e integração GitHub; não é plug-and-play para iniciantes.

README

A tradução para o português deste README ainda está na fila.

claude-kit (v0.1)

License: MIT Python 3.11+ Tests

Turn a PRD into shipped code. 33 engineering agents + 23 skills (default install) handle the entire development lifecycle — from PRD to code review to deployment — so you can focus on what to build, not how. An optional sales pack (5 agents + 5 skills, opt-in via --pack=sales) covers account / discovery / proposal workflows for teams sharing a repo with engineering.

Why claude-kit?

Positioning: trustworthy code in collaboration → AI dev team control plane. The kit's bet is that AI productivity is bottlenecked not by the model but by what surrounds it — concurrency, state, guardrails, decision capture, learning. Adding more agents doesn't close that gap; structuring the work does.

Claude Code is powerful on its own, but without structure it produces inconsistent results — skipped tests, forgotten reviews, PRs that drift from requirements. claude-kit solves this by giving Claude Code a repeatable process:

  • Structured pipeline: Every issue goes through spec (when required) → implement → review → ship. No shortcuts, no skipped phases.
  • Specialized agents: Instead of one generalist prompt, 33 engineering agents each handle what they're best at — an architect designs the system, a reviewer audits security, a QA designer writes test plans, a design-auditor critiques the system, a separate ui-reviewer critiques the implementation.
  • Decision capture: Non-trivial issues require a SPEC (/spec → docs/specs/SPEC-NNN.md) — Problem / Options ≥2 / Trade-offs / Decision / Rollback. Sprint mode auto-runs it; non-sprint mode HOLDs for review.
  • Automatic feedback loops: Review findings create follow-up issues. Test failures trigger root-cause analysis. Shipped code gets test gap detection. Nothing falls through the cracks.
  • Resumable state: Sprint progress is checkpointed to sprint_state.md. Crash or timeout? Just re-run /sprint to pick up where you left off.
  • Zero configuration: Install as a git submodule, run one script, and all agents/skills/hooks are ready. Pack opt-in via a single flag.

In short: claude-kit turns Claude Code from a smart assistant into a development team that follows engineering best practices.

Overview

claude-kit takes a PRD (Product Requirements Document) as input and orchestrates AI agents to support the entire development lifecycle — from requirements analysis to code review and deployment.

Core Principles:

  • GitHub-first: Issues and PRs are the single source of truth
  • 1 Issue = 1 PR: Each issue maps to exactly one pull request
  • issues.md as SSOT: Progress and completion are tracked by Status in this file
  • Skill orchestration: Skills feed back into each other — review findings auto-create issues, shipped code triggers test gap detection, standalone skills register in the sprint ecosystem

Core Use Cases

1. Build a product from scratch

/prd → /kickoff → /uiux → /sprint
# (optional pre-PRD: /brainstorm → /bizanalysis → /prd)

Start with an idea, validate it, write a PRD, generate planning docs, design the UI, and let the team-lead auto-implement everything.

2. Implement a single feature

/implement ISSUE-001 → /review ISSUE-001 → /ship

Pick an issue from issues.md, implement it with TDD, review with security audit, and merge.

3. Run a full sprint

/sprint

Team-lead picks up all ready issues, implements them in parallel, reviews each PR, ships merged code, and auto-creates follow-up issues from review findings.

4. Fix a bug

/diagnose "TypeError in auth.py line 42" → /review → /ship

Trace the root cause, apply a minimal fix with regression test, review, and ship.

5. Improve test coverage

/testgen src/auth/

Scan for missing or hollow tests, generate unit/integration/E2E tests, and create a PR.

6. Analyze an existing codebase

/scan

Reverse-engineer docs from code: architecture, requirements, test plan, and improvement issues — then feed into /sprint or /implement.

7. Add a feature to an existing product

/issue "Add Stripe payment processing with subscription tiers, billing page, and invoice history"

Auto-detects that this spans multiple screens/modules, estimates issue count, updates planning and design docs incrementally (append-only), and creates a batch of implementation issues with dependencies.

8. Maintain and evolve

/refactor src/legacy_module.py    # Improve code structure
/migrate "Django 5.0"             # Upgrade dependencies
/devops "github-actions"          # Set up CI/CD

Workflow

New project:

/prd → /kickoff → /uiux → /sprint
# (optional pre-PRD: /brainstorm → /bizanalysis → /prd)

Existing codebase (no PRD):

/scan → /sprint

Single issue:

/implement ISSUE-001 → /review ISSUE-001 → /ship

Add a feature to existing product:

/issue "feature description" → /sprint (or /implement per issue)

Optional pre-PRD: /brainstorm (Socratic exploration) and /bizanalysis (market + SWOT) are stand-alone primitives, not part of the default flow. If your idea is clear, start from /prd. These exist for the case where you genuinely don't know what to build yet. /uiux, /mobile-uiux, and /desktop-uiux are optional for UI projects. Backend/CLI projects go directly from /kickoff to /sprint. /sprint auto-orchestrates multiple issues. For a single issue, use /implement directly. /scan is for existing codebases without a PRD. It reverse-engineers planning docs from code.

Skill Orchestration

Skills automatically feed into each other within /sprint:

implement → developer reports Discovered Findings
         → team-lead invokes planner to create follow-up issues

review   → review_notes.md with severity-classified findings
         → team-lead triages Critical/High findings → auto-creates issues

ship     → post-ship test gap scan
         → team-lead auto-triggers /testgen for uncovered files

test failure → team-lead invokes diagnostician for root cause analysis
            → diagnostician fix applied before retry

review_lessons.md → patterns with Frequency ≥ 3 + Critical/High severity
                  → team-lead creates preventive issues via planner

Standalone skills (/testgen, /diagnose, /refactor) register their work in issues.md when it exists, so team-lead can track all work in sprint_state.md.

Packs

The default install ships the core layer — engineering agents, design pack (uiux / mobile-uiux / desktop-uiux), and safety guardrails. Domain-specific workflows live in opt-in packs that depend on core.

PackWhat it addsInstall command
core (default)33 engineering agents + 23 skillsbash .claude-kit/scripts/install_project.sh
sales5 sales agents + 5 sales skills + 7 sales templatesbash .claude-kit/scripts/install_project.sh --pack=sales
(every declared pack)core + every pack under packs/bash .claude-kit/scripts/install_project.sh --pack=all

Rules:

  • Packs are additive on top of core, never substitutes. Every pack's manifest.yaml declares depends_on: [core]. The installer enforces this — there is no "pack-only" install.
  • Pack entries (agents / skills) live alongside core's in .claude/agents/ and .claude/skills/ via per-entry symlinks. Re-running the installer with a different --pack set is the supported way to add / remove packs.
  • Pack settings.snippet.json (if declared) merges after core's, with pack values winning on key collision.

See packs/README.md for the manifest schema and rules for contributing new packs.

Decision Tree — Which skill should I use?

START
 │
 ├─ No PRD yet?
 │   └─ YES → /prd
 │   └─ (optional pre-PRD: direction unclear → /brainstorm → /bizanalysis → /prd)
 │
 ├─ PRD exists but no planning docs?
 │   └─ YES → /kickoff PRD.md
 │
 ├─ Planning docs ready, project has UI?
 │   ├─ Web → /uiux
 │   ├─ Mobile → /mobile-uiux
 │   ├─ Desktop → /desktop-uiux
 │   └─ Have Figma design → /figma2proto [--mobile|--desktop] <URLs>
 │
 ├─ Want to add a feature or issues to an existing product?
 │   ├─ Small (single task) → /issue "description" (creates 1 issue)
 │   └─ Medium (multi-screen/module) → /issue "feature description" (auto-detects batch mode, creates multiple issues)
 │
 ├─ Multiple issues to implement?
 │   ├─ YES → /sprint (team-lead auto-orchestrates)
 │   └─ Single issue → /implement ISSUE-001
 │
 ├─ PR is ready for review?
 │   └─ YES → /review ISSUE-001 → /ship
 │
 ├─ Bug occurred?
 │   └─ YES → /diagnose "error description"
 │
 ├─ Dependency/runtime upgrade?
 │   └─ YES → /migrate "target"
 │
 ├─ Code structure needs improvement?
 │   └─ YES → /refactor path/to/module
 │
 ├─ Tests are insufficient?
 │   └─ YES → /testgen [path] (full scan or specific path)
 │
 ├─ CI/CD, Docker, deployment setup?
 │   └─ YES → /devops "target"
 │
 └─ Existing codebase, no PRD?
     └─ YES → /scan → /sprint or /implement
SkillDescriptionOutputs
/brainstorm [idea]Interactive brainstorming via Socratic dialoguedocs/brainstorm_notes.md
/bizanalysis [idea]Business viability analysis with market researchdocs/business_analysis.md
/prd [path]Create or update a PRD via interactive conversationPRD.md (or specified path)
/kickoff PRD.mdAnalyze PRD and generate planning docsdocs/requirements.md, docs/ux_spec.md, docs/architecture.md, issues.md, docs/test_plan.md, STATUS.md
/issue [description]Create issues (single or batch) from natural language + auto-update planning and design docsissues.md, STATUS.md, related docs/*.md
/uiux [PRD.md]Design philosophy + design system + HTML/CSS prototypedocs/design_philosophy.md, docs/design_system.md, docs/wireframes.md, docs/interactions.md, prototype/
/mobile-uiux [PRD.md]Mobile design system + React Native (Expo) prototypedocs/design_philosophy.md, docs/design_system_mobile.md, docs/wireframes_mobile.md, docs/interactions_mobile.md, prototype-mobile/
/desktop-uiux [PRD.md]Desktop design system + Electron prototypedocs/design_philosophy.md, docs/design_system_desktop.md, docs/wireframes_desktop.md, docs/interactions_desktop.md, prototype-desktop/
/figma2proto [--mobile|--desktop] <URLs>Fetch Figma design via API and generate complete design deliverable (prototype + docs)prototype/, docs/design_system.md, docs/design_philosophy.md, docs/wireframes.md, docs/interactions.md, docs/copy_guide.md
/sprintAuto-orchestrate multiple issues via team-leaddocs/sprint_state.md, STATUS.md
/implement ISSUE-001Implement a single issue + create GH Issue/PRCode, tests, PR (Closes #N)
/review ISSUE-001Senior review + security audit + UI review + design audit + a11y audit on PRdocs/review_notes.md, docs/ui_review_notes.md, docs/design_audit.md, docs/a11y_audit.md
/shipMerge PR + update docs/changelog + test gap advisoryCHANGELOG.md, STATUS.md updated
/diagnose [error]Analyze a bug and propose a targeted fixDiagnosis + fix
/migrate [target]Plan and execute a migrationMigration plan + updated code/config
/refactor [path]Improve code structure without changing behaviorRefactored code
/testgen [path]Scan for missing/hollow tests and generate unit/integration/E2E testsGenerated tests, PR
/scanReverse-engineer docs from existing codebasedocs/prd_digest.md, docs/requirements.md, docs/architecture.md, docs/test_plan.md, issues.md, STATUS.md
/devops [target]Set up CI/CD, Dockerfiles, deployment configsInfrastructure files
/carefulActivate destructive command warnings for current sessionSafety guardrail
/freezeBlock file edits outside a specified directory boundarySafety guardrail
/guardActivate both careful + freeze modesSafety guardrail

Requirements

  • Claude Code — CLI, desktop app, or IDE extension
  • macOS / Linux
  • Python 3.11+
  • Git
  • GitHub CLI (gh) — authenticated

Installation

claude-kit is installed into a service repo as a git submodule.

1. Add the submodule

cd your-service-repo
git submodule add git@github.com:pillip/claude-dev-kit.git .claude-kit

2. Install user tools

Installs the status line script to ~/.claude/kit/bin/. Run once per machine.

bash .claude-kit/scripts/install_user.sh

3. Install into project

Symlinks core agents, skills, hooks, and settings into the project's .claude/ directory. Default install is core only:

bash .claude-kit/scripts/install_project.sh

To include the sales pack (account-research / discovery / proposal / meeting-capture / follow-up):

bash .claude-kit/scripts/install_project.sh --pack=sales

To include every declared pack:

bash .claude-kit/scripts/install_project.sh --pack=all

After installation:

your-service-repo/
├── .claude/
│   ├── agents/          # 33 core agents (or +5 if --pack=sales)
│   ├── skills/          # 23 core skills (or +5 if --pack=sales)
│   ├── hooks/           # agent_state.py (agent state tracking)
│   └── settings.json    # Status line + hook config (auto-merged)
├── .claude-kit/         # submodule (source — contains packs/ subtree too)
└── ...

Re-running the installer with a different --pack set is destructive of the pack entries from the previous install (the install set IS the active install). Symlinks are per-entry so core + selected packs coexist in the same .claude/agents/ and .claude/skills/.

4. Verify gh authentication

gh auth status

If not authenticated, run gh auth login.

Team-scale usage

The kit assumes the repo IS the team boundary. Two adoption patterns cover the common shapes — and there is deliberately no separate "team layer."

Pattern (a) — Monorepo (engineering or sales)

The common pattern. One repo holds all team work; the kit installs once at the root.

  • Engineering team: services live under services/<name>/ subdirectories. Each service worktree is created from the repo root via scripts/worktree.sh. Shared state (issues.md, STATUS.md, sprint_state.md) sits at the root.
  • Sales team: accounts live under accounts/<company>/ subdirectories. Cross-account patterns accumulate in repo-root docs/sales_lessons.md. Walk-up resolution via scripts/find_shared.sh finds shared sales-pack files (e.g., sales_email_persona.md) from inside any account directory.
~/work/my-team/                       # team boundary == repo boundary
├── .claude-kit/                      # submodule
├── .claude/                          # installed (--pack=sales for sales)
├── issues.md, STATUS.md
├── docs/                             # shared knowledge
├── services/auth/                    # (engineering) one git checkout
├── services/gateway/                 # ...
│   └── ...
# OR
├── accounts/customer-a/              # (sales) one account
├── accounts/customer-b/              # ...

Pattern (b) — Virtual monorepo wrapper (polyrepo teams)

When services genuinely cannot be in one repo (independent release cadence, vendor isolation, etc.), wrap them. A top-level wrapper directory is itself a git repo holding the .claude-kit/ submodule and shared kit state at its root; each independent service repo lives as an immediate subdirectory and is gitignored from the wrapper.

~/work/my-team/                       # wrapper = git repo
├── .git/
├── .gitignore                        # auth-service/, gateway-service/, ...
├── .claude-kit/                      # submodule
├── .claude/                          # installed at wrapper root
├── issues.md, STATUS.md, sprint_state.md
├── docs/
├── auth-service/                     # independent git repo (gitignored)
├── gateway-service/                  # independent git repo (gitignored)
└── payments-service/                 # independent git repo (gitignored)

Per-service work routes to the right subdirectory; kit state stays at the wrapper root. Code-level support for this layout (Target-Service field, worktree.sh --service flag, wrapper-root detection in flock_edit.sh) is tracked as ISSUE-008 — gated on telemetry signal that polyrepo friction is real before we ship the helpers.

Why no separate "team layer"

A separate layer would add concepts (a new manifest type, a new install scope) without adding capability:

  • Sales team accumulation already works via accounts/<company>/ subdirectories in a sales-pack install. The repo's accounts directory IS the team asset store.
  • Cross-team installation uses the existing --pack flag (one repo can install core + sales together).
  • Polyrepo collaboration uses the wrapper pattern above. The wrapper directory IS the team boundary.

Adding a "team layer" would raise the onboarding cost (more concepts to learn, more install steps) for zero new capability over what the existing core + pack + wrapper model already provides. This decision is intentional, not a transitional state. Documented here so contributors don't re-propose it.

Usage

Brainstorm — Explore ideas interactively

/brainstorm [idea description]

Starts a Socratic dialogue to help you explore a vague idea, define the problem space, and converge on a concrete direction. Uses web research to investigate the existing landscape and competitors. Output: docs/brainstorm_notes.md.

Business Analysis — Validate business viability

/bizanalysis [idea description]

Conducts a structured business analysis: market research, competitive landscape, SWOT analysis, and Go/Pivot/No-Go recommendation. Reads docs/brainstorm_notes.md if it exists for context. Output: docs/business_analysis.md.

PRD — Co-write a PRD interactively

/prd [output-path]

Starts an interactive conversation to help you create or update a PRD. If the file already exists, the agent reads it, summarizes the current state, and asks what you want to change — then produces an updated version with a diff summary. If the file doesn't exist, it guides you from scratch by asking about missing sections (goals, target users, requirements, etc.). Output follows the docs/example_prd.md format. Default output: PRD.md.

Kickoff — Generate project plan

/kickoff PRD.md

Reads the PRD and runs 6 subagents to generate planning documents:

  • requirement-analyst → docs/requirements.md
  • ux-designer → docs/ux_spec.md
  • architect → docs/architecture.md
  • data-modeler → docs/data_model.md
  • planner → issues.md
  • qa-designer → docs/test_plan.md

UI/UX — Design and prototype

/uiux [PRD.md]

Requires /kickoff outputs. Conducts a Design Interview to establish the project's unique design direction, then performs reference research to generate a differentiated design system. Builds on docs/ux_spec.md and docs/requirements.md to produce:

  1. Design Philosophy (docs/design_philosophy.md) — Named aesthetic direction with visual philosophy
  2. Design System (docs/design_system.md) — Colors, typography (Google Fonts), spacing, components as CSS custom properties
  3. Wireframes (docs/wireframes.md) — Screen layouts with responsive breakpoints
  4. Interaction Spec (docs/interactions.md) — User flows, state machines, animations
  5. HTML/CSS Prototype (prototype/) — Self-contained, opens via file:// in any browser

The skill applies Anthropic's frontend-design guidelines to avoid generic "AI slop" aesthetics — no Inter fonts, no purple gradients, no cookie-cutter layouts. Every design choice is intentional and driven by the product's identity.

Mobile UI/UX — Design and prototype for mobile

/mobile-uiux [PRD.md]

Requires /kickoff outputs. Like /uiux but for React Native (Expo) mobile apps. Conducts a Design Interview to establish the project's unique design direction, then performs reference research to generate a differentiated mobile design system. If docs/design_philosophy.md already exists (from /uiux), reuses it with user confirmation; otherwise generates it from scratch. Produces design philosophy, mobile-specific design system, wireframes with thumb zone considerations, and a runnable Expo prototype.

Desktop UI/UX — Design and prototype for desktop

/desktop-uiux [PRD.md]

Requires /kickoff outputs. Like /uiux but for Electron desktop apps. Conducts a Design Interview with an additional "Desktop Identity" question (native OS integration vs distinct branded identity). If docs/design_philosophy.md already exists (from /uiux or /mobile-uiux), reuses it with user confirmation; otherwise generates it from scratch. Produces desktop-specific design system with keyboard shortcuts, window chrome specs, and multi-window configurations, plus an Electron prototype with main/preload/renderer separation.

Figma to Prototype — Design from existing Figma

/figma2proto https://www.figma.com/design/ABC123/MyProject?node-id=42-1234
/figma2proto --mobile https://...?node-id=42-5678 https://...?node-id=42-9012
/figma2proto --desktop https://...?node-id=42-3456

Fetches design data from Figma via API and generates the same complete deliverable as /uiux — prototype, design system, design philosophy, wireframes, interactions, and copy guide. The Figma design is treated as the source of truth: the design philosophy is reverse-engineered from the design (not invented), and interactions/copy that Figma can't express are filled in by asking the user. Supports web (default), mobile (--mobile → React Native prototype), and desktop (--desktop). Requires FIGMA_TOKEN environment variable.

Issue — Create issues and update planning/design docs

/issue "description"

Creates issues from a natural language description and auto-updates related planning and design docs. Operates in two modes:

  • Single-issue mode: For small tasks (one module, one screen). Creates 1 issue, updates affected docs.
  • Batch mode: For medium-sized features spanning multiple modules/screens. Auto-detects scope, estimates issue count (3–8), and creates multiple issues with dependencies via the planner agent in append mode.

When design docs exist (design_philosophy.md, wireframes.md, etc.), the skill also detects and incrementally updates them — appending new screens to wireframes, new flows to interactions, new components to the design system, and new copy entries. Design philosophy is read-only; if a conflict is detected, the skill warns and suggests running /uiux.

Test Generation — Fill test gaps

/testgen [path]

Scans source files for missing or hollow tests (empty functions, no assertions). Detects unit, integration, and E2E gaps by cross-referencing docs/test_plan.md critical flows. Generates tests with real assertions and creates a PR. When issues.md exists, registers the work as an issue in the sprint ecosystem.

Sprint — Auto-orchestrate multiple issues

/sprint

Runs a phase-based sprint loop: each iteration reads sprint_state.md, picks the highest-priority phase (ship first, review second, implement last), and dispatches the team-lead agent for that single phase. This structural enforcement guarantees every issue completes the full implement → review → ship pipeline — no phase gets skipped. Includes automated feedback loops: review findings create follow-up issues, test failures trigger diagnostician, and shipped code gets test gap detection.

Implement — Build an issue

/implement ISSUE-001
  1. Reads issue spec from issues.md
  2. Creates GH Issue if missing
  3. Creates branch → implements → tests → commits → pushes
  4. Creates PR with Closes #<issue_number> in body
  5. Updates issues.md metadata

Review — Code review

/review ISSUE-001

Performs a senior code review with an integrated security audit. Checks correctness, maintainability, and complexity alongside OWASP Top 10 vulnerabilities, dependency CVEs, and hardcoded secrets. Outputs docs/review_notes.md with Code Review and Security Findings sections. Applies only minimal fixes; larger changes are proposed as follow-up issues.

Ship — Deploy

/ship

Verifies tests pass, updates documentation, merges the PR, and reports test coverage gaps in shipped code with suggestions to run /testgen.

Diagnose — Analyze and fix bugs

/diagnose [error description or file path]

Traces an error from stack trace or reproduction steps back to the root cause, proposes a minimal fix, and runs tests to confirm no regressions.

Migrate — Upgrade dependencies or runtime

/migrate [target, e.g. "Django 5.0" or "Python 3.12"]

Scans the codebase for impact, generates a step-by-step migration plan with rollback instructions, and applies changes incrementally with test verification.

Refactor — Improve code structure

/refactor [file or module path]

Identifies code smells, proposes prioritized refactorings, and applies them one at a time while running tests after each step. Never changes observable behavior.

Scan — Reverse-engineer docs from existing codebase

/scan

Analyzes an existing codebase (no PRD required) and generates planning documents by running 6 scan agents:

  • codebase-scanner — 4-pass analysis (identity, architecture, requirements, quality)
  • scan-analyst → docs/requirements.md (CONFIRMED/INFERRED requirements)
  • scan-architect → docs/architecture.md (as-is architecture)
  • scan-data-modeler → docs/data_model.md (conditional, only if DB detected)
  • scan-qa-designer → docs/test_plan.md (coverage gaps, risk matrix)
  • scan-planner → issues.md (improvement issues from observations)

Output is compatible with /sprint and /implement — scan a codebase, then start working on improvement issues immediately.

DevOps — Set up infrastructure

/devops [target, e.g. "github-actions", "docker", "compose"]

Creates or updates Dockerfiles, docker-compose configs, GitHub Actions workflows, and deployment scripts.

Safety Guardrails

/careful    # Warn before destructive commands (rm -rf, git reset --hard, etc.)
/freeze     # Block edits outside a specified directory
/guard      # Both careful + freeze combined

Session-scoped safety modes for working in sensitive environments or scoping edits to a specific module.

Agents

33 core engineering agents (default install) with optimized model assignments — opus for judgment/creativity, sonnet for structured extraction. The sales pack adds 5 more (account-researcher, champion-mapper, discovery-coach, meeting-synthesizer, proposal-writer) when installed with --pack=sales. See Packs for opt-in install.

AgentModelRoleTools
brainstormeropusInteractive brainstorming facilitatorRead, Glob, Grep, Write, Edit, WebSearch, WebFetch
business-analystopusBusiness viability analysis + market researchRead, Glob, Grep, Write, Edit, WebSearch, WebFetch
prd-writeropusInteractive PRD co-writing via conversationRead, Glob, Grep, Write, Edit
requirement-analystsonnetExtract requirements from PRDRead, Glob, Grep, Write, Edit
ux-designeropusCreate UX spec (v0: spec only)Read, Glob, Grep, Write, Edit
uiux-developeropusDesign philosophy + design system + HTML/CSS prototypeRead, Glob, Grep, Write, Edit, Bash, WebSearch, WebFetch
mobile-uiux-developeropusMobile design system + React Native (Expo) prototypeRead, Glob, Grep, Write, Edit, Bash, WebSearch, WebFetch
desktop-uiux-developeropusDesktop design system + Electron/Tauri prototypeRead, Glob, Grep, Write, Edit, Bash, WebSearch, WebFetch
copywriteropusWrite all user-facing copy (labels, errors, CTAs)Read, Glob, Grep, Write, Edit
figma-converteropusConvert Figma exports to clean prototype HTML with design tokensRead, Glob, Grep, Write, Edit, Bash
architectopusDesign software architectureRead, Glob, Grep, Write, Edit
data-modeleropusDesign schemas, indexes, migrations, query patternsRead, Glob, Grep, Write, Edit
planneropusBreak work into issues + convert review findings to issuesRead, Glob, Grep, Write, Edit
issue-writersonnetNatural language → issue creation + planning/design docs updateRead, Glob, Grep, Write, Edit, Bash
qa-designeropusDesign test strategy and casesRead, Glob, Grep, Write, Edit
team-leadopusSprint phase executor — receives one phase (implement/review/ship), executes it, returnsRead, Glob, Grep, Write, Edit, Bash, Task
developeropusImplement code + GH Issue/PR + report discovered findingsRead, Glob, Grep, Write, Edit, Bash
test-generatoropusGenerate missing unit/integration/E2E testsRead, Glob, Grep, Write, Edit, Bash
revieweropusSenior code review + security auditRead, Glob, Grep, Edit, Bash, Write
ui-reviewersonnetUI review — state coverage, copy, tokens, a11yRead, Glob, Grep, Edit, Write
design-auditorsonnetDesign system audit — token consistency, component completenessRead, Glob, Grep, Edit, Write
a11y-auditorsonnetWCAG 2.1 AA accessibility auditRead, Glob, Grep, Edit, Write
documentersonnetMaintain documentationRead, Glob, Grep, Write, Edit
diagnosticianopusAnalyze bugs and propose targeted fixesRead, Glob, Grep, Write, Edit, Bash
migratoropusPlan and execute migrationsRead, Glob, Grep, Write, Edit, Bash
refactoreropusImprove code structure without changing behaviorRead, Glob, Grep, Write, Edit, Bash
devopssonnetSet up CI/CD pipelines and deployment infraRead, Glob, Grep, Write, Edit, Bash
codebase-scannersonnetAnalyze existing codebase in 4 passes (identity, architecture, requirements, quality)Read, Glob, Grep
scan-analystsonnetReverse-engineer requirements from existing code and testsRead, Glob, Grep, Write, Edit
scan-architectsonnetDocument as-is architecture from scan contextRead, Glob, Grep, Write, Edit
scan-data-modelersonnetExtract data models from ORM/migration/schema declarationsRead, Glob, Grep, Write, Edit
scan-qa-designersonnetAssess existing test coverage and identify gapsRead, Glob, Grep, Write, Edit
scan-planneropusGenerate improvement issues from scan observationsRead, Glob, Grep, Write, Edit

Roadmap

The next layer the kit is building: AI dev team control plane — telemetry → eval → cumulative learning memory. Each issue ships as its own SPEC + PR; no dates committed.

  • ISSUE-001 — Run telemetry: every agent invocation, tool call, and phase emits a JSONL trace event so lead time, retry rate, and finding density can be measured without touching agent prompts.
  • ISSUE-002 — Workflow eval gate: LLM-as-judge scoring of review_notes.md against the PR diff. Non-blocking advisory at first; data feeds future thresholds.
  • ISSUE-003 — Cumulative learning memory: promote docs/review_lessons.md to a structured pattern store (.claude/memory/patterns.jsonl + docs/decision_log.md). The reviewer and planner agents consume top-N patterns as preamble context.
  • ISSUE-008 — Virtual monorepo wrapper code support: per-service routing helpers + wrapper-root detection. Gated on telemetry signal (ISSUE-001) that polyrepo teams actually hit friction.

Recently shipped (Cluster C + D this session): /spec skill + Spec-Required metadata (ISSUE-006), /implement Phase 0 spec gate (ISSUE-007), Pilot Gate hardening — neutral observation + separate-context critic + specificity + auto-cycle (ISSUE-010), Kill WebFetch reference fabrication (ISSUE-011), Reference Anchor tuning to 2–3 cues + literal_quote (ISSUE-012), design-auditor / ui-reviewer scope split (ISSUE-013). See docs/specs/ for each SPEC.

Project Structure

claude-dev-kit/
├── agents/                  # Core engineering agents (33)
├── skills/                  # Core engineering / design / safety skills (23)
├── packs/                   # Opt-in domain packs
│   └── sales/               # Sales pack (5 agents + 5 skills + 7 templates)
│       ├── agents/
│       ├── skills/
│       ├── templates/
│       └── manifest.yaml
│   ├── brainstorm/SKILL.md
│   ├── bizanalysis/SKILL.md
│   ├── prd/SKILL.md
│   ├── kickoff/SKILL.md
│   ├── issue/SKILL.md
│   ├── uiux/SKILL.md
│   ├── figma2proto/SKILL.md    # Convert Figma exports to prototype
│   ├── mobile-uiux/SKILL.md
│   ├── desktop-uiux/SKILL.md
│   ├── scan/SKILL.md        # Reverse-engineer docs from existing codebase
│   ├── sprint/SKILL.md
│   ├── implement/SKILL.md
│   ├── review/SKILL.md
│   ├── ship/SKILL.md
│   ├── diagnose/SKILL.md
│   ├── migrate/SKILL.md
│   ├── refactor/SKILL.md
│   ├── testgen/SKILL.md
│   ├── devops/SKILL.md
│   ├── careful/SKILL.md     # Safety guardrail: destructive command warnings
│   ├── freeze/SKILL.md      # Safety guardrail: edit boundary enforcement
│   └── guard/SKILL.md       # Safety guardrail: careful + freeze combined
├── templates/               # Core document templates (26)
├── project/                 # Files installed into target project
│   └── .claude/
│       ├── hooks/agent_state.py
│       └── settings.snippet.json
├── scripts/                 # Install and utility scripts
│   ├── install_user.sh
│   ├── install_project.sh
│   ├── ensure_gh.sh
│   ├── ensure_permissions.py
│   ├── merge_settings.py
│   ├── gen_skills.py        # Template → SKILL.md generator
│   ├── preambles.py         # Tiered preamble injection
│   ├── validate_issues.py   # issues.md format validator
│   ├── verify_checkpoint.py # Skill phase checkpoint verification
│   ├── verify_gates.py      # Platform gate engine (e2e-web, e2e-mobile, api, load, …)
│   ├── gate_server.sh       # Server lifecycle wrapper for e2e/api gates
│   ├── checkpoint.sh        # Wrapper: resolve repo root + run verify_checkpoint.py
│   ├── worktree.sh          # git worktree lifecycle (create/path/remove/root)
│   ├── wt_setup.sh          # Wrapper: worktree create + freeze marker in one step
│   ├── wt_cleanup.sh        # Wrapper: safe cd-to-root + worktree remove
│   ├── registry_edit.sh     # Wrapper: flock_edit on main-rooted registry files
│   └── flock_edit.sh        # file-lock wrapper for shared files
├── user/                    # User-level tools
│   └── kit/bin/cc-statusline.py
├── tests/                   # Tests
├── docs/                    # Kit documentation
│   └── PRD_agent_system_v0.md
└── README.md

Platform Gates

/implement and /ship automatically run platform-specific test gates via scripts/verify_gates.py. Gates are detected from the project layout — no manual wiring required if you use the default conventions.

GateDetected when…Default blocking
unittests/ directory or test_*.py / *.test.ts / *.spec.ts files existyes
integrationtests/integration/ directory existsyes
e2e-webplaywright.config.* exists or package.json lists React/Vue/Svelte/Next/Angular/Nuxtyes
e2e-mobileapp.json / android/ / ios/ exists or package.json lists react-nativeyes
apiopenapi.{yaml,json} exists or pyproject.toml lists FastAPI/Flask/Django (or Express in JS)yes
loadLocust / k6 / Artillery config presentno (warn)

Gate behavior by phase:

  • /implement → non-blocking: failing gates surface as warnings during implementation, flagging integration risks early without stopping the TDD loop.
  • /ship → blocking: failing a real gate must stop ship. load stays non-blocking even here, since perf work is typically out-of-band.

Missing tools (Playwright browsers, Maestro, Detox) are auto-installed before the gate runs. Server-based gates (e2e-web, api) use scripts/gate_server.sh to start the app, poll a health endpoint, run the test command, and clean up the process group on exit.

Configuring gates via docs/test_plan.md

qa-designer generates a ## Verify Gates Configuration section in docs/test_plan.md. Users can edit it to override defaults without touching Python:

## Verify Gates Configuration

Server start command: `npm run dev`
Server health URL: `http://localhost:3000`
Server startup timeout: 30
Mobile test framework: `maestro`
Mobile build command: `npm run build:ios`
Mobile Detox config: `ios.sim.debug`

### Gate Overrides
| Gate        | Enabled | Blocking |
|-------------|---------|----------|
| unit        | yes     | yes      |
| integration | yes     | yes      |
| e2e-web     | yes     | yes      |
| e2e-mobile  | yes     | yes      |
| api         | yes     | yes      |
| load        | yes     | no       |

Key names are parsed literally by scripts/verify_gates.py — do not rename them. If the section is absent, defaults are used.

Status Line

After installation, the Claude Code status line displays:

claude-opus-4-6 | agents:ux-designer,developer | tool:Write | tok:45230/200000 | $0.123

Shows the current model, active agents, last tool used, token usage, and cumulative cost.

Testing

pytest tests/ -q

Tests cover merge logic, agent state hooks, worktree lifecycle, file locking, integration checks (frontmatter, templates, cross-references), scan pipeline validation, skill generation, preamble injection, safety guardrails, and more.

Updating

Pull the latest submodule changes and re-run the project install script:

cd .claude-kit
git pull origin main
cd ..
bash .claude-kit/scripts/install_project.sh

Concurrency

Multiple skill sessions (e.g., two /implement runs on different issues) can execute in parallel thanks to git worktrees. Each session gets its own working directory under .worktrees/, so branches never collide.

# Worktree lifecycle (used internally by skills)
bash scripts/worktree.sh create issue/ISSUE-001-login   # → .worktrees/issue-ISSUE-001-login/
bash scripts/worktree.sh path   issue/ISSUE-001-login   # print path
bash scripts/worktree.sh remove issue/ISSUE-001-login   # cleanup
bash scripts/worktree.sh root                            # main repo root

Shared files (issues.md, STATUS.md) live in the main repo root and are protected by an exclusive file lock during read-modify-write:

ROOT="$(bash scripts/worktree.sh root)"
bash scripts/flock_edit.sh "$ROOT/issues.md" -- bash -c 'echo "update" >> "$ROOT/issues.md"'

flock_edit.sh uses flock(1) when available, falling back to mkdir-based locking on macOS.

Current Scope (v0.1)

  • Platform: macOS / Linux
  • Default stack (when PRD doesn't specify):
    • Backend: Django + Postgres
    • Web frontend: React + TypeScript
    • Mobile: React Native (Expo)
  • Custom stack: Define your preferred tech stack during /prd and the architect agent will follow it
  • Model mix: opus (21 agents) for judgment/creativity, sonnet (12 agents) for structured extraction

License

MIT

Ver o original no GitHub

Bom para

Relacionados