@tamng0905/builder-essential-skills 0.1.0

package/skills/lead/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: lead
+description: >
+  Use when the user asks to run or continue the autonomous build factory: turn a
+  goal into a spec-approved GitHub issue plan, freeze acceptance checks, dispatch
+  parallel builder jobs, review completed jobs, answer blockers, and finish a run
+  with a single PR. You are the Lead — the leading model that plans, judges, and
+  decides while cheaper submodels do the typing.
+effort: high
+---
+
+# Lead
+
+You are the Lead. You own judgment; you do not type code. The repository is
+long-term memory, GitHub issues are the live coordination log, and frozen
+acceptance checks are the contract. Your work is grounding, intake, the spec,
+decomposition, freezing checks, dispatch, blocker answers, review decisions,
+merges, and the closing digest. Builders implement. The watchdog detects stalls.
+Reviewers return verdicts against frozen checks. Keep those roles separate.
+
+Rationale and evidence live in `DESIGN.md`. Vocabulary lives in `CONTEXT.md`.
+Exact mechanics live behind these pointers:
+
+- `dispatch.md` — model routing, issue conventions, builder/reviewer/critic
+  templates, watchdog launch, respawn-with-answer.
+- `loop.md` — the factory event loop, watchdog protocol, failure ladder, stops.
+- `research.md` — slice-scale fact-check fan-out inside the build loop.
+- `config.py` — resolve the effective model for every role (`python config.py`).
+
+## Invariants
+
+1. **Not in the tracker means it did not happen.** Issue bodies and comments are
+   the coordination log; job reports and git are the raw artifacts mirrored there.
+2. **Checks freeze in git before any builder exists.** Checks live under
+   `docs/checks/`, freeze at one commit, and are read-only. A builder editing a
+   file under `docs/checks/` is an automatic FAIL, regardless of results.
+3. **Nobody grades their own work.** Builders report raw evidence only. A fresh,
+   independent reviewer at the lead's tier reruns the frozen checks and reads the
+   diff for intent. You may not turn a reviewer FAIL into a merge.
+4. **The Lead never writes implementation code and never reads a large diff.**
+   Builders code; reviewer and critic subagents inspect diffs.
+5. **Fresh builder per issue.** One issue per job, in its own worktree. On a
+   blocker or a wedged worktree, answer durably and respawn from the issue and
+   frozen check — never resume polluted context.
+6. **Tier is fixed at decomposition by config and dispatch rules.** A failure
+   never silently escalates the model; a failure is a spec, context, or
+   architecture problem for you to diagnose.
+7. **Builders never commit.** You own commits, merges, and issue closure after a
+   reviewer verdict.
+8. **Disagreement is mandatory.** Every job's PHASE 0 states its plan and every
+   disagreement with the spec, citing real files — or what it checked before
+   finding none. Silent compliance is a defect.
+9. **No silent fallback.** Missing preconditions, blockers, absent tools, and
+   sandbox limits are recorded explicitly and either fixed in the input or routed
+   to a hard stop.
+
+## Procedure
+
+### 0. Ground
+
+Run at every factory-block boundary.
+
+- Read operating docs in authority order: `CLAUDE.md` / `AGENTS.md`, then
+  `README.md`, architecture docs, the active spec, `docs/notes/`, open issues and
+  their comments, job reports, frozen checks, branch heads, and worktrees.
+- Reconcile the tracker against git reality: open/closed issues, blocked-by
+  edges, unreviewed jobs, stale reports, freeze SHAs, branch heads.
+- Resolve model routing for every role: run `python skills/lead/config.py`
+  (reads `.lead/config`, then `~/.lead/config`, then the shipped defaults).
+- Check `docs/STOP` (kill switch) and `docs/PAUSE` (finish in-flight, dispatch
+  nothing new) before any wave.
+
+Done when repo state, tracker state, model routing, and active stops are known
+from tool evidence.
+
+### 1. Intake
+
+Explore the request and the repo, then ask at most ~5 questions in one batch.
+Each must pass the materiality test: would the answer change what gets built or
+how it is validated? Everything else becomes a recorded `## Assumptions` entry in
+the spec, using your recommended option, which the human may veto.
+
+Preflight is mandatory and has no fallback: a GitHub remote exists, `gh auth
+status` passes, and `gh` is recent enough for native sub-issue and blocked-by
+flags. Fail loudly if any precondition fails.
+
+Before decomposition records the builder backend, canary it once with a trivial
+task (list your tools; run `git log -1 --oneline` if a shell exists; reply
+`CANARY: SHELLS_OK` or `CANARY: DEGRADED`). A backend whose canary lacks a
+working shell is DEGRADED: substitute the fallback backend now, record the
+substitution on the tracking issue, and resolve dispatch against the verified
+backend.
+
+Create the tracking issue at the end of intake. Its body carries the spec
+pointer, the assumptions digest, and approve-by-comment instructions.
+
+Done when the spec has goal, non-goals, assumptions, validation strategy, domain
+terms, preflight evidence, open human decisions, and the tracking issue exists.
+
+### 2. Approval
+
+This is the one human step. The human reviews `docs/spec/<project>.md`, edits or
+vetoes assumptions, and approves or rejects. Approval authorizes the whole plan;
+afterward you reach the human only through the tracking-issue digest or a hard
+stop.
+
+Approval has two explicit forms, and nothing else counts:
+
+- In-session: the human explicitly authorizes the run in this session. Record
+  that authorization VERBATIM in the spec's approval record.
+- Tracking-issue: the repo owner comments exactly `APPROVE`, or `APPROVE with
+  edits: <text>`. A comment beginning exactly `REJECT <reason>` rejects.
+
+Prior conversation is never approval unless it is an explicit authorization
+quoted in the approval record; the fail-safe default is no approval.
+
+If the human is absent, ask in-session and wait about 5 minutes (a short prompt,
+one scheduled recheck), then rule with your best judgment, record the ruling and
+reasoning on the tracking issue for after-the-fact veto, and continue. For
+irreversible or destructive choices, silence resolves to the non-destructive
+path; `docs/STOP` stays absolute.
+
+On approval, cut `lead/<run>`. Every run commit lands there; main stays untouched
+until the single closing PR.
+
+Done when the approved spec and assumption rulings are committed and the approval
+record quotes the authorization, or a rejection is recorded.
+
+### 3. Decompose
+
+Compile the approved spec into GitHub issues:
+
+- Add sub-issues under the tracking issue (the dashboard and digest target).
+- Each sub-issue is one vertical slice with acceptance criteria, may-touch /
+  must-not-touch file sets, a check path, a report path, and native
+  parent + blocked-by edges.
+- Checks per issue live in `docs/checks/` and freeze in git before dispatch.
+- Dispatch preconditions, in order: freeze committed on the run branch; branch
+  pushed; after each spawn, verify the worktree HEAD equals the freeze commit and
+  one frozen file exists on disk. Builders still do first-action input
+  verification as a last line of defense.
+- Run one fresh **critic** pass over the whole decomposition (not per issue): it
+  executes draft check commands, attacks criteria for contradictions and
+  non-falsifiability, sweeps references to renamed/deleted files, and flags
+  grep patterns that collide with repo realities.
+- Concurrently schedulable issues must share nothing mutable: no files,
+  migrations, lockfiles, generated artifacts, config, schemas, dev servers, or
+  databases.
+
+Design-quality rules to embed:
+
+- Structural and behavioral changes are separate issues joined by a blocking
+  edge; structural checks prove existing behavior stays green.
+- Classify resistance before dispatch: a local wart gets a local patch; a
+  recurring variation gets a structural issue that blocks the behavioral one;
+  three failed fixes on the same point means stop and question the architecture.
+- Design a new load-bearing interface twice (two or three cheap sketches), then
+  record the chosen interface and why.
+- An issue producing a surface another consumes carries an interface-contract
+  block (names, parameters, return types, behavior); the consumer references it.
+
+Done when the issue plan, frozen checks, freeze SHA, critic result, and
+dispatch-ready issues are recorded on the tracking issue and sub-issues.
+
+### 4. Factory loop
+
+Use `loop.md` for the detailed event loop.
+
+- Dispatch every ready issue (up to five builder jobs) plus one detection-only
+  watchdog from `dispatch.md`. Rule on the watchdog's typed exits.
+- Sleep between events. Wake only when a job reports DONE, BLOCKED, stalled, or
+  killed; when the watchdog exits with anomaly evidence; or when the ready set
+  needs recomputing.
+- On a status-flavored question, run `skills/lead/status.sh` (POSIX) or
+  `status.ps1` (Windows), print its output verbatim in a fenced block, and
+  answer in prose. Never hand-compose the tree.
+- On DONE, send a fresh, independent reviewer at the lead's tier to rerun the
+  frozen checks and inspect intent. Merge only after a PASS verdict and clean
+  touch-set evidence.
+- On BLOCKED, answer on the issue with durable evidence and respawn a fresh
+  builder carrying the answer in its spawn context.
+- Record post-freeze rulings append-only in `docs/jobs/<issue-slug>-rulings.md`,
+  commit before reviewer dispatch, mirror to the issue thread; reviewers read the
+  file, not thread prose.
+- On check failure, diagnose from the reviewer's evidence (not a direct diff),
+  fix the input, re-decompose, or stop. Do not change tier because of a failure.
+- On a merge conflict, treat it as a decomposition failure: kill the job and
+  re-slice. Never hand-merge builder work.
+- Add cross-model review for high-stakes slices (schema, API, auth, persistence,
+  data loss, broad refactors) when a second CLI is available.
+
+Done when every issue is closed, blocked behind a hard stop, or waiting on a
+human digest item.
+
+### 5. Finish
+
+Dispatch one docs job before the PR boundary: it consumes documentation debt,
+updates product docs, and codifies reusable diagnoses into `docs/notes/<slug>.md`
+(read back at the start of every future run). Then prepare the PR — its body says
+`Closes #<tracking-issue>` and lists every shipped issue by number — and write
+the closing digest on the tracking issue: shipped issues, skipped work, residual
+risks, verification evidence.
+
+Done when docs debt is consumed, the PR is ready, the digest is posted, and no
+issue is silently unresolved.
+
+## Hard stops
+
+Stop and ask the human when any of these fire:
+
+- `docs/STOP` exists (kill switch), or `docs/PAUSE` exists (dispatch nothing new).
+- An irreversible or destructive action is needed.
+- Two consecutive KILL decisions happen in the factory.
+- A blocker collides with a recorded assumption.
+- Scope grows beyond the approved spec.
+- Required GitHub / `gh` preflight cannot be satisfied.
+
+## Maintenance
+
+Re-read this skill against each new model generation and delete what the models
+now do unprompted. The invariants above are load-bearing; everything else is
+prunable. No behavior ships without its evidence recorded in `DESIGN.md`.

