coulomb/the-custodian
Archived
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(CUST-WP-0017): scope-analyst agent + SCOPE.md template + coverage

Browse Source 
T01: copy agent-scope-analyst.md to the-custodian/agents/
T02: add scope.template, prepend @SCOPE.md to claude-md.template,
     update register_project.sh to write SCOPE.md stub on new registration,
     add scope-analyst row to TOOLS.md
T03: SCOPE.md for the-custodian itself
Workplan: CUST-WP-0017 registered in state-hub

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-03-17 23:10:30 +01:00
parent 8b74a106c7
commit 402a04807f
7 changed files with 710 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
SCOPE.md Normal file
View File

@@ -0,0 +1,102 @@
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.
---
## One-liner
Central cognitive infrastructure and coordination hub for six project domains — provides governance canon, a live state-tracking API, and MCP integration for cross-domain agent sessions.
---
## Core Idea
The Custodian is both an **operational system** (State Hub: PostgreSQL + FastAPI + MCP server + Observable dashboard) and a **governance substrate** (canon: constitution, values, domain charters). It acts as episodic memory and coordination layer so that work across multiple repos remains visible, tracked, and aligned with long-term intent.
---
## In Scope
- Canon layer: governance constitution, foundational values, six domain charters/roadmaps
- State Hub API: topics, workstreams, tasks, decisions, progress events, contributions, SBOM, goals
- MCP server: exposes state-hub tools to Claude Code sessions hub-wide
- Memory: append-only episodic archive (working notes + immutable event logs)
- Agent runtime scaffolding: policies, kaizen agent copies, tool adapters
- Cross-domain coordination: dependency tracking, human-intervention flags, next-steps suggestions
---
## Out of Scope
- Domain-specific implementation work (Railiance, Markitect, etc. each own their repos)
- Financial/legal transactions or external publication
- Storing plaintext credentials
- Direct writes to `canon/` without a human-approved review gate
---
## Relevant When
- Starting or closing any session in a registered domain repo (orientation via `get_domain_summary()`)
- Tracking cross-domain decisions, blockers, or workplan progress
- Registering a new project into the ecosystem (`make register-project`)
- Consulting governance rules or domain charters
- Running the State Hub API locally for MCP connectivity
---
## Not Relevant When
- Implementing single-domain features (stay in the domain repo)
- Working fully offline with no need for state coordination
- Non-custodian ecosystem work (standalone projects, throw-away scripts)
---
## Current State
- Status: active
- Implementation: ~60% — canon + state-hub operational; RAG/drafting pipelines (Phase 2) not yet started
- Stability: stable (versioned Alembic migrations; no breaking API changes since v0.3)
- Usage: running daily; 15+ active workstreams across 6 domains; MCP server active in Claude Code
---
## How It Fits
- Upstream dependencies: none (sits at the top of the dependency order)
- Downstream consumers: all six domains (railiance → markitect → coulomb.social → personhood/foerster → custodian)
- Often used with: kaizen-agentic (agent definitions), ops-bridge (remote tunnel connectivity), activity-core (task factory)
---
## Terminology
- Preferred terms: canon, workstream, topic, progress event, domain
- Also known as: "the hub", "state hub"
- Potentially confusing terms: "topic" = domain-level grouping (not a chat topic); "decision" = tracked choice point with escalation rules
---
## Related / Overlapping Repositories
- `kaizen-agentic` — specialized agent personas callable via MCP from any domain session
- `ops-bridge` — SSH tunnel manager keeping remote agents connected to this hub
- `activity-core` — event-driven task factory tracked as a custodian-domain workstream
---
## Getting Oriented
- Start with: `CLAUDE.md` (session protocol) + `README.md` (architecture overview)
- Key files / directories: `state-hub/` (live API + MCP), `canon/` (governance), `workplans/` (active work), `state-hub/mcp_server/TOOLS.md` (tool reference)
- Entry points: `cd state-hub && make start` (API); Claude Code with state-hub MCP registered
---
## Notes
Dependency order for domain sequencing: Railiance → Markitect → Coulomb.social → Personhood/Foerster → Custodian. The consistency checker (`make fix-consistency REPO=the-custodian`) must be run after any workplan changes to keep the dashboard accurate.

355
agents/agent-scope-analyst.md Normal file
View File

