diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdaaef9..35920a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## Adding a Workflow -Most command logic lives in YAML workflows executed by the Go engine. Only 6 slash commands remain as tab-completable entry points — everything else is context-activated via skills. +Most command logic lives in YAML workflows executed by the Go engine. In current Claude Code all skills are tab-completable slash commands — new entry points go in `skills/`, not `commands/` (which is legacy). 1. Create `workflows/my-workflow.yml` with steps, model assignments, and loop/gate definitions 2. Test with `devkit_start` MCP tool or `devkit workflow my-workflow "input"` from terminal @@ -10,19 +10,22 @@ Most command logic lives in YAML workflows executed by the Go engine. Only 6 sla See `skills/creating-workflows/SKILL.md` for YAML schema reference. -### Adding a Slash Command (rare — only for top-level entry points) +### Adding a User-Only Entry Point -Only add a command if it needs tab-completion. Most workflows are invoked via MCP tools (`devkit_start`/`devkit_advance`) or context-activated skills. +For side-effecting actions (install / deploy / setup) that should only run when the user explicitly invokes them, create a skill with `disable-model-invocation: true`: -1. Create `commands/my-command.md` with YAML frontmatter: +1. Create `skills/my-skill/SKILL.md` with YAML frontmatter: ```markdown --- - description: What this command does. + name: my-skill + description: What this skill does and when to use it. + disable-model-invocation: true --- - Use `devkit_start` MCP tool with workflow name to execute. + # Skill Title + Instructions... ``` -The command name is derived from the filename: `commands/my-command.md` becomes `/devkit:my-command`. +This makes `/devkit:my-skill` tab-completable but prevents Claude from auto-triggering it — useful for installers (`setup-rules`) and other side-effecting operations. The `commands/` directory is legacy; don't add new files there. ## Adding a Context-Activated Skill @@ -49,7 +52,7 @@ The skill will be auto-discovered as `devkit:my-skill`. 1. Create a YAML file in `workflows/` 2. See the `creating-workflows` skill for schema reference -3. Run with `/devkit:workflow my-workflow` +3. Run with `/my-workflow` — every workflow has its own tab-completable skill ## Guidelines diff --git a/README.md b/README.md index 6cd7528..eb7f1b0 100644 --- a/README.md +++ b/README.md @@ -125,18 +125,17 @@ Enforcement (runs automatically): ## Commands -6 tab-completable slash commands. All other workflows are context-activated via skills (auto-triggered by natural language) or invoked via MCP tools. +All skills are tab-completable slash commands in current Claude Code. The primary user-facing entry points: | Command | What it does | |---|---| -| `/tri:review` | Code review from 1-3 agents, consolidated report | -| `/tri:debug` | Independent root-cause analysis from each agent | -| `/tri:security` | Security audit with severity-ranked consensus | -| `/devkit:workflow` | Run any YAML workflow by name | +| `/tri-review` | Code review from 1-3 agents, consolidated report | +| `/tri-debug` | Independent root-cause analysis from each agent | +| `/tri-security` | Security audit with severity-ranked consensus | | `/devkit:status` | Health check | -| `/devkit:setup-rules` | Install language-specific coding rules to `~/.claude/rules/` | +| `/devkit:setup-rules` | Install language-specific coding rules to `~/.claude/rules/` (user-only — `disable-model-invocation` prevents auto-trigger) | -Tasks like "ship this PR" or "submit a PR" auto-activate the `pr-ready` skill — no slash command needed. +Every workflow also has a dedicated slash command: `/feature`, `/bugfix`, `/audit`, `/refactor`, `/pr-ready`, `/self-*`, etc. Tasks like "ship this PR" or "submit a PR" also auto-activate the `pr-ready` skill via natural language. ### Workflows @@ -305,8 +304,8 @@ Terminal usage (devkit workflow ""): ``` devkit/ -├── commands/ # 6 slash commands (tab-completable entry points) -├── skills/ # 36 context-activated skills + _principles.yml +├── commands/ # Legacy (references/ only); new entry points go in skills/ +├── skills/ # 38 skills (workflow triggers, principles, tools, utilities) + _principles.yml ├── agents/ # 6 agents (reviewer, researcher, improver, ...) ├── hooks/ # 12 hooks (safety, security, quality gates, workflow enforcement) ├── workflows/ # 21 YAML workflow definitions diff --git a/ROADMAP.md b/ROADMAP.md index d1bb5a7..cc6cff8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -3,9 +3,9 @@ ## Implemented - **MCP engine** — Go server exposes `devkit_start`, `devkit_advance`, `devkit_status`, `devkit_list` tools inside Claude Code. Step ordering enforced via MCP tool scoping + PreToolUse hook exit 2. Session state in session.json (hot path, <50ms hook reads) + SQLite (cold history). ~65% token reduction vs old monolithic prompts. -- **6 slash commands** — Tab-completable entry points for things that need explicit invocation (tri-review, tri-debug, tri-security, status, setup-rules, workflow); 18 former commands now context-activated via skills or invoked via MCP tools (pr-monitor folded into pr-ready workflow; pr-ready is now a natural-language skill) +- **Skills-first architecture** — All entry points are skills in `skills/` (tab-completable slash commands in current Claude Code). Primary user-facing commands: `/tri-review`, `/tri-debug`, `/tri-security`, `/devkit:status`, `/devkit:setup-rules` (user-only via `disable-model-invocation`). Every workflow also has a dedicated skill for natural-language dispatch. The `commands/` directory is retained for backward compat but empty of new entries — redundant tri-* command files were removed (skills take precedence per Claude Code docs) and the generic `/devkit:workflow ` runner was removed since every workflow now has its own slash command (`/feature`, `/bugfix`, etc.). - **Deterministic workflow conversion** — All command logic moved from LLM-interpreted markdown to Go-engine-driven YAML workflows; ~3,600 lines of inline logic removed -- **36 context-activated skills** — 21 workflow trigger skills (feature, bugfix, refactor, audit, research, deep-research, pr-ready, autoloop, test-gen, doc-gen, onboard, tri-review, tri-debug, tri-security, tri-dispatch, self-audit, self-improve, self-lint, self-migrate, self-perf, self-test) + 7 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck, scratchpad) + 4 tools (gcli, scrape, screenshot, browser) + 1 meta-orchestration (mega-pr) + 2 content (changelog, adr) + 1 reference (creating-workflows) +- **38 skills** — 21 workflow trigger skills (feature, bugfix, refactor, audit, research, deep-research, pr-ready, autoloop, test-gen, doc-gen, onboard, tri-review, tri-debug, tri-security, tri-dispatch, self-audit, self-improve, self-lint, self-migrate, self-perf, self-test) + 7 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck, scratchpad) + 4 tools (gcli, scrape, screenshot, browser) + 1 meta-orchestration (mega-pr) + 2 content (changelog, adr) + 1 reference (creating-workflows) - **Deterministic skill dispatch for every workflow** — Every one of the 21 workflows has a natural-language trigger skill with keyword-rich description. Saying "build a feature", "tri review", "deep research X", etc. deterministically invokes the matching skill, which calls `devkit_start` and the engine enforces every step from there. Closes the entry-gate non-determinism where 11/18 workflows previously had no natural-language path. Skill tool added to the guard allowlist so nested mid-workflow skill dispatch works. - **6 agents** — Scoped tool access, worktree isolation, model assignment - **12 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification, language-aware code review), optimization (RTK token compression), workflow enforcement (devkit-guard, devkit-stop-guard) diff --git a/commands/tri-debug.md b/commands/tri-debug.md deleted file mode 100644 index 271a5c5..0000000 --- a/commands/tri-debug.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: Triple-agent debugging — independent root-cause hypotheses from Claude, Codex, and Gemini, then consensus fix. ---- - -## Invoke - -Start the workflow via the devkit engine: - -Use the `devkit_start` tool with workflow: "tri-debug" and input: "{input}". - -Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps. diff --git a/commands/tri-review.md b/commands/tri-review.md deleted file mode 100644 index 1435a2c..0000000 --- a/commands/tri-review.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: Triple-agent code review — dispatches to Claude, Codex, and Gemini in parallel, consolidates findings. ---- - -## Invoke - -Start the workflow via the devkit engine: - -Use the `devkit_start` tool with workflow: "tri-review" and input: "{input}". - -Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps. diff --git a/commands/tri-security.md b/commands/tri-security.md deleted file mode 100644 index 1dfc36b..0000000 --- a/commands/tri-security.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: Triple-agent security audit — independent security reviews from Claude, Codex, and Gemini, consolidated with severity ranking. ---- - -## Invoke - -Start the workflow via the devkit engine: - -Use the `devkit_start` tool with workflow: "tri-security" and input: "{input}". - -Then follow each step the engine returns. Call `devkit_advance` after completing each step. The engine controls step order, gates, and loops. Do NOT skip steps. diff --git a/commands/workflow.md b/commands/workflow.md deleted file mode 100644 index ba884d7..0000000 --- a/commands/workflow.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: Run a YAML workflow by name via the devkit engine (feature, bugfix, refactor, self-*, audit, etc.). ---- - -# Workflow Runner - -Generic entry point for any YAML workflow in `workflows/`. The devkit engine controls step order, loops, gates, and branches. - -## Invoke - -Use the `devkit_list` tool first to see available workflows, or pick one by name: - -``` -devkit_start(workflow: "", input: "") -``` - -Then call `devkit_advance(session: "")` after completing each step the engine returns. The engine controls step order, gates, and loops. Do NOT skip steps. - -## Available Workflows - -| Workflow | Purpose | -|---|---| -| `feature` | Brainstorm, plan, implement, test, lint, review | -| `bugfix` | Reproduce, diagnose, fix, regression test, verify | -| `refactor` | Analyze smells, plan, restructure, verify nothing broke | -| `research` | Clarify, decompose, parallel search, synthesize | -| `deep-research` | ACH hypotheses, disconfirmation, evidence matrix | -| `self-test` | Run tests, fix failures, loop until passing | -| `self-lint` | Run linter, fix violations, loop until clean | -| `self-perf` | Benchmark, optimize, loop until target met | -| `self-improve` | Run metric, fix issues, loop until passing | -| `self-migrate` | Migrate code incrementally with test gate | -| `self-audit` | Measure codebase, rank improvements by evidence | -| `autoloop` | Autonomous audit/fix/measure/keep-or-revert loop | -| `audit` | Dependencies, vulnerabilities, licenses, lint, security | -| `pr-ready` | Full PR preparation pipeline | -| `tri-review` | Multi-agent code review | -| `tri-debug` | Multi-agent debugging | -| `tri-security` | Multi-agent security audit | -| `tri-dispatch` | Generic parallel dispatch to multiple agents | - -## Examples - -``` -# List workflows -devkit_list() - -# Run a feature workflow -devkit_start(workflow: "feature", input: "add JWT auth to src/auth/") - -# Run self-test with the project test command -devkit_start(workflow: "self-test", input: "npm test") - -# Autonomous improvement loop -devkit_start(workflow: "autoloop", input: "improve test coverage | metric: go test -cover ./... | direction: higher-is-better | iterations: 10") -``` - -## Rules - -- The engine enforces step order — you cannot skip steps -- Command steps execute automatically when you call `devkit_advance` -- Loop steps repeat based on gate/until/max conditions -- Branch steps jump based on output content matching -- Parallel steps dispatch to subagents via the Agent tool + plugins -- Call `devkit_status` anytime to check current progress diff --git a/commands/setup-rules.md b/skills/setup-rules/SKILL.md similarity index 83% rename from commands/setup-rules.md rename to skills/setup-rules/SKILL.md index e87649c..12c3696 100644 --- a/commands/setup-rules.md +++ b/skills/setup-rules/SKILL.md @@ -1,5 +1,7 @@ --- -description: Install devkit coding rules to ~/.claude/rules/ for language-specific auto-activation +name: setup-rules +description: Install devkit coding rules to ~/.claude/rules/ for language-specific auto-activation. Use when the user explicitly asks to set up devkit rules, install language rules, or run /devkit:setup-rules. One-shot installer with side effects (writes to ~/.claude/rules/) — user-only invocation, never auto-triggered. +disable-model-invocation: true --- # Setup Coding Rules diff --git a/commands/status.md b/skills/status/SKILL.md similarity index 75% rename from commands/status.md rename to skills/status/SKILL.md index f08e86b..140a95f 100644 --- a/commands/status.md +++ b/skills/status/SKILL.md @@ -1,5 +1,6 @@ --- -description: Check devkit health — which external CLIs are installed, which agents are available, and which commands are ready to use. +name: status +description: Check devkit health — which external CLIs (codex, gemini, gh, rtk, sg, gcli) are installed, which agents are available, which skills are ready to use. Use when asked about devkit status, "is devkit working?", "what's installed?", "what devkit capabilities do I have?", diagnosing devkit setup issues, or running /devkit:status. Read-only diagnostic, safe to auto-invoke. --- # Devkit Status @@ -46,15 +47,15 @@ fi List all agents from `agents/` directory with their model and isolation settings. -### Command Availability +### Skill Availability -List all commands, marking which ones need external CLIs: +List all skills from `skills/` directory, marking which ones need external CLIs: ``` ## Devkit Status ### Plugins -| Plugin | Status | Commands | +| Plugin | Status | Skills | |--------|--------|----------| | codex | ✓ installed | /codex:rescue, /codex:review, /codex:result | | gemini | ✗ not installed | /gemini:rescue, /gemini:review, /gemini:result | @@ -62,19 +63,18 @@ List all commands, marking which ones need external CLIs: ### External CLIs (fallback if plugins not installed) | CLI | Status | Required by | |-----|--------|------------| -| codex | ✓ installed (v1.2.0) | tri:* commands (fallback) | -| gemini | ✗ not installed | tri:* commands (fallback) | +| codex | ✓ installed (v1.2.0) | tri:* skills (fallback) | +| gemini | ✗ not installed | tri:* skills (fallback) | | gh | ✓ installed (v2.40.0) | pr-ready skill | | rtk | ✓ installed (v0.34.2) | token optimization (optional) | -### Commands -| Command | Status | Notes | -|---------|--------|-------| -| /tri:review | ⚠ partial | 2/3 agents available (no gemini) | -| /tri:debug | ⚠ partial | 2/3 agents available | -| /tri:security | ⚠ partial | 2/3 agents available | -| /devkit:workflow | ✓ ready | Runs YAML workflows via Go engine | -| /devkit:status | ✓ ready | This command | +### Skills +| Skill | Status | Notes | +|-------|--------|-------| +| /tri-review | ⚠ partial | 2/3 agents available (no gemini) | +| /tri-debug | ⚠ partial | 2/3 agents available | +| /tri-security | ⚠ partial | 2/3 agents available | +| /devkit:status | ✓ ready | This skill | | /devkit:setup-rules | ✓ ready | One-time setup | ### Agents