From d86b3cec14c20169151da3c8d4f5a2b63aa27ad8 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
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 <noreply@anthropic.com>
---
 mcp_server/TOOLS.md                      |   1 +
 scripts/project_rules/claude-md.template |   1 +
 scripts/project_rules/scope.template     | 120 +++++++++++++++++++++++
 scripts/register_project.sh              |   9 ++
 4 files changed, 131 insertions(+)
 create mode 100644 scripts/project_rules/scope.template

diff --git a/mcp_server/TOOLS.md b/mcp_server/TOOLS.md
index 7d42f0e..218fbcb 100644
--- a/mcp_server/TOOLS.md
+++ b/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/scripts/project_rules/claude-md.template b/scripts/project_rules/claude-md.template
index 5d4c8c6..bb274fb 100644
--- a/scripts/project_rules/claude-md.template
+++ b/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/scripts/project_rules/scope.template b/scripts/project_rules/scope.template
new file mode 100644
index 0000000..605b284
--- /dev/null
+++ b/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
+
+<!-- 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. -->
diff --git a/scripts/register_project.sh b/scripts/register_project.sh
index d257790..849358b 100755
--- a/scripts/register_project.sh
+++ b/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."