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 Root Files (from /draft:index)
Generated at the monorepo root level when /draft:index aggregates service contexts:
| File | Purpose |
|---|---|
draft/service-index.md |
Directory of all detected services with status, tech stack, dependencies, and team ownership |
draft/dependency-graph.md |
Inter-service dependency mapping with Mermaid topology and topological ordering |
draft/tech-matrix.md |
Technology distribution across services with organizational standards and variances |
draft/config.yaml |
Index configuration: service detection patterns, exclusions, re-index triggers |
draft/bughunt-summary.md |
Aggregate bughunt results across services (created by /draft:index bughunt) |
<service>/draft/manifest.json |
Per-service metadata: name, type, summary, primary tech, dependencies, dependents, team, timestamps |
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.