Filesystem Conventions

Workspace Structure

factory/
├── agents.yaml          # Agent definitions — only the human edits this
├── specs/
│   ├── inbox/           # Raw intents from the human
│   ├── drafting/        # Spec agent is working on these
│   ├── ready/           # Specced and ready for Builder
│   └── archive/         # Completed specs (reference library)
├── tasks/
│   ├── research/        # Research requests from any agent → Researcher picks up
│   ├── research-done/   # Completed research briefs → requesting agent reads
│   ├── building/        # Builder's work-in-progress (Verifier CANNOT see)
│   ├── review/          # Completed work awaiting verification
│   ├── verified/        # Passed verification
│   ├── failed/          # Failed verification (with failure reports)
│   ├── decisions/       # Structured decision requests awaiting operator or auto-resolved
│   └── maintenance/     # Ongoing ops tasks (Operator's domain)
├── scenarios/           # HOLDOUT — Builder cannot read this
├── skills/
│   ├── shared/          # Approved skills for all agents
│   ├── proposed/        # Self-authored skills awaiting Librarian review
│   └── {agent}/         # Agent-specific skills
├── memory/
│   ├── shared/          # Cross-agent knowledge (Librarian curates)
│   │   ├── KNOWLEDGE.md # Durable facts, decisions, conventions
│   │   └── PROJECTS.md  # Master project status
│   ├── daily/{agent}/   # Append-only daily logs
│   └── {agent}/MEMORY.md # Private curated memory
├── learnings/
│   ├── failures/        # What went wrong and why
│   ├── corrections/     # Human corrections (highest signal)
│   └── discoveries/     # New patterns, better approaches
├── universe/            # Reference docs — read-only for all agents
├── projects/            # The actual codebases (git repos) — or registered externally via .factory
├── notifications/       # → NanoClaw IPC (symlink). Write JSON here to send WhatsApp messages.
└── runs/                # Execution history