playbooks

home / skills / martinffx / claude-code-atelier / atelier-spec-project-structure

atelier-spec-project-structure skill

/plugins/atelier-spec/skills/atelier-spec-project-structure

This skill helps you organize project structure using a 3-layer AgentOS model for docs, specs, and task tracking.

npx playbooks add skill martinffx/claude-code-atelier --skill atelier-spec-project-structure

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

Files (1)
SKILL.md
2.6 KB
---
name: atelier-spec-project-structure
description: Directory layout implementing AgentOS 3-layer context. Use when setting up projects, organizing docs, or explaining where specs and changes go.
user-invocable: false
---

# Project Structure

Directory layout implementing the AgentOS 3-layer context model.

## 3-Layer Directory Structure

```
project/
├── docs/
│   ├── standards/        # Layer 1: How you build
│   ├── product/          # Layer 2: What and why
│   └── spec/             # Layer 3: What to build next
├── .beads/               # Beads task tracking
└── CLAUDE.md             # Project overview
```

**AgentOS 3-Layer Model:**
- **Layer 1 (standards/)**: Technical patterns, coding principles, architecture decisions
- **Layer 2 (product/)**: Product vision, roadmap, business context
- **Layer 3 (spec/)**: Feature specs and change proposals

## Layer 1: Standards (docs/standards/)

Technical standards adapted for the project's technology stack:

- **coding.md** - TDD patterns (Stub → Test → Implement → Refactor), coding principles
- **architecture.md** - Layered architecture (Router → Service → Repository → Entity → Database)

## Layer 2: Product (docs/product/)

Product-level documentation:

- **product.md** - Product definition, target users, core features, success metrics
- **roadmap.md** - Next 3 features in priority order, implementation strategy, current status

## Layer 3: Specs (docs/spec/)

### Greenfield Features (New Code)

```
docs/spec/<feature>/
└── spec.md          # Unified requirements + technical design
```

**spec.md** contains:
- Requirements (user stories, acceptance criteria, business rules)
- Technical Design (data models, API design, component structure)

### Brownfield Changes (Existing Code)

```
docs/changes/<feature>/<change>/
├── proposal.md      # Change proposal
├── delta.md         # ADDED/MODIFIED/REMOVED changes
└── tasks.md         # Implementation tasks
```

**Workflow:**
1. `/spec:propose` creates proposal.md and delta.md
2. `/spec:work` executes implementation
3. `/spec:complete` merges delta into spec.md, deletes change folder

## Beads Task Tracking

```
.beads/
├── beads.jsonl      # Git-tracked task data
├── beads.db         # Local cache (gitignored)
└── bd.sock          # Socket (gitignored)
```

**.gitignore entries:**
```
.beads/beads.db
.beads/bd.sock
```

Beads provides dependency-aware task management. Commands like `/spec:create` and `/spec:propose` automatically create epics with tasks ordered by technical dependencies (Entity → Repository → Service → Router).

Overview

This skill provides a three-layer directory layout implementing the AgentOS context model for spec-driven development. It organizes standards, product context, and actionable specs so teams can separate long-lived principles from feature work and change proposals. Use it to set up new projects, document decisions, and manage spec-to-implementation workflows.

How this skill works

The layout places technical patterns and architecture in docs/standards, product strategy and roadmaps in docs/product, and all feature specs or change proposals in docs/spec (and docs/changes for brownfield updates). Beads task tracking lives in .beads to capture dependency-aware tasks and epics. Workflow commands create proposals, open work items, and merge completed deltas back into canonical spec documents.

When to use it

  • Starting a new codebase or repo to enforce consistent documentation and workflow
  • Onboarding engineers so they know where standards, product context, and specs live
  • Managing feature development from proposal through implementation and completion
  • Coordinating brownfield changes with clear proposals, deltas, and task lists
  • Integrating dependency-aware task tracking with development commands

Best practices

  • Keep docs/standards authoritative and stable; record architecture decisions and coding patterns there
  • Write each feature spec.md to include both user-facing requirements and technical design
  • For changes to existing code, create a change folder with proposal.md, delta.md, and tasks.md before touching code
  • Use beads to store task metadata in .beads/beads.jsonl and keep local caches gitignored
  • Merge completed deltas into the corresponding spec and remove transient change folders to avoid drift

Example use cases

  • Greenfield feature: create docs/spec/my-feature/spec.md with requirements, API design, and data models before implementation
  • Brownfield update: open docs/changes/feature/x/proposal.md and delta.md to describe what will be added/modified/removed, then produce tasks.md
  • Roadmap planning: list the next three prioritized features and implementation strategy in docs/product/roadmap.md
  • Quality gate: refer to docs/standards/coding.md and architecture.md during PR review to check adherence to patterns
  • Automated workflows: run commands that generate epics and ordered tasks based on Entity→Repository→Service→Router dependency order

FAQ

How do I organize a small tweak vs a full feature?

Small tweaks belong in docs/changes/<feature>/<change>/ with proposal.md and delta.md. Full new features get a docs/spec/<feature>/spec.md that combines requirements and technical design.

What belongs in docs/standards vs docs/product?

docs/standards holds technical rules and architecture (how you build). docs/product holds context like product definition, users, and roadmap (what and why).