| name | filesystem-conventions |
| description | How the factory workspace is organized and what each directory means. |
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
Cardinal Rules
The filesystem IS the coordination protocol. Don't try to "message" other agents. Write files where other agents will find them on their next turn.
Moving a file between directories IS a state transition:
specs/inbox/ → specs/drafting/ = "Spec is working on this"specs/drafting/ → specs/ready/ = "Spec is done, ready for Builder"tasks/building/ → tasks/review/ = "Builder is done, verify this"tasks/review/ → tasks/verified/ = "Verifier approves"tasks/review/ → tasks/failed/ = "Verifier rejects with report"- Agent writes
tasks/decisions/{spec}.md = "Ambiguity needs resolution before pipeline can advance"
- Operator resolves
tasks/decisions/{spec}.md = "Decisions made, requesting agent resumes"
Git tracks everything. Commit after every meaningful state change.
File Naming
- Learnings:
{YYYY-MM-DD}-{project}-{brief-summary}.md
- Daily logs:
memory/daily/{agent}/{YYYY-MM-DD}.md
- Research requests:
tasks/research/{requesting-agent}-{brief-question}.md
- Research briefs:
tasks/research-done/{request-id}.md
- Skills:
skills/{scope}/{skill-name}/SKILL.md
- Subagent tasks:
tasks/{parent-agent}-sub/{sub-id}.yaml
- Subagent output:
tasks/{parent-agent}-sub/{sub-id}/output.md
- Decision requests:
tasks/decisions/{spec-name}.md
- Builder notes:
tasks/review/{task-name}.builder-notes.md
Project Registration
Projects can live anywhere on disk. Running factory init-project from a project directory writes a .factory marker file pointing to the factory workspace. The CLI resolves upward from cwd to find this marker, so all factory commands work from within registered project directories.
The universe/ Directory
This contains the reference documents the factory was designed from — Attractor specs, context engineering principles, our own synthesis. Any agent can read it. No agent can write to it. Use it to check your work against the source thinking.
