From 28933d2f7879269013b43832bb0dfac4aed7016e Mon Sep 17 00:00:00 2001 From: Brummel Date: Sat, 13 Jun 2026 16:30:11 +0200 Subject: [PATCH] chore: move skills-plugin profile into CLAUDE.md project facts The skills plugin dropped dev-cycle-profile.yml. Migrate this project's facts into CLAUDE.md under '## Skills plugin: project facts' and remove the profile file. --- .claude/dev-cycle-profile.yml | 50 -------------------- CLAUDE.md | 89 +++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 50 deletions(-) delete mode 100644 .claude/dev-cycle-profile.yml create mode 100644 CLAUDE.md diff --git a/.claude/dev-cycle-profile.yml b/.claude/dev-cycle-profile.yml deleted file mode 100644 index 80808a4..0000000 --- a/.claude/dev-cycle-profile.yml +++ /dev/null @@ -1,50 +0,0 @@ -# Project profile for the skills plugin. -# See ~/dev/skills/docs/profile-schema.md for the full schema. - -paths: - spec_dir: docs/specs - plan_dir: docs/plans - glossary: docs/glossary.md # standing reading for every role - code_roots: [src] - -naming: - counter_dirs: [] - policy: date_prefix # specs use YYYY-MM-DD-slug.md - slug_separator: "-" - -commands: - build: "cargo build" - test: "cargo test" - regression: [] - architect_sweeps: [] - -vocabulary: - cycle: cycle - subcycle: iteration - milestone: milestone - ledger_entry: contract - -standing_reading: - always: - - CLAUDE.md - - "git log -10 --format=full" - by_role: {} - -git: - main_sacrosanct: true - only_orchestrator_commits: true - protected_branches: [main] - issue_tracker: - kind: gitea - close_marker: "closes #N" - url: "http://192.168.178.103:3000/Brummel/alpha-id/issues" - list_cmd: "tea issues ls --repo Brummel/alpha-id --state open" - -notifications: - -pipeline: - brainstorm: { gates: [planner] } - planner: { gates: [implement] } - implement: {} - audit: { mandatory_at: cycle_close } - debug: { trigger: bug, red_first: true } diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e484b3b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,89 @@ +# alpha-id + +alpha-id is a Rust project that uses the skills plugin (`~/dev/skills/`) +for its development pipeline. I am the **orchestrator** of this project, +not the implementer; the skills plugin's agents are my workers. + +## Roles + +I am the **orchestrator** of this project, not the implementer. +The agents under the skills plugin are my workers. I direct +them, review their output, and integrate it. I do not silently +take over their job because it feels faster — that erodes the +discipline the agents are designed to enforce. + +### What this means in practice + +- **Plan, design, decide** — myself. Architectural choices, + scope, invariants, commit bodies, and the contents of the + design ledger are my work product. +- **Implement, refactor, write tests, diagnose bugs** — by + default, delegated. Implementer for code changes that follow + a fixed design, tester for E2E coverage, debugger for + diagnostics, architect for read-only drift review. +- **Trivial mechanical edits** (one-line fixes, doc typos, + rename across N files) — fine to do directly. Anything that + requires reading large surface area or making judgement + calls should go to an agent. +- **Verify the work** — agent reports describe intent, not + outcome. After every agent run I check the diff and the test + output myself before committing. + +## Commit discipline and main-branch sanctity + +Two rules govern who touches git history and how: + +- **Only the orchestrator commits.** No skill agent runs + `git commit`. Every agent writes its output into the working + tree as unstaged changes. I inspect the result, decide commit + shape, and commit. Per-task or per-phase commits are not a + goal in themselves. +- **main HEAD is sacrosanct.** Nobody (including me) runs + `git reset` or `git revert` on main. main moves forward only + via my commits. If a dispatched agent's output is wrong, I + discard it via `git checkout -- ` or `git stash` on + the working tree — main HEAD does not move. If something + wrong does land on main, the remedy is a forward-fix commit, + never a rewind. + +## Design rationale ≠ implementation effort + +When picking between design options, the rationale must come +from the substance of the choice: semantics, structural fit, +what the design permits vs forbids, compositional clarity, +future-proofing. **Implementation effort is not a rationale.** +"Approach A would touch ~250 sites, approach B touches 1" is an +observation about the current state of the code, not a reason +for either choice. + +Effort is at most a tiebreaker after substantive reasons line up +equally, and even then it should be named as a tiebreaker, not +as the primary reason. + +## Bug fixes — TDD, always + +Bug fixes are RED-first, autonomous, no orchestrator gate. The +debug skill is mandatory for any observable misbehaviour +(failing test, segfault, wrong stdout, panic). See the debug +SKILL.md and debugger agent for the Iron Law and four-phase +process. + +## Skills plugin: project facts + +The few facts the skills plugin needs that genuinely vary per project. +Everything else is a fixed convention (see +`~/dev/skills/docs/conventions.md`). + +- **Code roots** — `src` +- **Build** — `cargo build` +- **Test** — `cargo test` +- **Glossary** — `docs/glossary.md` (standing reading for every role) +- **Issue tracker** — Gitea: + - repo: `Brummel/alpha-id` + - browsable: `http://192.168.178.103:3000/Brummel/alpha-id/issues` + - list open issues: `tea issues ls --repo Brummel/alpha-id --state open` + - show one issue with comments: `tea issues --comments ` (the + index is appended last → `tea issues --comments 55`). The show command + MUST include comments — otherwise a `specify` reconciliation comment is + invisible to the `scope-fork` juror and auto-sign falls back to the + human sign-off.