methodology
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 truthdocs/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
- Draft change proposal
- Review until consensus
- Implement tasks
- Archive change, merge delta into spec
Dependency Tracking (Beads)
Beads enforces implementation order through dependencies:
bd readysurfaces 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.
More from martinffx/claude-code-atelier
python:architecture
Python application architecture with functional core, effectful shell, DDD, and data modeling. Use when designing application layers, separating pure business logic from IO, defining domain models, implementing validation, or structuring bounded contexts.
14python:monorepo
Python monorepo architecture with uv workspaces, mise, and apps/packages pattern. Use when setting up project structure, configuring workspaces, managing dependencies across packages, or designing multi-app Python repositories.
13python:build-tools
Python project tooling with uv, mise, ruff, basedpyright, and pytest. Use when setting up pyproject.toml, running builds, typechecking, configuring tests, linting, formatting, or managing Python environments.
12python:sqlalchemy
SQLAlchemy ORM patterns for Python database access. Use when defining models, writing queries, implementing upserts, working with JSON columns, or managing database sessions.
12python:fastapi
Building REST APIs with FastAPI, Pydantic validation, and OpenAPI. Use when creating routes, handling requests, designing endpoints, implementing validation, error responses, pagination, or generating API documentation.
11atelier-typescript-functional-patterns
Functional programming patterns for reliable TypeScript. Use when modeling state machines, discriminated unions, Result/Option types, branded types, or building type-safe domain models.
8