# Repository Navigation Guide — For Efficient Agentic Exploration

**Purpose:** Quick reference for agents (Claude/Cursor/Codex/Aider/etc.) and humans to understand repo structure, find code/docs, and avoid redundant exploration.

> **🎯 Single source of truth:** `wiki/` is the knowledge vault. All plans, specs, decisions, debriefs, and research live there — regardless of which AI agent created them.

---

## 1. Where to Start (Entry Points by Task)

### You are an AI agent starting work on this repo

→ Read: `AGENTS.md` (operational guide) + `.agents/MEMORY.md` (project status)
→ Check: `CHANGELOG.md` for recent releases; `wiki/Architecture/Specs/DOCUMENT_INDEX.md` for canonical docs
→ Query: `wiki/Hot.md` (recent context cache) — start here for "what changed lately"

### You need to understand the architecture

→ See: `wiki/Architecture/Specs/DOCUMENT_INDEX.md` (read order for canonical docs)
→ Read: `wiki/Architecture/Specs/05-DESIGN-NORTH-STAR.md` (target), then `04-PROJECT-STATE.md` (current)
→ Reference: `AGENTS.md` §Architecture Quick Reference (package dependency tree)
→ Code: Browse `packages/{core,llm-provider,reasoning,tools}/src/` in that order

### You need to write a plan or spec

→ **Plans:** `wiki/Planning/Implementation-Plans/YYYY-MM-DD-<feature>.md` — see `wiki/Planning/Planning-Index.md`
→ **Architecture specs:** `wiki/Architecture/Design-Specs/YYYY-MM-DD-<spec>.md`
→ **Decisions:** `wiki/Decisions/YYYY-MM-DD-<decision>.md`
→ **Templates:** `wiki/_Templates/` (Experiment, Decision, Concept templates)
→ **Convention:** This is agent-agnostic. Claude, Cursor, Codex, Aider — all write to wiki/. See AGENTS.md §Plans, Specs & Knowledge Storage.

### You need to implement a feature

→ Read: `AGENTS.md` §Development Workflow
→ Find relevant package: Use Package Map below
→ Reference skill: Load `.agents/skills/{effect-ts-patterns, implement-service, implement-test, your-domain}`
→ Active plans: Check `wiki/Planning/Implementation-Plans/` for ongoing work

### You need to fix a bug

→ Read: `wiki/Architecture/Specs/02-FAILURE-MODES.md` for category, then `AGENTS.md` §Common Debugging Entry Points
→ Narrow to file: Use Package Map below + diagnostics skill
→ Check: `wiki/Failure-Modes/` for documented failure mode details (FM-A through FM-H)

### You need to understand a specific package

→ Navigate to: `packages/<name>/`
→ Read: `packages/<name>/src/index.ts` (exports), `src/runtime.ts` (layer factory)
→ Tests: `packages/<name>/tests/*.test.ts` (examples of use)
→ Wiki: `wiki/Packages/00 Package Index.md` for overview

### You need user-facing docs on a feature

→ Search: `apps/docs/src/content/docs/` by category (guides/, features/, reference/, concepts/)
→ Code reference: Check that example in README.md or AGENTS.md matches current API
→ Note: `apps/docs/` is the public Astro site (docs.reactiveagents.dev) — distinct from internal `wiki/`

---

## 2. Repository Structure (Quick Map)

