diff --git a/README.md b/README.md index 42c38b4..7b47ee9 100644 --- a/README.md +++ b/README.md @@ -1,494 +1,268 @@ # Devkit -A deterministic development harness for AI agents. - -AI agents write code fast but cut corners — they skip error handling, introduce race conditions, ignore edge cases, and refactor things you didn't ask them to touch. Devkit is the infrastructure layer between you and the agents. A Go engine executes workflows deterministically — branching, loops, budget enforcement, and parallel dispatch all happen in compiled code, not LLM reasoning. 9 language-aware hooks enforce quality at every stage of the lifecycle across Go, TypeScript, Rust, Python, and Shell — many learned directly from bugs found in previous review cycles. The system gets better every time it catches something new. - -Define your workflow in YAML. The engine handles orchestration. The agent handles creativity. Every change is measured, gated, and auditable. +A deterministic development harness for AI agents. The Go engine controls orchestration (loops, branches, gates, budgets). The agent handles creativity. Every change is measured, gated, and auditable. Works with just Claude. Optionally adds Codex and Gemini for multi-agent consensus. +--- + ## Install +### 1. Devkit (required) + ```bash /plugin marketplace add https://github.com/5uck1ess/marketplace.git /plugin install devkit@5uck1ess-plugins ``` -### Holistic Setup +Auto-updates are enabled by default. Devkit updates itself when you restart Claude Code. -Devkit focuses on enforcement, orchestration, and multi-agent workflows. For a complete setup, add these companion plugins — each handles a different concern with no overlap. +### 2. Multi-agent plugins (optional) -| Plugin | What it handles | Install | -|---|---|---| -| **[superpowers](https://github.com/obra/superpowers)** | Methodology — brainstorming, planning, TDD, verification, debugging | `/plugin install superpowers@claude-plugins-official` | -| **[feature-dev](https://github.com/anthropics/claude-plugins-official)** | Deep feature exploration — parallel codebase analysis, architecture proposals, interactive design | `/plugin install feature-dev@claude-plugins-official` | -| **[pr-review-toolkit](https://github.com/anthropics/claude-plugins-official)** | Specialized review agents — comment accuracy, type design, silent failure hunting, error handling | `/plugin install pr-review-toolkit@claude-plugins-official` | -| **[commit-commands](https://github.com/anthropics/claude-plugins-official)** | Quick commits — auto-message `/commit`, one-shot `/commit-push-pr`, stale branch cleanup `/clean_gone` | `/plugin install commit-commands@claude-plugins-official` | -| **[hookify](https://github.com/anthropics/claude-plugins-official)** | Hook creation — markdown-based rules, hot reload, conversation analysis for auto-detection | `/plugin install hookify@claude-plugins-official` | -| **[skill-creator](https://github.com/anthropics/claude-plugins-official)** | Skill development — eval/benchmark framework, blind A/B comparison, iterative improvement | `/plugin install skill-creator@claude-plugins-official` | -| **[context-mode](https://github.com/mksglu/context-mode)** | Context window management — sandboxes large outputs, session continuity via SQLite, 98% savings | See below | - -#### Context Mode Install +These enable `tri:*` commands (tri-review, tri-debug, tri-security, etc.) to run Claude + Codex + Gemini in parallel. -Plugin install (recommended — includes hooks + slash commands): ```bash -/plugin marketplace add mksglu/context-mode -/plugin install context-mode@context-mode +# Codex plugin +/plugin marketplace add openai/codex-plugin-cc +/plugin install codex@openai-codex + +# Gemini plugin +/plugin marketplace add abiswas97/gemini-plugin-cc +/plugin install gemini@abiswas97-gemini ``` -MCP-only install (lighter — sandbox tools only, no auto-routing): +If plugins aren't installed, the CLI fallbacks work too: ```bash -claude mcp add context-mode -- npx -y context-mode +brew install codex gemini-cli ``` -Verify with `/context-mode:ctx-doctor` (plugin install) or check MCP tools are available (MCP install). +### 3. Companion plugins (optional) + +These handle concerns devkit doesn't — methodology, specialized reviews, and context management. No overlap. + +```bash +# Methodology — brainstorming, planning, TDD, verification, debugging +/plugin install superpowers@claude-plugins-official -**Why these and not others?** We evaluated every plugin in the official marketplace. These are the ones that add unique value without duplicating what devkit already does. Notably: +# Specialized review agents — comment accuracy, type design, silent failures +/plugin install pr-review-toolkit@claude-plugins-official -- **`code-simplifier`** — skip it. Thin, single-agent, hardcoded to React/TS. Devkit's `refactor` + `clean-code`/`dry`/`yagni` skills are more comprehensive. -- **`security-guidance`** — skip it. Devkit's `security-patterns` hook + `tri-security` command cover more patterns across more languages. -- **`code-review`** — skip it. Devkit's `tri-review` provides cross-model diversity (Claude + Codex + Gemini). -- **`ralph-loop`** — skip it. Devkit's `self-*` loops are specialized with proper metric gates. +# Deep feature exploration — parallel codebase analysis, architecture proposals +/plugin install feature-dev@claude-plugins-official -### How they fit together +# Quick commits — /commit, /commit-push-pr, /clean_gone +/plugin install commit-commands@claude-plugins-official +# Hook creation — markdown rules, hot reload, conversation analysis +/plugin install hookify@claude-plugins-official + +# Skill development — eval/benchmark framework, blind A/B testing +/plugin install skill-creator@claude-plugins-official + +# Context window management — sandboxes large outputs, 98% token savings +/plugin marketplace add mksglu/context-mode +/plugin install context-mode@context-mode ``` -┌─────────────────────────────────────────────────────┐ -│ Your Project │ -├──────────┬──────────┬──────────┬─────────────────────┤ -│ Thinking │ Building │ Shipping │ Maintaining │ -├──────────┼──────────┼──────────┼─────────────────────┤ -│superpow- │ devkit │ devkit │ devkit │ -│ers: │ feature │ pr-ready │ self-improve/test/ │ -│ brain- │ bugfix │ pr-moni- │ lint/perf/migrate │ -│ storm │ refactor │ tor │ │ -│ plan │ decompose│ │ tri-review/debug/ │ -│ TDD │ │ commit- │ security/test-gen │ -│ debug │feature- │ commands │ │ -│ │dev: │ │ pr-review-toolkit │ -│ │ explore │ │ │ -│ │ design │ │ audit, repo-map │ -├──────────┴──────────┴──────────┴─────────────────────┤ -│ Auto skills: test-gen, doc-gen, changelog, onboard, │ -│ research, scrape (no slash command needed) │ -├──────────────────────────────────────────────────────┤ -│ Always active: devkit hooks (safety, security, │ -│ audit, slop, lang-review, security, stop-gate) │ -├──────────────────────────────────────────────────────┤ -│ Meta: hookify (create hooks), skill-creator (skills) │ -│ context-mode (token management) │ -└──────────────────────────────────────────────────────┘ + +### 4. Optional tools + +```bash +brew install rtk # Token optimization (60-90% savings on Bash output) +brew install ast-grep # AST-based repo mapping (/devkit:repo-map) ``` +### Verify + +```bash +/devkit:status +``` + +This shows which CLIs are installed, which agents are available, and which commands are ready. + --- ## Quick Start ```bash -# Check what's available -/devkit:status - # These activate automatically — just ask naturally: # "write tests for src/parser.ts" # "generate a changelog" # "help me understand this codebase" # "research the best auth library for Node" -# "scrape this URL: https://example.com" # Slash commands for complex workflows: -/self:lint --lint "npm run lint" --target src/ -/devkit:pr-ready -/tri:review +/devkit:pr-ready # Full PR pipeline +/tri:review # Multi-agent code review +/self:lint --lint "npm run lint" # Fix all lint errors ``` --- ## Commands -### Solo Commands (Claude-only, no external CLIs needed) +### Development Lifecycle -| Command | Description | +| Command | What it does | |---|---| -| `/devkit:pr-ready` | Full PR pipeline — lint, test, security, changelog, create PR | -| `/devkit:pr-monitor` | Post-PR review monitor — watches CI, resolves reviewer comments iteratively | -| `/devkit:repo-map` | AST-based symbol index — exports, classes, imports, dependency graph, cached | -| `/devkit:workflow` | Run user-defined YAML workflows from `workflows/` | -| `/devkit:bugfix` | Full bug fix lifecycle — reproduce, diagnose, fix, regression test, verify | -| `/devkit:feature` | Full feature lifecycle — brainstorm, plan, implement, test, lint, review | -| `/devkit:refactor` | Full refactor lifecycle — analyze, plan, restructure, verify, compare | -| `/devkit:decompose` | Goal decomposition — break into task DAG, assign agents, execute in dependency order | -| `/devkit:audit` | Full project health audit — deps, vulnerabilities, licenses, lint, security | -| `/devkit:deep-research` | ACH-enhanced deep research — competing hypotheses, directed disconfirmation, evidence matrix, sensitivity analysis | -| `/devkit:status` | Health check — installed CLIs, available agents, ready commands | -| `/devkit:setup-rules` | Install language-specific coding rules to `~/.claude/rules/` | - -### Self-Improvement Loops (Claude-only) +| `/devkit:feature` | Brainstorm, plan, implement, test, lint, review | +| `/devkit:bugfix` | Reproduce, diagnose, fix, regression test, verify | +| `/devkit:refactor` | Analyze smells, plan, restructure, verify nothing broke | +| `/devkit:decompose` | Break a goal into a task DAG, assign agents, execute in order | -Automated propose → measure → keep/discard → repeat cycles. +### Shipping -| Command | Description | +| Command | What it does | |---|---| -| `/self:improve` | General-purpose improvement loop with custom metric gate | -| `/self:test` | Iteratively generate tests until coverage target is hit | -| `/self:lint` | Iteratively fix lint/type errors until zero remain | -| `/self:perf` | Hypothesis-driven performance investigation — evidence, hypotheses, one-at-a-time testing | -| `/self:migrate` | Incremental migration (JS→TS, class→hooks, etc.) with test gate | -| `/self:audit` | Codebase audit inspired by karpathy/autoresearch — measure everything, rank hypotheses, report only | -| `/devkit:autoloop` | Autonomous improvement loop — audit, fix, measure, keep or revert, repeat | +| `/devkit:pr-ready` | Lint, test, security, changelog, create PR | +| `/devkit:pr-monitor` | Watch CI, fetch reviewer comments, fix iteratively, push | -### Multi-Agent Commands (Claude + optional Codex/Gemini) +### Self-Improvement Loops -These run with whatever agents are available. Claude always runs. Codex and Gemini are used if installed. +Automated propose / measure / keep or discard / repeat cycles. -| Command | Description | +| Command | What it does | |---|---| -| `/tri:review` | Code review from 1–3 agents, consolidated report | -| `/tri:dispatch` | Send any task to available agents, compare outputs | -| `/tri:debug` | Multi-perspective debugging — independent root-cause analysis | -| `/tri:test-gen` | Generate tests from multiple agents, merge best coverage | -| `/tri:security` | Security audit from multiple agents, severity-ranked consensus | +| `/self:improve` | General-purpose loop with custom metric gate | +| `/self:test` | Generate tests until coverage target is hit | +| `/self:lint` | Fix lint/type errors until zero remain | +| `/self:perf` | Hypothesis-driven perf investigation | +| `/self:migrate` | Incremental migration (JS->TS, etc.) with test gate | +| `/self:audit` | Measure everything, rank hypotheses, report only | +| `/devkit:autoloop` | Autonomous improvement loop — audit, fix, measure, repeat | ---- - -## Agents - -| Agent | Model | Isolation | Effort | Max Turns | Used by | -|---|---|---|---|---|---| -| `reviewer` | Opus | Worktree | High | 10 | tri:review | -| `researcher` | Sonnet | Worktree | Medium | 15 | tri:dispatch, tri:debug, onboard | -| `improver` | Opus | Worktree | High | 10 | self:*, tri:dispatch | -| `test-writer` | Sonnet | Worktree | Medium | 15 | test-gen, self:test, tri:test-gen | -| `documenter` | Haiku | Worktree | Medium | 10 | doc-gen | -| `security-auditor` | Opus | Worktree | High | 10 | tri:security, pr-ready, audit | - ---- - -## Skills - -Skills activate automatically based on context — no slash command needed. Just ask naturally. +### Multi-Agent (Claude + Codex + Gemini) -### Context-Activated Workflows +Runs with whatever agents are available. Claude always runs. -These replace slash commands. Ask naturally and the skill fires: - -| Skill | Triggers on | -|---|---| -| `devkit:test-gen` | "write tests for X", "add test coverage", "generate tests" | -| `devkit:doc-gen` | "document this module", "generate API docs", "write docs for" | -| `devkit:changelog` | "generate a changelog", "release notes", "what changed since" | -| `devkit:onboard` | "explain this codebase", "help me understand the architecture", "onboard" | -| `devkit:research` | "research X", "compare approaches for", "investigate options" | -| `devkit:deep-research` | "deep research", "validate this", "make sure this is right", "rigorous analysis" | -| `devkit:scrape` | "scrape this URL", "fetch content from", "extract from this page" | -| `devkit:adr` | "create an ADR", "document this decision", "record why we chose X" | - -### Coding Principles - -Loaded as reference material when relevant: - -| Skill | Description | +| Command | What it does | |---|---| -| `devkit:executing` | Execute plans methodically — understand, implement, verify, commit | -| `devkit:clean-code` | Meaningful names, small functions, single responsibility, flat nesting | -| `devkit:dry` | Rule of Three, when duplication is fine, extracting the right abstraction | -| `devkit:yagni` | Build only what's needed, no speculative features or premature abstractions | -| `devkit:dont-reinvent` | Use existing libraries, tools, and stdlib before building custom solutions | -| `devkit:stuck` | Detect agent looping/failing, structured recovery — backtrack, simplify, escalate | -| `devkit:scratchpad` | Iteration memory protocol — prevents Groundhog Day loops by recording what was tried | +| `/tri:review` | Code review from 1-3 agents, consolidated report | +| `/tri:dispatch` | Send any task to all agents, compare outputs | +| `/tri:debug` | Independent root-cause analysis from each agent | +| `/tri:test-gen` | Generate tests from multiple agents, merge coverage | +| `/tri:security` | Security audit with severity-ranked consensus | -### Tools +### Utility -| Skill | Description | +| Command | What it does | |---|---| -| `devkit:gcli` | Google Workspace CLI (Gmail, Calendar, Drive) via gcli with `--for-ai` | -| `devkit:creating-workflows` | How to create workflow YAML files — schema, step types, interpolation | - -For brainstorming, planning, TDD, verification, and skill authoring — install [superpowers](https://github.com/obra/superpowers). - -### Coding Rules (user-level) +| `/devkit:repo-map` | AST-based symbol index with dependency graph | +| `/devkit:deep-research` | Competing hypotheses, disconfirmation, evidence matrix | +| `/devkit:audit` | Dependencies, vulnerabilities, licenses, lint, security | +| `/devkit:workflow` | Run user-defined YAML workflows | +| `/devkit:status` | Health check | +| `/devkit:setup-rules` | Install language-specific coding rules to `~/.claude/rules/` | -Language-specific rules that auto-activate when Claude reads matching files. Installed to `~/.claude/rules/` (not part of the plugin — plugins don't support `rules/`). These complement hooks: **rules guide how to write, hooks catch what you missed**. +--- -Install with one command: +## Skills -``` -/devkit:setup-rules -``` +Skills activate automatically based on context. No slash command needed. -| File | Paths | Examples (see file for full list) | -|---|---|---| -| `go.md` | `**/*.go` | Error wrapping, context.Context, defer traps, JSON float64 gotcha, range var reuse | -| `typescript.md` | `**/*.{ts,tsx,js,jsx,mjs,cjs}` | unknown not any, discriminated unions, catch narrowing, nullish coalescing, sort mutation | -| `python.md` | `**/*.py` | Exception chains, type hints, dataclasses, pathlib, ruff, is vs == | -| `rust.md` | `**/*.rs` | Ownership/borrowing, ? propagation, newtypes, if let/let else, clippy-as-errors | -| `shell.md` | `**/*.sh` | set -euo pipefail, quoting, macOS portability, subshell traps, mktemp + trap | +| Trigger | Skill | +|---|---| +| "write tests for X" | `test-gen` | +| "document this module" | `doc-gen` | +| "generate a changelog" | `changelog` | +| "explain this codebase" | `onboard` | +| "research X" | `research` | +| "deep research", "validate this" | `deep-research` | +| "scrape this URL" | `scrape` | +| "create an ADR" | `adr` | -Each file uses `paths:` frontmatter for scoped activation. ~10 rules per file, ~20 lines — minimal token overhead. +Coding principles (`clean-code`, `dry`, `yagni`, `dont-reinvent`, `executing`, `stuck`, `scratchpad`) load as reference when relevant. --- ## Hooks -Devkit ships 10 hooks across 4 lifecycle events. All are installed automatically with the plugin — no setup required. - -### PreToolUse - -| Hook | Matcher | What it does | -|---|---|---| -| **safety-check** | Bash, Edit, Write | Blocks destructive commands (`rm -rf /`, `DROP TABLE`, private key writes). Prompts on risky operations (force push, `git reset --hard`, editing secrets). | -| **security-patterns** | Edit, Write | Catches vulnerability patterns at creation time — `eval()`, XSS, shell injection, weak hashes, hardcoded secrets, path traversal. Language-aware (JS/TS/Python/Go). | -| **audit-trail** | Bash | Logs every command to `.devkit/audit.log` with UTC timestamps. Auto-rotates at 10k lines. | -| **pr-gate** | Bash | Detects `gh pr create` and prompts to run `/devkit:pr-ready` first. 10-minute cooldown. | -| **rtk-rewrite** | Bash | Rewrites commands through [RTK](https://github.com/rtk-ai/rtk) for 60-90% token savings. No-op if RTK not installed. | - -### PostToolUse - -| Hook | Matcher | What it does | -|---|---|---| -| **post-validate** | Bash, Edit, Write | Warns on suppressed errors, leaked secrets in written content, writes outside repo. | -| **slop-detect** | Edit, Write | Catches AI code patterns — doc/code ratio imbalance, restating comments, excessive JSDoc in .js files. | -| **lang-review** | Edit, Write | Language-aware code quality checks. Detects language from file extension and runs the right checks: Go (error-path access, map races, nil-error returns, filepath traversal), TypeScript (empty catches, any-type, unhandled promises), Rust (unwrap in non-test, let _ = discard, unsafe blocks), Python (bare except, pass-in-except, mutable defaults), Shell (macOS portability — grep -P, sed -i, readlink -f, timeout). | - -### SubagentStop - -| Hook | Matcher | What it does | -|---|---|---| -| **subagent-stop** | Stop | Verifies subagent work products before accepting. Recognizes Go, Node, Python, Rust, and generic test frameworks. | - -### Stop +10 hooks across 4 lifecycle events. All installed automatically with the plugin. -| Hook | Matcher | What it does | +| Event | Hook | What it catches | |---|---|---| -| **stop-gate** | Stop | Consolidated quality gate: detects merge conflicts, checks cross-domain test evidence (blocks if backend + frontend changed but only one tested), runs language-appropriate linter (go vet + race detector, cargo clippy, tsc --noEmit, ruff). | +| PreToolUse | **safety-check** | `rm -rf /`, `DROP TABLE`, force push, editing secrets | +| PreToolUse | **security-patterns** | `eval()`, XSS, shell injection, weak hashes, hardcoded secrets | +| PreToolUse | **audit-trail** | Logs every command to `.devkit/audit.log` | +| PreToolUse | **pr-gate** | Prompts to run `/devkit:pr-ready` before `gh pr create` | +| PreToolUse | **rtk-rewrite** | Compresses Bash output via RTK (no-op if not installed) | +| PostToolUse | **post-validate** | Suppressed errors, leaked secrets, writes outside repo | +| PostToolUse | **slop-detect** | AI code patterns — doc/code imbalance, restating comments | +| PostToolUse | **lang-review** | Language-aware checks: Go, TypeScript, Rust, Python, Shell | +| SubagentStop | **subagent-stop** | Verifies subagent work before accepting | +| Stop | **stop-gate** | Merge conflicts, cross-domain test gaps, linter pass | --- -## RTK Token Optimization - -Optional [RTK](https://github.com/rtk-ai/rtk) integration compresses Bash output before it reaches the context window. +## Agents -| Operation | Before | After | Savings | -|---|---|---|---| -| Directory listing | ~2,000 tokens | ~400 tokens | 80% | -| Test output | ~25,000 tokens | ~2,500 tokens | 90% | -| Git operations | ~3,000 tokens | ~600 tokens | 80% | -| Search results | ~16,000 tokens | ~3,200 tokens | 80% | +| Agent | Model | Used by | +|---|---|---| +| `reviewer` | Opus | tri:review | +| `researcher` | Sonnet | tri:dispatch, tri:debug, onboard | +| `improver` | Opus | self:*, tri:dispatch | +| `test-writer` | Sonnet | test-gen, self:test, tri:test-gen | +| `documenter` | Haiku | doc-gen | +| `security-auditor` | Opus | tri:security, pr-ready, audit | -```bash -brew install rtk -``` +All agents run in worktree isolation. --- -## Presets +## Coding Rules -Reusable prompt templates in `presets/`. Reference with `--preset`: +Language-specific rules that auto-activate when Claude reads matching files. Installed to `~/.claude/rules/` — rules guide how to write, hooks catch what you missed. ```bash -/tri:review --preset security-web -/tri:security --preset security-go -/self:perf --preset react-perf -``` - -### Included Presets - -None yet — `presets/` is reserved for future use. - ---- - -## Architecture - -``` -devkit workflow (generic YAML engine) - ├── Parse YAML → validate steps, branches, budget - ├── Create session + git branch - ├── Walk steps sequentially: - │ ├── Interpolate {{variables}} in prompts - │ ├── Call runner (Claude/Codex/Gemini) - │ ├── Evaluate branches (case-insensitive substring match → goto) - │ ├── Loop with hard counter + until-string match - │ ├── Parallel dispatch via goroutines - │ └── Budget enforcement (checked every step + inside loops) - └── Commit, report, clean up - -/tri:review (or any tri:* command) - ├── Claude → native background agent (always runs) - ├── Codex → plugin (preferred) or CLI subprocess (fallback) - └── Gemini → plugin (preferred) or CLI subprocess (fallback) - -/self:improve (or any self:* command) - └── Claude → improver agent in worktree - ↓ propose change - ↓ run metric - ↓ keep if pass / revert if fail - ↓ repeat -``` - ---- - -## Repository Structure - -``` -devkit/ -├── .claude-plugin/ -│ └── plugin.json # Plugin metadata (name, version, author) -├── ROADMAP.md # Implemented features and future plans -├── PREFERENCES.md # Agent behavior guidelines -├── commands/ # 24 slash commands (tab-completable) -│ ├── tri-*.md # Multi-agent dispatch (5) -│ ├── self-*.md # Self-improvement loops (6) -│ ├── pr-ready.md # PR preparation pipeline -│ ├── pr-monitor.md # Post-PR review monitor -│ ├── bugfix.md # Bug fix lifecycle -│ ├── feature.md # Feature lifecycle -│ ├── refactor.md # Refactor lifecycle -│ ├── decompose.md # Goal decomposition -│ ├── workflow.md # YAML workflow runner -│ ├── audit.md # Project health audit -│ ├── repo-map.md # AST-based symbol index -│ ├── status.md # Health check -│ └── setup-rules.md # Install coding rules to ~/.claude/rules/ -├── skills/ # 18 context-activated skills -│ ├── executing/SKILL.md # Principle: methodical execution -│ ├── clean-code/SKILL.md # Principle: readability -│ ├── dry/SKILL.md # Principle: don't repeat yourself -│ ├── yagni/SKILL.md # Principle: no speculative features -│ ├── dont-reinvent/SKILL.md # Principle: use existing solutions -│ ├── stuck/SKILL.md # Principle: loop recovery -│ ├── creating-workflows/SKILL.md # Tool: YAML workflow authoring -│ ├── gcli/SKILL.md # Tool: Google Workspace CLI -│ ├── changelog/SKILL.md # Auto: "generate a changelog" -│ ├── doc-gen/SKILL.md # Auto: "document this module" -│ ├── test-gen/SKILL.md # Auto: "write tests for X" -│ ├── onboard/SKILL.md # Auto: "explain this codebase" -│ ├��─ research/SKILL.md # Auto: "research X" -│ ├── deep-research/SKILL.md # Auto: "deep research", ACH pipeline -│ ├── scratchpad/SKILL.md # Iteration memory protocol -│ ├── scrape/SKILL.md # Auto: "scrape this URL" -│ └── adr/SKILL.md # Auto: "create an ADR", decision records -├── agents/ # 6 agents -│ ├── reviewer.md # Opus, worktree isolation -│ ├── researcher.md # Sonnet, worktree isolation -│ ├── improver.md # Opus, worktree isolation -│ ├── test-writer.md # Sonnet, worktree isolation -│ ├── documenter.md # Haiku, worktree isolation -│ └── security-auditor.md # Opus, worktree isolation -├── hooks/ # 10 hooks across 4 lifecycle events -│ ├── hooks.json # Hook config (auto-loaded) -│ ├── safety-check.sh # Dangerous operation blocker -│ ├── security-patterns.sh # Edit-time vulnerability detection -│ ├── audit-trail.sh # Command logging -│ ├── rtk-rewrite.sh # Token optimization -│ ├── pr-gate.sh # PR pipeline prompt -│ ├── post-validate.sh # Output validation -│ ├── slop-detect.sh # AI pattern detection -│ ├── lang-review.sh # Language-aware code quality (Go/TS/Rust/Python/Shell) -│ ├── subagent-stop.sh # Subagent work verification -│ └── stop-gate.sh # Consolidated quality gate (cross-domain + vet/lint) -├── resources/rules/ # Reference rule files (installed via /devkit:setup-rules) -├── workflows/ # 15 YAML workflow definitions -├── presets/ # Reserved for future use -├── .github/workflows/ # CI/CD -│ ├── ci.yml # Build + test + vet on push/PR -│ └── release.yml # Auto-tag + release on version bump -└── src/ # Go CLI harness - ├── cmd/ # Cobra commands (including workflow) - ├── engine/ # Generic YAML workflow engine — parser, executor, tests - ├── lib/ # DB, git, metric, state, report - ├── loops/ # Improve, feature, bugfix, refactor, testgen, review, dispatch - └── runners/ # Claude, Codex, Gemini runner interfaces +/devkit:setup-rules ``` ---- - -## Autonomy Flags - -Set automatically in each multi-agent command: - -| Agent | Flags | +| Language | Examples | |---|---| -| Claude | `--dangerously-skip-permissions` | -| Codex | `/codex:rescue --background` (via [codex-plugin-cc](https://github.com/openai/codex-plugin-cc)) or `codex -q` (CLI fallback) | -| Gemini | `/gemini:rescue --background` (via [gemini-plugin-cc](https://github.com/abiswas97/gemini-plugin-cc)) or `-y` (CLI fallback) | +| Go | Error wrapping, context.Context, defer traps, JSON float64 gotcha | +| TypeScript | `unknown` not `any`, discriminated unions, catch narrowing | +| Python | Exception chains, type hints, dataclasses, pathlib | +| Rust | Ownership, `?` propagation, newtypes, clippy-as-errors | +| Shell | `set -euo pipefail`, quoting, macOS portability | --- ## Go CLI Harness -Deterministic orchestration binary — the machine controls the loop, the agent is the body. +The compiled Go binary handles deterministic orchestration — the machine controls the loop, the agent is the body. -```bash -cd src && make build && make link -devkit --help -``` - -Or install directly: +### Build ```bash cd src && make install ``` -### Commands - -All loop commands support `--agent` to choose the AI agent (default: `claude`). - -| Command | Description | -|---|---| -| `devkit workflow` | **Generic YAML workflow engine** — runs any workflow from `workflows/` deterministically | -| `devkit improve` | Metric-gated iteration loop — one agent invocation per iteration | -| `devkit feature` | Plan, implement, test, lint — commits only after tests pass | -| `devkit bugfix` | Diagnose, fix, verify — reverts if tests break | -| `devkit refactor` | Analyze, transform, verify — reverts if behavior changes | -| `devkit test-gen` | Generate tests, run, fix failures — iterates until green | -| `devkit review` | Parallel multi-agent code review | -| `devkit dispatch` | Send any task to multiple agents, compare outputs | -| `devkit status` | Show all sessions, costs, iteration history | -| `devkit resume` | Pick up a crashed or paused session | - ### What it does that plugins can't -- **Exact iteration counts** — Go binary owns the loop, not the LLM -- **Generic YAML workflows** — `devkit workflow ` executes any workflow definition deterministically. Branching, loops, parallel dispatch, budget enforcement, and variable interpolation all happen in Go — zero tokens spent on orchestration -- **Triage-based phase skipping** — feature and bugfix workflows classify task scope (TINY/SMALL/MEDIUM/LARGE) and skip unnecessary steps. A typo fix doesn't run a 14-step pipeline -- **Crash recovery** — SQLite state + handoff files survive crashes -- **Hard budget caps** — stops spawning at your dollar limit, including inside loops -- **CI/CD integration** — runs headless, no conversation needed +- **Exact iteration counts** — Go owns the loop, not the LLM +- **Command steps** — run shell commands directly in workflows, $0 cost +- **Loop gates** — shell command after each iteration, auto-revert on failure +- **YAML workflows** — branching, loops, parallel dispatch, budget enforcement +- **Triage-based skipping** — typo fix doesn't run a 14-step pipeline +- **Crash recovery** — SQLite state survives crashes +- **Hard budget caps** — stops at your dollar limit - **True parallel dispatch** — goroutines, not sequential prompts -- **Multi-agent support** — `--agent claude`, `--agent codex`, or `--agent gemini` ### Examples ```bash -# Run 50 improvement iterations overnight, stop at $20 +# Run 50 improvement iterations, stop at $20 devkit improve --metric "npm test" --iterations 50 --budget 20.00 -# Same thing with Codex instead of Claude -devkit improve --metric "npm test" --iterations 50 --agent codex - # Implement a feature with test verification devkit feature "add JWT auth" --target src/auth/ --test "npm test" -# Fix a bug with automated verification -devkit bugfix "login 500 on plus sign emails" --test "go test ./..." - -# Generate tests for a module -devkit test-gen src/parser/ --test "go test ./..." - -# Multi-agent review with all available agents +# Multi-agent review devkit review -# Run any YAML workflow by name +# Run any YAML workflow devkit workflow feature "add JWT auth" -devkit workflow bugfix "null pointer on empty input" - -# List available workflows -devkit workflow list -# Resume a crashed session -devkit resume abc123def456 - -# Check what happened +# Check session history devkit status ``` @@ -498,69 +272,52 @@ devkit status cd src && go test ./... -v ``` -100+ tests across 5 packages (engine, lib, runners, loops, cmd). Engine tests cover parsing, interpolation, branching, loops, budget, parallel dispatch, cycle detection. All tests use mock runners — no API calls needed. - -### CI/CD - -- **CI pipeline** (`.github/workflows/ci.yml`): build + vet + test (with `-race`) + gofmt check on every push/PR to main -- **Auto-release** (`.github/workflows/release.yml`): auto-bumps version, tags, and creates GitHub release on merged PRs +140+ tests across 6 packages. All use mock runners — no API calls needed. --- -## Prerequisites - -**Required:** Claude Code (you're already here) - -**Optional** (for multi-agent commands): -```bash -# Codex plugin (preferred for tri:* commands) -/plugin marketplace add openai/codex-plugin-cc -/plugin install codex@openai-codex - -# Gemini plugin (preferred for tri:* commands) -/plugin marketplace add abiswas97/gemini-plugin-cc -/plugin install gemini@abiswas97-gemini -``` +## Architecture -**CLI fallbacks** (used only if plugins are not installed): -```bash -brew install codex gemini-cli ``` +Workflow Engine (Go binary) + ├── Parse YAML → validate steps, branches, budget + ├── Create session + git branch + ├── Walk steps: + │ ├── Command steps → shell execution (deterministic, $0) + │ ├── Prompt steps → LLM runner (Claude/Codex/Gemini) + │ ├── Loop with gate → run, verify, keep or revert + │ ├── Branch → case-insensitive substring match → goto + │ ├── Parallel → goroutines with mutex + │ └── Budget check every step + └── Commit, report, clean up -**Optional** (for token optimization): -```bash -brew install rtk -``` +Multi-Agent (tri:* commands) + ├── Claude → native background agent (always) + ├── Codex → plugin or CLI (optional) + └── Gemini → plugin or CLI (optional) -**Optional** (for AST-based repo mapping): -```bash -brew install ast-grep +Self-Improvement (self:* commands) + └── Loop: propose → measure → keep/revert → repeat ``` -Check status with `/devkit:status`. - --- -## Roadmap - -See [ROADMAP.md](ROADMAP.md) for full details. - -- [x] Go CLI harness — 9 commands, SQLite state, crash recovery, budget enforcement, multi-agent support -- [x] CI/CD pipeline — build, vet, test, auto-release on version bump -- [x] Branch protection — PRs required for main -- [x] Edit-time security hooks — vulnerability pattern detection on Write/Edit -- [x] Slop detection — AI code pattern enforcement -- [x] Audit trail — command logging with timestamps -- [x] Project health audit — unified deps, vulns, licenses, lint, security -- [x] Post-PR monitor — CI watching + iterative comment resolution -- [x] AST-based repo map — symbol index with dependency graph -- [x] Hypothesis-driven perf — evidence gathering, ranked theories, one-at-a-time testing -- [x] Generic YAML workflow engine — deterministic step execution, branching, loops, parallel, budget -- [x] Triage-based phase skipping — TINY/SMALL/MEDIUM/LARGE classification with fast paths -- [x] Iteration scratchpads — persistent memory across loop iterations to prevent repeated failures -- [x] Cross-domain dirty-bit enforcement — blocks completion without test evidence per domain -- [x] Go code quality hooks — error-path access, nil-return, race detection, portability -- [x] **Language-universal hooks** — consolidated Go-specific hooks into `lang-review.sh` with Go, TypeScript, Rust, Python, and Shell support -- [x] **Hook consolidation** — merged 14 hooks into 10, reduced per-edit shell processes from 7 to 4. Consolidated stop hooks (dirty-bit + go-vet-stop + old stop-gate) into single `stop-gate.sh` - -All planned items complete. See [ROADMAP.md](ROADMAP.md) for retired items and rationale. +## Repository Structure + +``` +devkit/ +├── commands/ # 24 slash commands +├── skills/ # 18 context-activated skills +├── agents/ # 6 agents (reviewer, researcher, improver, ...) +├── hooks/ # 10 hooks (safety, security, quality gates) +├── workflows/ # 15 YAML workflow definitions +├── resources/rules/ # Language-specific coding rules +├── presets/ # Reserved for future use +├── src/ # Go CLI harness +│ ├── engine/ # YAML workflow engine (parser, executor, tests) +│ ├── runners/ # Claude, Codex, Gemini interfaces +│ ├── loops/ # Improve, feature, bugfix, refactor, testgen +│ ├── lib/ # DB, git, metrics, reporting +│ └── cmd/ # CLI entry points +└── .github/workflows/ # CI (build+test+vet) + auto-release +``` diff --git a/hooks/stop-gate.sh b/hooks/stop-gate.sh index 0f71e5e..6c859b5 100755 --- a/hooks/stop-gate.sh +++ b/hooks/stop-gate.sh @@ -154,13 +154,27 @@ if $HAS_RUST && command -v cargo >/dev/null 2>&1 && [ -f "$REPO_ROOT/Cargo.toml" fi # --- TypeScript --- +# Filter tsc output to only errors in changed files. Running tsc --noEmit +# checks the whole project — pre-existing errors in untouched files must +# not block the agent (this caused infinite loops in large TS codebases). +# tsc error format: "path/file.ts(line,col): error TS..." — we extract the +# path before "(" and compare against changed files for exact matching. if $HAS_TS && [ -f "$REPO_ROOT/tsconfig.json" ] && command -v npx >/dev/null 2>&1; then - TSC_OUTPUT=$(cd "$REPO_ROOT" && npx tsc --noEmit 2>&1) || TSC_EXIT=$? - if [ "${TSC_EXIT:-0}" -ne 0 ]; then - TSC_ERRORS=$(echo "$TSC_OUTPUT" | grep -E 'error TS' | head -5 || true) - if [ -n "$TSC_ERRORS" ]; then - jq -n --arg msg "TypeScript errors:\n$TSC_ERRORS" '{ decision: "block", reason: $msg }' - exit 0 + TS_FILES=$(printf '%s\n' "$CHANGED_FILES" | grep -E '\.(ts|tsx|js|jsx|mjs|cjs)$' || true) + if [ -n "$TS_FILES" ]; then + TSC_OUTPUT=$(cd "$REPO_ROOT" && npx tsc --noEmit 2>&1) || TSC_EXIT=$? + if [ "${TSC_EXIT:-0}" -ne 0 ]; then + # Extract error lines, then match only errors whose path (before the "(") + # exactly matches a changed file. Avoids substring false positives like + # "button.tsx" matching "icon-button.tsx". + TSC_ERRORS=$(printf '%s\n' "$TSC_OUTPUT" | grep -E 'error TS' | while IFS= read -r line; do + err_path=$(printf '%s' "${line%%\(*}" | tr -d '\r') + printf '%s\n' "$TS_FILES" | grep -qFx "$err_path" && printf '%s\n' "$line" + done | head -5) + if [ -n "$TSC_ERRORS" ]; then + jq -n --arg msg "TypeScript errors in changed files:\n$TSC_ERRORS" '{ decision: "block", reason: $msg }' + exit 0 + fi fi fi fi