Terrain — prepares the ground so agents don't have to guess where to stand. 🔗 GitHub: https://github.com/sopaco/terrain The Tech Lead's Pain: Documentation as Technical Debt As a Tech Lead, you've definitely experienced: Architecture docs that took two weeks to write become unrecognizable after one iteration Every code review requires explaining "that's not how it's actually designed anymore" When newcomers ask "how is this system organized?" you can only answer verbally because the Wiki is long outdated When you ask a new AI assistant to explain the system architecture, it can only guess from the code Once architecture docs drift from code, they become liabilities—worse than having no docs at all. Terrain's solution: let documentation emerge from code automatically, instead of being manually written from memory. Knowledge Factory: Code as the Source of Documentation Terrain's core is a "knowledge factory"—starting from a Git repository, it auto-generates three layers of documentation: Git Code Repository │ ├── scan ──► index.md (Project Index) │ ├── pack ──► repomix.md (Source Index) │ ├── context (LLM) ──► agent/context.md (Agent Macro Architecture Context) │ ├── docs (ACP) ──► human/ (Five C4 Architecture Docs + Mermaid Diagrams) │ └── track ──► freshness.json (Freshness Score) Five C4 architecture documents auto-generated, covering all levels from containers to code, with Mermaid diagrams. Why Can It Stay "Always in Sync"? Incremental Updates Instead of Full Regeneration Traditional documentation tools regenerate everything each time. Terrain doesn't: Tracks Git HEAD — Precisely knows which files changed since the last scan. Only regenerates changed portions — Changes involve a module → update corresponding C4 doc; unrelated modules → reuse existing artifacts. Baseline ledger — Records the Git HEAD for each scan; subsequent refreshes do incremental diffs only. This means refreshing knowledge for a large project might take seconds instead of minutes. Freshness Scoring System Every knowledge asset carries a freshness score, based on: Git code change volume vs. documentation's last generation time CodeGraph symbol graph drift detection results When the score drops below 50, Agents automatically reduce the weight of that knowledge asset—ensuring incorrect suggestions are never made based on outdated architectural information. The project list interface clearly displays each project's freshness score. Stale assets are instantly visible. Dual-Track Output: Human-Readable, AI-Consumable Audience Document Path Format Human Developers / Tech Leads .terrain/human/ Narrative C4 docs + Mermaid diagrams AI Coding Assistants .terrain/agent/context.md Structured architecture overview (≤ 14 KiB) AI Source Retrieval .terrain/agent/repomix.md Repomix source packs Business Knowledge .terrain/knowledge/ Glossary and internal conventions C4 docs cover four levels: Container → Component → Code → Dynamic, paired with Mermaid diagrams, unfolding layer by layer from macro architecture to micro implementation. Source-First Trust Model When documentation conflicts with code, Terrain follows clear priority: repomix source code > CodeGraph symbol graph > context.md > human docs This isn't empty talk—repomix packages real source code, CodeGraph indexes real symbol relationships. Architecture docs are just "visual interpretations" of source code. When interpretation conflicts with source, source code is always right. Four-Phase SDD: Making Design Reviewable Terrain's SDD (Specification-Driven Development) workflow divides development into four phases, each producing reviewable Markdown artifacts: Phase Output Execution Engine Requirements Analysis 1.requirements.md Native LLM Technical Design 2.tech-design.md Native LLM Code Generation 3.implementation.md + repo changes ACP Agent Code Review 4.code-review.md Native LLM SDD four-phase workflow. Each phase produces reviewable Markdown artifacts that Tech Leads can examine step by step. This means Tech Leads can: Review whether requirements specifications are accurate Examine whether technical design is reasonable Confirm whether code generation matches the design Verify whether code review is thorough Every step is documented and traceable. Every step is reviewable. Quick Start # Initialize a project (auto-generate C4 docs and Agent context) terrain init ./my-repo # View architecture overview terrain project overview --project my-repo # Run SDD requirements analysis phase terrain sdd run --project my-repo --phase requirements # Refresh knowledge (incremental, only update changed parts) terrain refresh ./my-repo Who Is This For? Tech Leads — Architecture docs never go stale, always in sync with code. Architects — C4 docs auto-generated from code, eliminating massive maintenance overhead. Team Managers — New member onboarding compressed from days to minutes. Code Reviewers — SDD workflow makes every design step traceable and reviewable. "Great architecture isn't written—it grows from code."