Context Map¶
If you're new here, this is where everything is. AI agents and humans read the same map.
This is the audience-tagged inventory of every context surface in the repo — what each surface holds, how it stays fresh, and the canonical way to read it. When you're hunting for "where do I find X?", start here.
Surfaces¶
| Surface | Audience | What lives here | How updated | Freshness rule | Read via (skill/tool) |
|---|---|---|---|---|---|
CLAUDE.md |
AI agents (project) | Quick context, tech stack, just-recipes, key patterns, critical files, skills reference | Manual edit on convention changes | Review every PR that touches infra/skills/rules | Auto-loaded into every Claude Code session |
AGENTS.md |
AI agents (other) | Pointer/parity doc for non-Claude AI tools | Manual edit; mirror major CLAUDE.md changes | Quarterly review | Read directly |
README.md |
Humans (new devs) | Setup, dev loop, deploy, project overview, links to deeper docs | Manual edit on workflow/tooling changes | Review every PR that changes setup/commands | Open in editor / GitHub |
docs/ (with docs/INDEX.md) |
Humans (devs) | Architecture, auth, frontend/backend deep-dives, runbooks, diagrams, weekly reports | Manual edit per change; /deep-extract for refresh |
Stale if last-touched > 90 days for a still-live area | Browse docs/INDEX.md; /explore for trace |
docs/KNOWLEDGE_BASE.md |
Humans (devs) | Deep-docs index (73 files, 11 diagrams) — comprehensive code-derived references | /deep-extract regenerates; manual edits allowed |
Refresh after major refactors | Read directly or via /deep-explore |
wiki/ (with wiki/INDEX.md) |
Humans (business + product) | Confluence-synced FSDs, PRDs, glossary, product/PM docs, demo prep | just confluence-sync (mirrors Confluence) |
🟢 < 7 days; 🟡 7–30; 🔴 > 30 (see just context-health) |
/confluence-reader; wiki/INDEX.md |
jira/ (per-ticket folders) |
AI agents + humans | Per-ticket synced Jira fields, description, comments, attachments + sibling spec.md/plan.md/notes.md | just jira-tickets-sync (mirrors Jira) |
🟢 < 7 days; 🟡 7–30; 🔴 > 30 | /jira-tickets LCO-NNN |
knowledge/ |
AI agents | Curated learnings, architecture notes, decision records exported from claude-mem / deep-think | Manual + /deep-extract outputs |
Append-only; prune stale before quarterly review | Browse directly; cross-linked from CLAUDE.md |
.claude/rules/ |
AI agents | Hard rules for codegen: schemas, routers, repositories, services, styling, hooks, components, stores, api-services | Manual edit when a convention changes | Update on every detected convention shift | Auto-included via CLAUDE.md hierarchy |
.claude/learnings/ |
AI agents | Aggregated bot/PR-review findings, recurring-mistake patterns | tools/learnings/aggregate-findings.py + cron-aggregate-learnings.yml (weekly) |
🟢 < 7 days since last aggregate | Browse directly; surfaced to PR-review agents |
.claude/skills/ |
AI agents | Project + plugin skills (slash commands) — bundled domain workflows | Manual edit per skill; plugins update via marketplace | Skill SKILL.md should reflect current commands | Invoked as /skill-name; listed in CLAUDE.md |
.claude/agents/ |
AI agents | Project-defined subagent personas (lco-fullstack-implementer, lco-code-reviewer, etc.) |
Manual edit per agent | Re-review when feature workflow changes | Invoked via Agent tool with subagent_type |
.claude/hotspots.json |
AI agents | Top-churn files for current sprint — feeds check-hotspot.sh hook |
tools/refresh-hotspots.py + cron-refresh-hotspots.yml (weekly) |
🟢 < 7 days; 🔴 > 14 | Read by PreToolUse hook; inspect via cat |
.claude-plans/ (with archive/) |
AI agents + humans | Ephemeral implementation plans, specs, brainstorms; archive/legacy-plans/ holds retired material |
Manual; agents drop plans here mid-task | Archive plans after they land; never delete in-flight | Browse directly; convention-only |
.tdd/ |
AI agents | Ticket-driven-dev backlog, in_progress, completed, registry.json | Plugin-managed (/ticket-manager, /tackle-ticket, etc.) |
Plugin reconciles; /tdd-doctor audits drift |
/ticket-manager, /tackle-ticket, /tdd-doctor |
| claude-mem | AI agents | Persistent cross-session memory and observation database | Auto-captured per session via hooks | Continuously refreshed; query as needed | /mem-search, /timeline-report, /smart-explore |
.github/workflows/ |
Humans + CI | Cron + workflow_dispatch automations (confluence sync, jira sync, hotspots refresh, learnings aggregation, release PRs). Workflow inventory: .github/workflows/README.md | Manual edit | Validate with actionlint; check Actions tab weekly |
Open in editor / GitHub Actions UI |
scripts/claude-hooks/ |
AI agents (harness) | Shell hooks invoked by .claude/settings.json (hotspot check, branch-context loader) |
Manual edit; settings.json wires them up | Test locally with printf '{}' | bash <hook> |
Triggered by Claude Code harness |
Open questions / not yet stable¶
knowledge/is still in flux — directory layout will likely be reorganized once/deep-extractoutput schema stabilizes. Treat existing files as authoritative-for-now but expect churn.AGENTS.mdcontent split vs.CLAUDE.md— currently overlaps; long-term,AGENTS.mdshould hold tool-agnostic guidance andCLAUDE.mdshould hold Claude-specific overrides. Not yet decoupled.docs/deep-docs/vs. top-leveldocs/— duplication exists because/deep-extractwrites alongside hand-authored docs. Canonicalization is a future spec.- Per-ticket sibling docs in
jira/LCO-NNN/(spec.md / plan.md / notes.md / decisions/) aren't lifecycle-managed yet — no rule for when to promote them intodocs/orknowledge/vs. archive on ticket close. .claude-plans/archive/retention policy — currently append-forever; eventual prune cadence is undecided.