```
reactive-agents-ts/
├── Root docs (entry points + conventions)
│   ├── AGENTS.md ........................ canonical agent workflow + build commands
│   ├── CLAUDE.md ........................ lightweight pointer to AGENTS.md
│   ├── README.md ........................ public API overview + quickstart
│   ├── CAPABILITIES.md .................. CI-enforced capability registry
│   ├── CODING_STANDARDS.md .............. TypeScript/Effect-TS authority
│   ├── CHANGELOG.md ..................... release history (auto-generated by changesets)
│   ├── CONTRIBUTING.md .................. contribution guidelines
│   ├── QUICK_START.md ................... 5-min setup
│   ├── ROADMAP.md ....................... public milestone tracker
│   └── NAVIGATION.md .................... THIS FILE
│
├── .agents/ .............................. agent-internal guidance
│   ├── MEMORY.md ........................ cross-session project memory (READ FIRST)
│   └── skills/ .......................... 24 contributor skills for framework development
│
├── wiki/ ................................. 🎯 KNOWLEDGE VAULT (single source of truth)
│   ├── Home.md .......................... vault entry point + index
│   ├── Hot.md ........................... recent context cache (≤500 words, regenerate at session end)
│   ├── Log.md ........................... append-only session log
│   │
│   ├── Architecture/ ................... system design & specs
│   │   ├── Specs/ ...................... canonical project specs (00-VISION, 04-PROJECT-STATE, etc.)
│   │   ├── Design-Specs/ ............... feature-level design documents
│   │   └── (Architecture MOC.md)
│   │
│   ├── Planning/ ....................... plans & roadmap
│   │   ├── Implementation-Plans/ ....... ALL plans go here (agent-agnostic)
│   │   │   └── Superpowers/ ............ legacy superpowers-skill plans (read-only archive)
│   │   ├── Roadmap.md .................. mirrored from /ROADMAP.md
│   │   └── Planning-Index.md ........... index of all plans by status
│   │
│   ├── Decisions/ ...................... decisions & RFCs
│   │   └── Decision-Index.md ........... searchable decision log
│   │
│   ├── Concepts/ ....................... conceptual knowledge
│   │
│   ├── Reference/ ...................... reference material
│   │   ├── Benchmarks/ ................. benchmark results
│   │   ├── Distribution/ ............... package distribution info
│   │   ├── Changelog-History/ .......... archived CHANGELOG entries
│   │   └── (release artifacts)
│   │
│   ├── Research/ ....................... research, debriefs, audits, harness data, spikes
│   │   ├── Debriefs/ ................... post-feature engineering notes
│   │   ├── Audit-Reports-YYYY-MM-DD/ ... periodic audit reports
│   │   ├── Harness-Reports/ ............ phase validations, baselines, gate traces (REPORTS_DIR)
│   │   ├── Prototypes/ ................. spike scripts (pNN-*.ts) + RESULTS + RESEARCH_LOG
│   │   └── (deep research archives)
│   │
│   ├── Development/ .................... contributor docs (mirrors of root files)
│   │   ├── Agents-Instruction.md ....... mirror of /AGENTS.md
│   │   ├── Contributing.md ............. mirror of /CONTRIBUTING.md
│   │   └── Coding-Standards.md ......... mirror of /CODING_STANDARDS.md
│   │
│   ├── Guides/ ......................... user guides (mirrors)
│   │   └── Quick-Start.md .............. mirror of /QUICK_START.md
│   │
│   ├── Failure-Modes/ .................. FM-A through FM-H catalog
│   ├── Experiments/ .................... experiment logs (M1-M13 mechanism validations)
│   ├── Issues/ ......................... running issues log
│   ├── Packages/ ....................... per-package documentation
│   ├── MOCs/ ........................... maps of content (navigation hubs)
│   ├── _Templates/ ..................... templates for new notes
│   └── .obsidian/ ...................... Obsidian config (do not edit by hand)
│
├── packages/ ............................. 29 packages (28 published, 1 private: benchmarks)
│   ├── core/ ............................ EventBus, AgentService, TaskService, types
│   ├── llm-provider/ .................... 6 LLM providers + adapter hooks
│   ├── memory/ .......................... 4-layer memory system
│   ├── reasoning/ ....................... 5 strategies + composable kernel
│   ├── tools/ ........................... ToolService, 11 built-in tools, MCP client
│   ├── guardrails/ ...................... injection/PII/toxicity detection
│   ├── verification/ .................... semantic entropy, NLI, hallucination detection
│   ├── cost/ ............................ complexity router, budget enforcer
│   ├── identity/ ........................ RBAC, Ed25519 certs
│   ├── observability/ ................... tracing, metrics, structured logging
│   ├── gateway/ ......................... persistent harness: heartbeats, webhooks
│   ├── eval/ ............................ LLM-as-judge, regression testing
│   ├── orchestration/ ................... multi-agent workflows
│   ├── interaction/ ..................... autonomy modes, approval gates
│   ├── prompts/ ......................... template engine, tier-adaptive variants
│   ├── a2a/ ............................. agent-to-agent networking
│   ├── runtime/ ......................... ExecutionEngine, ReactiveAgentBuilder
│   ├── reactive-agents/ ................. public API facade (re-exports)
│   └── benchmarks/ (private) ............ evaluation suite
│
├── apps/
│   ├── docs/ ............................ Starlight/Astro public docs site
│   │   ├── src/content/docs/ ........... user-facing documentation
│   │   └── skills/ ..................... consumer-facing AI agent skills (publicly fetchable)
│   ├── cli/ ............................. rax CLI (entry point: main.ts)
│   ├── cortex/ .......................... SvelteKit admin UI (Bun + SQLite)
│   ├── examples/ ........................ 34 usage examples
│   └── meta-agent/ ...................... internal meta-agent for framework testing
│
├── scripts/ ............................. utility scripts
├── docker/ .............................. container configs
├── .github/workflows/ ................... CI: tests, lint, publish, docs deploy
└── .claude/
    └── skills/ .......................... 24 contributor development skills
```

