generated from coulomb/repo-seed
refactor(docs): split CLAUDE.md into scoped rules files under .claude/rules/
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 <noreply@anthropic.com>
This commit is contained in:
31
.claude/rules/architecture.md
Normal file
31
.claude/rules/architecture.md
Normal file
@@ -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>/{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`
|
||||
6
.claude/rules/repo-boundary.md
Normal file
6
.claude/rules/repo-boundary.md
Normal file
@@ -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/`
|
||||
7
.claude/rules/repo-identity.md
Normal file
7
.claude/rules/repo-identity.md
Normal file
@@ -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
|
||||
24
.claude/rules/session-protocol.md
Normal file
24
.claude/rules/session-protocol.md
Normal file
@@ -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
|
||||
```
|
||||
46
.claude/rules/stack-and-commands.md
Normal file
46
.claude/rules/stack-and-commands.md
Normal file
@@ -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 .
|
||||
```
|
||||
6
.claude/rules/workplan-convention.md
Normal file
6
.claude/rules/workplan-convention.md
Normal file
@@ -0,0 +1,6 @@
|
||||
### Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/BRIDGE-WP-NNNN-<slug>.md`
|
||||
Prefix: `BRIDGE-WP`
|
||||
|
||||
<!-- Ralph Loop rules are defined globally in ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||
133
CLAUDE.md
133
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-<slug>.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>/{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
|
||||
|
||||
Reference in New Issue
Block a user