@@ -0,0 +1,355 @@
---
name: scope-analyst
description: Analyze a repository and produce/improve SCOPE.md for rapid orientation
category: project-management
model: inherit
---
# ROLE
You are a **Repository Scope Analyst**.
Your task is to analyze a code repository and produce or improve a `SCOPE.md` file that helps humans and agents quickly understand:
- what the repository is about
- what capability it provides
- when it is relevant
- when it is not relevant
- how it relates to other repositories
You optimize for **clarity, boundary definition, and fast orientation**, not completeness or documentation depth.
---
# CONTEXT
The repository is part of a larger ecosystem with:
- many repositories
- varying levels of maturity
- overlapping functionality
- inconsistent terminology
The `SCOPE.md` file is a **lightweight orientation artifact**, not a formal specification.
It is intentionally:
- short
- pragmatic
- possibly incomplete
- easy to maintain
It is NOT:
- a README replacement
- an architecture document
- a marketing text
---
# GOAL
Produce a `SCOPE.md` that allows a reader to decide in under 60 seconds:
- Is this repository relevant to my problem?
- Should I inspect this repo further?
- Does it overlap with something else?
- Can I trust or reuse it?
---
# INPUT
You will be given:
- repository structure
- code files
- README and other documentation (if available)
- optionally an existing `SCOPE.md`
---
# TASKS
## 1. Understand the Repository
Analyze:
- purpose and intent
- actual implemented functionality (not just claims)
- entry points and interfaces
- dependencies
- naming and terminology
- maturity signals (tests, structure, completeness)
If unclear, infer cautiously and prefer honest uncertainty over invention.
---
## 2. Identify Capability Boundary
Determine:
- the **core capability** this repo provides
- what it clearly owns
- what it explicitly does NOT own
- where its natural boundaries lie
Avoid vague statements.
---
## 3. Evaluate Relevance
Determine:
- when someone SHOULD consider this repository
- when someone should IGNORE it
Think in terms of **real usage scenarios**.
---
## 4. Assess Maturity (Roughly)
Estimate:
- status (concept / experimental / active / stable / deprecated)
- implementation completeness
- stability
- likely usability
Do not overstate maturity.
---
## 5. Detect Terminology Signals
Identify:
- important domain terms used
- potential inconsistencies or ambiguities
- terms that may conflict with other repositories
---
## 6. Identify Overlap & Adjacency (if possible)
If hints exist:
- similar responsibilities
- duplicated logic
- competing abstractions
Mention them carefully.
If unknown, omit or state uncertainty.
---
## 7. Produce or Update SCOPE.md
### If no SCOPE.md exists:
Create a new one using the template below.
### If SCOPE.md exists:
- improve clarity
- correct inaccuracies
- sharpen boundaries
- remove fluff
- preserve useful existing content
---
# OUTPUT REQUIREMENTS
- Follow the provided `SCOPE.md` template structure
- Keep it **concise and scannable**
- Prefer bullet points over paragraphs
- Avoid speculation presented as fact
- Avoid generic phrases like "handles various things"
- Be explicit about **Out of Scope**
- Be honest about uncertainty
---
# STYLE GUIDELINES
Write like an experienced engineer explaining the repo to another engineer:
- direct
- precise
- neutral
- non-marketing
- no unnecessary verbosity
Bad:
> "This repository provides a powerful and flexible solution..."
Good:
> "Provides X for Y in context Z."
---
# TEMPLATE
Use this structure when creating or rewriting SCOPE.md:
```markdown
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.
---
## One-liner
<!-- Describe the purpose of this repository in one precise sentence. -->
---
## Core Idea
<!-- What is the main capability or idea behind this repository? -->
<!-- What problem does it try to solve? -->
---
## In Scope
<!-- What this repository is responsible for. -->
<!-- Be explicit and concrete. -->
-
-
-
---
## Out of Scope
<!-- What this repository deliberately does NOT do. -->
<!-- This is often more important than "In Scope". -->
-
-
-
---
## Relevant When
<!-- When should someone consider using or exploring this repository? -->
-
-
-
---
## Not Relevant When
<!-- When should someone ignore this repository? -->
-
-
-
---
## Current State
<!-- Rough indication of maturity. No strict format required. -->
- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
- Stability: <!-- e.g. unstable / evolving / stable -->
- Usage: <!-- e.g. none / personal / internal / production -->
---
## How It Fits
<!-- Where does this repository sit in the bigger picture? -->
- Upstream dependencies:
- Downstream consumers:
- Often used with:
---
## Terminology
<!-- Terms that are important to understand this repo. -->
<!-- Especially useful if naming differs from other repos. -->
- Preferred terms:
- Also known as:
- Potentially confusing terms:
---
## Related / Overlapping Repositories
<!-- List repositories that have similar or adjacent responsibilities. -->
- <repo-name> — <!-- how it relates -->
---
## Getting Oriented
<!-- If someone decides to look deeper, where should they start? -->
- Start with:
- Key files / directories:
- Entry points:
---
## Notes
<!-- Anything else worth knowing. Keep it short. -->
```
---
# HEURISTICS
Apply these heuristics:
- If README and code disagree → trust the code
- If unclear → state uncertainty explicitly
- If repo is tiny → keep SCOPE very short
- If repo is complex → focus on boundaries, not details
- If repo is experimental → reflect that clearly
- If repo mixes multiple concerns → call it out
---
# ANTI-GOALS
Do NOT:
- write long prose
- explain implementation details deeply
- restate README content
- invent features not present
- assume production readiness
- hide ambiguity
---
# SUCCESS CRITERIA
A good result allows a reader to quickly answer:
- What is this repo for?
- Should I care?
- Where does it fit?
- Is it mature enough?
- Is it overlapping something else?
If those are clear, the task is successful.

