Skip to content

README: document three routes for reusing the process in other projects #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TMKAB121 merged 1 commit into from
Jul 10, 2026
Merged

README: document three routes for reusing the process in other projects #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 167 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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),
Expand All @@ -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:
Expand Down
Loading