CLAUDE.md

Navigation map for Claude Code working in this repo. Anchor-style, not narrative — keep it short. pr-ready's doc-check targets this file, so stale entries get caught at PR time.

devkit is a Claude Code plugin: deterministic YAML workflow engine, dispatcher and capability skills, enforcement hooks, multi-agent consensus.

Layout

Architectural invariants

• Workflows are deterministic. The engine controls step sequencing, loops, branches, and gates — not the model. YAML is parsed once, the graph is fixed, steps run with state persistence and hook enforcement.
• Skills come in two flavors. Engine-shim skills (most) are thin dispatchers that call devkit_start then loop on devkit_advance, delegating to the workflow engine. Capability skills (e.g., skills/scrape/) are runtime-interpreted prompt templates where the model is the executor — it picks a backend from what's installed, generates shell/script via heredoc, judges output, falls through on failure. Use the capability form when work needs on-the-spot adaptation that pre-compiled YAML can't express (anti-bot arms races, heterogeneous backend outputs, content-judgment branching).
• Parallel step pattern. Steps listed in another step's parallel: [ids] are skipped during the sequential walk (Workflow.NextIndex in src/engine/workflow.go, used by both the CLI engine and the MCP server) and run only inside their dispatcher — runParallel in the CLI, per-child outputs on devkit_advance over MCP. Never expect a step that appears in a parallel list to also execute in its sequential position.
• Enforce levels gate hook permissions. enforce: soft lets gather/setup steps run git diff and other shell work during dispatch; enforce: hard blocks them. The gatekeeper logic lives in src/cmd/guard.go; see guard_test.go for the allow/deny matrix.
• Engine binary is separate from the CLI wrapper. bin/devkit is the committed shell wrapper; it execs devkit-engine (compiled Go, gitignored). The wrapper handles install/version checks; the engine handles workflow execution.
• Skills are the future; commands/ is legacy. PR #77 migrated commands to skills. Both auto-discover, but skills support paths, disable-model-invocation, and supporting files.

Conventions

• State assumptions before implementing. If multiple interpretations exist, present them — don't pick silently.
• Never push directly to main. Always PR. Direct push bypasses the version-bump and release pipeline.
• Never amend commits — create new ones, even after pre-commit hook failures.
• Never skip hooks (--no-verify, --no-gpg-sign) without explicit user consent.
• Commit message style: check recent git log before writing one. Repo uses conventional-commit prefixes (docs:, fix:, feat:, refactor:, chore:).
• Version bumps happen automatically on PR merge — don't hand-edit .claude-plugin/plugin.json version.
• CHANGELOG.md is managed by the release pipeline, not by pr-ready's doc-check or manual edits.
• No direct edits to ~/Documents/LocalDev/claude-shared/ — the OneDrive copy is primary; the local path is a GitHub backup.

Fixing this file

If a row above is wrong or a lookup keeps failing, fix it in the same PR that changed the underlying code — pr-ready's doc-check targets CLAUDE.md. If you find a recurring exploration query that isn't covered, add a one-liner anchor to the layout table. Keep it short; this file exists to save tokens, not to explain devkit.