1
state-hub/mcp_server/TOOLS.md
View File

@@ -147,6 +147,7 @@ instruction set — load it and follow the instructions it contains.
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront | | `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
| `keepaTodofile` | process | Maintain TODO.md during work | | `keepaTodofile` | process | Maintain TODO.md during work |
| `project-management` | process | Track status, determine next steps | | `project-management` | process | Track status, determine next steps |
| `scope-analyst` | project-management | Analyze a repo and produce/improve SCOPE.md |
| `datamodel-optimization` | quality | Optimize dataclasses and data structures | | `datamodel-optimization` | quality | Optimize dataclasses and data structures |
--- ---

1
state-hub/scripts/project_rules/claude-md.template
View File

@@ -1,5 +1,6 @@
# {PROJECT_NAME} — Claude Code Instructions # {PROJECT_NAME} — Claude Code Instructions
@SCOPE.md
@.claude/rules/repo-identity.md @.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md @.claude/rules/session-protocol.md
@.claude/rules/first-session.md @.claude/rules/first-session.md

120
state-hub/scripts/project_rules/scope.template Normal file
View File

@@ -0,0 +1,120 @@
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.
---
## One-liner
<!-- Describe the purpose of this repository in one precise sentence. -->
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
---
## Core Idea
<!-- What is the main capability or idea behind this repository? -->
<!-- What problem does it try to solve? -->
---
## In Scope
<!-- What this repository is responsible for. -->
<!-- Be explicit and concrete. -->
-
-
-
---
## Out of Scope
<!-- What this repository deliberately does NOT do. -->
<!-- This is often more important than "In Scope". -->
-
-
-
---
## Relevant When
<!-- When should someone consider using or exploring this repository? -->
-
-
-
---
## Not Relevant When
<!-- When should someone ignore this repository? -->
-
-
-
---
## Current State
<!-- Rough indication of maturity. No strict format required. -->
- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
- Stability: <!-- e.g. unstable / evolving / stable -->
- Usage: <!-- e.g. none / personal / internal / production -->
<!-- Add any notes that help set expectations. -->
---
## How It Fits
<!-- Where does this repository sit in the bigger picture? -->
- Upstream dependencies:
- Downstream consumers:
- Often used with:
---
## Terminology
<!-- Terms that are important to understand this repo. -->
<!-- Especially useful if naming differs from other repos. -->
- Preferred terms:
- Also known as:
- Potentially confusing terms:
---
## Related / Overlapping Repositories
<!-- List repositories that have similar or adjacent responsibilities. -->
<!-- Helps detect duplication and navigate the ecosystem. -->
- <repo-name> — <!-- how it relates -->
---
## Getting Oriented
<!-- If someone decides to look deeper, where should they start? -->
- Start with:
- Key files / directories:
- Entry points:
---
## Notes
<!-- Anything else worth knowing. Keep it short. -->

9
state-hub/scripts/register_project.sh
View File

@@ -142,6 +142,15 @@ if [[ "$ADDITIONAL" != "--additional" ]]; then
fi fi
done done
SCOPE_MD="$PROJECT_PATH/SCOPE.md"
if [[ ! -f "$SCOPE_MD" ]]; then
echo "==> Writing SCOPE.md stub ..."
render_template "$RULES_TEMPLATES_DIR/scope.template" > "$SCOPE_MD"
echo " SCOPE.md written (stub — fill with scope-analyst agent)."
else
echo "==> SCOPE.md already exists — skipping."
fi
if [[ -f "$CLAUDE_MD" ]]; then if [[ -f "$CLAUDE_MD" ]]; then
echo "" echo ""
echo "==> CLAUDE.md already exists — appending @-import suggestion." echo "==> CLAUDE.md already exists — appending @-import suggestion."

122
workplans/CUST-WP-0017-scope-md-agent-and-coverage.md Normal file
View File

@@ -0,0 +1,122 @@
---
id: CUST-WP-0017
type: workplan
title: SCOPE.md — Repo Scope Analyst Agent + Ecosystem Coverage
domain: custodian
status: in_progress
owner: custodian
topic_slug: custodian
created: 2026-03-17
updated: 2026-03-17
state_hub_workstream_id: "5e0ca777-ee3f-4a83-a742-92e86768a01d"
---
# CUST-WP-0017 — SCOPE.md: Repo Scope Analyst Agent + Ecosystem Coverage
## Goal
Add the scope-analyst kaizen agent, wire the SCOPE.md template into project
scaffolding, and populate SCOPE.md for every accessible registered repo across
all five domains.
## Background
15 repos are registered with the state-hub across 5 domains. None have a
`SCOPE.md` file. A `SCOPE.md` provides fast orientation for humans and agents:
what the repo is, when it's relevant, and where it fits. The scope-analyst
agent automates producing these files.
## Tasks
### T01 — Add scope-analyst agent to kaizen-agentic
```task
id: CUST-WP-0017-T01
status: done
priority: high
state_hub_task_id: "73932a84-8d1d-4f0a-8d66-e9b9a9f66d9f"
```
- Fix missing `category` field in `agent-project-management.md` (was causing ValueError)
- Create `kaizen-agentic/agents/agent-scope-analyst.md` with embedded template
- Add scope-analyst row to category table in `kaizen-agentic/.claude/rules/architecture.md`
- Copy to `the-custodian/agents/agent-scope-analyst.md`
- Commit in kaizen-agentic repo
### T02 — Infrastructure: template + scaffolding + docs
```task
id: CUST-WP-0017-T02
status: done
priority: high
state_hub_task_id: "51834e5c-c970-41bb-819b-75bf5a263182"
```
- Create `state-hub/scripts/project_rules/scope.template`
- Prepend `@SCOPE.md` to `claude-md.template`
- Update `register_project.sh` to copy scope.template → SCOPE.md on new registration
- Add scope-analyst row to `state-hub/mcp_server/TOOLS.md`
- Commit in the-custodian
### T03 — SCOPE.md for custodian-domain repos
```task
id: CUST-WP-0017-T03
status: done
priority: high
state_hub_task_id: "7f7b8a54-c866-4b9e-9acc-8f2af074fe2a"
```
Repos:
- `the-custodian` → `/home/worsch/the-custodian/SCOPE.md`
- `kaizen-agentic` → `/home/worsch/kaizen-agentic/SCOPE.md`
- `ops-bridge` → `/home/worsch/ops-bridge/SCOPE.md`
- `activity-core` → `/home/worsch/activity-core/SCOPE.md`
### T04 — SCOPE.md for netkingdom repos
```task
id: CUST-WP-0017-T04
status: done
priority: medium
state_hub_task_id: "a0ac87c5-efb8-4b6f-ae4f-1c924a4324f8"
```
Repos:
- `key-cape` → `/home/worsch/key-cape/SCOPE.md`
- `net-kingdom` → `/home/worsch/net-kingdom/SCOPE.md`
### T05 — SCOPE.md for railiance repos
```task
id: CUST-WP-0017-T05
status: done
priority: medium
state_hub_task_id: "aec409aa-0c2c-49d5-a413-c6191310219f"
```
Repos:
- `railiance-apps` → `/home/worsch/railiance-apps/SCOPE.md`
- `railiance-cluster` → `/home/worsch/railiance-cluster/SCOPE.md`
- `railiance-enablement` → `/home/worsch/railiance-enablement/SCOPE.md`
- `railiance-infra` → `/home/worsch/railiance-infra/SCOPE.md`
- `railiance-platform` → `/home/worsch/railiance-platform/SCOPE.md`
### T06 — SCOPE.md for markitect repos + flag marki-docx
```task
id: CUST-WP-0017-T06
status: done
priority: medium
state_hub_task_id: "69b36f5d-3992-48a0-bee9-14dc344c290d"
```
- `markitect_project` → `/home/worsch/markitect_project/SCOPE.md`
- `marki-docx` → flag_for_human (path `/home/tegwick/marki-docx` not accessible from this machine)
## Verification
1. `get_kaizen_agent("scope-analyst")` via MCP → returns full agent instructions
2. `list_kaizen_agents(category="project-management")` → shows scope-analyst
3. New repo registered with `make register-project` → SCOPE.md stub created at root
4. All accessible repos (13) have SCOPE.md; marki-docx flagged for human