coulomb/state-hub
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(register): modular @-import CLAUDE.md structure (ops-bridge pattern)

Browse Source 
Replaces the monolithic project_claude_md.template with a directory of
7 focused rule files in scripts/project_rules/. register_project.sh now
generates .claude/rules/*.md + a thin CLAUDE.md index of @-imports,
matching the pattern established in ops-bridge.

Template files:
  claude-md.template          — 9-line @-import index
  repo-identity.template      — purpose, domain, slug, topic ID (machine-gen)
  session-protocol.template   — orient/inbox/workplans/brief/close (machine-gen)
  first-session.template      — bootstrap flow; delete once past FSP
  workplan-convention.template— prefix, location; delegates to global CLAUDE.md
  stack-and-commands.template — language/deps/commands (stub, manual)
  architecture.template       — design overview (stub, manual)
  repo-boundary.template      — what this repo does NOT own (stub, manual)

register_project.sh changes:
  - Generates .claude/rules/ from templates with variable substitution
  - Writes thin CLAUDE.md if none exists; appends suggestion comment if one does
  - Step 7: auto-registers this machine's local path via POST /repos/{slug}/paths/
  - project_claude_md.template deprecated to a redirect notice

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-03-16 18:35:02 +01:00
parent 82552b8d59
commit 196e6c5aed
10 changed files with 286 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
scripts/register_project.sh
View File

@@ -4,7 +4,7 @@
# Usage: scripts/register_project.sh <domain> <project_path> [--additional]
# domain: slug of an active domain (e.g. custodian, railiance)
# project_path: absolute path to the project directory
# --additional: add a second repo to an existing domain; skip CLAUDE.md
# --additional: add a second repo to an existing domain; skip CLAUDE.md generation
#
# Example:
# scripts/register_project.sh railiance /home/worsch/railiance
@@ -15,9 +15,12 @@
# 2. Verify the domain exists via GET /domains/{slug}/
# 3. Look up the topic ID for the domain (first active topic)
# 4. Check that state-hub is in ~/.claude.json; warn if missing
# 5. Write $project_path/CLAUDE.custodian.md (suggestion; repo agent integrates → CLAUDE.md)
# 5. Write CLAUDE.md + .claude/rules/*.md (modular @-import structure)
# - If CLAUDE.md already exists, writes .claude/rules/ only and appends
# an @-import comment block to the existing CLAUDE.md
# 6. POST to /repos/ to register the repo
# 7. POST a progress event recording the registration
# 7. POST /repos/{slug}/paths/ to register this machine's local path (host_paths)
# 8. POST a progress event recording the registration
set -euo pipefail
@@ -26,6 +29,7 @@ PROJECT_PATH="${2:-}"
ADDITIONAL="${3:-}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
STATE_HUB_DIR="$(dirname "$SCRIPT_DIR")"
RULES_TEMPLATES_DIR="$SCRIPT_DIR/project_rules"
API_BASE="${API_BASE:-http://127.0.0.1:8000}"
# ── Validate args ──────────────────────────────────────────────────────────────
@@ -45,6 +49,10 @@ fi
PROJECT_NAME="$(basename "$PROJECT_PATH")"
REPO_SLUG="$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-\|-$//g')"
# Derive a workplan prefix: uppercase first token + -WP (e.g. marki-docx → MARKI-WP)
FIRST_TOKEN="$(echo "$REPO_SLUG" | cut -d'-' -f1 | tr '[:lower:]' '[:upper:]')"
WP_PREFIX="${FIRST_TOKEN}-WP"
# ── Step 1: API health check ───────────────────────────────────────────────────
echo "==> Checking API at $API_BASE ..."
if ! curl -sf "$API_BASE/state/health" > /dev/null; then
@@ -58,33 +66,27 @@ echo " API OK"
# ── Step 2: Verify domain exists ───────────────────────────────────────────────
echo "==> Verifying domain '$DOMAIN' ..."
DOMAIN_JSON="$(curl -sf "$API_BASE/domains/$DOMAIN/" 2>/dev/null || echo 'NOT_FOUND')"
if [[ "$DOMAIN_JSON" == "NOT_FOUND" ]] || echo "$DOMAIN_JSON" | python3 -c "import json,sys; d=json.load(sys.stdin); sys.exit(0 if d.get('slug') else 1)" 2>/dev/null; then
if [[ "$DOMAIN_JSON" == "NOT_FOUND" ]] || ! echo "$DOMAIN_JSON" | python3 -c "import json,sys; d=json.load(sys.stdin); sys.exit(0 if d.get('slug') else 1)" 2>/dev/null; then
echo "ERROR: Domain '$DOMAIN' not found in the State Hub."
echo " To create: make add-domain DOMAIN=$DOMAIN NAME=\"<display name>\""
echo " To list available: curl -s $API_BASE/domains/ | python3 -m json.tool"
exit 1
fi
if [[ "$DOMAIN_JSON" == "NOT_FOUND" ]] || ! echo "$DOMAIN_JSON" | python3 -c "import json,sys; d=json.load(sys.stdin); sys.exit(0 if d.get('slug') else 1)" 2>/dev/null; then
echo "ERROR: Domain '$DOMAIN' not found in the State Hub."
echo " To create: make add-domain DOMAIN=$DOMAIN NAME=\"<display name>\""
echo " To list available: curl -s $API_BASE/domains/ | python3 -m json.tool"
exit 1
fi
echo " Domain OK"
# ── Step 3: Look up topic ID ───────────────────────────────────────────────────
echo "==> Looking up topic for domain '$DOMAIN' ..."
TOPICS_JSON="$(curl -sf "$API_BASE/topics/?status=active")"
TOPIC_ID="$(echo "$TOPICS_JSON" | python3 -c "
import json, sys
topics = json.load(sys.stdin)
match = next((t for t in topics if t.get('domain_slug') == sys.argv[1]), None)
if not match:
print('NOT_FOUND')
else:
print(match['id'])
print(match['id'] if match else 'NOT_FOUND')
" "$DOMAIN")"
if [[ "$TOPIC_ID" == "NOT_FOUND" ]]; then
echo "WARNING: No active topic found for domain '$DOMAIN'. CLAUDE.md will omit topic_id."
TOPIC_ID=""
echo "WARNING: No active topic found for domain '$DOMAIN'. repo-identity.md will omit topic_id."
TOPIC_ID="(none)"
else
echo " topic_id: $TOPIC_ID"
fi
@@ -99,124 +101,165 @@ if not f.exists():
print('MISSING_FILE')
else:
d = json.loads(f.read_text())
servers = d.get('mcpServers', {})
print('OK' if 'state-hub' in servers else 'NOT_REGISTERED')
print('OK' if 'state-hub' in d.get('mcpServers', {}) else 'NOT_REGISTERED')
")"
case "$MCP_OK" in
MISSING_FILE) echo "WARNING: ~/.claude.json not found. MCP server not registered." ;;
NOT_REGISTERED) echo "WARNING: 'state-hub' not in ~/.claude.json. See global CLAUDE.md §MCP Server Registration." ;;
*) echo " MCP OK" ;;
esac
if [[ "$MCP_OK" == "MISSING_FILE" ]]; then
echo "WARNING: ~/.claude.json not found. MCP server is not registered."
elif [[ "$MCP_OK" == "NOT_REGISTERED" ]]; then
echo "WARNING: 'state-hub' not found in ~/.claude.json."
echo " To register, see CLAUDE.md MCP Server Registration section."
else
echo " MCP OK"
fi
# ── Step 5: Write CLAUDE.custodian.md (suggestion for the repo agent) ─────────
CLAUDE_MD="$PROJECT_PATH/CLAUDE.md"
SUGGESTION_FILE="$PROJECT_PATH/CLAUDE.custodian.md"
TEMPLATE="$SCRIPT_DIR/project_claude_md.template"
echo "==> Writing custodian suggestion to $SUGGESTION_FILE ..."
{
cat <<'PREAMBLE'
<!--
CUSTODIAN SUGGESTION — generated by `make register-project`
This file was written by the Custodian State Hub registration workflow.
It contains the standard State Hub integration block for this repository.
A Claude Code agent in this repo should:
1. Read this file and the existing CLAUDE.md side by side
2. Integrate the sections below into CLAUDE.md — preserve all existing
project-specific conventions; add or update the hub integration block
3. Delete this file once integration is complete and commit the result
Do NOT add this file to .gitignore. It is a temporary artefact that signals
pending integration work to the repo agent.
-->
PREAMBLE
# ── Helper: render a template with variable substitution ──────────────────────
render_template() {
local tmpl="$1"
sed \
-e "s|{PROJECT_NAME}|$PROJECT_NAME|g" \
-e "s|{PROJECT_DESCRIPTION}|$PROJECT_NAME — (fill in purpose)|g" \
-e "s|{DOMAIN}|$DOMAIN|g" \
-e "s|{TOPIC_ID}|$TOPIC_ID|g" \
-e "s|{REPO_SLUG}|$REPO_SLUG|g" \
"$TEMPLATE"
} > "$SUGGESTION_FILE"
echo " Written. The repo agent should integrate it into CLAUDE.md and delete this file."
-e "s|{WP_PREFIX}|$WP_PREFIX|g" \
"$tmpl"
}
# ── Step 5: Write .claude/rules/ + CLAUDE.md ──────────────────────────────────
if [[ "$ADDITIONAL" != "--additional" ]]; then
RULES_DIR="$PROJECT_PATH/.claude/rules"
CLAUDE_MD="$PROJECT_PATH/CLAUDE.md"
echo "==> Writing .claude/rules/ ..."
mkdir -p "$RULES_DIR"
for rule in repo-identity session-protocol first-session workplan-convention \
stack-and-commands architecture repo-boundary; do
tmpl="$RULES_TEMPLATES_DIR/${rule}.template"
out="$RULES_DIR/${rule}.md"
if [[ -f "$tmpl" ]]; then
render_template "$tmpl" > "$out"
echo " .claude/rules/${rule}.md"
else
echo "WARNING: template missing: $tmpl"
fi
done
if [[ -f "$CLAUDE_MD" ]]; then
echo ""
echo "==> CLAUDE.md already exists — appending @-import suggestion."
cat >> "$CLAUDE_MD" << 'SUGGESTION'
<!-- ── Custodian State Hub Integration (added by register_project.sh) ──────
The rule files in .claude/rules/ contain the full integration content.
Replace this file's body with the @-import index below once you have
merged any existing project-specific content into the rule files.
# PROJECT_NAME — Claude Code Instructions
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
-->
SUGGESTION
echo " Suggestion appended to existing CLAUDE.md."
else
echo "==> Writing CLAUDE.md ..."
render_template "$RULES_TEMPLATES_DIR/claude-md.template" > "$CLAUDE_MD"
echo " CLAUDE.md written."
fi
echo ""
echo "Rule files needing manual content:"
echo " .claude/rules/repo-identity.md — update purpose description"
echo " .claude/rules/stack-and-commands.md — language, deps, dev commands"
echo " .claude/rules/architecture.md — design overview"
echo " .claude/rules/repo-boundary.md — what this repo does NOT own"
echo " .claude/rules/workplan-convention.md — verify WP prefix: $WP_PREFIX"
fi
# ── Step 6: Register repo in State Hub ────────────────────────────────────────
echo ""
echo "==> Registering repo '$PROJECT_NAME' under domain '$DOMAIN' ..."
REPO_PAYLOAD="$(python3 -c "
import json
payload = {
print(json.dumps({
'domain_slug': '$DOMAIN',
'slug': '$REPO_SLUG',
'name': '$PROJECT_NAME',
'local_path': '$PROJECT_PATH',
}
print(json.dumps(payload))
}))
")"
REPO_RESULT="$(curl -sf -X POST "$API_BASE/repos/" \
-H "Content-Type: application/json" \
-d "$REPO_PAYLOAD" 2>/dev/null || echo 'REPO_EXISTS')"
-d "$REPO_PAYLOAD" 2>/dev/null || echo 'CONFLICT')"
if [[ "$REPO_RESULT" == "REPO_EXISTS" ]]; then
echo " Repo '$REPO_SLUG' already registered (or slug conflict) — skipping."
if [[ "$REPO_RESULT" == "CONFLICT" ]]; then
echo " Repo '$REPO_SLUG' already registered — skipping POST."
else
echo " Repo registered: $REPO_SLUG"
fi
# ── Step 7: Record progress event ─────────────────────────────────────────────
# ── Step 7: Register this machine's local path ────────────────────────────────
echo "==> Registering host path for $(hostname) ..."
curl -sf -X POST "$API_BASE/repos/$REPO_SLUG/paths/" \
-H "Content-Type: application/json" \
-d "{\"host\": \"$(hostname)\", \"path\": \"$PROJECT_PATH\"}" > /dev/null \
&& echo " host_paths[$(hostname)] = $PROJECT_PATH"
# ── Step 8: Record progress event ─────────────────────────────────────────────
echo "==> Recording registration event ..."
EVENT_JSON="$(python3 -c "
import json
python3 - <<PYEOF
import json, urllib.request
payload = {
$([ -n '$TOPIC_ID' ] && echo "'topic_id': '$TOPIC_ID',")
'event_type': 'milestone',
'summary': 'Project registered with State Hub: $PROJECT_NAME ($DOMAIN)',
'author': 'custodian',
'detail': {
'project_path': '$PROJECT_PATH',
'suggestion_file': '$SUGGESTION_FILE',
'domain': '$DOMAIN',
'repo_slug': '$REPO_SLUG',
'host': '$(hostname)',
},
}
print(json.dumps(payload))
")"
curl -sf -X POST "$API_BASE/progress/" \
-H "Content-Type: application/json" \
-d "$EVENT_JSON" > /dev/null
$([ "$TOPIC_ID" != "(none)" ] && echo "payload['topic_id'] = '$TOPIC_ID'" || echo "")
req = urllib.request.Request(
'$API_BASE/progress/',
data=json.dumps(payload).encode(),
headers={'Content-Type': 'application/json'},
method='POST',
)
urllib.request.urlopen(req)
PYEOF
echo " Event recorded."
echo ""
echo "Registration complete!"
echo " Project: $PROJECT_NAME"
echo " Domain: $DOMAIN"
echo " Repo slug: $REPO_SLUG"
[[ -n "$TOPIC_ID" ]] && echo " Topic ID: $TOPIC_ID"
echo " Suggestion: $SUGGESTION_FILE (repo agent should integrate → CLAUDE.md)"
[[ "$TOPIC_ID" != "(none)" ]] && echo " Topic ID: $TOPIC_ID"
echo " WP prefix: $WP_PREFIX (update .claude/rules/workplan-convention.md if wrong)"
echo ""
echo "Next: restart Claude Code for the MCP server to be available in this project."
echo "Next steps:"
echo " 1. Fill in TODO stubs in .claude/rules/"
echo " 2. Restart Claude Code for the MCP server to be available in this project"
# ── Optional: SBOM ingest ─────────────────────────────────────────────────────
if [[ "$ADDITIONAL" != "--additional" ]]; then
echo ""
read -r -p "==> Run SBOM ingest now? (auto-detects lockfile in $PROJECT_PATH) [y/N] " INGEST_NOW </dev/tty || INGEST_NOW="N"
read -r -p "==> Run SBOM ingest now? [y/N] " INGEST_NOW </dev/tty || INGEST_NOW="N"
if [[ "$INGEST_NOW" =~ ^[Yy]$ ]]; then
echo "==> Ingesting SBOM for '$REPO_SLUG' ..."
INGEST_UV="$STATE_HUB_DIR/.venv/bin/python"
if [[ -x "$INGEST_UV" ]]; then
"$INGEST_UV" "$SCRIPT_DIR/ingest_sbom.py" \
INGEST_PY="$STATE_HUB_DIR/.venv/bin/python"
if [[ -x "$INGEST_PY" ]]; then
"$INGEST_PY" "$SCRIPT_DIR/ingest_sbom.py" \
--repo "$REPO_SLUG" \
--repo-path "$PROJECT_PATH" \
--api-base "$API_BASE" && echo " SBOM ingested." || echo " SBOM ingest failed (non-fatal)."
else
echo " Skipping: .venv not found. Run 'make install' first, then 'make ingest-sbom REPO=$REPO_SLUG'."
echo " Skipping: .venv not found. Run 'make install' then 'make ingest-sbom REPO=$REPO_SLUG'."
fi
fi
fi