playbooks

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

methodology skill

/plugins/atelier-spec/skills/methodology

This skill explains how AgentOS context layers, orchestrated delegation, and OpenSpec living specifications flow together to guide multi-agent collaboration

npx playbooks add skill martinffx/claude-code-atelier --skill 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: 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 that combines AgentOS three-layer context, orchestrated delegation, and OpenSpec living specifications. It shows how context flows through layers, how specialized agents collaborate, and how specifications evolve as source of truth. Use it to design reproducible workflows that keep humans and AI aligned before code is written.

How this skill works

Context is split into three layers—Standards, Product, and Specs—so agents load only what’s relevant to their current task. A primary agent delegates work to specialized subagents (clerk, oracle, architect), each with a focused role and model profile. Living specs (OpenSpec) capture requirements, scenarios, and change deltas; Beads tracks dependencies and surfaces the next unblocked task for ordered implementation.

When to use it

  • When you need clear separation of concerns between design standards, product intent, and actionable specs.
  • When coordinating multiple agents or humans across planning, spec authoring, and implementation.
  • When managing brownfield changes that require explicit deltas and review cycles.
  • When you need deterministic task ordering driven by technical dependencies.
  • When you want a living source of truth that evolves with proposals, reviews, and merges.

Best practices

  • Keep Standards, Product, and Specs in separate docs and load only the layer needed for the task.
  • Use primary agents to orchestrate and delegate to clerk, oracle, and architect rather than one agent doing everything.
  • Write specs with SHALL/MUST language and scenario-based acceptance criteria for testability.
  • Model changes as deltas (ADDED/MODIFIED/REMOVED) and iterate proposals until consensus before implementation.
  • Use Beads to encode dependencies and rely on its ready signal to pick the next unblocked task.

Example use cases

  • Shaping a new feature: run spec:create to draft spec, interview stakeholders via oracle, and scaffold files via clerk.
  • Brownfield change: draft a delta, review with team, generate Beads-ordered tasks, then implement in dependency order.
  • Orchestrated implementation: architect breaks work into tasks and delegates execution to subagents with minimal context.
  • Enforcing code quality: embed Standards layer for linters, architecture patterns, and language-specific idioms during code reviews.
  • Roadmap alignment: surface Product context to agents when prioritizing specs so work reflects mission and user needs.

FAQ

How does the three-layer model reduce agent overload?

By exposing only the relevant layer (Standards, Product, or Specs) for the current task, agents receive concise, targeted context instead of the entire codebase and docs.

What guarantees ordered implementation?

Beads encodes task dependencies and provides a ready signal that surfaces the next unblocked task, enforcing bottom-up implementation order.