Welcome to the part of the project where we admit future-you exists.
This documentation is organized by audience and workflow, not by who happened to write the last markdown file at 2:13 AM.
| If you are... | Start here | Then go to |
|---|---|---|
| New to Loop | User Guide | Learning Paths |
| Building features | Developer Guide | Workflow Cookbook |
| Debugging internals | Internals | Runtime Walkthrough |
| Looking for architecture rationale | Concepts | System Principles |
| Looking up exact commands | Reference | Command Reference |
- User Guide: Start-to-finish guidance by skill level.
- Learning Paths: Guided progression for beginners through power users.
- Claude Code Adapter Guide: Capability envelope, limits, and OODA behavior.
- Workflow Recipes: End-to-end task playbooks.
- Power User Playbook: Performance, scale, and control.
- Developer Guide: Build and change Loop safely.
- Setup: Environment bootstrap.
- Workflow Cookbook: Change-type specific contribution runbooks.
- Quality Gates: Tests, checks, governance.
- Contribution Workflow: Branch-to-merge routine.
- Concepts: Mental models and design vocabulary.
- System Principles: Decision criteria and tradeoff posture.
- Internals: Runtime architecture and module boundaries.
- Architecture: System structure and data flow.
- OODA + Execution Flow: Observe/Orient/Decide/Act mapping.
- Runtime Walkthrough: Step-by-step request lifecycle trace.
- Python Orchestrator Swap Analysis: Tradeoffs and decision framework for full Python orchestrator migration.
- Module Map: Where behavior actually lives.
- Troubleshooting: Fast diagnosis and fix paths.
- Incident Playbook: Severity-based response and closure criteria.
- Common Issues: Known failure patterns.
- Diagnostics Checklist: Structured incident capture.
- Reference Index: Quick lookup section.
- Command Reference: Canonical command map by workflow.
- Documentation Architecture: How docs are structured and maintained.
- Specification Set: Canonical feature contracts (SPEC-20 through SPEC-27).
- Spec Lineage Status: How origin-era design/migration specs map to current live status.
- Execution Plan: Program-level planning, evidence, and governance.
- Architecture Decisions: Long-lived technical decisions and context.
- Glossary: Shared terms and definitions.
- Writing Style: Documentation voice and formatting contract.
- Behavior over aspiration: document what exists and runs.
- Workflow over component: prefer "how to get outcome X" over "here is a list of modules".
- Reproducibility over vibes: include concrete commands and expected outputs.
- Honesty over smoothness: if something is sharp, say so plainly.
- Friendly precision: direct writing, with enough personality that reading it does not feel like filing taxes.
- Concepts: Mental Model
- Concepts: System Principles
- User Guide
- Developer Setup
- Internals Architecture
- Troubleshooting
The docs in this folder are the operational surface. Deep design history and migration rationale still live in long-form docs such as:
docs/unified-rlm-library-design.mddocs/lean-formal-verification-design.mddocs/migration-spec-recurse.mddocs/migration-spec-rlm-claude-code.md
Those are excellent references; they are not where a newcomer should start unless they really enjoy scrolling.
For live implementation status and active backlog, use:
bd status/bd readydocs/execution-plan/STATUS.mddocs/execution-plan/TASK-REGISTRY.md