playbooks

home / skills / martinffx / claude-code-atelier / atelier-spec-methodology

atelier-spec-methodology skill

/plugins/atelier-spec/skills/atelier-spec-methodology

This skill explains and applies a 3-layer context model, living specifications, and beads for coordinated, spec-driven development across agents.

npx playbooks add skill martinffx/claude-code-atelier --skill atelier-spec-methodology

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.0 KB
---
name: atelier-spec-methodology
description: AgentOS 3-layer context, orchestrated delegation, and OpenSpec living specifications. Use when explaining how context flows through layers, how agents collaborate, or how specs evolve.
user-invocable: false
---

# Spec-Driven Development Methodology

This plugin combines three innovations: AgentOS context layers and delegation, OpenSpec living specifications, and Beads dependency tracking.

## 3-Layer Context Model (AgentOS)

Rather than overwhelming agents with all knowledge at once, provide contextually relevant information at the right moments:

| Layer | Contains | Purpose | Location |
|-------|----------|---------|----------|
| **Standards** | Coding conventions, architecture patterns | How you build | `docs/standards/` |
| **Product** | Mission, users, roadmap | What and why | `docs/product/` |
| **Specs** | Requirements, design, tasks | What to build next | `docs/spec/<feature>/` |

Agents load only the context layer they need for their current task.

## Workflow Phases (AgentOS)

| AgentOS Phase | Our Command | Agents Used |
|---------------|-------------|-------------|
| Plan Product | (manual) | - |
| Shape Spec | `/spec:create` | clerk → oracle |
| Write Spec | `/spec:create` | architect → clerk |
| Create Tasks | `/spec:create` | architect (Beads) |
| Implement Tasks | `/spec:work` | direct implementation |
| Orchestrate Tasks | `/spec:work` | architect delegation |

## Orchestrated Delegation

Commands delegate to specialized subagents with controlled context:

| Agent | Model | Role |
|-------|-------|------|
| **clerk** | haiku | Fast context retrieval, file scaffolding |
| **oracle** | opus | Requirements interviews, strategic analysis |
| **architect** | opus | Technical design, task breakdown |

Pattern: Primary agent delegates to specialized subagents rather than trying to do everything itself.

## Living Specifications (OpenSpec)

**Core principle**: Align humans and AI on what to build before any code is written.

### Spec Format

- Requirements with SHALL/MUST language
- Scenarios as acceptance criteria
- Hierarchical: Requirements contain nested Scenarios

### Directory Structure

- `docs/spec/<feature>/spec.md` - Source of truth
- `docs/changes/<feature>/<change>/` - Proposed changes (proposal.md, delta.md, tasks.md)

### Delta Format (Brownfield Changes)

- **ADDED** Requirements - New capabilities
- **MODIFIED** Requirements - Altered behavior (complete updated text)
- **REMOVED** Requirements - Deprecated features

### Living Spec Cycle

1. Draft change proposal
2. Review until consensus
3. Implement tasks
4. Archive change, merge delta into spec

## Dependency Tracking (Beads)

Beads enforces implementation order through dependencies:

- `bd ready` surfaces next unblocked task
- Dependencies enforce bottom-up implementation (Entity → Repository → Service → Router)
- Git-backed persistence via `.beads/beads.jsonl`

Commands like `/spec:create` automatically create Beads epics with tasks ordered by technical dependencies.

Overview

This skill explains a spec-driven development methodology built on AgentOS 3-layer context, orchestrated delegation, and OpenSpec living specifications. It shows how to control context flow, coordinate specialist agents, and evolve requirements as first-class artifacts. Use it to align humans and AI before code is written and to enforce technical dependency order during implementation.

How this skill works

The model separates knowledge into three context layers—Standards, Product, and Specs—so agents load only the layer required for their task. Primary agents delegate to specialist subagents (clerk, oracle, architect) with scoped context and roles to avoid cognitive overload. OpenSpec living specifications store requirements, scenarios, and deltas in a clear file layout while Beads tracks dependencies and surfaces the next unblocked task for ordered implementation.

When to use it

  • When you need to coordinate multiple agents across planning, design, and implementation
  • When you want living specs that evolve safely with traceable deltas
  • When enforcing implementation order matters (e.g., entity → repository → service → router)
  • When onboarding contributors to a codebase with clear standards and product context
  • When automating spec-to-task generation with dependency-aware ordering

Best practices

  • Keep Standards, Product, and Specs small and focused so agents only load what they need
  • Write requirements with SHALL/MUST language and include scenario-based acceptance criteria
  • Use the clerk for fast scaffolding, oracle for stakeholder interviews, and architect for task breakdowns
  • Represent changes as deltas (ADDED, MODIFIED, REMOVED) and iterate proposals before implementation
  • Persist Beads dependency graphs in git so task state and ordering remain auditable

Example use cases

  • Drafting a new feature spec: architect and clerk collaborate to produce hierarchical requirements and tasks
  • Brownfield change: propose a delta, review until consensus, then create Beads-ordered tasks for implementation
  • Implementing a microservice: ensure entity and repository are built before service and router using Beads
  • Product alignment workshops: load only Product context for mission and roadmap discussions with oracle
  • Automated task orchestration: architect delegates sub-tasks to implementers while tracking dependencies

FAQ

How do agents avoid being overwhelmed by project knowledge?

They load one context layer at a time—Standards, Product, or Specs—so each agent receives only the information relevant to its role and command.

What does a living spec look like in practice?

A living spec lives in docs/spec/<feature>/spec.md, uses SHALL/MUST requirements, includes scenario-based acceptance criteria, and accepts deltas in docs/changes/<feature>/.

How does Beads ensure correct implementation order?

Beads models dependencies and surfaces the next unblocked task with commands like bd ready; tasks are persisted to a git-backed beads file for reproducible ordering.