> **Note:** `docs/` directory was eliminated in May 2026. All previous content moved to `wiki/`. If you find yourself wanting to write to `docs/`, write to `wiki/` instead.

---

## 3. Plans, Specs & Knowledge Storage (Critical for ALL Agents)

**This convention applies to every AI agent (Claude Code, Cursor, Codex, Aider, GitHub Copilot, etc.) and human contributors.**

| Content Type | Location | Naming Pattern |
|--------------|----------|----------------|
| Implementation plans | `wiki/Planning/Implementation-Plans/` | `YYYY-MM-DD-<feature-name>.md` |
| Architecture specs | `wiki/Architecture/Design-Specs/` | `YYYY-MM-DD-<spec-name>.md` |
| Canonical project specs | `wiki/Architecture/Specs/` | `NN-NAME.md` (numbered) |
| Decisions/RFCs | `wiki/Decisions/` | `YYYY-MM-DD-<decision>.md` |
| Debriefs | `wiki/Research/Debriefs/` | `YYYY-MM-DD-<feature>-debrief.md` |
| Audit reports | `wiki/Research/Audit-Reports-YYYY-MM-DD/` | descriptive names |
| Failure modes | `wiki/Failure-Modes/` | `FM-<X>-<name>.md` |
| Experiments | `wiki/Experiments/` | `YYYY-MM-DD-<name>.md` |

### For superpowers `writing-plans` skill users

The skill defaults to `docs/superpowers/plans/` — **override to `wiki/Planning/Implementation-Plans/`** in this repo. The override is project convention, not a per-session choice.

### Hard rules

1. **No new files in `docs/`** — that directory no longer exists
2. **Update the index** after creating any plan/spec/decision (Planning-Index, Decision-Index)
3. **Use frontmatter** with `type`, `status`, `created`, `tags` on every wiki file

---

## 4. Package Map (All 29 Packages)

