--- title: SCOPE.md — Reference --- # SCOPE.md — Reference SCOPE.md is a lightweight, strategic orientation artifact placed at the root of every registered repository. It helps humans and agents quickly understand what a repo is about, when it is relevant, and where it fits in the ecosystem. --- ## What SCOPE.md is SCOPE.md answers these questions **in under 60 seconds**: - What is this repository for? - Should I care about it right now? - When is it relevant to my work? - Where does it fit in the ecosystem? - Is it mature enough to trust or reuse? - Does it overlap with something else? It is **not** a README, not architecture documentation, and not marketing text. It is a pragmatic, scannable boundary definition. --- ## Template structure Every SCOPE.md follows an 11-section template: | Section | Purpose | |---------|---------| | **One-liner** | One precise sentence describing the repo's purpose | | **Core Idea** | Main capability and what problem it solves | | **In Scope** | What the repo is explicitly responsible for — concrete, not vague | | **Out of Scope** | What it deliberately does NOT do (often more important) | | **Relevant When** | Real usage scenarios when someone should consider this repo | | **Not Relevant When** | When someone should look elsewhere | | **Current State** | Maturity indicators: status, implementation, stability, usage | | **How It Fits** | Upstream dependencies, downstream consumers, often-used-with | | **Terminology** | Domain terms, potential confusions with similar concepts | | **Related / Overlapping** | Repos with similar or adjacent responsibilities | | **Provided Capabilities** | What this repo's domain can provide to others on request | | **Getting Oriented** | Entry points, key files, where to start | The template is at `state-hub/scripts/project_rules/scope.template`. --- ## Current State indicators The Current State section uses four axes: | Axis | Values | |------|--------| | **Status** | concept / experimental / active / stable / deprecated | | **Implementation** | idea / partial / substantial / complete | | **Stability** | unstable / evolving / stable | | **Usage** | none / personal / internal / production | These help an agent decide whether to depend on, extend, or avoid a repo without needing to read its full codebase. --- ## Design principles - **Intentionally short and scannable** — not comprehensive documentation - **Pragmatic** — real usage scenarios, not ideals - **Easy to maintain** — update when scope changes, not on every commit - **Direct language** — no filler, no marketing, no invented features - **Honest about gaps** — if something is incomplete or unstable, say so **Anti-goals:** - No long prose or verbose explanations - No repetition of README content - No hiding ambiguity behind vague language - No assumption of production readiness --- ## How SCOPE.md is created ### New repositories When a repo is registered via `make register-project`, the scaffold copies `scope.template` → `SCOPE.md` at the repo root. The human or an agent then populates the sections from the repo's actual state. ### Existing repositories The **scope-analyst** kaizen agent persona can be loaded to generate or refine a SCOPE.md: ``` get_kaizen_agent("scope-analyst") ``` This agent reads the repo's codebase, existing documentation, and CLAUDE.md to produce a SCOPE.md that accurately reflects the current state. --- ## Ecosystem coverage SCOPE.md files exist across all custodian domains: | Domain | Repos with SCOPE.md | |--------|-------------------| | **custodian** | the-custodian, kaizen-agentic, ops-bridge, activity-core | | **custodian** (netkingdom) | net-kingdom, key-cape | | **railiance** | railiance-apps, railiance-cluster, railiance-enablement, railiance-infra, railiance-platform | | **markitect** | markitect_project | --- ## Provided Capabilities section The `## Provided Capabilities` section uses fenced `capability` blocks that are machine-readable and ingested into the state-hub capability catalog: ````markdown ```capability type: infrastructure title: Cluster provisioning description: Provision k8s clusters and managed instances for any domain. keywords: [cluster, k8s, privacy, instance] ``` ```` | Field | Required | Purpose | |-------|----------|---------| | **type** | yes | Category: `infrastructure`, `api`, `data`, `security`, `documentation`, `other` | | **title** | yes | Short name (unique within domain + type) | | **description** | no | What this capability provides | | **keywords** | no | Routing hints for auto-matching capability requests | The ingest script (`make ingest-capabilities-all`) parses these blocks from all registered repos and populates the state-hub catalog table. This follows ADR-001: **files are the origin of truth, DB is cache/index**. --- ## Relation to capabilities SCOPE.md is both the **human-readable boundary definition** and the **origin of truth for the capability catalog**: | | SCOPE.md | Capability Catalog (DB) | |-|----------|------------------------| | **Role** | Origin of truth | Derived index | | **Granularity** | Per-repository | Per-domain (aggregated from repo files) | | **Purpose** | "What is this repo?" + "What can it provide?" | Routing engine for capability requests | | **Updates** | Edit the file, re-ingest | Auto-populated from SCOPE.md | | **Readable without hub** | Yes — just open the file | No — requires API | This means a repo is fully self-describing: you can understand what it provides by reading SCOPE.md alone, without any centralized infrastructure. --- ## Relation to other concepts | Concept | Relationship | |---------|-------------| | **CLAUDE.md** | Build/test/lint instructions — *how* to work with the repo | | **SCOPE.md** | Boundary definition — *what* the repo is and isn't | | **Capability Catalog** | Operational routing — *what the domain can provide* on request | | **Domain Goals** | Strategic direction — *where the domain is heading* | | **Project Charters** | Founding intent — *why the domain exists* (in `canon/projects/`) | --- *SCOPE.md is the boundary definition layer. It tells you whether you are in the right place before you start reading code.*