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

project-structure skill

safe

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

This skill helps you organize project structure using the AgentOS 3-layer model, clarifying standards, product, and specs across docs and tasks.

npx playbooks add skill martinffx/claude-code-atelier --skill 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: 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 clear project directory layout implementing the AgentOS 3-layer context model for standards, product, and specs. It helps teams organize documentation, track change proposals, and connect specs to implementation tasks using beads task tracking. Use it to align technical patterns, product intent, and feature work in a single predictable structure.

How this skill works

The skill defines three docs layers under docs/: standards/ for technical rules, product/ for vision and roadmaps, and spec/ for greenfield specs and brownfield change proposals. It prescribes file conventions (coding.md, architecture.md, product.md, roadmap.md, spec.md, proposal.md, delta.md, tasks.md) and a workflow for proposing, implementing, and completing changes. It also includes a .beads/ layout for dependency-aware task tracking and gitignore guidance for local artifacts.

When to use it

Setting up a new project to enforce consistent documentation and decision capture
Organizing product and engineering artifacts so requirements map to implementation
Creating or reviewing feature specs and change proposals
Coordinating work across teams using dependency-aware task tracking
Maintaining architecture and coding standards as the codebase evolves

Best practices

Keep Layer 1 standards concise, actionable, and technology-specific (coding patterns, architecture decisions)
Document product context in Layer 2: target users, core success metrics, and a 3-feature roadmap
For greenfield features, put unified requirements and design in spec.md inside docs/spec/<feature>/
For brownfield changes, use a change folder with proposal.md, delta.md, and tasks.md and follow propose→work→complete lifecycle
Track tasks in .beads/beads.jsonl and ignore runtime artifacts (.beads/beads.db, .beads/bd.sock) in gitignore

Example use cases

Kickstarting a new service: create docs/standards/coding.md and docs/spec/<feature>/spec.md to align devs
Rolling out a breaking change: file docs/changes/<feature>/<change>/proposal.md and delta.md to capture impact
Planning releases: keep docs/product/roadmap.md synced with prioritized spec folders for the next three features
Onboarding: point new team members to CLAUDE.md and the three-layer docs to explain where to find decisions and next work
Running spec-driven sprints: use beads commands to generate epics and ordered tasks following technical dependencies

FAQ

How do I choose what belongs in standards vs product vs spec?

Standards are how you build (patterns, rules). Product holds why and what matters to users. Specs contain concrete feature requirements and technical designs for implementation.

When should I use a change folder instead of a new spec?

Use a change folder for brownfield work that modifies existing behavior or implementation. Use a new spec for greenfield features that add new capabilities.