agent-atelier

Agent Atelier

Autonomous product development loop for Claude Code. An AI agent team that cycles through spec drafting, implementation, validation, and self-correction — escalating only irreversible decisions to the human.

How It Works

Agent Atelier orchestrates a team of specialized agents through a file-based state machine. The human provides a service concept; the team refines it into a behavior spec, decomposes it into work items, implements them in isolated worktrees, validates with an independent runtime, and iterates on review findings until all work items pass.

DISCOVER --> SPEC_DRAFT --> SPEC_HARDEN --> BUILD_PLAN --> IMPLEMENT
                                ^                            |
                                |                            v
                           AUTOFIX <--- REVIEW_SYNTHESIS <-- VALIDATE
                                |
                                '------------------------------> DONE

Mode transitions follow a formal protocol defined in the run skill. IMPLEMENT and VALIDATE may overlap — a Builder can work on the next work item while the VRM validates the current candidate.

Agent Team

Category	Roles	Activation
Always-on Core	Orchestrator (lead), State Manager, PM, Architect	Every loop iteration
Conditional Executors	Builder (full-stack), UI Designer, VRM	On demand per phase
Conditional Reviewers	QA Reviewer, Pragmatic UX Reviewer	Most validation loops
Milestone-only	Aesthetic UX Reviewer	Release candidates

10 production role prompts in references/prompts/. The Orchestrator role is played by the lead agent; the remaining 3 core roles are spawned as teammates via Agent Teams.

Key Design Choices

• Documents are truth, conversations are ephemeral. Teammates read project context from disk, not conversation history.
• Information barrier. VRM and reviewers never see Builder summaries or diffs — inputs are assembled from work items and specs only.
• Single writer. All state mutations go through state-commit with revision-based optimistic concurrency and WAL crash recovery.
• Non-blocking human gates. When a decision requires human approval, the team continues all unblocked work.

Installation

Add to your project's .claude/settings.json:

{
  "permissions": {
    "additionalDirectories": []
  },
  "extraKnownMarketplaces": {
    "agent-atelier": {
      "source": { "source": "github", "repo": "ether-moon/agent-atelier" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "agent-atelier@agent-atelier": true
  }
}

Claude Code 설정에 다음 환경변수가 필요합니다:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Requires Claude Code with Opus 4.6 (Agent Teams support) and Python 3.

Usage

/agent-atelier:init          # bootstrap .agent-atelier/ state directory
# write or place your behavior spec at docs/product/behavior-spec.md
/agent-atelier:run           # start the autonomous loop

The loop runs autonomously. Human gates appear when irreversible or product-level decisions arise — respond in chat and the team resumes.

Monitor progress at any time:

/agent-atelier:status        # orchestration dashboard

Skills

Skill	Purpose
init	Bootstrap orchestration workspace (.agent-atelier/)
status	Show orchestration dashboard — mode, active candidate set, open gates, WI summary
wi	Work item planning: list, show, upsert
execute	Execution lifecycle: claim, heartbeat, requeue, complete, attempt
candidate	Candidate pipeline: enqueue, activate, clear
validate	Validation evidence recording with manifest and WI status update
gate	Human decision gates: list, open, resolve
watchdog	Health check, lease recovery, stale candidate demotion, budget monitoring
run	Orchestration loop entry point — team spawn, state machine, continuous monitoring

All skills are invoked as /agent-atelier:<skill-name>.

Architecture