| Package | Purpose | Key Files | Layer | Depends On |
|---------|---------|-----------|-------|-----------|
| `core` | EventBus, types, AgentService | `src/services/event-bus.ts` | Foundation | none |
| `llm-provider` | 6 LLM providers, streaming, tool calling | `src/runtime.ts`, `src/providers/` | Foundation | core |
| `memory` | 4-layer memory | `src/runtime.ts`, `src/services/` | Foundation | core, llm-provider |
| `reasoning` | 5 strategies + kernel | `src/strategies/kernel/`, `src/services/` | Composition | core, llm-provider, memory, tools |
| `tools` | ToolService, 11 built-in tools, MCP | `src/services/tool-service.ts` | Composition | core, llm-provider |
| `guardrails` | Injection/PII/toxicity, KillSwitch | `src/services/guardrail-service.ts` | Quality | core, llm-provider |
| `verification` | Semantic entropy, NLI | `src/services/verification-service.ts` | Quality | core, llm-provider |
| `cost` | Complexity router, budget enforcer | `src/services/cost-service.ts` | Efficiency | core, llm-provider, memory |
| `identity` | RBAC, Ed25519 certs | `src/services/identity-service.ts` | Security | core |
| `observability` | Tracing, metrics, logging | `src/services/observability-service.ts` | Observability | core |
| `prompts` | Template engine, tier variants | `src/services/prompt-service.ts` | Composition | core, llm-provider |
| `eval` | LLM-as-judge, EvalStore | `src/services/eval-service.ts` | Testing | core, llm-provider |
| `interaction` | 5 autonomy modes, approval gates | `src/services/interaction-service.ts` | Control | core |
| `orchestration` | Multi-agent workflows | `src/services/orchestration-service.ts` | Composition | core, llm-provider, tools |
| `a2a` | Agent Cards, JSON-RPC 2.0 | `src/services/a2a-service.ts` | Networking | core |
| `gateway` | Persistent harness | `src/services/gateway-service.ts` | Persistence | core, llm-provider, tools |
| `runtime` | ExecutionEngine, Builder | `src/builder.ts`, `src/gateway-chat.ts` | Orchestration | ALL |
| `reactive-agents` | Public API facade | `src/index.ts` | Public API | runtime |
| `benchmarks` (private) | Evaluation harness | `src/` | Testing | all |

---

## 5. How to Find Things

### Find code

→ **By symptom:** `AGENTS.md` §Common Debugging Entry Points (11-row table)
→ **By package:** `packages/<name>/src/index.ts` (barrel) → `src/runtime.ts` (layer)
→ **By feature:** Use IDE "Go to File" or grep
→ **By test:** `packages/<name>/tests/*.test.ts` (usage examples)

### Find documentation

| Need | Location |
|------|----------|
| Architecture target | `wiki/Architecture/Specs/05-DESIGN-NORTH-STAR.md` |
| Current state | `wiki/Architecture/Specs/04-PROJECT-STATE.md` |
| Roadmap (internal) | `wiki/Architecture/Specs/07-ROADMAP-v1.0.md` |
| Roadmap (public) | `ROADMAP.md` (or `wiki/Planning/Roadmap.md`) |
| Failure modes | `wiki/Architecture/Specs/02-FAILURE-MODES.md` + `wiki/Failure-Modes/` |
| API reference | `apps/docs/src/content/docs/reference/builder-api.md` |
| User guides | `apps/docs/src/content/docs/guides/` |
| Examples | `apps/examples/src/` (34 patterns) |
| Recent context | `wiki/Hot.md` |
| Decision log | `wiki/Decisions/Decision-Index.md` |
| Active plans | `wiki/Planning/Planning-Index.md` |
| Past debriefs | `wiki/Research/Debriefs/` |
| Methodology | `wiki/Architecture/Specs/01-RESEARCH-DISCIPLINE.md` |

---

## 6. Common Agent Patterns

### Pattern 1: "Implement a feature in package X"
```
1. Find package: packages/<name>/src/index.ts
2. Load skill: .agents/skills/effect-ts-patterns/SKILL.md
3. Study: packages/<name>/tests/*.test.ts
4. (If multi-step) Write plan: wiki/Planning/Implementation-Plans/YYYY-MM-DD-<feature>.md
5. Implement: services first, then wire in runtime.ts
6. Test: bun test packages/<name>/tests/your-feature.test.ts
7. Update docs: README.md + apps/docs/ + CHANGELOG via changeset
```

### Pattern 2: "Something is broken in the kernel"
```
1. Identify symptom: AGENTS.md §Common Debugging Entry Points
2. Read that file + neighbors
3. Check: context? → context-builder.ts | tool-call? → phases/act.ts | loop? → loop-detector.ts
4. Test: bun test packages/reasoning/tests/kernel-*.test.ts
5. (If significant fix) Write debrief: wiki/Research/Debriefs/YYYY-MM-DD-<bug>-debrief.md
```

