diff --git a/README.md b/README.md index c9f8771..0769ff6 100644 --- a/README.md +++ b/README.md @@ -100,11 +100,37 @@ app/test/ node --test suite .github/workflows/ci.yml CI: test suite + zero-dependency + design-token audits ``` -## Using this process in another codebase +## Using this process in other projects -The process is plain markdown — nothing to install, no runtime, no cloning -required beyond grabbing the files once. To adopt it in any repo where you -use Claude Code: +The process is plain markdown plus three small hook scripts — nothing to +install, no runtime. There are three ways to reuse it, ordered by how much +you intend to keep iterating on the process itself: + +| Route | Best for | How process updates reach projects | +|---|---|---| +| **A. Copy the files** | Adopting once in a repo that will diverge | Manual re-copy | +| **B. Package as a Claude Code plugin** | Running the same process across several repos while evolving it here | Push here → `/plugin marketplace update` in each project | +| **C. Personal `~/.claude`** | Quick personal reuse of the agents/commands only | Edit in place; applies to all your projects | + +Whichever route you pick, four things are **always per-project** and never +port as-is: + +1. `CLAUDE.md` — rewrite the **Tech stack** and **Commands** sections (agents + build with whatever the target's CLAUDE.md declares: React, Python, + anything). The Roles, Workflow rules, and Artifact conventions sections + carry over unchanged — they *are* the process. +2. `docs/design-system.md` — swap the placeholder tokens for the target + product's brand values. +3. The artifact directories: `docs/specs/`, `docs/qa/test-plans/`, + `docs/qa/defects/`, `docs/qa/evidence/`, `docs/design-reviews/`, + `docs/pipeline/`. +4. The `LANES` path table in `enforce-lanes.js` — the one deliberately + project-coupled piece; it maps each agent to the target repo's real paths + (e.g. `src/components/` instead of `app/public/`). The package-manager + `permissions.deny` rules are likewise this demo's zero-dependency policy, + not part of the process — keep or drop per project. + +### Route A: copy the files 1. **Copy verbatim** (fully stack-agnostic): - `.claude/agents/` — the four role agents @@ -117,17 +143,10 @@ use Claude Code: - `tools/browser.js` — QA evidence capture (degrades gracefully where no Chromium is installed) - `docs/qa/TEMPLATE-defect.md` -2. **Copy, then edit for the target project**: - - `CLAUDE.md` — rewrite the **Tech stack** section (agents build with - whatever it declares: React, Vue, Python, anything) and the **Commands** - section (how to run and test that project). Keep the Roles, Workflow - rules, and Artifact conventions sections as-is. - - `docs/design-system.md` — swap the placeholder tokens for the target - product's brand values. -3. **Create the artifact directories**: `docs/specs/`, `docs/qa/test-plans/`, - `docs/qa/defects/`, `docs/qa/evidence/`, `docs/design-reviews/`, - `docs/pipeline/`. -4. **Optional but recommended**: copy the three seeded `001-status-dashboard` +2. **Copy `CLAUDE.md` and `docs/design-system.md`, then do the four + per-project edits** listed above (CLAUDE.md sections, tokens, artifact + directories, lane table). +3. **Optional but recommended**: copy the three seeded `001-status-dashboard` artifacts (spec, test plan, design review) as format exemplars — the agent prompts reference them as the pattern to follow. They work without them (the required sections are also described inline in each agent prompt), @@ -153,6 +172,139 @@ cp "$SRC/docs/qa/TEMPLATE-defect.md" docs/qa/ overwrite: append the Roles/Workflow/Artifact sections to the existing `CLAUDE.md` and drop the agent/command files into the existing directories.) +### Route B: package as a Claude Code plugin (recommended for multi-project use) + +A [plugin](https://code.claude.com/docs/en/plugins) makes this repo the single +source of truth: every project installs the same agents, commands, and hooks; +process improvements land by pushing here, and each project pulls them with +`/plugin marketplace update` instead of re-copying files. This repo doubles as +its own [marketplace](https://code.claude.com/docs/en/plugin-marketplaces) — +no separate hosting. + +1. **Create the plugin layout** in this repo. Plugin component directories + must sit at the plugin root (not under `.claude-plugin/` and not under + `.claude/`), so mirror the existing files into a `plugin/` directory: + + ``` + plugin/ + ├── .claude-plugin/plugin.json # {"name": "agentic-dev", "version": "0.1.0", "description": "..."} + ├── agents/ # copy of .claude/agents/ + ├── commands/ # copy of .claude/commands/ + ├── hooks/ + │ ├── hooks.json # hook registration (step 2) + │ ├── enforce-lanes.js # copies of .claude/hooks/*.js + │ ├── check-footer.js + │ └── session-start.js + └── templates/ # TEMPLATE-defect.md, design-system.md, browser.js + ``` + +2. **Register the hooks in `plugin/hooks/hooks.json`** — same shape as the + `hooks` block in `.claude/settings.json`, but script paths must use + `${CLAUDE_PLUGIN_ROOT}`: installed plugins run from a cache directory, so + `$CLAUDE_PROJECT_DIR/.claude/hooks/...` no longer points at the scripts. + + ```json + { + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit|Bash", + "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/enforce-lanes.js\"" }] + } + ], + "SubagentStop": [ + { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check-footer.js\"" }] } + ], + "SessionStart": [ + { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js\"" }] } + ] + } + } + ``` + +3. **Make the lane table per-project.** Inside a plugin, `enforce-lanes.js` + lives in the read-only plugin cache, so target projects can't edit `LANES` + directly. Change the plugin copy to read an optional + `$CLAUDE_PROJECT_DIR/.claude/lanes.json` (same shape as the `LANES` object, + plus optional `protected` and `bashDeny` overrides) and fall back to the + built-in table when absent. Each project then declares its own paths + without forking the hook. + +4. **Publish it via a marketplace file** at the **repo root**, + `.claude-plugin/marketplace.json`: + + ```json + { + "name": "agentic-dev", + "owner": { "name": "tmkab121" }, + "plugins": [ + { "name": "agentic-dev", "source": "./plugin", "description": "Agentic dev process: 4 role agents, /feature pipeline, lane enforcement" } + ] + } + ``` + + Push, and the plugin is installable from the GitHub repo. Bump `version` + in `plugin.json` when you cut a release — projects then update + deliberately instead of on every commit. + +5. **Install in a target project**: + + ```shell + /plugin marketplace add tmkab121/agentic-dev + /plugin install agentic-dev@agentic-dev + ``` + + Then do the four per-project edits from the top of this section + (CLAUDE.md sections, design tokens, artifact dirs, `.claude/lanes.json`). + Plugin commands are namespaced: `/agentic-dev:feature "add X"`, + `/agentic-dev:backlog list`, etc. + +6. **Smoke-test once per install**: run a trivial + `/agentic-dev:feature` and confirm the lane hook isn't denying everything. + The hook keys off the `agent_type` field in hook input, and unknown agents + fail closed — if plugin-provided agents surface with a namespaced type + (e.g. `agentic-dev:ux-designer`), add those keys to the lane table / + `lanes.json`. `claude plugin validate` catches structural mistakes before + you push. + + For teams, the target repo can auto-prompt installation by declaring the + marketplace in its `.claude/settings.json`: + + ```json + { + "extraKnownMarketplaces": { + "agentic-dev": { "source": { "source": "github", "repo": "tmkab121/agentic-dev" } } + }, + "enabledPlugins": { "agentic-dev@agentic-dev": true } + } + ``` + +### Route C: personal user-level install + +Copy `.claude/agents/` and `.claude/commands/` into `~/.claude/agents/` and +`~/.claude/commands/` and the four roles plus the slash commands exist in +every project you open, with un-namespaced names and zero project setup. +Do **not** move the hooks into `~/.claude/settings.json`: they would fire in +every repo you touch, and the lane table only makes sense per project. Use +this as a stopgap for trying the roles somewhere quickly; for real adoption +the target still needs the per-project pieces (routes A/B). + +### Experimenting with process variants + +The process being markdown makes variants cheap — a variant is a branch: + +- Develop a variant on a branch of this repo, then trial it inside any real + project with `claude --plugin-dir /path/to/agentic-dev/plugin` (no install + needed; a local `--plugin-dir` copy overrides the installed plugin of the + same name for that session). `/reload-plugins` picks up edits live while + you tune prompts mid-session. +- Keep `main` as the stable process. When a variant proves out on a real + feature, merge it and bump the plugin `version`; projects adopt it on their + next `/plugin marketplace update`. +- The demo app in `app/` stays valuable here: it's a fixed, known-good target + for A/B-ing process changes (same ask, `main` vs. variant branch) without + risking a real codebase. + ## Lane enforcement Lane boundaries are enforced mechanically, on top of the prompt discipline: