Project structure
A governed AgentXchain project has four practical file classes. Knowing which class a path belongs to determines whether it should live in git, stay only on disk, or be treated as short-lived execution residue.
Layer 1: Committed project contract
These files define the repo's product and workflow contract. Commit them and review them like any other product artifact.
| Path | Purpose |
|---|---|
agentxchain.json | Project config: roles, runtimes, phases, gates, workflow kit |
.planning/ | Plans, specs, QA evidence, and human-owned vision artifacts |
| Product code and docs | The repo's actual shipped surface |
Layer 2: Durable framework state (gitignored by default in fresh scaffolds)
These files are still real state. The framework reads and writes them for status, recovery, dashboard views, export/restore, and continuity. Fresh governed scaffolds ignore them by default to keep raw git status focused on project artifacts instead of framework churn.
You can still force-add them if your repo wants git-backed runtime audit history. .gitignore only suppresses new untracked copies; it does not hide files that are already tracked.
| Path | Purpose |
|---|---|
.agentxchain/state.json | Current governed run state: active turns, phase, baselines |
.agentxchain/session.json | Session metadata: run continuity, checkpoints |
.agentxchain/history.jsonl | Completed turn history with results, costs, timing |
.agentxchain/events.jsonl | Lifecycle event log: dispatched, accepted, rejected, escalated |
.agentxchain/decision-ledger.jsonl | Decision records with rationale and evidence |
.agentxchain/repo-decisions.jsonl | Repo-level decision entries |
.agentxchain/run-history.jsonl | Terminal run retrospectives and continuity metadata |
.agentxchain/intake/ | Injected intent records and intake loop state |
.agentxchain/missions/, .agentxchain/multirepo/ | Mission and coordinator runtime state |
.agentxchain/reviews/, .agentxchain/reports/, .agentxchain/proposed/ | Framework-owned review and evidence surfaces |
.agentxchain/SESSION_RECOVERY.md | Human-readable recovery report |
TALK.md | Agent-to-agent handoff log |
HUMAN_TASKS.md | Legacy/operator task surface when present |
Layer 3: Transient execution artifacts (never commit)
These are created during turn dispatch and cleaned up after acceptance. They are scaffolded into .gitignore automatically.
| Path | Purpose | Gitignored? |
|---|---|---|
.agentxchain/staging/ | Turn results waiting for acceptance | Yes |
.agentxchain/dispatch/ | Active dispatch bundles (PROMPT.md, CONTEXT.md) | Yes |
.agentxchain/transactions/ | In-flight transaction state | Yes |
.env | Environment secrets (API keys, tokens) | Yes |
If any of these are missing from your .gitignore, run agentxchain doctor — it will flag the gap.
Layer 4: Planning artifacts (committed, human-owned)
These live in .planning/ and represent the project's design context.
| Path | Purpose |
|---|---|
.planning/VISION.md | Human-owned product vision (AI agents must never modify) |
.planning/PM_SIGNOFF.md | Planning phase gate file |
.planning/ROADMAP.md | Current project roadmap |
.planning/SYSTEM_SPEC.md | System specification |
.planning/*.md | Additional specs, research, decision records |
Key rule: .planning/VISION.md is the canonical source of truth for product direction. AI agents treat it as immutable. If it needs to change, a human changes it directly.
Root-level files
| Path | Purpose | Who owns it |
|---|---|---|
README.md | Public front door for the repo | Shared (human + agents) |
TALK.md | Agent collaboration log (gitignored by default in fresh scaffolds) | Agents |
agentxchain.json | Governed project config | Shared |
.gitignore | Git ignore rules | Shared |
What goes in root vs. .planning/
| Content type | Location | Why |
|---|---|---|
| Product vision | .planning/VISION.md | Protected from agent modification |
| Specs and roadmaps | .planning/*.md | Organized as planning artifacts |
| Public docs and README | Root or docs/ | Visible to repo visitors |
| Governed config | agentxchain.json (root) | Required by the CLI |
| Run state and runtime evidence | .agentxchain/ | Managed by the framework and gitignored by default in fresh scaffolds |
Freshly scaffolded project anatomy
After agentxchain init --governed, your project looks like:
my-project/
├── agentxchain.json # ← commit this
├── .gitignore # ← commit this (pre-configured)
├── TALK.md # ← gitignored by default; force-add only if your repo wants it tracked
├── .agentxchain/
│ ├── state.json # ← gitignored by default, but durable on disk
│ ├── session.json # ← gitignored by default, but durable on disk
│ ├── history.jsonl # ← gitignored by default, but durable on disk
│ ├── events.jsonl # ← gitignored by default, but durable on disk
│ ├── decision-ledger.jsonl # ← gitignored by default, but durable on disk
│ ├── staging/ # ← gitignored (transient)
│ ├── dispatch/ # ← gitignored (transient)
│ └── transactions/ # ← gitignored (transient)
└── .planning/
├── PM_SIGNOFF.md # ← commit this
├── ROADMAP.md # ← commit this
└── SYSTEM_SPEC.md # ← commit this
Rule of thumb: if git status shows a new untracked file under .agentxchain/staging/, .agentxchain/dispatch/, or core runtime-state paths like .agentxchain/state.json, your scaffold .gitignore is incomplete. If git status shows one of those files as modified, the file is already tracked and .gitignore cannot hide it until you explicitly untrack it.