[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M758NWVG263HMHW3DM27RJ3G":3,"skill-same:01M758NWVG263HMHW3DM27RJ3G":52},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M758NWVG263HMHW3DM27RJ3G","context-architecture",null,"Progressive disclosure architecture for organizing project context as a DAG (directed acyclic graph).\nAgents enter at the root and traverse only the subgraph relevant to their task.\nCovers the 4-tier information flow (refs → kits → plans → impl), CLAUDE.md hierarchy\nacross context\u002F and source tree, index files as DAG hub nodes, nesting rules, and backward compatibility.\nTrigger phrases: \"context architecture\", \"progressive disclosure\", \"organize context for agents\",\n\"context directory structure\", \"how to structure docs for AI\", \"context hierarchy\"","davidcoachdev\u002Fdcfiles","davidcoachdev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F69812733?v=4","01M758C4BR16TAV1N47W319E9V","David H. Caycedo Blum.","01M758C4CCZA2ZYGA0BGMXCDRH",1,"MIT","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fcontext-architecture\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: context-architecture\ndescription: |\n  Progressive disclosure architecture for organizing project context as a DAG (directed acyclic graph).\n  Agents enter at the root and traverse only the subgraph relevant to their task.\n  Covers the 4-tier information flow (refs → kits → plans → impl), CLAUDE.md hierarchy\n  across context\u002F and source tree, index files as DAG hub nodes, nesting rules, and backward compatibility.\n  Trigger phrases: \"context architecture\", \"progressive disclosure\", \"organize context for agents\",\n  \"context directory structure\", \"how to structure docs for AI\", \"context hierarchy\"\n---\n\n# Context Architecture: DAG-Based Progressive Disclosure\n\n## Core Principle\n\n**Agents should only read what they need.** Documents are organized as a directed acyclic graph (DAG) where index files act as hub nodes. An agent reads the index, identifies relevant edges, and follows only those to leaf documents. No agent ever loads the full tree.\n\n---\n\n## The 4-Tier Information Flow\n\n```\nrefs\u002F (what IS)  -->  kits\u002F (what MUST BE)  -->  plans\u002F (HOW)  -->  impl\u002F (what WAS DONE)\n     Tier 1                  Tier 2                     Tier 3              Tier 4\n```\n\nEach tier consumes the previous tier's output. Cross-references between tiers create the DAG edges that agents traverse.\n\n---\n\n## The Second Axis: Knowledge Stability\n\nThe 4-tier flow above answers **\"where did this knowledge come from?\"**. It does not answer **\"how fast does it rot?\"**. These are orthogonal axes — a `refs\u002F` document and an `impl\u002F` document can each be stable or volatile.\n\nClassify every piece of project knowledge on the stability axis as well:\n\n| Tier | Knowledge | Cadence | Budget | Owner |\n|------|-----------|---------|--------|-------|\n| **S0** | Essence — what the project is, why it exists, who it serves | Quarterly \u002F major version | ~500 tk | `sdd-init` |\n| **S1** | Architecture — components, data flow, patterns | Monthly \u002F sprint | ~1000 tk | `sdd-init`, `architecture-intelligence` |\n| **S2** | Decisions — tradeoffs and their rationale | Per decision | ~800 tk | `ck:adr` (canonical) |\n| **S3** | Dynamics — active issues, standing constraints, workarounds | As they arise | ~600 tk | graduated from `ck:impl-tracking` |\n\n**Total budget: ~2,900 tokens.** Loading the entire project knowledge base should cost under 3k. Exceeding a tier's budget is a signal to split or prune — never to expand the budget.\n\n### Never write a bare \"Tier N\"\n\nFlow tiers are `1-4`. Stability tiers are `S0-S3`. \"Tier 2\" is ambiguous — it means `kits\u002F` on one axis and decisions on the other. Always qualify: **\"Tier 2 (kits)\"** or **\"S2 (decisions)\"**.\n\n### Where each tier lives\n\nThe `artifact_store` mode chosen at SDD preflight decides persistence — do not introduce a separate switch:\n\n| Mode | S0 \u002F S1 \u002F S3 | S2 |\n|------|--------------|-----|\n| `engram` | topic_keys only | pointer to `docs\u002Fadr\u002F` |\n| `openspec` | files under `openspec\u002F` | `docs\u002Fadr\u002F` |\n| `hybrid` | files canonical, Engram as decaying index | `docs\u002Fadr\u002F` + Engram pointer |\n\nEngram topic_keys and their decay:\n\n```\nS0  sdd-init\u002F{project}                review_after: quarterly\nS1  architecture\u002F{project}\u002Foverview   review_after: monthly\nS2  → docs\u002Fadr\u002Findex.md               (file-canonical, pointer only)\nS3  dynamics\u002F{project}\u002Factive         review_after: short\n```\n\n**S2 is always file-canonical.** ADRs get reviewed in pull requests; Engram holds a pointer, never a copy. Duplicating ADR content into `context\u002F` guarantees drift.\n\n### Static knowledge complements exploration — it does not replace it\n\nWrite S0-S3 to help an agent orient faster, not to describe everything. If an agent can learn it in one `grep`, it does not belong here. The test: **would a competent new contributor still be confused after reading the code?** If no, leave it out.\n\n---\n\n## Operating the Knowledge Tiers\n\n### Session-start protocol (ported from Litho's `.ai-context`)\nOn any session that touches a project, an agent should:\n1. Read **S0** (`PROJECT-ESSENCE` \u002F `sdd-init\u002F{project}`) — always.\n2. Scan **S3** (`DYNAMICS` \u002F `dynamics\u002F{project}\u002Factive`) for active issues and standing constraints.\n3. Read **S1** (`ARCHITECTURE`) only when working across components.\n4. Read **S2** (`DECISIONS` \u002F `docs\u002Fadr`) only when changing established patterns.\n\nReading order: **S0 → S1 → S2 → S3**. Activate the full base when starting a session, hitting unfamiliar code\u002Farchitecture, planning structural changes, or debugging unexpected behavior. Do **not** activate for simple mechanical edits with clear context.\n\n### Tier Drift Audit & S3 Stale Audit (ported from Litho's `check-drift` \u002F `audit-dynamics`)\nKnowledge rots. Run periodically (monthly recommended) or before a release:\n- **Drift audit** — verify each tier still matches reality: S0\u002FS1 reflect the current stack and architecture; S2 entries match actual `docs\u002Fadr`; S3 items are still true. Mismatch = stale tier → refresh or delete.\n- **S3 stale audit** — flag any S3 item whose `review_after` passed without re-validation. A standing constraint that silently expired is worse than none. If still true, bump the date; if resolved, move it to \"Recently Resolved\".\n\nThese procedures operationalize the `review_after` decay above — decay without an audit is just forgotten knowledge.\n\n### Scaling knowledge discovery (ported from Litho's `litho-documents-skill`)\nScale the scan to project size to avoid context bloat:\n\n| Size | Criterion | Strategy |\n|------|-----------|----------|\n| Small | \u003C100 source files | README + entry points + config; list dirs |\n| Medium | 100–500 files | README + entry + config + semantic search for concepts |\n| Large | >500 files | README + main config + entry outline + targeted grep; delegate deep reads to sub-agents |\n\nPersist intermediate findings to Engram (or a temp `.litho-agent\u002F`-style dir) so long analyses don't lose data to context pressure. Use progressive depth: analyze core modules deeply, supporting modules standard, generic modules briefly.\n\n### Tier templates\nMinimal starting shapes (full versions: Litho's `ai-context-generator\u002Ftemplates`):\n- **S0 PROJECT-ESSENCE** — What \u002F Why \u002F Who \u002F Key features \u002F Core constraints.\n- **S1 ARCHITECTURE** — system diagram (produce it with the `c4-architecture` skill) + component responsibilities + data flow + key dependencies + patterns.\n- **S2 DECISIONS (ADR)** — non-obvious choice + trade-off + constraints accepted + revisit condition.\n- **S3 DYNAMICS** — see `ck:impl-tracking` graduation format (Quick Scan + Active Issues + Known Constraints + Recently Resolved).\n\n---\n\n## Directory Layout\n\n```\ncontext\u002F\n├── CLAUDE.md                              # Root entry node: describes all tiers + design layer\n├── refs\u002F                                  # Tier 1: Source material (read-only input)\n│   ├── CLAUDE.md                          # \"Source of truth. Organized by source. Read-only.\"\n│   └── {source}\u002F                          # Subdirs per source (e.g., prd\u002F, api-spec\u002F)\n│       └── ...\n├── kits\u002F                            # Tier 2: WHAT to build\n│   ├── CLAUDE.md                          # \"Start at cavekit-overview.md. R-numbered reqs.\"\n│   ├── cavekit-overview.md              # Index node (DAG hub)\n│   ├── cavekit-{domain}.md              # Leaf — simple domain (single file)\n│   └── {domain}\u002F                          # Complex domain gets a subdirectory\n│       ├── cavekit-{domain}.md          # Domain index (becomes hub node)\n│       └── cavekit-{domain}-{sub}.md    # Sub-domain leaves\n├── designs\u002F                               # Cross-cutting: visual design system\n│   ├── CLAUDE.md                          # \"DESIGN.md at project root is canonical.\"\n│   └── design-changelog.md               # Append-only change log\n├── plans\u002F                                 # Tier 3: HOW to build (task graphs)\n│   ├── CLAUDE.md                          # \"Start at plan-overview.md. Task dependency tiers.\"\n│   ├── plan-overview.md                   # Index node\n│   ├── build-site.md                      # Primary build site\n│   ├── build-site-{feature}.md            # Feature-specific build sites\n│   └── {domain}\u002F                          # Complex plans get subdirectories\n│       └── plan-{domain}-{area}.md\n├── impl\u002F                                  # Tier 4: What WAS DONE\n│   ├── CLAUDE.md                          # \"Start at impl-overview.md. Update after every session.\"\n│   ├── impl-overview.md                   # Index node\n│   ├── impl-{domain}.md                   # Per-domain tracking\n│   ├── impl-review-findings.md            # Codex review findings ledger\n│   ├── dead-ends.md                       # Failed approaches (shared across domains)\n│   └── archive\u002F                           # Compacted\u002Farchived tracking\n```\n\n> **Note:** `designs\u002F` is a **cross-cutting constraint layer**, not a fifth tier. DESIGN.md (at project root) is read by agents at every Hunt phase — Draft reads it to constrain visual decisions, Architect references tokens in task descriptions, Build uses it for implementation, Inspect validates against it. It parallels how CLAUDE.md files provide conventions, but for visual design.\n\n### Backward Compatibility: sites\u002F → plans\u002F\n\nBuild sites previously lived in `context\u002Fsites\u002F`. All Cavekit commands check both locations:\n\n1. Look in `context\u002Fplans\u002F`\n2. If not found, fall back to `context\u002Fsites\u002F`\n3. If found in `sites\u002F`, use it — no auto-migration, no breakage\n\n`\u002Fck:init` offers optional migration. Declining is permanent — the system works with either layout.\n\n---\n\n## CLAUDE.md Hierarchy\n\n### Scope: Full Repository\n\n`CLAUDE.md` files extend beyond `context\u002F` into the source code tree. They form the connective tissue between code and the context DAG.\n\n```\nproject\u002F\n├── CLAUDE.md                          # Project root: build\u002Ftest commands,\n│                                      #   \"context\u002F has the full hierarchy\"\n├── context\u002F\n│   ├── CLAUDE.md                      # Root context node: 4 tiers described\n│   ├── refs\u002FCLAUDE.md                 # Tier 1 conventions\n│   ├── kits\u002FCLAUDE.md           # Tier 2 conventions\n│   ├── plans\u002FCLAUDE.md                # Tier 3 conventions\n│   └── impl\u002FCLAUDE.md                 # Tier 4 conventions\n│\n├── src\u002F\n│   ├── CLAUDE.md                      # Source code conventions\n│   ├── auth\u002F\n│   │   ├── CLAUDE.md                  # \"implements cavekit-auth.md R1-R3\"\n│   │   └── ...\n│   └── parser\u002F\n│       ├── CLAUDE.md                  # \"implements cavekit-grammar.md R1-R4,\n│       │                              #   see plans\u002Fbuild-site.md T-012 through T-018\"\n│       └── ...\n│\n├── tests\u002F\n│   ├── CLAUDE.md                      # Test conventions, how to run\n│   └── ...\n└── scripts\u002F\n    ├── CLAUDE.md                      # Utility script conventions\n    └── ...\n```\n\n### Loading Behavior\n\nWhen an agent works in `src\u002Fauth\u002F`, it loads hierarchically:\n1. `project\u002FCLAUDE.md` — project-level conventions\n2. `project\u002Fsrc\u002FCLAUDE.md` — source code conventions\n3. `project\u002Fsrc\u002Fauth\u002FCLAUDE.md` — **\"implements cavekit-auth.md R1-R3\"**\n\nThe third file bridges to the context DAG. The agent knows which cavekit to load without loading the entire `context\u002Fkits\u002F` directory.\n\n### CLAUDE.md Design Principles\n\n- **Minimal** — 3-10 lines for source-tree files. Never duplicate cavekit content.\n- **Connective** — each one names the cavekit requirements and plan tasks it relates to.\n- **Contextual** — includes module-specific conventions (error handling patterns, test fixture locations).\n- **Honest** — `\u002Fck:make` only writes mappings it is certain about (tasks it completed, files it created).\n\n---\n\n## Progressive Disclosure: The DAG Traversal\n\n### How Agents Navigate\n\n1. **Enter at root** — read `context\u002FCLAUDE.md` to understand the 4 tiers\n2. **Select tier** — based on current task, navigate to the relevant tier's `CLAUDE.md`\n3. **Read index** — the tier's overview file is the DAG hub, listing all domains with one-line summaries\n4. **Follow edges** — read only the domain files relevant to the current task\n5. **Cross-reference** — if a domain references another, follow that edge only if needed\n6. **Nest deeper** — if a domain has subdirectories, its root file is the sub-index; spider from there\n\n### Index File Format\n\nEvery overview file follows the same format:\n\n```markdown\n# Cavekit Overview\n\n| Domain | File | Summary | Status |\n|--------|------|---------|--------|\n| Authentication | cavekit-auth.md | Registration, login, sessions, OAuth | DRAFT |\n| Data Models | cavekit-data-models.md | Core entities, relationships, validation | DRAFT |\n| Type System | cavekit-type-system.md | Effects lattice, tagged values (see type-system\u002F) | DRAFT |\n```\n\nAn agent reads this table, identifies \"I need Authentication,\" and loads only `cavekit-auth.md`.\n\n### Cross-Reference Edges\n\n```markdown\n**Dependencies:** cavekit-auth.md R2 (session tokens required for API auth)\n**See also:** cavekit-api.md R4 (rate limiting uses auth identity)\n```\n\nAgents follow these only when the cross-referenced content is needed for the current task.\n\n---\n\n## Nesting Rule\n\nA domain stays flat (single file) by default. When a file covers multiple independent concerns that could be understood separately, it becomes an index file pointing to a subdirectory.\n\n**Trigger:** Cohesion, not line count. If a file has sections that an agent working on one section would never need to read the others, decompose it.\n\n**Example:** `cavekit-type-system.md` covers effects lattice, tagged values, and inference rules:\n\n```\nkits\u002F\n├── cavekit-type-system.md                        # Now an index\n└── type-system\u002F\n    ├── cavekit-type-system-effects.md\n    ├── cavekit-type-system-tagged.md\n    └── cavekit-type-system-inference.md\n```\n\nThe original file stays in place as the index — no reference breakage.\n\n---\n\n## Backpropagation via CLAUDE.md\n\nWhen a bug is found, source-tree CLAUDE.md files provide the reverse traversal:\n\n```\nBug in src\u002Fauth\u002Flogin.ts\n    |\n    v\nsrc\u002Fauth\u002FCLAUDE.md says \"implements cavekit-auth.md R2\"\n    |\n    v\ncavekit-auth.md R2 — check acceptance criteria\n    |\n    |-- Criteria missing?  --> update cavekit (spec gap)\n    |-- Criteria wrong?    --> fix cavekit (spec bug)\n    |-- Criteria present but code violates? --> fix code (impl bug)\n    |\n    v\nIf cavekit changed --> propagate to plans\u002F --> flag affected tasks\n```\n\n### Forward Propagation\n\nWhen a cavekit changes via `\u002Fck:revise`:\n1. Scan all `src\u002F*\u002FCLAUDE.md` files for references to the changed requirement\n2. Flag those modules as potentially affected\n3. New requirements with no source-tree CLAUDE.md references are unimplemented\n\n---\n\n## Bootstrapping\n\nRun `\u002Fck:init` to create the full hierarchy. It:\n1. Scans existing project structure\n2. Creates context directories (refs\u002F, kits\u002F, plans\u002F, impl\u002F)\n3. Creates CLAUDE.md files using standard templates\n4. Creates empty index files (cavekit-overview.md, plan-overview.md, impl-overview.md)\n5. Offers migration if legacy `context\u002Fsites\u002F` exists\n\nProperties: idempotent, non-destructive, no questions asked.\n\n---\n\n## Build-Time Updates\n\nAfter `\u002Fck:make` completes, source-tree CLAUDE.md files are generated\u002Fupdated:\n- New source directories get a CLAUDE.md with cavekit\u002Fplan references\n- Existing CLAUDE.md files get new references appended (never removed)\n- `impl-overview.md` and `plan-overview.md` are updated with current status\n\n---\n\n## Multi-Repo Strategy\n\nFor shared kits across implementations, use git submodules:\n\n```\nTier 1-2 (shared): shared-context\u002F (submodule)\n    └── refs\u002F + kits\u002F\n\nTier 3-4 (per-repo): context\u002F\n    └── plans\u002F + impl\u002F\n```\n\nEach framework repo includes the shared context as a submodule. Updates propagate via `git submodule update`.\n\n---\n\n## Integration with Other Skills\n\n| Skill | Integration |\n|-------|------------|\n| `ck:cavekit-writing` | Kits go in `context\u002Fkits\u002F` following naming conventions |\n| `ck:design-system` | DESIGN.md lives at project root; `context\u002Fdesigns\u002F` has CLAUDE.md and changelog |\n| `ck:impl-tracking` | Tracking lives in `context\u002Fimpl\u002F`, compacted when exceeding ~500 lines |\n| `ck:validation-first` | Validation results recorded in impl tracking within the hierarchy |\n| `ck:revision` | `\u002Fck:revise` traverses CLAUDE.md edges in reverse to trace bugs to specs |\n| `c4-architecture` | Generates the 4-level C4 model; diagrams populate the S1 (ARCHITECTURE) tier via `ctx_index(source: \"architecture\")` |\n| `ck:methodology` | Context structure established during Draft phase, maintained throughout the Hunt |\n\n---\n\n## Anti-Patterns\n\n| Anti-Pattern | Why It's Wrong | Fix |\n|-------------|---------------|-----|\n| Flat file dump | No progressive disclosure, agents load everything | Use standard directory structure with indexes |\n| Missing CLAUDE.md files | No convention guidance, no DAG edges | Run `\u002Fck:init` or add manually |\n| Monolithic documents | Defeats progressive disclosure | Decompose into domains with overview indexes |\n| Stale archives in active dirs | Wastes context window | Move to `impl\u002Farchive\u002F` |\n| Duplicating cavekit content in CLAUDE.md | Content drifts, double maintenance | CLAUDE.md files only contain references |\n","# Context Architecture: DAG-Based Progressive Disclosure\n\n## Core Principle\n\n**Agents should only read what they need.** Documents are organized as a directed acyclic graph (DAG) where index files act as hub nodes. An agent reads the index, identifies relevant edges, and follows only those to leaf documents. No agent ever loads the full tree.\n\n---\n\n## The 4-Tier Information Flow\n\n```\nrefs\u002F (what IS)  -->  kits\u002F (what MUST BE)  -->  plans\u002F (HOW)  -->  impl\u002F (what WAS DONE)\n     Tier 1                  Tier 2                     Tier 3              Tier 4\n```\n\nEach tier consumes the previous tier's output. Cross-references between tiers create the DAG edges that agents traverse.\n\n---\n\n## The Second Axis: Knowledge Stability\n\nThe 4-tier flow above answers **\"where did this knowledge come from?\"**. It does not answer **\"how fast does it rot?\"**. These are orthogonal axes — a `refs\u002F` document and an `impl\u002F` document can each be stable or volatile.\n\nClassify every piece of project knowledge on the stability axis as well:\n\n| Tier | Knowledge | Cadence | Budget | Owner |\n|------|-----------|---------|--------|-------|\n| **S0** | Essence — what the project is, why it exists, who it serves | Quarterly \u002F major version | ~500 tk | `sdd-init` |\n| **S1** | Architecture — components, data flow, patterns | Monthly \u002F sprint | ~1000 tk | `sdd-init`, `architecture-intelligence` |\n| **S2** | Decisions — tradeoffs and their rationale | Per decision | ~800 tk | `ck:adr` (canonical) |\n| **S3** | Dynamics — active issues, standing constraints, workarounds | As they arise | ~600 tk | graduated from `ck:impl-tracking` |\n\n**Total budget: ~2,900 tokens.** Loading the entire project knowledge base should cost under 3k. Exceeding a tier's budget is a signal to split or prune — never to expand the budget.\n\n### Never write a bare \"Tier N\"\n\nFlow tiers are `1-4`. Stability tiers are `S0-S3`. \"Tier 2\" is ambiguous — it means `kits\u002F` on one axis and decisions on the other. Always qualify: **\"Tier 2 (kits)\"** or **\"S2 (decisions)\"**.\n\n### Where each tier lives\n\nThe `artifact_store` mode chosen at SDD preflight decides persistence — do not introduce a separate switch:\n\n| Mode | S0 \u002F S1 \u002F S3 | S2 |\n|------|--------------|-----|\n| `engram` | topic_keys only | pointer to `docs\u002Fadr\u002F` |\n| `openspec` | files under `openspec\u002F` | `docs\u002Fadr\u002F` |\n| `hybrid` | files canonical, Engram as decaying index | `docs\u002Fadr\u002F` + Engram pointer |\n\nEngram topic_keys and their decay:\n\n```\nS0  sdd-init\u002F{project}                review_after: quarterly\nS1  architecture\u002F{project}\u002Foverview   review_after: monthly\nS2  → docs\u002Fadr\u002Findex.md               (file-canonical, pointer only)\nS3  dynamics\u002F{project}\u002Factive         review_after: short\n```\n\n**S2 is always file-canonical.** ADRs get reviewed in pull requests; Engram holds a pointer, never a copy. Duplicating ADR content into `context\u002F` guarantees drift.\n\n### Static knowledge complements exploration — it does not replace it\n\nWrite S0-S3 to help an agent orient faster, not to describe everything. If an agent can learn it in one `grep`, it does not belong here. The test: **would a competent new contributor still be confused after reading the code?** If no, leave it out.\n\n---\n\n## Operating the Knowledge Tiers\n\n### Session-start protocol (ported from Litho's `.ai-context`)\nOn any session that touches a project, an agent should:\n1. Read **S0** (`PROJECT-ESSENCE` \u002F `sdd-init\u002F{project}`) — always.\n2. Scan **S3** (`DYNAMICS` \u002F `dynamics\u002F{project}\u002Factive`) for active issues and standing constraints.\n3. Read **S1** (`ARCHITECTURE`) only when working across components.\n4. Read **S2** (`DECISIONS` \u002F `docs\u002Fadr`) only when changing established patterns.\n\nReading order: **S0 → S1 → S2 → S3**. Activate the full base when starting a session, hitting unfamiliar code\u002Farchitecture, planning structural changes, or debugging unexpected behavior. Do **not** activate for simple mechanical edits with clear context.\n\n### Tier Drift Audit & S3 Stale Audit (ported from Litho's `check-drift` \u002F `audit-dynamics`)\nKnowledge rots. Run periodically (monthly recommended) or before a release:\n- **Drift audit** — verify each tier still matches reality: S0\u002FS1 reflect the current stack and architecture; S2 entries match actual `docs\u002Fadr`; S3 items are still true. Mismatch = stale tier → refresh or delete.\n- **S3 stale audit** — flag any S3 item whose `review_after` passed without re-validation. A standing constraint that silently expired is worse than none. If still true, bump the date; if resolved, move it to \"Recently Resolved\".\n\nThese procedures operationalize the `review_after` decay above — decay without an audit is just forgotten knowledge.\n\n### Scaling knowledge discovery (ported from Litho's `litho-documents-skill`)\nScale the scan to project size to avoid context bloat:\n\n| Size | Criterion | Strategy |\n|------|-----------|----------|\n| Small | \u003C100 source files | README + entry points + config; list dirs |\n| Medium | 100–500 files | README + entry + config + semantic search for concepts |\n| Large | >500 files | README + main config + entry outline + targeted grep; delegate deep reads to sub-agents |\n\nPersist intermediate findings to Engram (or a temp `.litho-agent\u002F`-style dir) so long analyses don't lose data to context pressure. Use progressive depth: analyze core modules deeply, supporting modules standard, generic modules briefly.\n\n### Tier templates\nMinimal starting shapes (full versions: Litho's `ai-context-generator\u002Ftemplates`):\n- **S0 PROJECT-ESSENCE** — What \u002F Why \u002F Who \u002F Key features \u002F Core constraints.\n- **S1 ARCHITECTURE** — system diagram (produce it with the `c4-architecture` skill) + component responsibilities + data flow + key dependencies + patterns.\n- **S2 DECISIONS (ADR)** — non-obvious choice + trade-off + constraints accepted + revisit condition.\n- **S3 DYNAMICS** — see `ck:impl-tracking` graduation format (Quick Scan + Active Issues + Known Constraints + Recently Resolved).\n\n---\n\n## Directory Layout\n\n```\ncontext\u002F\n├── CLAUDE.md                              # Root entry node: describes all tiers + design layer\n├── refs\u002F                                  # Tier 1: Source material (read-only input)\n│   ├── CLAUDE.md                          # \"Source of truth. Organized by source. Read-only.\"\n│   └── {source}\u002F                          # Subdirs per source (e.g., prd\u002F, api-spec\u002F)\n│       └── ...\n├── kits\u002F                            # Tier 2: WHAT to build\n│   ├── CLAUDE.md                          # \"Start at cavekit-overview.md. R-numbered reqs.\"\n│   ├── cavekit-overview.md              # Index node (DAG hub)\n│   ├── cavekit-{domain}.md              # Leaf — simple domain (single file)\n│   └── {domain}\u002F                          # Complex domain gets a subdirectory\n│       ├── cavekit-{domain}.md          # Domain index (becomes hub node)\n│       └── cavekit-{domain}-{sub}.md    # Sub-domain leaves\n├── designs\u002F                               # Cross-cutting: visual design system\n│   ├── CLAUDE.md                          # \"DESIGN.md at project root is canonical.\"\n│   └── design-changelog.md               # Append-only change log\n├── plans\u002F                                 # Tier 3: HOW to build (task graphs)\n│   ├── CLAUDE.md                          # \"Start at plan-overview.md. Task dependency tiers.\"\n│   ├── plan-overview.md                   # Index node\n│   ├── build-site.md                      # Primary build site\n│   ├── build-site-{feature}.md            # Feature-specific build sites\n│   └── {domain}\u002F                          # Complex plans get subdirectories\n│       └── plan-{domain}-{area}.md\n├── impl\u002F                                  # Tier 4: What WAS DONE\n│   ├── CLAUDE.md                          # \"Start at impl-overview.md. Update after every session.\"\n│   ├── impl-overview.md                   # Index node\n│   ├── impl-{domain}.md                   # Per-domain tracking\n│   ├── impl-review-findings.md            # Codex review findings ledger\n│   ├── dead-ends.md                       # Failed approaches (shared across domains)\n│   └── archive\u002F                           # Compacted\u002Farchived tracking\n```\n\n> **Note:** `designs\u002F` is a **cross-cutting constraint layer**, not a fifth tier. DESIGN.md (at project root) is read by agents at every Hunt phase — Draft reads it to constrain visual decisions, Architect references tokens in task descriptions, Build uses it for implementation, Inspect validates against it. It parallels how CLAUDE.md files provide conventions, but for visual design.\n\n### Backward Compatibility: sites\u002F → plans\u002F\n\nBuild sites previously lived in `context\u002Fsites\u002F`. All Cavekit commands check both locations:\n\n1. Look in `context\u002Fplans\u002F`\n2. If not found, fall back to `context\u002Fsites\u002F`\n3. If found in `sites\u002F`, use it — no auto-migration, no breakage\n\n`\u002Fck:init` offers optional migration. Declining is permanent — the system works with either layout.\n\n---\n\n## CLAUDE.md Hierarchy\n\n### Scope: Full Repository\n\n`CLAUDE.md` files extend beyond `context\u002F` into the source code tree. They form the connective tissue between code and the context DAG.\n\n```\nproject\u002F\n├── CLAUDE.md                          # Project root: build\u002Ftest commands,\n│                                      #   \"context\u002F has the full hierarchy\"\n├── context\u002F\n│   ├── CLAUDE.md                      # Root context node: 4 tiers described\n│   ├── refs\u002FCLAUDE.md                 # Tier 1 conventions\n│   ├── kits\u002FCLAUDE.md           # Tier 2 conventions\n│   ├── plans\u002FCLAUDE.md                # Tier 3 conventions\n│   └── impl\u002FCLAUDE.md                 # Tier 4 conventions\n│\n├── src\u002F\n│   ├── CLAUDE.md                      # Source code conventions\n│   ├── auth\u002F\n│   │   ├── CLAUDE.md                  # \"implements cavekit-auth.md R1-R3\"\n│   │   └── ...\n│   └── parser\u002F\n│       ├── CLAUDE.md                  # \"implements cavekit-grammar.md R1-R4,\n│       │                              #   see plans\u002Fbuild-site.md T-012 through T-018\"\n│       └── ...\n│\n├── tests\u002F\n│   ├── CLAUDE.md                      # Test conventions, how to run\n│   └── ...\n└── scripts\u002F\n    ├── CLAUDE.md                      # Utility script conventions\n    └── ...\n```\n\n### Loading Behavior\n\nWhen an agent works in `src\u002Fauth\u002F`, it loads hierarchically:\n1. `project\u002FCLAUDE.md` — project-level conventions\n2. `project\u002Fsrc\u002FCLAUDE.md` — source code conventions\n3. `project\u002Fsrc\u002Fauth\u002FCLAUDE.md` — **\"implements cavekit-auth.md R1-R3\"**\n\nThe third file bridges to the context DAG. The agent knows which cavekit to load without loading the entire `context\u002Fkits\u002F` directory.\n\n### CLAUDE.md Design Principles\n\n- **Minimal** — 3-10 lines for source-tree files. Never duplicate cavekit content.\n- **Connective** — each one names the cavekit requirements and plan tasks it relates to.\n- **Contextual** — includes module-specific conventions (error handling patterns, test fixture locations).\n- **Honest** — `\u002Fck:make` only writes mappings it is certain about (tasks it completed, files it created).\n\n---\n\n## Progressive Disclosure: The DAG Traversal\n\n### How Agents Navigate\n\n1. **Enter at root** — read `context\u002FCLAUDE.md` to understand the 4 tiers\n2. **Select tier** — based on current task, navigate to the relevant tier's `CLAUDE.md`\n3. **Read index** — the tier's overview file is the DAG hub, listing all domains with one-line summaries\n4. **Follow edges** — read only the domain files relevant to the current task\n5. **Cross-reference** — if a domain references another, follow that edge only if needed\n6. **Nest deeper** — if a domain has subdirectories, its root file is the sub-index; spider from there\n\n### Index File Format\n\nEvery overview file follows the same format:\n\n```markdown\n# Cavekit Overview\n\n| Domain | File | Summary | Status |\n|--------|------|---------|--------|\n| Authentication | cavekit-auth.md | Registration, login, sessions, OAuth | DRAFT |\n| Data Models | cavekit-data-models.md | Core entities, relationships, validation | DRAFT |\n| Type System | cavekit-type-system.md | Effects lattice, tagged values (see type-system\u002F) | DRAFT |\n```\n\nAn agent reads this table, identifies \"I need Authentication,\" and loads only `cavekit-auth.md`.\n\n### Cross-Reference Edges\n\n```markdown\n**Dependencies:** cavekit-auth.md R2 (session tokens required for API auth)\n**See also:** cavekit-api.md R4 (rate limiting uses auth identity)\n```\n\nAgents follow these only when the cross-referenced content is needed for the current task.\n\n---\n\n## Nesting Rule\n\nA domain stays flat (single file) by default. When a file covers multiple independent concerns that could be understood separately, it becomes an index file pointing to a subdirectory.\n\n**Trigger:** Cohesion, not line count. If a file has sections that an agent working on one section would never need to read the others, decompose it.\n\n**Example:** `cavekit-type-system.md` covers effects lattice, tagged values, and inference rules:\n\n```\nkits\u002F\n├── cavekit-type-system.md                        # Now an index\n└── type-system\u002F\n    ├── cavekit-type-system-effects.md\n    ├── cavekit-type-system-tagged.md\n    └── cavekit-type-system-inference.md\n```\n\nThe original file stays in place as the index — no reference breakage.\n\n---\n\n## Backpropagation via CLAUDE.md\n\nWhen a bug is found, source-tree CLAUDE.md files provide the reverse traversal:\n\n```\nBug in src\u002Fauth\u002Flogin.ts\n    |\n    v\nsrc\u002Fauth\u002FCLAUDE.md says \"implements cavekit-auth.md R2\"\n    |\n    v\ncavekit-auth.md R2 — check acceptance criteria\n    |\n    |-- Criteria missing?  --> update cavekit (spec gap)\n    |-- Criteria wrong?    --> fix cavekit (spec bug)\n    |-- Criteria present but code violates? --> fix code (impl bug)\n    |\n    v\nIf cavekit changed --> propagate to plans\u002F --> flag affected tasks\n```\n\n### Forward Propagation\n\nWhen a cavekit changes via `\u002Fck:revise`:\n1. Scan all `src\u002F*\u002FCLAUDE.md` files for references to the changed requirement\n2. Flag those modules as potentially affected\n3. New requirements with no source-tree CLAUDE.md references are unimplemented\n\n---\n\n## Bootstrapping\n\nRun `\u002Fck:init` to create the full hierarchy. It:\n1. Scans existing project structure\n2. Creates context directories (refs\u002F, kits\u002F, plans\u002F, impl\u002F)\n3. Creates CLAUDE.md files using standard templates\n4. Creates empty index files (cavekit-overview.md, plan-overview.md, impl-overview.md)\n5. Offers migration if legacy `context\u002Fsites\u002F` exists\n\nProperties: idempotent, non-destructive, no questions asked.\n\n---\n\n## Build-Time Updates\n\nAfter `\u002Fck:make` completes, source-tree CLAUDE.md files are generated\u002Fupdated:\n- New source directories get a CLAUDE.md with cavekit\u002Fplan references\n- Existing CLAUDE.md files get new references appended (never removed)\n- `impl-overview.md` and `plan-overview.md` are updated with current status\n\n---\n\n## Multi-Repo Strategy\n\nFor shared kits across implementations, use git submodules:\n\n```\nTier 1-2 (shared): shared-context\u002F (submodule)\n    └── refs\u002F + kits\u002F\n\nTier 3-4 (per-repo): context\u002F\n    └── plans\u002F + impl\u002F\n```\n\nEach framework repo includes the shared context as a submodule. Updates propagate via `git submodule update`.\n\n---\n\n## Integration with Other Skills\n\n| Skill | Integration |\n|-------|------------|\n| `ck:cavekit-writing` | Kits go in `context\u002Fkits\u002F` following naming conventions |\n| `ck:design-system` | DESIGN.md lives at project root; `context\u002Fdesigns\u002F` has CLAUDE.md and changelog |\n| `ck:impl-tracking` | Tracking lives in `context\u002Fimpl\u002F`, compacted when exceeding ~500 lines |\n| `ck:validation-first` | Validation results recorded in impl tracking within the hierarchy |\n| `ck:revision` | `\u002Fck:revise` traverses CLAUDE.md edges in reverse to trace bugs to specs |\n| `c4-architecture` | Generates the 4-level C4 model; diagrams populate the S1 (ARCHITECTURE) tier via `ctx_index(source: \"architecture\")` |\n| `ck:methodology` | Context structure established during Draft phase, maintained throughout the Hunt |\n\n---\n\n## Anti-Patterns\n\n| Anti-Pattern | Why It's Wrong | Fix |\n|-------------|---------------|-----|\n| Flat file dump | No progressive disclosure, agents load everything | Use standard directory structure with indexes |\n| Missing CLAUDE.md files | No convention guidance, no DAG edges | Run `\u002Fck:init` or add manually |\n| Monolithic documents | Defeats progressive disclosure | Decompose into domains with overview indexes |\n| Stale archives in active dirs | Wastes context window | Move to `impl\u002Farchive\u002F` |\n| Duplicating cavekit content in CLAUDE.md | Content drifts, double maintenance | CLAUDE.md files only contain references |\n",{"name":5,"description":7},"main","5dc86f90a5cbe45db3acd917825461b3ed6937fb","config\u002F.config\u002Fopencode\u002Fskills\u002Fcontext-architecture",0,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev","🌐 Apasionado por crear soluciones web escalables y eficientes. \r\n🧑‍🏫 Coach Dev.\r\n💻 Frontend Dev. \r\n🎚️Backend Dev.\r\n📊 Agile\u002FScrum.\r\n🚀100% remoto.","2026-08-26 07:28:05",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add davidcoachdev\u002Fdcfiles --skill context-architecture",{"tool":38,"command":39},"bunx","bunx skills add davidcoachdev\u002Fdcfiles --skill context-architecture",{"tool":41,"command":42},"pnpm","pnpm dlx skills add davidcoachdev\u002Fdcfiles --skill context-architecture","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fcontext-architecture\u002FSKILL.md",true,[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"README.md","REFERENCE","参考文档",431,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fcontext-architecture\u002FREADME.md",[53,61,68,75,82,89],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":57,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M7740FETMZY1VTYAEFY1TWY7","zustand-5","Zustand 5 state management patterns. Trigger: When managing React state with Zustand.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fzustand-5\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":57,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M773ZZM9V68SA1AKP4WF4J29","zod-4","Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fzod-4\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":57,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M773ZJFR90CQAY0N9QR40QVP","x-bookmark-quote-posts","Workflow para revisar bookmarks de X\u002FTwitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fx-bookmark-quote-posts\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M773Z2RGV3786FV310SDB0YD","writing-skills","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M773YJH3KDSW467CSS63CSRJ","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":57,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M773Y3S3H2CPRK5S8YFHWB5C","work-unit-commits","Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fwork-unit-commits\u002FSKILL.md",[],[]]