{ "markdown": "# Atelier Pipeline\n\n

\n \"Atelier\n

\n\nMulti-agent orchestration for AI-powered IDEs. Quality gates, continuous QA, and persistent institutional memory — for Claude Code and Cursor.\n\n## What It Does\n\nAtelier Pipeline has two core systems:\n\n**Multi-Agent Orchestration.** Eleven specialized agent personas with clear responsibilities, strict boundaries, and independent quality verification. Eva orchestrates, Robert handles product, Sable designs UX, Sarah architects, Colby builds, Poirot blind-reviews every wave, Agatha documents, Ellis commits, Distillator compresses cross-phase artifacts, Sherlock investigates user-reported bugs, and Sentinel audits security (opt-in). Custom agents can be added via agent discovery. Specs get written, designs get validated, every change passes Eva's mechanical test gate plus Poirot blind review, and nothing ships without review. Works with Claude Code and Cursor.\n\n**Atelier Brain.** A persistent memory layer backed by PostgreSQL and vector embeddings that gives your agents institutional memory across sessions. Without it, every time you close a terminal you lose the architectural decisions that shaped your implementation, the user corrections that steered scope, the rejected alternatives that explain why you didn't go a different way, and the QA lessons that prevent recurring bugs. The brain captures all of this during pipeline runs and surfaces it automatically when agents need context. It includes write-time conflict detection, TTL-based knowledge decay, and background consolidation that synthesizes raw observations into higher-level insights. The pipeline works without the brain -- but with it, session 12 of a feature build has the same context as session 1.\n\n> **The brain is essentially free to run.** It uses OpenRouter for embeddings (`text-embedding-3-small` at $0.02/1M tokens) and occasional conflict detection (`gpt-4o-mini`). Real-world cost: **3,500+ thoughts stored over one month of heavy daily use for $0.06 total** in OpenRouter fees. Extrapolated, that's **under $0.72/year**. Fund $1.00 on OpenRouter and you're covered for a long time. Per ADR-0054, you can also point the brain at GitHub Models (free for GitHub Enterprise users via `GITHUB_TOKEN`) or a local Ollama instance (free, no API key) instead of OpenRouter.\n\nFor full documentation, see the [User Guide](docs/guide/user-guide.md) and [Technical Reference](docs/guide/technical-reference.md).\n\n## Getting Started\n\n### 1. Install the Plugin\n\nAdd the marketplace and install:\n\n```\n/plugin marketplace add robertsfeir/atelier-pipeline\n/plugin install atelier-pipeline@atelier-pipeline\n```\n\nRestart Claude Code after install.\n\n**Cursor:**\n\nInstall from the Cursor Marketplace — search \"atelier-pipeline\".\n\nOr manually:\n\n```bash\ngit clone https://github.com/robertsfeir/atelier-pipeline.git /tmp/atelier-pipeline\n```\n\nThen in Cursor:\n\n```\nRead /tmp/atelier-pipeline/.cursor-plugin/skills/pipeline-setup/SKILL.md and follow its instructions\n```\n\n### 2. Set Up the Pipeline\n\nOpen your IDE (Claude Code or Cursor) in your project and run:\n\n```\n/pipeline-setup\n```\n\nClaude walks you through project configuration one question at a time:\n- Tech stack and framework\n- Test commands (lint, typecheck, test suite)\n- Source structure and database patterns\n- Coverage and complexity thresholds\n- Branching strategy\n\nIt then installs ~40 files into your project (agent personas, commands, references, enforcement hooks, path-scoped rules, branch lifecycle rules, and state tracking). At the end, it offers optional features: Sentinel security agent, Agent Teams parallel execution, and Atelier Brain persistent memory.\n\n### 3. Set Up the Brain (optional but recommended)\n\nIf you skipped the brain offer during pipeline setup, run it separately:\n\n```\n/brain-setup\n```\n\nThe setup asks:\n\n1. **Personal or shared?** Personal config stays local (never committed). Shared config is committed to the repo with `${ENV_VAR}` placeholders -- no bare secrets.\n2. **Docker, local PostgreSQL, or remote PostgreSQL?** Docker is one command (`docker compose up`). Local PostgreSQL requires pgvector and ltree extensions. Remote PostgreSQL (RDS, Supabase, etc.) connects to an existing managed database -- setup verifies the connection, checks for required extensions, and applies the schema if needed.\n3. **LLM provider for vector embeddings.** Pick one: **OpenRouter** (default — get a key at https://openrouter.ai/keys and set `export OPENROUTER_API_KEY=\"sk-or-...\"`), **GitHub Models** (free for GitHub Enterprise users — uses your existing `GITHUB_TOKEN`), or **local Ollama** (free, no API key required). See ADR-0054 for the full provider matrix.\n4. **Scope path.** A dot-separated namespace like `myorg.myproduct` that organizes knowledge.\n\nSetup verifies the connection and confirms:\n\n```\nBrain is live.\n Tools available: 6\n Scope: myorg.myproduct\n Config: personal (~/.claude/plugins/data/atelier-pipeline/brain-config.json)\n Database: Local PostgreSQL (myproject_brain)\n```\n\n**Teammate onboarding:** If a shared brain config already exists in the repo, `/brain-setup` detects it automatically and tells the new team member which environment variables to set. No interactive setup needed.\n\n### 4. Hydrate the Brain (optional)\n\nFor existing projects with ADRs, specs, or git history:\n\n```\n/brain-hydrate\n```\n\nScans your project artifacts, extracts the reasoning behind decisions (not the content itself), and imports it as brain thoughts. Safe to re-run -- duplicate detection prevents re-importing.\n\n### 5. Start Building\n\nDescribe a feature idea, or type `/pipeline` to start Eva. She sizes the work and routes to the right agent.\n\n## Updating the Plugin\n\n**Claude Code:**\n```\nclaude plugin marketplace update atelier-pipeline\nclaude plugin update atelier-pipeline@atelier-pipeline\n```\nThen restart Claude Code and re-run `/pipeline-setup`.\n\n**Cursor:**\nPull the latest from the marketplace in Cursor's plugin settings, restart Cursor, and re-run `/pipeline-setup`.\n\nA session-start hook notifies you when your project's pipeline files are outdated.\n\n### Manual Setup (without plugin system)\n\n**Claude Code:**\n\n```bash\ngit clone https://github.com/robertsfeir/atelier-pipeline.git /tmp/atelier-pipeline\n```\n\nThen in Claude Code:\n\n```\nRead /tmp/atelier-pipeline/skills/pipeline-setup/SKILL.md and follow its\ninstructions to install the pipeline in this project\n```\n\n**Cursor:**\n\n```bash\ngit clone https://github.com/robertsfeir/atelier-pipeline.git /tmp/atelier-pipeline\n```\n\nThen in Cursor:\n\n```\nRead /tmp/atelier-pipeline/.cursor-plugin/skills/pipeline-setup/SKILL.md and follow its instructions\n```\n\n## Skills\n\nThe plugin provides five skills:\n\n| Skill | Trigger | Purpose |\n|-------|---------|---------|\n| `/pipeline-setup` | \"set up the pipeline\", \"install atelier\" | Installs all agent personas, commands, references, and state files into your project |\n| `/pipeline-overview` | \"how does the pipeline work\", \"explain atelier\" | Quick reference for the pipeline system, agents, and principles |\n| `/brain-setup` | \"set up the brain\", \"configure brain\" | Configures the Atelier Brain persistent memory (Docker, local PostgreSQL, or remote PostgreSQL) |\n| `/brain-hydrate` | \"hydrate brain\", \"seed memory\", \"import history\" | Imports existing project knowledge (ADRs, specs, git history) into the brain |\n| `/dashboard` | \"open dashboard\", \"show telemetry\" | Opens the Atelier Dashboard for telemetry visualization |\n\n## The Pipeline\n\nEva sizes every request and runs the right amount of process. A large feature gets the full pipeline; a bug fix gets Colby, the mechanical test gate, Poirot, and Ellis.\n\n### Full pipeline (Large)\n\n```mermaid\nflowchart TD\n IDEA([Idea]):::system --> ROBERT(Robert — Spec):::robert\n ROBERT --> SABLE_UX(Sable — UX):::sable\n ROBERT --> AGATHA_PLAN(Agatha — Doc Plan):::agatha\n SABLE_UX --> COLBY_MOCK(Colby — Mockup):::colby\n AGATHA_PLAN --> COLBY_MOCK\n COLBY_MOCK --> SABLE_V(Sable — Verify):::sable\n SABLE_V --> UAT([User UAT]):::user\n UAT --> SARAH(Sarah — ADR):::sarah\n\n SARAH --> BUILD\n\n subgraph BUILD [Wave Build Cycle - repeats]\n COLBY_B(Colby — Build Units):::colby --> GATE(Eva — Mechanical Test Gate):::gate\n GATE --> POIROT_W(Poirot — Blind Review):::poirot\n POIROT_W --> ELLIS_W(Ellis — Wave Commit):::ellis\n end\n\n ELLIS_W --> REVIEW\n\n subgraph REVIEW [Review Juncture - parallel]\n POIROT_F(Poirot — Final Review):::poirot\n ROBERT_F(Robert — Acceptance):::robert\n SABLE_F(Sable — UX):::sable\n SENTINEL_F(Sentinel — Security):::sentinel\n end\n\n REVIEW --> AGATHA(Agatha — Docs):::agatha\n AGATHA --> RECONCILE{Reconciliation}:::gate\n RECONCILE --> ELLIS_F(Ellis — Final Commit):::ellis\n ELLIS_F --> DONE([Shipped]):::user\n\n classDef sarah fill:#3b82f6,stroke:#2563eb,color:#fff,font-weight:bold\n classDef colby fill:#22c55e,stroke:#16a34a,color:#fff,font-weight:bold\n classDef ellis fill:#06b6d4,stroke:#0891b2,color:#fff,font-weight:bold\n classDef robert fill:#f97316,stroke:#ea580c,color:#fff,font-weight:bold\n classDef sable fill:#ec4899,stroke:#db2777,color:#fff,font-weight:bold\n classDef poirot fill:#8b5cf6,stroke:#7c3aed,color:#fff,font-weight:bold\n classDef agatha fill:#14b8a6,stroke:#0d9488,color:#fff,font-weight:bold\n classDef sentinel fill:#ef4444,stroke:#dc2626,color:#fff,font-weight:bold\n classDef system fill:#6b7280,stroke:#4b5563,color:#fff,font-weight:bold\n classDef user fill:#6b7280,stroke:#4b5563,color:#fff,font-weight:bold\n classDef gate fill:#9ca3af,stroke:#6b7280,color:#fff,font-weight:bold\n\n style BUILD fill:#f0fdf4,stroke:#86efac,stroke-width:2px,stroke-dasharray:5 5\n style REVIEW fill:#faf5ff,stroke:#c4b5fd,stroke-width:2px,stroke-dasharray:5 5\n```\n\n### Phase sizing\n\nNot every feature runs every phase. Eva adjusts:\n\n| Size | When | What runs |\n|------|------|-----------|\n| **Micro** | Rename, typo, import fix (≤2 files, mechanical only) | Colby -> test suite -> Ellis |\n| **Small** | Bug fix, <3 files, \"quick fix\" | Colby -> mechanical test gate -> Poirot -> Ellis (+ Agatha if doc impact) |\n| **Medium** | 2-4 ADR steps, typical feature | Robert -> Sarah -> wave build (Colby + mechanical gate + Poirot) -> review juncture -> Agatha -> Ellis |\n| **Large** | 5+ ADR steps, new system | Full pipeline above |\n\n### Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full release history.\n\n## Agents\n\n| Agent | Role | Type |\n|-------|------|------|\n| **Eva** | Pipeline Orchestrator / DevOps | Skill (main thread) |\n| **Robert** | Chief Product Officer | Skill + Subagent |\n| **Sable** | Senior UI/UX Designer | Skill + Subagent |\n| **Sarah** | Senior Software Architect | Skill + Subagent |\n| **Colby** | Senior Software Engineer | Subagent |\n| **Poirot** | Blind Code Investigator (default post-build verifier) | Subagent |\n| **Sherlock** | Sr. Detective -- user-reported bug diagnose-only hunt | Subagent |\n| **Agatha** | Documentation Specialist | Skill + Subagent |\n| **Ellis** | Commit and Changelog Manager | Subagent |\n| **Distillator** | Compression Engine | Subagent |\n| **Sentinel** | Security Auditor (opt-in) | Subagent |\n\n**Skills** run in the main conversation thread (Claude Code or Cursor) for conversational work. **Subagents** run in their own context windows for focused execution. Some agents have both modes -- conversational for authoring, subagent for verification. Custom agents can be added via [agent discovery](#agent-discovery) without modifying core pipeline files.\n\n> **Note:** On Cursor, subagents run as skills in the main thread since Cursor does not support Agent spawning. All agents are available on both platforms.\n\n### Agent Teams (Experimental, Claude Code only)\n\nAgent Teams enables parallel wave execution during the Colby build phase. When multiple ADR steps are independent (no shared files), Eva normally executes them sequentially. With Agent Teams enabled, Eva creates Colby Teammate instances that execute those steps simultaneously.\n\n**Two gates must pass:**\n\n| Gate | Setting | Purpose |\n|------|---------|---------|\n| Config gate | `\"agent_teams_enabled\": true` in `.claude/pipeline-config.json` | Pipeline-level opt-in, set during `/pipeline-setup` |\n| Environment gate | `export CLAUDE_AGENT_TEAMS=1` | Claude Code feature flag that enables the Agent Teams runtime |\n\nBoth gates must pass. If either fails, the pipeline falls back to sequential execution with zero behavioral change. Agent Teams affects execution speed, not correctness or quality. All twelve mandatory gates are preserved.\n\n### Agent Discovery\n\nEva discovers custom agents at session boot by scanning `.claude/agents/` for non-core persona files. Discovered agents are additive only -- they never replace core agent routing. Core agents always have priority. To route a discovered agent automatically, Eva asks for your consent when it detects domain overlap with a core agent. No-overlap agents are available via explicit name mention (e.g., \"ask my-agent about this\").\n\nTo create a custom agent, paste an agent definition into the chat. Eva recognizes the pattern and offers to convert it into a pipeline-compatible persona file with proper frontmatter, XML tags, and read-only enforcement defaults.\n\n## Slash Commands\n\nThese are installed into your project by `/pipeline-setup`:\n\n| Command | Agent | Purpose |\n|---------|-------|---------|\n| `/pm` | Robert | Feature discovery and product spec |\n| `/ux` | Sable | UI/UX design and interaction patterns |\n| `/architect` | Sarah | Architecture clarification and ADR production |\n| `/debug` | Sherlock -> Colby -> Poirot | Investigation, fix, blind verification chain |\n| `/pipeline` | Eva | Full pipeline orchestration |\n| `/devops` | Eva | Infrastructure and deployment |\n| `/docs` | Agatha | Documentation planning and writing |\n\n## Atelier Brain\n\nThe brain is an MCP server with 6 tools that agents use automatically during pipeline runs:\n\n| Tool | Purpose |\n|------|---------|\n| `agent_capture` | Save a decision, lesson, preference, or correction |\n| `agent_search` | Semantic search across brain thoughts |\n| `atelier_browse` | Paginated browse by type or status |\n| `atelier_stats` | Brain health check (thought count, config, status) |\n| `atelier_relation` | Create typed edges between thoughts (supersedes, contradicts, evolves_from) |\n| `atelier_trace` | Walk relation chains from a thought |\n\nAgents capture thoughts during pipeline runs and search for relevant context before making decisions. Write-time conflict detection catches contradictions (>0.9 similarity = duplicate, 0.7-0.9 = LLM-classified). TTL decay expires stale knowledge per thought type. Background consolidation synthesizes raw observations into reflections.\n\n## What Gets Installed\n\n`/pipeline-setup` installs ~40 files into your project:\n\n```\nyour-project/\n .claude/\n rules/ # Always loaded by the IDE\n default-persona.md # Eva orchestrator persona\n agent-system.md # Orchestration rules, routing, gates\n pipeline-orchestration.md # Pipeline operations (path-scoped, loads during active pipelines)\n pipeline-models.md # Model selection tables (path-scoped)\n branch-lifecycle.md # Branch lifecycle rules (selected strategy variant)\n agents/ # Loaded when subagents are invoked\n sarah.md # Architect\n colby.md # Engineer\n robert.md # Product reviewer\n robert-spec.md # Product spec producer\n sable.md # UX reviewer\n sable-ux.md # UX design producer\n investigator.md # Poirot (blind code investigator)\n sherlock.md # User-reported bug detective\n distillator.md # Compression engine\n ellis.md # Commit manager\n agatha.md # Documentation\n sentinel.md # Security audit (opt-in)\n commands/ # Loaded when user types slash command\n pm.md # /pm (robert-spec)\n ux.md # /ux (sable-ux)\n architect.md # /architect (Sarah)\n debug.md # /debug (Sherlock -> Colby -> Poirot)\n pipeline.md # /pipeline (Eva)\n devops.md # /devops (Eva)\n docs.md # /docs (Agatha)\n references/ # Loaded by agents on demand\n dor-dod.md # Quality framework\n retro-lessons.md # Shared lessons (starts empty)\n invocation-templates.md # Subagent invocation examples\n pipeline-operations.md # Continuous QA, feedback loops, batch mode\n agent-preamble.md # Shared agent behaviors\n xml-prompt-schema.md # XML tag vocabulary for persona files\n branch-mr-mode.md # Colby branch/MR procedures\n hooks/ # Mechanical enforcement (PreToolUse + SubagentStop + PreCompact)\n enforce-paths.sh # Blocks Write/Edit outside agent's allowed paths\n enforce-sequencing.sh # Blocks out-of-order agent invocations\n enforce-git.sh # Blocks git write ops and test commands from main thread\n session-hydrate.sh # Runs telemetry hydration at SessionStart\n pre-compact.sh # Compaction marker for pipeline state preservation\n enforcement-config.json # Project-specific paths and rules\n pipeline-config.json # Branching strategy, Sentinel, Agent Teams config\n settings.json # Hook registration\n docs/\n pipeline/ # Eva reads at session start for recovery\n pipeline-state.md # Session recovery state\n context-brief.md # Cross-session context\n error-patterns.md # Error pattern tracking\n investigation-ledger.md # Debug hypothesis tracking\n last-qa-report.md # Poirot's most recent QA report\n```\n\n**Requires:** `jq` for hook enforcement (`brew install jq` on macOS, `apt install jq` on Linux).\n\n**For Cursor:** the same structure installs into `.cursor/` with rules using `.mdc` extension and frontmatter.\n\n## Key Principles\n\n- **Wave-based QA.** Each wave is a work unit with its own build-test-review cycle. Colby builds, Eva runs the mechanical test gate, Poirot blind-reviews the cumulative wave diff, Ellis commits once per wave.\n- **DoR/DoD.** Every agent proves it read upstream artifacts (DoR) and covers all requirements (DoD).\n- **Twelve mandatory gates.** Eva enforces twelve quality gates that are never skipped, covering sequencing, test-before-ship, documentation, and wave-level pipeline discipline.\n- **Six enforcement hooks.** Three PreToolUse hooks (path enforcement, sequencing, git ops), one SubagentStop hook (DoR/DoD warnings), one PreCompact hook (compaction marker), and one config file. Behavioral guidance tells agents what to do; hooks ensure they can't do what they shouldn't.\n- **Information asymmetry.** Three parallel reviewers see constrained context to prevent anchoring -- Poirot sees only the diff, Robert sees only the spec, Sable sees only the UX doc. Sentinel sees only the diff and Semgrep scan results.\n- **Four-layer investigation.** Debug flows check Application, Transport, Infrastructure, Environment. Two rejected hypotheses at one layer forces escalation.\n- **Living artifacts.** Specs and UX docs are updated at pipeline end. ADRs are immutable records.\n- **Retro lessons.** Error patterns recurring 3+ times get injected as warnings into future agent prompts.\n- **One phase per turn.** On Medium and Large pipelines, Eva performs one phase transition per response. No silent chaining through multiple phases.\n- **Loop-breaker.** Three consecutive failures on the same task halt the pipeline. Eva presents a Stuck Pipeline Analysis instead of retrying indefinitely.\n- **Mechanical enforcement.** PreToolUse hooks block agents from writing outside their designated paths, enforce pipeline sequencing (no commits without QA), and prevent Eva from running git operations or tests directly.\n\n## Customization\n\nDuring setup, you configure project-specific values:\n\n- Test commands (lint, typecheck, test suite)\n- Source structure (where features, components, services live)\n- Database/store patterns\n- Coverage and complexity thresholds\n- Build and deploy commands\n- Branching strategy (trunk-based, GitHub Flow, GitLab Flow, GitFlow)\n- Sentinel security agent (opt-in)\n- Agent Teams parallel execution (opt-in, experimental)\n\nThe orchestration patterns and quality gates are stack-agnostic.\n\n## Author\n\nRobert Sfeir\n\n## License\n\nApache License 2.0 -- see [LICENSE](LICENSE) for details.\n", "bytes": 20904, "sha": "4003a7c4397f9d9ec6ceb91402eb1732cff40c394f71a7c72d4a0531ec194aa5", "repo_slug": "robertsfeir/atelier-pipeline", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_robertsfeir_atelier_pipeline_atelier_pip_babc9edb/readme" }