Agent Workflow Kit
Chapter 03
Technical engraving of files moving through an installation jig from one tray to another
Fig. 03Installing the files into place.

03 — Installation

When to read this: First time setting up the kit, or when something is broken in the install. Takes about 5 minutes.

The kit ships as a folder of templates and scripts. Two install steps: one once-per-machine, one once-per-project.

Requirements#

  • macOS or Linux (the install scripts are bash; Windows users need WSL).
  • A POSIX shell — bash or zsh both work.
  • git for version control of the projects you'll bootstrap.
  • A directory on your PATH where you can drop a binary symlink. The default is ~/.local/bin. The install script puts it there automatically.

Optional but recommended for the full experience:

  • Claude Code (the IDE-integrated CLI) and/or Cursor. The kit's commands and subagents are designed for both.
  • Bun — the continual-learning Stop hook (.claude/hooks/continual-learning-stop.ts) is a Bun TypeScript file. Install Bun if you want continual learning to run automatically. The rest of the kit works without it. You just won't get auto-memory updates.
  • Playwright MCP — required for the design-reviewer subagent to take real screenshots. Without it, design-reviewer falls back to a code-only review and tells you so.
  • Node.js + npm for the a11y test (tests/a11y.spec.ts requires @axe-core/playwright and @playwright/test).

You don't need any of these to install the kit itself. They're for the per-feature behaviors.

Step 1 — One-time global install#

Get the kit onto your machine.

Option A — clone the repo:

git clone <kit-repo-url> ~/agent-workflow-kit
cd ~/agent-workflow-kit

Option B — copy the folder:

If the kit is part of a larger monorepo or you have it locally already:

cp -R /path/to/agent-workflow-kit ~/agent-workflow-kit
cd ~/agent-workflow-kit

You should now be in the kit's root directory — the one with bin/, scripts/, templates/, and README.md.

Run the install script:

chmod +x scripts/install-global.sh bin/agent-workflow
./scripts/install-global.sh

This does three things:

  1. Copies the kit to ~/.local/share/agent-workflow-kit/ (using rsync --delete if available, otherwise cp -R).
  2. Makes bin/agent-workflow executable.
  3. Symlinks ~/.local/bin/agent-workflow → the kit's bin/agent-workflow.

The output will end with a hint about adding ~/.local/bin to your PATH if it's not already there.

Make sure the binary is on your PATH#

Run:

which agent-workflow

If it prints a path, you're set. If it says agent-workflow not found, add this to your ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

Open a new terminal and run which agent-workflow again. It should print ~/.local/bin/agent-workflow.

Verify the install#

agent-workflow --dry-run /tmp

You should see a list of wrote /tmp/... lines (with the [dry-run] prefix). Nothing should actually be written. If you see those lines, the install worked.

Step 2 — Bootstrap a project#

In any new project directory, run:

agent-workflow

That writes the kit's templates into the current directory, skipping any files that already exist:

CLAUDE.md
AGENTS.md
GETTING-STARTED.md
prompts/{prompt-roadmap.md, prompt-seed-backlog.md}
.claude/{commands/, agents/, skills/, hooks/, settings.json}
.cursor/{rules/, hooks/state/}
docs/{backlog.md, agent-workflow-skills.md}
scripts/check-tokens.sh
tests/a11y.spec.ts

The output names every file it writes and every file it skips. Read it.

Flags#

agent-workflow --dry-run     # show what would run, don't actually write
agent-workflow --force       # overwrite existing kit files (be careful)
agent-workflow /other/dir    # bootstrap a different directory than cwd

A note on --force: it overwrites kit-managed files, but never overwrites .claude/settings.json. That file is project-specific. If you want to reset settings.json to the kit's example, copy templates/claude-settings.example.json by hand.

What --dry-run is good for#

Run agent-workflow --dry-run in any project to see what would change before committing. Useful when you're not sure whether a project has been bootstrapped already, or when you've edited the kit's templates and want to see the diff impact.

Step 3 — First-time project setup#

