From 101244bd1dd093b6279a3fa87c6b99a1f3f71f61 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 16 Mar 2026 18:11:52 +0100 Subject: [PATCH] refactor(docs): split CLAUDE.md into scoped rules files under .claude/rules/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each concern (identity, session protocol, workplan convention, stack, architecture, repo boundary) now lives in its own file with a single responsibility. CLAUDE.md becomes a thin @-import integrator. Removes Ralph Loop duplication — global ~/.claude/CLAUDE.md remains authoritative. Co-Authored-By: Claude Sonnet 4.6 --- .claude/rules/architecture.md | 31 +++++++ .claude/rules/repo-boundary.md | 6 ++ .claude/rules/repo-identity.md | 7 ++ .claude/rules/session-protocol.md | 24 +++++ .claude/rules/stack-and-commands.md | 46 +++++++++ .claude/rules/workplan-convention.md | 6 ++ CLAUDE.md | 133 ++------------------------- 7 files changed, 126 insertions(+), 127 deletions(-) create mode 100644 .claude/rules/architecture.md create mode 100644 .claude/rules/repo-boundary.md create mode 100644 .claude/rules/repo-identity.md create mode 100644 .claude/rules/session-protocol.md create mode 100644 .claude/rules/stack-and-commands.md create mode 100644 .claude/rules/workplan-convention.md diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 0000000..e302e1d --- /dev/null +++ b/.claude/rules/architecture.md @@ -0,0 +1,31 @@ +## Architecture + +OpsBridge has two logical components: + +**1. OpsBridge — tunnel lifecycle manager** (this repo) +Manages named SSH reverse tunnels defined in `~/.config/bridge/tunnels.yaml`. +Each tunnel runs in a subprocess with a reconnect backoff loop; PIDs are tracked +in `~/.local/state/bridge/`. Bridge states: `stopped → starting → connected → +degraded → failed`. The `degraded` state means SSH is up but the optional HTTP +health check is failing. + +**2. OpsCatalog — operations knowledge repository** (planned extension) +A Git-backed YAML catalog of operations domains, targets, bridges, and actor +classes. OpsBridge consumes this catalog to resolve bridge identifiers and +orient operators. Schema examples are in `wiki/OpsCatalogSpecification.md`. +The catalog layout follows: `opscatalog/domains//{domain.yaml, +targets/, bridges/, docs/}`. + +Key design constraints: +- OpsBridge owns lifecycle management only; it does not own identity/credentials +- Each tunnel is identified by name (e.g. `state-hub-coulombcore`); names used + in config, CLI args, and log filenames must stay consistent +- Actor attribution (human operator vs. automation agent) is tracked per bridge + for audit log traceability (FRS §5.7) + +Specification docs are in `wiki/`: PRD (`OpsBridgePrd.md`), FRS +(`OpsBridgeFrs.md`), and OpsCatalog spec (`OpsCatalogSpecification.md`). + +## Quick Reference + +`~/the-custodian/state-hub/mcp_server/TOOLS.md` diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..85cfd71 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,6 @@ +## Repo boundary + +This repo owns **tunnel lifecycle management only**. It does not own: +- State hub code → `the-custodian/state-hub/` +- SSH key management → `railiance-infra/` (S1) or user dotfiles +- Ansible/provisioning → `railiance-infra/` diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..2a0576d --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,7 @@ +**Purpose:** SSH reverse tunnel lifecycle manager. Keeps remote execution +environments (COULOMBCORE, Railiance nodes) connected to the local Custodian +State Hub so Claude Code sessions on those machines have full MCP connectivity. + +**Domain:** custodian +**Repo slug:** ops-bridge +**Repo ID:** 1bf99f56-6e94-4379-a9ea-295a4c181889 diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..7c1242d --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,24 @@ +## Custodian State Hub Integration + +State Hub: http://127.0.0.1:8000 + +### Session Protocol + +**Step 1 — Orient** +``` +get_domain_summary("custodian") +``` + +**Step 2 — Scan workplans** +``` +ls workplans/ +``` + +**During work:** use `record_decision()`, `add_progress_event()`, `resolve_decision()`. + +**Session close:** `add_progress_event()` with workstream_id. + +If workplan files were modified, run from `~/the-custodian/state-hub/`: +```bash +make fix-consistency REPO=ops-bridge +``` diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md new file mode 100644 index 0000000..db04aa8 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,46 @@ +## What this repo builds + +A CLI tool (`bridge`) that manages named SSH reverse tunnels: + +``` +bridge up [TUNNEL] # start tunnel(s) +bridge down [TUNNEL] # stop tunnel(s) +bridge restart [TUNNEL] # restart tunnel(s) +bridge status # show all tunnels: state, uptime, last health check +bridge logs [TUNNEL] # tail reconnect log +``` + +Config file: `~/.config/bridge/tunnels.yaml` + +Each tunnel: +- Named (e.g. `state-hub-coulombcore`) +- Reverse SSH port-forward: `ssh -R remote_port:127.0.0.1:local_port host` +- Auto-reconnects on drop (backoff loop) +- Optional HTTP health check to confirm the forwarded service is reachable + +PRD: `workplans/BRIDGE-WP-0001-initial-implementation.md` + +## Stack + +- **Language:** Python 3.11+ +- **CLI framework:** Typer +- **Dependencies:** typer, pyyaml, httpx +- **Packaging:** `uv tool install` (single command install, no venv activation) +- **No system daemons** — process management is internal, PID tracked in + `~/.local/state/bridge/` + +## Dev Commands + +```bash +# Install locally for development +uv tool install -e . + +# Run tests +uv run pytest + +# Run a single test +uv run pytest tests/test_tunnel.py::test_name -v + +# Lint +uv run ruff check . +``` diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..67cd970 --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,6 @@ +### Workplan Convention (ADR-001) + +File location: `workplans/BRIDGE-WP-NNNN-.md` +Prefix: `BRIDGE-WP` + + diff --git a/CLAUDE.md b/CLAUDE.md index fdb1405..4cc7212 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,129 +1,8 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - # ops-bridge — Claude Code Instructions -**Purpose:** SSH reverse tunnel lifecycle manager. Keeps remote execution -environments (COULOMBCORE, Railiance nodes) connected to the local Custodian -State Hub so Claude Code sessions on those machines have full MCP connectivity. - -**Domain:** custodian -**Repo slug:** ops-bridge -**Repo ID:** 1bf99f56-6e94-4379-a9ea-295a4c181889 - -## Custodian State Hub Integration - -State Hub: http://127.0.0.1:8000 - -### Session Protocol - -**Step 1 — Orient** -``` -get_domain_summary("custodian") -``` - -**Step 2 — Scan workplans** -``` -ls workplans/ -``` - -**During work:** use `record_decision()`, `add_progress_event()`, `resolve_decision()`. - -**Session close:** `add_progress_event()` with workstream_id. - -If workplan files were modified, run from `~/the-custodian/state-hub/`: -```bash -make fix-consistency REPO=ops-bridge -``` - -### Workplan Convention (ADR-001) - -File location: `workplans/BRIDGE-WP-NNNN-.md` -Prefix: `BRIDGE-WP` - -## What this repo builds - -A CLI tool (`bridge`) that manages named SSH reverse tunnels: - -``` -bridge up [TUNNEL] # start tunnel(s) -bridge down [TUNNEL] # stop tunnel(s) -bridge restart [TUNNEL] # restart tunnel(s) -bridge status # show all tunnels: state, uptime, last health check -bridge logs [TUNNEL] # tail reconnect log -``` - -Config file: `~/.config/bridge/tunnels.yaml` - -Each tunnel: -- Named (e.g. `state-hub-coulombcore`) -- Reverse SSH port-forward: `ssh -R remote_port:127.0.0.1:local_port host` -- Auto-reconnects on drop (backoff loop) -- Optional HTTP health check to confirm the forwarded service is reachable - -PRD: `workplans/BRIDGE-WP-0001-initial-implementation.md` - -## Stack - -- **Language:** Python 3.11+ -- **CLI framework:** Typer -- **Dependencies:** typer, pyyaml, httpx -- **Packaging:** `uv tool install` (single command install, no venv activation) -- **No system daemons** — process management is internal, PID tracked in - `~/.local/state/bridge/` - -## Dev Commands - -```bash -# Install locally for development -uv tool install -e . - -# Run tests -uv run pytest - -# Run a single test -uv run pytest tests/test_tunnel.py::test_name -v - -# Lint -uv run ruff check . -``` - -## Architecture - -OpsBridge has two logical components: - -**1. OpsBridge — tunnel lifecycle manager** (this repo) -Manages named SSH reverse tunnels defined in `~/.config/bridge/tunnels.yaml`. -Each tunnel runs in a subprocess with a reconnect backoff loop; PIDs are tracked -in `~/.local/state/bridge/`. Bridge states: `stopped → starting → connected → -degraded → failed`. The `degraded` state means SSH is up but the optional HTTP -health check is failing. - -**2. OpsCatalog — operations knowledge repository** (planned extension) -A Git-backed YAML catalog of operations domains, targets, bridges, and actor -classes. OpsBridge consumes this catalog to resolve bridge identifiers and -orient operators. Schema examples are in `wiki/OpsCatalogSpecification.md`. -The catalog layout follows: `opscatalog/domains//{domain.yaml, -targets/, bridges/, docs/}`. - -Key design constraints: -- OpsBridge owns lifecycle management only; it does not own identity/credentials -- Each tunnel is identified by name (e.g. `state-hub-coulombcore`); names used - in config, CLI args, and log filenames must stay consistent -- Actor attribution (human operator vs. automation agent) is tracked per bridge - for audit log traceability (FRS §5.7) - -Specification docs are in `wiki/`: PRD (`OpsBridgePrd.md`), FRS -(`OpsBridgeFrs.md`), and OpsCatalog spec (`OpsCatalogSpecification.md`). - -## Repo boundary - -This repo owns **tunnel lifecycle management only**. It does not own: -- State hub code → `the-custodian/state-hub/` -- SSH key management → `railiance-infra/` (S1) or user dotfiles -- Ansible/provisioning → `railiance-infra/` - -## Quick Reference - -`~/the-custodian/state-hub/mcp_server/TOOLS.md` +@.claude/rules/repo-identity.md +@.claude/rules/session-protocol.md +@.claude/rules/workplan-convention.md +@.claude/rules/stack-and-commands.md +@.claude/rules/architecture.md +@.claude/rules/repo-boundary.md