Appendix B: File Reference
Every file Draft generates, organized by directory. For each file: name, purpose, typical size, audience, and lifecycle.
The draft/ directory structure, color-coded by file type: AI-facing context files, human-editable config, internal state tracking, and per-feature track files.
draft/ (Root)
| File | Purpose | Size | Audience | Created | Updated |
|---|---|---|---|---|---|
architecture.md |
Graph-primary high-signal reference. Source of truth for project architecture. Graph Health Dashboard + 9 focused sections with fidelity declarations, provenance on claims, coverage gaps, and relationship to other docs. | 1000-3000 lines | Human & AI | /draft:init |
/draft:init refresh, /draft:decompose |
.ai-context.md |
Token-optimized AI context derived from architecture.md via Condensation Subroutine. Self-contained with 15+ mandatory sections: architecture, invariants, interface contracts, data flows, concurrency rules, error handling, implementation catalogs, testing strategy, glossary. |
200-400 lines | AI | /draft:init |
Auto-refreshed when architecture.md changes |
.ai-profile.md |
Ultra-compact always-injected project profile. Contains: language, framework, database, auth, API style, critical invariants, safety rules, active tracks, recent changes. | 20-50 lines | AI | /draft:init |
Auto-refreshed on mutations |
product.md |
Product vision, target users, success criteria, and guidelines. Defines what the product does and for whom. | 50-150 lines | Human & AI | /draft:init |
Manual edits, /draft:init refresh |
tech-stack.md |
Technology choices: languages, frameworks, databases, key dependencies, and accepted patterns. | 30-100 lines | Human & AI | /draft:init |
Manual edits, /draft:adr (when tech changes) |
workflow.md |
TDD preferences, commit conventions, review process, Jira project key. | 20-60 lines | Human & AI | /draft:init |
Manual edits, /draft:jira create (adds Jira config) |
guardrails.md |
Hard guardrails, learned conventions, and learned anti-patterns. Entries include dual-layer timestamps for temporal reasoning (discovered_at, established_at, last_verified, last_active). | 30-200 lines | AI | /draft:init |
/draft:learn |
tracks.md |
Registry of all tracks with their status, type, and phase progress. | 10-100 lines | Human & AI | /draft:new-track |
/draft:new-track, /draft:implement, /draft:revert |
draft/.state/
Internal state files for incremental refresh, signal classification, and cross-session continuity. Not intended for direct editing.
| File | Purpose | Size | Audience | Created | Updated |
|---|---|---|---|---|---|
freshness.json |
SHA fingerprints of source files. Used to detect changes since last /draft:init run, enabling incremental refresh instead of full re-analysis. |
1-5 KB | AI (internal) | /draft:init |
/draft:init refresh |
signals.json |
Detected signal categories from codebase analysis. Classifies what types of patterns, frameworks, and conventions are present. | 1-5 KB | AI (internal) | /draft:init |
/draft:init refresh |
run-memory.json |
Cross-session continuity data. Records what happened in previous sessions to enable context persistence across agent invocations. | 1-10 KB | AI (internal) | First agent invocation | Each session |
facts.json |
Atomic architectural facts with temporal metadata, source references, confidence scores, and relationship edges. Enables fact-level contradiction detection during refresh. | 1-20 KB | AI (internal) | /draft:init |
/draft:init refresh |
draft/tracks/<track-name>/
Each track (feature, fix, or refactor) gets its own directory with these files:
| File | Purpose | Size | Audience | Created | Updated |
|---|---|---|---|---|---|
spec.md |
Requirements and acceptance criteria for this track. Defines what "done" looks like. Includes functional requirements, edge cases, error scenarios, and explicit non-goals. | 50-200 lines | Human & AI | /draft:new-track |
/draft:change, manual edits |
plan.md |
Phased implementation plan with ordered tasks, verification steps, and status markers ([ ] Pending, [~] In Progress, [x] Completed, [!] Blocked). Each phase has a goal and verification criteria. |
50-300 lines | Human & AI | /draft:new-track |
/draft:implement, /draft:change, /draft:decompose, /draft:revert |
metadata.json |
Track metadata: type (feature/bugfix/refactor), priority, timestamps (created, started, completed), branch name, phase and task counts, progress counters. | 0.5-2 KB | AI | /draft:new-track |
/draft:implement (after each task), /draft:decompose |
Optional Track Files
These files are created by specific commands when run against a track:
| File | Purpose | Created By |
|---|---|---|
architecture.md |
Track-scoped module decomposition with dependency mapping and implementation order | /draft:decompose |
review-report-<timestamp>.md |
Three-stage review findings (validation, spec compliance, code quality) | /draft:review |
bughunt-report-<timestamp>.md |
14-dimension bug discovery results with evidence and fix recommendations | /draft:bughunt |
jira-export-<timestamp>.md |
Jira issue definitions (epic, stories, sub-tasks, bugs) for review and creation | /draft:jira preview |
jira-export-latest.md |
Symlink to the most recent Jira export file | /draft:jira preview |
review-report-latest.md |
Symlink to the most recent review report | /draft:review |
bughunt-report-latest.md |
Symlink to the most recent bughunt report | /draft:bughunt |
validation-report.md |
Track validation results when validation is enabled | /draft:implement |
draft/adrs/
| File | Purpose | Created By |
|---|---|---|
<NNN>-<kebab-case-title>.md |
Architecture Decision Record capturing context, decision, alternatives, and consequences. Numbered sequentially (001, 002, ...). Lifecycle: Proposed → Accepted → Deprecated/Superseded. | /draft:adr |
Monorepo Files (scope-aware /draft:init)
Monorepo federation in Draft uses scope-aware /draft:init rather than a separate index command. Running /draft:init inside a sub-module writes one additional file to that module's draft/graph/ directory:
| File | Purpose | Created By |
|---|---|---|
<module>/draft/graph/root-link.json |
Pointer from a sub-module to the root knowledge graph. Contains the relative path to the root draft/graph/ directory. Enables cross-module queries from within any sub-module without any aggregation step. |
/draft:init (when run inside a sub-module) |
The root-level draft/ directory (created by running /draft:init at the repo root) contains the standard context files (architecture.md, .ai-context.md, .ai-profile.md, product.md, tech-stack.md, workflow.md, guardrails.md) scoped to the whole-repo view, plus the draft/graph/schema.yaml gate marker pointing to the live engine.
Source of Truth Hierarchy
architecture.md is the source of truth. .ai-context.md is derived from it (token-optimized for AI). .ai-profile.md is derived from .ai-context.md (ultra-compact, always loaded). Edits flow downward: update architecture.md, then the derived files are regenerated automatically via the Condensation Subroutine.