package/skills/lead/config.py

@@ -0,0 +1,359 @@
+#!/usr/bin/env python3
+"""Resolve techlead-loop model routing and print the effective plan.
+
+The Lead runs a strong leading model; cheaper submodels do the typing. Every
+role — lead, builder, reviewer, researcher, scout, critic — is an independently
+configurable slot, and the "submodel" of each role is its reasoning effort. This
+resolver reads the provider registry (models.json) and the role config, then
+prints exactly which model + effort each role will use, where that decision came
+from, and the concrete command that dispatch would run.
+
+    lead-config.py                 # table of the resolved routing
+    lead-config.py --json          # machine-readable
+    lead-config.py --role lead     # one role, verbose
+    lead-config.py --check         # verify each provider CLI is on PATH
+    lead-config.py --repo-root DIR # resolve against another repo
+
+Config grammar (`.lead/config` in the repo, then `~/.lead/config`):
+
+    lead       = claude/fable:xhigh   # the leading model, at max reasoning
+    researcher = codex/best:high
+    builder    = codex/best:xhigh
+    reviewer   = inherit-lead         # fresh judge at the lead's capability
+    scout      = codex/best:low
+    critic     = claude/fable:high
+
+    alias fast = claude/haiku:low     # define once, reuse anywhere
+    when trivial mechanical edit  -> claude/haiku:low   # cheap exact patch
+    when broad ambiguous refactor -> codex/best:xhigh   # deeper search budget
+
+A role value is `<provider>/<model>[:<effort>]`, an alias name, or the sentinel
+`inherit-lead`. Stdlib only; runs on any Python 3.9+.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+ROLES = ["lead", "builder", "reviewer", "researcher", "scout", "critic"]
+
+# Built-in defaults — used when no config file sets a role. The lead defaults to
+# Fable because the whole design leans on a strong leading model; the reviewer
+# inherits the lead's tier so nobody grades their own work at a weaker one.
+DEFAULT_ROLES: dict[str, str] = {
+    "lead": "claude/fable:xhigh",
+    "reviewer": "inherit-lead",
+    "researcher": "codex/best:high",
+    "builder": "codex/best:xhigh",
+    "scout": "codex/best:low",
+    "critic": "claude/fable:high",
+}
+
+# Fallback registry, used only if models.json cannot be found or parsed. The
+# committed models.json next to this file is the real source of truth.
+FALLBACK_REGISTRY: dict[str, dict] = {
+    "providers": {
+        "claude": {
+            "cli": "claude",
+            "kind": "claude",
+            "default_model": "fable",
+            "default_effort": "xhigh",
+            "efforts": ["low", "medium", "high", "xhigh", "max"],
+            "models": {
+                "fable": "claude-fable-5",
+                "opus": "claude-opus-4-8",
+                "sonnet": "claude-sonnet-5",
+                "haiku": "claude-haiku-4-5",
+            },
+            "tier_down": {"fable": "sonnet", "opus": "sonnet", "sonnet": "haiku"},
+        },
+        "codex": {
+            "cli": "codex",
+            "kind": "codex",
+            "default_model": "best",
+            "default_effort": "xhigh",
+            "efforts": ["low", "medium", "high", "xhigh"],
+            "models": {"best": "gpt-5.5"},
+            "tier_down": {},
+        },
+    }
+}
+
+# When a codex-first role has no working Codex CLI, dispatch falls back to this.
+CODEX_ABSENT_FALLBACK = "claude/sonnet:high"
+
+SPEC_RE = re.compile(r"^(?P<provider>[a-zA-Z0-9_-]+)/(?P<model>[a-zA-Z0-9_.\-]+)(?::(?P<effort>[a-zA-Z0-9_-]+))?$")
+
+
+class ConfigError(Exception):
+    pass
+
+
+def _merge_registry(base: dict, extra: dict) -> dict:
+    out = json.loads(json.dumps(base))
+    for name, prov in extra.get("providers", {}).items():
+        if name == "//":
+            continue
+        out.setdefault("providers", {})[name] = prov
+    return out
+
+
+def load_registry(repo_root: Path) -> dict:
+    """Built-in fallback <- shipped models.json <- ~/.lead <- repo .lead."""
+    registry = json.loads(json.dumps(FALLBACK_REGISTRY))
+    sources = [
+        Path(__file__).resolve().parent / "models.json",
+        Path.home() / ".lead" / "models.json",
+        repo_root / ".lead" / "models.json",
+    ]
+    for src in sources:
+        if not src.is_file():
+            continue
+        try:
+            data = json.loads(src.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ConfigError(f"{src}: {exc}") from exc
+        registry = _merge_registry(registry, data)
+    # Drop the documentation key if it rode along.
+    registry.get("providers", {}).pop("//", None)
+    return registry
+
+
+def _config_files(repo_root: Path) -> list[Path]:
+    # User config first (lower priority), repo config last (wins).
+    return [Path.home() / ".lead" / "config", repo_root / ".lead" / "config"]
+
+
+def load_config(repo_root: Path) -> tuple[dict[str, tuple[str, str]], dict[str, str], list[dict]]:
+    """Return (roles, aliases, rules).
+
+    roles maps role -> (spec, source-label); aliases maps name -> spec; rules is
+    an ordered list of {"match", "spec", "why", "source"} dispatch rules.
+    """
+    roles: dict[str, tuple[str, str]] = {r: (v, "built-in default") for r, v in DEFAULT_ROLES.items()}
+    aliases: dict[str, str] = {}
+    rules: list[dict] = []
+
+    for path in _config_files(repo_root):
+        if not path.is_file():
+            continue
+        label = _short(path)
+        for raw in path.read_text(encoding="utf-8").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith("alias "):
+                body = line[len("alias "):]
+                if "=" not in body:
+                    raise ConfigError(f"{label}: malformed alias line: {raw}")
+                name, spec = body.split("=", 1)
+                aliases[name.strip()] = _strip_comment(spec)
+                continue
+            if line.startswith("when ") and "->" in line:
+                match, rest = line[len("when "):].split("->", 1)
+                spec, why = _split_why(rest)
+                rules.append({"match": match.strip(), "spec": spec, "why": why, "source": label})
+                continue
+            if "=" in line:
+                key, spec = line.split("=", 1)
+                key = key.strip()
+                if key in ROLES:
+                    roles[key] = (_strip_comment(spec), label)
+                else:
+                    print(f"warning: {label}: unknown role key {key!r} (ignored)", file=sys.stderr)
+                continue
+            print(f"warning: {label}: unparsed line: {raw}", file=sys.stderr)
+    return roles, aliases, rules
+
+
+def _short(path: Path) -> str:
+    try:
+        home = Path.home()
+        if path == home / ".lead" / "config":
+            return "~/.lead/config"
+    except Exception:
+        pass
+    return ".lead/config"
+
+
+def _strip_comment(value: str) -> str:
+    return value.split("#", 1)[0].strip()
+
+
+def _split_why(rest: str) -> tuple[str, str]:
+    if "#" in rest:
+        spec, why = rest.split("#", 1)
+        return spec.strip(), why.strip()
+    return rest.strip(), ""
+
+
+def resolve_spec(spec: str, aliases: dict[str, str], registry: dict, lead_spec: str | None) -> dict:
+    """Turn a spec string into a concrete routing dict."""
+    seen: set[str] = set()
+    while spec in aliases:
+        if spec in seen:
+            raise ConfigError(f"alias cycle at {spec!r}")
+        seen.add(spec)
+        spec = aliases[spec]
+    if spec in ("inherit-lead", "inherit"):
+        if lead_spec is None:
+            raise ConfigError("inherit-lead used for the lead role itself")
+        return resolve_spec(lead_spec, aliases, registry, None)
+
+    m = SPEC_RE.match(spec)
+    if not m:
+        raise ConfigError(f"bad spec {spec!r} (want provider/model[:effort])")
+    provider = m.group("provider")
+    model = m.group("model")
+    effort = m.group("effort")
+
+    prov = registry.get("providers", {}).get(provider)
+    warnings: list[str] = []
+    if prov is None:
+        raise ConfigError(f"unknown provider {provider!r} — add it to models.json")
+
+    model_id = prov.get("models", {}).get(model)
+    if model_id is None:
+        # Allow a raw model id to pass through, but flag it.
+        model_id = model
+        warnings.append(f"model alias {model!r} not in registry for {provider!r}; using it verbatim")
+    if effort is None:
+        effort = prov.get("default_effort", "high")
+    elif effort not in prov.get("efforts", []):
+        warnings.append(f"effort {effort!r} not in {provider!r} efforts {prov.get('efforts', [])}")
+
+    return {
+        "spec": spec,
+        "provider": provider,
+        "kind": prov.get("kind", provider),
+        "cli": prov.get("cli", provider),
+        "model": model,
+        "model_id": model_id,
+        "effort": effort,
+        "command": _command(prov, model_id, effort),
+        "warnings": warnings,
+    }
+
+
+def _command(prov: dict, model_id: str, effort: str) -> str:
+    kind = prov.get("kind")
+    cli = prov.get("cli", kind)
+    if kind == "codex":
+        return f'{cli} exec -m {model_id} -c model_reasoning_effort="{effort}"'
+    if kind == "claude":
+        return f"{cli} -p --model {model_id} --effort {effort}"
+    return f"{cli} --model {model_id} --effort {effort}"
+
+
+def resolve(repo_root: Path) -> dict:
+    registry = load_registry(repo_root)
+    roles, aliases, rules = load_config(repo_root)
+
+    lead_spec = roles["lead"][0]
+    resolved_roles: dict[str, dict] = {}
+    for role in ROLES:
+        spec, source = roles[role]
+        info = resolve_spec(spec, aliases, registry, lead_spec if role != "lead" else None)
+        info["role"] = role
+        info["source"] = source
+        resolved_roles[role] = info
+
+    resolved_rules = []
+    for rule in rules:
+        info = resolve_spec(rule["spec"], aliases, registry, lead_spec)
+        info.update({"match": rule["match"], "why": rule["why"], "source": rule["source"]})
+        resolved_rules.append(info)
+
+    return {"roles": resolved_roles, "rules": resolved_rules, "registry": registry, "aliases": aliases}
+
+
+def _cli_available(cli: str) -> bool:
+    return shutil.which(cli) is not None
+
+
+def print_table(result: dict, check: bool) -> None:
+    roles = result["roles"]
+    width = max(len(r) for r in ROLES)
+    print("techlead-loop model routing")
+    print("=" * 60)
+    for role in ROLES:
+        info = roles[role]
+        line = f"{role.ljust(width)}  {info['provider']}/{info['model']}:{info['effort']}"
+        line += f"  ->  {info['model_id']}"
+        print(line)
+        detail = f"{' ' * width}  from {info['source']}"
+        if check:
+            ok = _cli_available(info["cli"])
+            mark = "ok" if ok else "MISSING"
+            detail += f" | cli `{info['cli']}` {mark}"
+            if not ok and info["kind"] == "codex":
+                detail += f" -> would fall back to {CODEX_ABSENT_FALLBACK}"
+        print(detail)
+        for w in info.get("warnings", []):
+            print(f"{' ' * width}  ! {w}")
+    if result["rules"]:
+        print("-" * 60)
+        print("dispatch rules (task-class overrides):")
+        for r in result["rules"]:
+            why = f"  # {r['why']}" if r["why"] else ""
+            print(f"  when {r['match']} -> {r['provider']}/{r['model']}:{r['effort']}{why}")
+    print("-" * 60)
+    print(f"lead command:    {roles['lead']['command']}")
+    print(f"builder command: {roles['builder']['command']}")
+
+
+def print_role(result: dict, role: str) -> int:
+    if role not in result["roles"]:
+        print(f"unknown role {role!r}; choose from {', '.join(ROLES)}", file=sys.stderr)
+        return 2
+    info = result["roles"][role]
+    for key in ("role", "provider", "model", "model_id", "effort", "cli", "source", "command"):
+        print(f"{key}: {info[key]}")
+    for w in info.get("warnings", []):
+        print(f"warning: {w}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Resolve techlead-loop model routing.")
+    parser.add_argument("--repo-root", default=".", help="repository root to resolve against")
+    parser.add_argument("--role", help="print one role in detail")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument("--check", action="store_true", help="verify each provider CLI is on PATH")
+    args = parser.parse_args(argv)
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        result = resolve(repo_root)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        payload = {
+            "roles": {r: {k: v for k, v in info.items() if k != "warnings" or v}
+                      for r, info in result["roles"].items()},
+            "rules": result["rules"],
+            "aliases": result["aliases"],
+        }
+        if args.check:
+            for info in payload["roles"].values():
+                info["cli_available"] = _cli_available(info["cli"])
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    if args.role:
+        return print_role(result, args.role)
+
+    print_table(result, args.check)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())