### Pattern 3: "Adding a new provider or tool"
```
1. Read: AGENTS.md §Adaptive Calibration + §Golden Rules
2. Implement: packages/llm-provider/src/providers/<name>.ts OR packages/tools/src/tools/<name>.ts
3. Export: src/index.ts
4. Update: CAPABILITIES.md (CI-enforced registry)
5. Test: bun test packages/{llm-provider,tools}/tests/
6. Document: apps/docs/src/content/docs/features/ + skill in apps/docs/skills/
```

### Pattern 4: "Understanding kernel phases"
```
1. Read: wiki/Architecture/Specs/05-DESIGN-NORTH-STAR.md §Cognitive Architecture
2. Browse: packages/reasoning/src/strategies/kernel/phases/ (12 phase files)
3. Trace: kernel-runner.ts calls them in sequence
4. Code example: packages/reasoning/tests/kernel-*.test.ts
```

### Pattern 5: "Tests are failing"
```
1. Run: bun test packages/<affected>/tests/<file>.test.ts (scoped)
2. Read: the test file (understand intent)
3. Find: source code (src/)
4. Check: AGENTS.md §Terminal Execution Rules (timeouts, server cleanup)
5. Fix: minimum change, re-run scoped test
```

---

## 7. Token Optimization for Agent Exploration

**Read these in order (5-10 min total) to avoid redundant searches:**

1. `AGENTS.md` — canonical operational guide
2. `.agents/MEMORY.md` — cross-session project status
3. `wiki/Hot.md` — recent context cache (≤500 words)
4. This file (NAVIGATION.md) — repo structure + quick patterns

**After that:**

- Navigate by symptom (AGENTS.md §Debugging) or task (this file §Common Patterns)
- Query Obsidian vault for decisions/experiments via `obsidian-vault-query`
- Use IDE's "Go to File" / grep for specific code

**Avoid:**

- Reading the full AGENTS.md when you only need one section — use Read with offset/limit
- Exploring packages without reading their `src/index.ts` first
- Running the full test suite to verify a change (use scoped `bun test <file>`)
- Writing plans/specs to root or `docs/` — they go to `wiki/`

---

## 8. Cross-Reference Quick Links

| Need | Path |
|------|------|
| Spec doc read order | `wiki/Architecture/Specs/DOCUMENT_INDEX.md` |
| Package dependency graph | `AGENTS.md` §Architecture Quick Reference |
| Common pitfalls | `AGENTS.md` §Common Pitfalls |
| Debug symptoms → files | `AGENTS.md` §Common Debugging Entry Points |
| Failure modes | `wiki/Architecture/Specs/02-FAILURE-MODES.md` |
| CI capabilities | `CAPABILITIES.md` |
| Code standards | `CODING_STANDARDS.md` |
| Changelog | `CHANGELOG.md` |
| Roadmap (public) | `ROADMAP.md` |
| Roadmap (internal) | `wiki/Architecture/Specs/07-ROADMAP-v1.0.md` |
| Vision | `wiki/Architecture/Specs/00-VISION.md` |
| Design target | `wiki/Architecture/Specs/05-DESIGN-NORTH-STAR.md` |
| Recent context | `wiki/Hot.md` |
| Active plans | `wiki/Planning/Planning-Index.md` |
| Decisions log | `wiki/Decisions/Decision-Index.md` |
| Methodology | `wiki/Architecture/Specs/01-RESEARCH-DISCIPLINE.md` |
| API reference | `apps/docs/src/content/docs/reference/builder-api.md` |
| User guides | `apps/docs/src/content/docs/guides/` |
| Examples | `apps/examples/src/` |

---

**Last updated:** 2026-05-05 (wiki consolidation pass)
**Maintenance:** Keep synchronized with AGENTS.md and wiki/Home.md when restructuring.
