generated from coulomb/repo-seed
feat(capability-requests): add cross-domain capability catalog and request routing
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>
This commit is contained in:
177
dashboard/src/docs/scope.md
Normal file
177
dashboard/src/docs/scope.md
Normal file
@@ -0,0 +1,177 @@
|
||||
---
|
||||
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.*
|
||||
Reference in New Issue
Block a user