Atelier Pipeline -- Setup
This skill installs the full Atelier Pipeline multi-agent orchestration system into the user's project.
<contract> <requires> - `CLAUDE_PLUGIN_ROOT` (Claude Code) or `CURSOR_PROJECT_DIR` (Cursor) environment variable set by the runtime. - Plugin `source/` tree present at `${CLAUDE_PLUGIN_ROOT}/source/` (shared, claude, cursor overlays). - Write access to project root (`.claude/`, `docs/`, `CLAUDE.md`). - `jq` available on `PATH` for hook registration in `settings.json`. </requires> <produces> - `.claude/rules/`, `.claude/agents/`, `.claude/commands/`, `.claude/references/`, `.claude/hooks/` populated from source overlays. - `.claude/pipeline-config.json` with branching strategy, project name, and feature flags. - `.claude/settings.json` with hook registrations (PreToolUse, SubagentStart, SubagentStop, SessionStart, PreCompact, PostCompact, StopFailure). - `.claude/.atelier-version` plugin version marker. - `docs/pipeline/` state files (`pipeline-state.md`, `context-brief.md`, `error-patterns.md`, `investigation-ledger.md`). - `CLAUDE.md` with pipeline section appended. - Cursor only: `.cursor-plugin/rules/*.mdc` reference wrappers. </produces> <invalidates> - Any prior install's `.claude/rules/`, `.claude/agents/`, `.claude/commands/`, `.claude/references/`, and `.claude/hooks/` contents (overwritten from source on re-sync; live state files in `docs/pipeline/` and `.claude/pipeline-config.json` are preserved). - Deprecated `quality-gate.sh`, orphan brain-capture hooks, orphan `session-hydrate.sh` registration, and stale `atelier-brain` `.mcp.json` entries (Steps 0–0d). </invalidates> </contract> <procedure id="setup">Heads-up (Claude Code < 2.1.89): Agent persona frontmatter declares an
effortfield (values:low,medium,high,xhigh) in addition tomodel. Claude Code runtimes older than 2.1.89 ignore theeffortfield silently -- the pipeline still functions, but effort-based promotion signals are not honoured by the runtime. See ADR-0041 for the full effort-tier model. If your team is on an older Claude Code build, either upgrade or treat theeffortfield as documentation-only. Cursor users: theeffortfield is passed through as metadata; refer to Cursor release notes for runtime support.
Setup Procedure
Where Files Are Installed
Before gathering project information, understand where the pipeline installs files and how they interact with your project:
| Location | What Goes There | Git Status | Shared With Team? |
|---|---|---|---|
.claude/rules/ | Eva persona, orchestration rules, model selection, branch lifecycle | Project-local, committed to repo | Yes -- team members get the same pipeline rules |
.claude/agents/ | Agent persona files (Sarah, Colby, etc.) | Project-local, committed to repo | Yes -- consistent agent behavior across the team |
.claude/commands/ | Slash command definitions (/pm, /pipeline, etc.) | Project-local, committed to repo | Yes -- same commands available to all |
.claude/references/ | Quality framework, invocation templates | Project-local, committed to repo | Yes -- shared knowledge base |
.claude/hooks/ | Enforcement scripts (path, sequencing, git guards) | Project-local, committed to repo | Yes -- same guardrails for everyone |
.claude/pipeline-config.json | Branching strategy, feature flags | Project-local, committed to repo | Yes -- team-wide configuration |
.claude/settings.json | Hook registrations (tells Claude Code to run the hooks) | Project-local, committed to repo | Yes -- hooks activate for all team members |
docs/pipeline/ | Pipeline state, context brief, error patterns | Project-local, committed to repo | Yes -- session recovery works across machines |
CLAUDE.md | Pipeline section appended to project instructions | Project-local, committed to repo | Yes -- Claude Code reads this automatically |
Key points:
- All installed files live inside the project directory -- nothing is written to
~/.claude/or other user-level locations. - Everything is designed to be committed to git so team members inherit the pipeline when they clone.
- The plugin itself (installed via
claude plugin add) is user-level, but the project files it generates are project-level. - To remove all installed files later, use the
/pipeline-uninstallskill.
Step 0: Clean Up Deprecated quality-gate.sh
Before gathering any project information, unconditionally run this cleanup on every /pipeline-setup invocation. It is silent unless it finds something to remove.
- Check file: Check if
.claude/hooks/quality-gate.shexists. If found: delete the file. Note that removal occurred. - Check settings.json: Check if
.claude/settings.jsonexists and contains a hook entry referencingquality-gate.shin any command string across all hook event types (PreToolUse, SubagentStop, PreCompact, etc.). If found:- Parse the JSON. If the JSON is malformed or invalid, log a warning ("Warning: .claude/settings.json is malformed JSON -- skipping quality-gate.sh entry removal. Does not block setup.") and continue to step 3.
- Remove the hook entry containing "quality-gate" from the command string.
- If removing that entry leaves an empty hooks array for an event type, remove the event type entry entirely (no empty arrays left behind).
- Write the updated JSON back to
.claude/settings.json. - Note that removal occurred.
- Print notice (conditional): If either artifact was found and removed: print exactly
Removed deprecated quality-gate.sh (see retro lesson #003). - Silent no-op: If neither found: do nothing. No output.
Edge case handling:
- File exists but settings.json entry already removed: detect file, delete it, print notice. Check settings.json independently of file existence.
- settings.json has quality-gate.sh entry but file does not exist: detect entry in settings.json, remove it, print notice.
- Both found: remove both, print single notice (not two).
- Neither found: silent no-op.
This cleanup targets only quality-gate.sh entries. Other hook entries (enforce-eva-paths.sh, enforce-sequencing.sh, enforce-git.sh, etc.) are not affected.
Step 0b: Clean Up Orphan Brain-Capture Hooks
Unconditionally run this cleanup on every /pipeline-setup invocation. Silent unless it finds something to remove.
- Check prompt-brain-capture.sh: If
.claude/hooks/prompt-brain-capture.shexists, delete it withrm -f .claude/hooks/prompt-brain-capture.sh. Note that removal occurred. - Check warn-brain-capture.sh: If
.claude/hooks/warn-brain-capture.shexists, delete it withrm -f .claude/hooks/warn-brain-capture.sh. Note that removal occurred. - Print notice (conditional): If either file was found and removed: print exactly
Removed orphan brain-capture hooks (superseded by brain-extractor agent). - Silent no-op: If neither found: do nothing. No output.
Step 0c: Clean Up Orphan session-hydrate.sh Registration
Unconditionally run this cleanup on every /pipeline-setup invocation. Silent unless it finds something to remove.
session-hydrate.sh is now an intentional no-op (superseded by the atelier_hydrate MCP tool) and must NOT be registered in .claude/settings.json. Older installs may still have a registration entry.
- Check settings.json: Check if
.claude/settings.jsonexists and contains a hook entry whose command string contains exactlysession-hydrate.sh(notsession-hydrate-enforcement.shor other similarly-named hooks) across all hook event types (SessionStart is the typical location). If found:- Parse the JSON. If the JSON is malformed or invalid, log a warning ("Warning: .claude/settings.json is malformed JSON -- skipping session-hydrate.sh entry removal. Does not block setup.") and continue to Step 1 (Gather Project Information).
- Rem