Skip to content

CLAUDE.md

Latest commit

 

History

History
57 lines (44 loc) · 2.7 KB

CLAUDE.md

File metadata and controls

57 lines (44 loc) · 2.7 KB
Raw

CLAUDE.md — operating guide for this control plane

This is a control-plane repo, not a code repo. When you work here you are helping orchestrate and map projects, not shipping application code.

What this repo is

  • registry/owners.txt — the GitHub owners the map covers, one per line.
  • registry/repos.generated.yaml — generated index of every repo under those owners. Never hand-edit it. To refresh, run ./scripts/sync-registry.sh.
  • registry/context/<repo>.md — the human-owned truth about a project: what it is, how it relates to others, current goals. Read the relevant one before reasoning about a project. Keep them short and current.
  • orchestration/playbooks/<name>.md — reusable recipes for running thurbox.
  • orchestration/runs/<date>-<slug>.md — a log per orchestration run.

Orchestration model

This repo drives thurbox directly. Do not invoke an external orchestrate skill or any other outside orchestration workflow — the control plane is deliberately self-contained.

The loop:

  1. Clarify the goal. Pick a playbook in orchestration/playbooks/, or write one.
  2. Open a run log from orchestration/runs/_TEMPLATE.md, named <YYYY-MM-DD>-<slug>.md.
  3. For each unit of work, launch a thurbox worker session with one self-contained prompt. Workers share no context with you and none with each other, so each prompt states the goal, the constraints, and what "done" looks like, from scratch.
  4. Each worker targets a real repo and its own git worktree — the control plane holds the plan and the log, never the workers' branches.
  5. Record every session (name, repo, prompt intent, outcome, PR/artifact) in the run log as it happens. The run log is the source of truth for what happened.
  6. Review the PRs. Delete each session as it closes out.

.claude/skills/thurbox-session/ is the detailed driving surface for step 3: spawning, prompting, completion detection, cleanup. Use it.

Keeping the map honest

  • After adding, renaming, or archiving a repo — or after editing registry/owners.txt — run ./scripts/sync-registry.sh locally and push. Never edit the generated YAML directly.
  • When you learn something durable about a project (its purpose shifted, a new dependency between repos, a parked goal), update its registry/context/<repo>.md. That file is where judgement lives.

Gates

CI only runs on pull requests, and routine control-plane changes go straight to main. So gate locally before you push: shellcheck scripts/*.sh, and parse every YAML file.

extension.toml is generated by ./scripts/install-extension.sh and gitignored. Edit extension.toml.in instead, and re-run the installer.