File Structure

Aigon stores workflow state as local files. Human-readable specs live in your repository under docs/specs/; the authoritative feature/research lifecycle is the workflow-core event log and snapshot under .aigon/workflows/.

Core principles

Engine-first lifecycle: feature and research status comes from workflow-core snapshots; folders are the committed projection users can inspect.
Decoupled Lifecycles: Research explores what to build; Features define how to build it
Traceable History: workflow events, snapshots, telemetry, specs, and logs stay on disk in the repo checkout.

Directory layout


your-repo/
├── .agents/              # Codex Skills (.agents/skills/aigon-*/SKILL.md)
├── .aigon/               # Local runtime state + Aigon-owned docs (mostly gitignored)
├── .claude/              # Claude Code config + aigon commands
├── .codex/               # Codex config (config.toml only)
├── .cursor/              # Cursor config + aigon commands
├── .gemini/              # Gemini CLI config + aigon commands
├── .githooks/            # Git hooks (merge gate scanning)
├── docs/
│   └── specs/
│       ├── features/     # Delivery pipeline
│       │   ├── 01-inbox/
│       │   ├── 02-backlog/
│       │   ├── 03-in-progress/
│       │   ├── 04-in-evaluation/
│       │   ├── 05-done/
│       │   ├── 06-paused/
│       │   ├── evaluations/
│       │   └── logs/
│       ├── research-topics/  # Discovery pipeline
│       │   ├── 01-inbox/
│       │   ├── 02-backlog/
│       │   ├── 03-in-progress/
│       │   ├── 04-in-evaluation/
│       │   ├── 05-done/
│       │   ├── 06-paused/
│       │   └── logs/
│       └── feedback/     # Triage pipeline
│           ├── 01-inbox/
│           ├── 02-triaged/
│           ├── 03-actionable/
│           ├── 04-done/
│           ├── 05-wont-fix/
│           └── 06-duplicate/
├── AGENTS.md             # Optional user-owned shared agent orientation
└── CLAUDE.md             # Optional user-owned Claude Code instructions

Lifecycle folders (Kanban)

Features & Research

Folder	Purpose
`01-inbox/`	New, unprioritised items
`02-backlog/`	Prioritised, assigned an ID
`03-in-progress/`	Currently being worked on
`04-in-evaluation/`	Submitted, pending evaluation (Fleet)
`05-done/`	Merged and complete
`06-paused/`	Temporarily on hold

Feedback

Folder	Purpose
`01-inbox/`	New, unreviewed feedback
`02-triaged/`	Classified and validated
`03-actionable/`	Ready to promote to a feature or research topic
`04-done/`	Resolved
`05-wont-fix/`	Acknowledged, not actioned
`06-duplicate/`	Duplicate of an existing item

Supporting files

.aigon/docs/ — Aigon-installed operational docs, including development_workflow.md and agents/<id>.md
.aigon/install-manifest.json — manifest of Aigon-owned installed files
logs/ — implementation logs (selected winners + alternatives)
evaluations/ — Fleet comparison reports

Naming conventions

Stage	Pattern	Example
Draft (inbox)	`feature-description.md`	`feature-dark-mode.md`
Prioritised	`feature-{ID}-description.md`	`feature-55-dark-mode.md`
Agent-specific (Fleet)	`feature-{ID}-{agent}-description-log.md`	`feature-55-cc-dark-mode-log.md`

State machine

Feature and research specs transition through workflow-core. Events are appended to .aigon/workflows/<type>/<id>/events.jsonl; snapshots are derived from those events; the XState machine validates lifecycle transitions and derives valid actions.

All transitions should go through Aigon commands or dashboard actions. Do not move spec files manually to change state; that creates folder/snapshot drift. If drift appears, run aigon doctor --fix.

The `.aigon/` directory

Local runtime state lives in .aigon/ (gitignored). Spec folders in docs/specs/ are the committed, human-readable view; .aigon/ is the engine underneath.

Path	Purpose
`.aigon/config.json`	Project-level configuration
`.aigon/docs/`	Aigon-owned docs installed into consumer projects
`.aigon/install-manifest.json`	Tracks Aigon-owned installed files
`.aigon/state/feature-{id}-{agent}.json`	Per-agent status files (heartbeat, session metadata)
`.aigon/workflows/features/{id}/events.jsonl`	Append-only workflow event log
`.aigon/workflows/features/{id}/snapshot.json`	Derived workflow snapshot
`.aigon/telemetry/`	Normalised per-session telemetry records (agent, model, tokens, cost, duration)
`.aigon/cache/`	Cached data (e.g. `commits.json` for commit analytics)

Run aigon doctor --fix to detect and repair desyncs between spec folders and engine state.

The complete lifecycle loop

Forward traceability: “Feature #108 addresses feedback #42 and was informed by research #07”

Backward traceability: “Feedback #42 resulted in feature #108, shipped in v2.1”