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:

• /spec:propose creates proposal.md and delta.md

• /spec:work executes implementation

• /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).