# 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 -- <paths>` 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 <index>` (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.