From 402a04807f447364f30bbd4d505549bedbb25704 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 17 Mar 2026 23:10:30 +0100 Subject: [PATCH] feat(CUST-WP-0017): scope-analyst agent + SCOPE.md template + coverage 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 --- SCOPE.md | 102 +++++ agents/agent-scope-analyst.md | 355 ++++++++++++++++++ state-hub/mcp_server/TOOLS.md | 1 + .../scripts/project_rules/claude-md.template | 1 + .../scripts/project_rules/scope.template | 120 ++++++ state-hub/scripts/register_project.sh | 9 + ...UST-WP-0017-scope-md-agent-and-coverage.md | 122 ++++++ 7 files changed, 710 insertions(+) create mode 100644 SCOPE.md create mode 100644 agents/agent-scope-analyst.md create mode 100644 state-hub/scripts/project_rules/scope.template create mode 100644 workplans/CUST-WP-0017-scope-md-agent-and-coverage.md diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..d810551 --- /dev/null +++ b/SCOPE.md @@ -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. diff --git a/agents/agent-scope-analyst.md b/agents/agent-scope-analyst.md new file mode 100644 index 0000000..b8d491c --- /dev/null +++ b/agents/agent-scope-analyst.md @@ -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 + + + +--- + +## Core Idea + + + + +--- + +## In Scope + + + + +- +- +- + +--- + +## Out of Scope + + + + +- +- +- + +--- + +## Relevant When + + + +- +- +- + +--- + +## Not Relevant When + + + +- +- +- + +--- + +## Current State + + + +- Status: +- Implementation: +- Stability: +- Usage: + +--- + +## How It Fits + + + +- Upstream dependencies: +- Downstream consumers: +- Often used with: + +--- + +## Terminology + + + + +- Preferred terms: +- Also known as: +- Potentially confusing terms: + +--- + +## Related / Overlapping Repositories + + + +- — + +--- + +## Getting Oriented + + + +- Start with: +- Key files / directories: +- Entry points: + +--- + +## Notes + + +``` + +--- + +# 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. diff --git a/state-hub/mcp_server/TOOLS.md b/state-hub/mcp_server/TOOLS.md index 7d42f0e..218fbcb 100644 --- a/state-hub/mcp_server/TOOLS.md +++ b/state-hub/mcp_server/TOOLS.md @@ -147,6 +147,7 @@ instruction set — load it and follow the instructions it contains. | `requirements-engineering` | process | Prevent interface/mock mismatches upfront | | `keepaTodofile` | process | Maintain TODO.md during work | | `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 | --- diff --git a/state-hub/scripts/project_rules/claude-md.template b/state-hub/scripts/project_rules/claude-md.template index 5d4c8c6..bb274fb 100644 --- a/state-hub/scripts/project_rules/claude-md.template +++ b/state-hub/scripts/project_rules/claude-md.template @@ -1,5 +1,6 @@ # {PROJECT_NAME} — Claude Code Instructions +@SCOPE.md @.claude/rules/repo-identity.md @.claude/rules/session-protocol.md @.claude/rules/first-session.md diff --git a/state-hub/scripts/project_rules/scope.template b/state-hub/scripts/project_rules/scope.template new file mode 100644 index 0000000..605b284 --- /dev/null +++ b/state-hub/scripts/project_rules/scope.template @@ -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 + + + + +--- + +## Core Idea + + + + +--- + +## In Scope + + + + +- +- +- + +--- + +## Out of Scope + + + + +- +- +- + +--- + +## Relevant When + + + +- +- +- + +--- + +## Not Relevant When + + + +- +- +- + +--- + +## Current State + + + +- Status: +- Implementation: +- Stability: +- Usage: + + + +--- + +## How It Fits + + + +- Upstream dependencies: +- Downstream consumers: +- Often used with: + +--- + +## Terminology + + + + +- Preferred terms: +- Also known as: +- Potentially confusing terms: + +--- + +## Related / Overlapping Repositories + + + + +- — + +--- + +## Getting Oriented + + + +- Start with: +- Key files / directories: +- Entry points: + +--- + +## Notes + + diff --git a/state-hub/scripts/register_project.sh b/state-hub/scripts/register_project.sh index d257790..849358b 100755 --- a/state-hub/scripts/register_project.sh +++ b/state-hub/scripts/register_project.sh @@ -142,6 +142,15 @@ if [[ "$ADDITIONAL" != "--additional" ]]; then fi 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 echo "" echo "==> CLAUDE.md already exists — appending @-import suggestion." diff --git a/workplans/CUST-WP-0017-scope-md-agent-and-coverage.md b/workplans/CUST-WP-0017-scope-md-agent-and-coverage.md new file mode 100644 index 0000000..69f871a --- /dev/null +++ b/workplans/CUST-WP-0017-scope-md-agent-and-coverage.md @@ -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