tegwick
d45234531b
Introduces a capability catalog (CUST-WP-0022) so domains can advertise what they provide and agents can request capabilities from other domains with auto-routing, lifecycle tracking, and task-unblocking on completion. - New models: CapabilityCatalog, CapabilityRequest with full lifecycle (requested → accepted → in_progress → ready_for_review → completed/rejected/withdrawn) - Migration i6d7e8f9a0b1: capability_catalog + capability_requests tables - Router /capability-catalog and /capability-requests with accept/status endpoints - 7 new MCP tools: register_capability, list_capabilities, request_capability, accept_capability_request, update_capability_request_status, list_capability_requests, get_capability_request - StateSummary gains open_capability_requests count - Dashboard: capability-requests.md page + docs/capabilities.md + docs/scope.md - SCOPE.md: three seed capabilities documented (MCP registration, state tracking, SBOM) - scope.template: Provided Capabilities section with example block - scripts/ingest_capabilities.py + make ingest-capabilities[/-all] targets Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
6.1 KiB
title
| 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:
```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.