pipeline-setup

Atelier Pipeline -- Setup

This skill installs the full Atelier Pipeline multi-agent orchestration system into the user's project.

Heads-up (Claude Code < 2.1.89): Agent persona frontmatter declares an effort field (values: low, medium, high, xhigh) in addition to model. Claude Code runtimes older than 2.1.89 ignore the effort field 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 the effort field as documentation-only. Cursor users: the effort field is passed through as metadata; refer to Cursor release notes for runtime support.

<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">

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-uninstall skill.

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.

1. Check file: Check if .claude/hooks/quality-gate.sh exists. If found: delete the file. Note that removal occurred.
2. Check settings.json: Check if .claude/settings.json exists and contains a hook entry referencing quality-gate.sh in any command string across all hook event types (PreToolUse, SubagentStop, PreCompact, etc.). If found:
3. 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.
4. Remove the hook entry containing "quality-gate" from the command string.
5. If removing that entry leaves an empty hooks array for an event type, remove the event type entry entirely (no empty arrays left behind).
6. Write the updated JSON back to .claude/settings.json.
7. Note that removal occurred.
8. Print notice (conditional): If either artifact was found and removed: print exactly Removed deprecated quality-gate.sh (see retro lesson #003).
9. 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.

1. Check prompt-brain-capture.sh: If .claude/hooks/prompt-brain-capture.sh exists, delete it with rm -f .claude/hooks/prompt-brain-capture.sh. Note that removal occurred.
2. Check warn-brain-capture.sh: If .claude/hooks/warn-brain-capture.sh exists, delete it with rm -f .claude/hooks/warn-brain-capture.sh. Note that removal occurred.
3. Print notice (conditional): If either file was found and removed: print exactly Removed orphan brain-capture hooks (superseded by brain-extractor agent).
4. 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.

1. Check settings.json: Check if .claude/settings.json exists and contains a hook entry whose command string contains exactly session-hydrate.sh (not session-hydrate-enforcement.sh or other similarly-named hooks) across all hook event types (SessionStart is the typical location). If found:
2. 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).
3. Rem