After bootstrap, there's one read-once file: GETTING-STARTED.md at the project root. Open it. It walks you through the first-session sequence:

  1. Run prd-grill → write docs/PRD.md.
  2. (If architecturally loaded) Run architecture-md-builder → docs/ARCHITECTURE.md.
  3. (If any UI) Run design-md-builder → DESIGN.md.
  4. Use prompts/prompt-roadmap.md to draft docs/ROADMAP.md.
  5. Fill the {{PLACEHOLDERS}} in CLAUDE.md.
  6. Use prompts/prompt-seed-backlog.md to seed docs/backlog.md Inbox.
  7. Run /backlog-triage, then start the daily loop.

Chapter 04: Quickstart walks through this sequence concretely with a worked example.

Updating the kit#

When the kit changes (new template, new subagent, fixed script), pull the latest into your kit source directory and re-run the global install:

cd ~/agent-workflow-kit          # or wherever your kit source lives
git pull                         # if you cloned it
./scripts/install-global.sh

The install script uses rsync --delete, so any files removed from the kit source are also removed from ~/.local/share/agent-workflow-kit/. The symlink at ~/.local/bin/agent-workflow points at the same path either way, so nothing else needs updating.

Existing projects don't auto-update. When you bootstrap a project, the kit copies templates into the project folder. Those copies are yours from then on. They don't get re-overwritten when you update the kit. To pull the latest version of a specific template into an existing project, copy it manually:

cp ~/.local/share/agent-workflow-kit/templates/claude-agents/design-reviewer.md \
   .claude/agents/design-reviewer.md

This is deliberate. If you've customized a subagent for your project, an auto-update would clobber your customizations.

Uninstall#

rm -rf ~/.local/share/agent-workflow-kit
rm ~/.local/bin/agent-workflow

That's it. The kit doesn't write anywhere else on your system.

Per-project files written by agent-workflow stay in the project (CLAUDE.md, .claude/, etc.) until you delete them yourself. Most are version-controlled, so just don't git pull them out.

Troubleshooting#

agent-workflow: command not found#

~/.local/bin isn't on your PATH. Add this to ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

Open a new terminal. Run which agent-workflow.

If it's still not found, check that the symlink exists:

ls -la ~/.local/bin/agent-workflow

Should show a symlink pointing to ~/.local/share/agent-workflow-kit/bin/agent-workflow. If it's broken or missing, re-run ./scripts/install-global.sh from the kit source.

agent-workflow runs but says "kit not found"#

The wrapper script tries to find the kit via the AGENT_WORKFLOW_KIT environment variable, then via the parent directory of the symlink target. If you moved the kit folder after installing, that lookup breaks.

Fix by either re-running ./scripts/install-global.sh from the kit's new location, or by setting the env var explicitly:

export AGENT_WORKFLOW_KIT="/path/to/your/kit/folder"

Bootstrap skipped my .claude/settings.json#

That's expected. The kit refuses to overwrite .claude/settings.json, even with --force, because settings tend to be customized per-project.

If you want the kit's example settings (which wires up the check-tokens.sh and continual-learning Stop hooks), copy them manually:

cp templates/claude-settings.example.json .claude/settings.json

If you already had a settings.json, merge the hooks.Stop block from the example into your existing file rather than replacing the whole file. The example block looks like:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "bash scripts/check-tokens.sh" },
          { "type": "command", "command": "bun run .claude/hooks/continual-learning-stop.ts" }
        ]
      }
    ]
  }
}

Bun isn't installed#

The continual-learning Stop hook is a Bun TypeScript file. If you don't have Bun, the hook will fail when Claude Code tries to run it on every Stop event.

Options:

  • Install Bun: curl -fsSL https://bun.sh/install | bash. Restart your terminal.
  • Or remove the continual-learning hook from .claude/settings.json (just delete that one entry from the hooks.Stop[].hooks array).

The rest of the kit works fine without Bun. You just lose the auto-memory loop.

Playwright MCP isn't configured#

Without Playwright MCP, the design-reviewer subagent can't take real screenshots. It falls back to a code-only review and prints a note at the top of its report.

Install with:

claude mcp add playwright -- npx @playwright/mcp@latest

Then restart Claude Code. The next design-reviewer run will use real screenshots.

Re-running bootstrap doesn't pick up template changes#

By design — the kit skips files that exist. Use --force to overwrite, or copy specific files by hand.

Continue#

The kit is installed. Next: Chapter 04: Quickstart walks through using it on a real project.