Startup

Startup — orient, fast and read-only

Get oriented at the top of a session (target: under 30 seconds). Read-only and lean — read the docs and git state, report trust, state the next task, stop. This is not onboarding (repo-init / adopt) and not an audit (repo-align).

What this skill does NOT do

• No scaffolding or onboarding — a fresh repo gets pointed at repo-init; an established repo without the doc model gets pointed at adopt.
• No deep audit, contradiction check, or doc filing — that's repo-align. (The mechanical scans are read-only and near-instant — evidence, not an audit.)
• No reading of docs/archive/.
• No cleanup, no writes of any kind, no commits, no fixing anything the trust report flags.
• No offering to run wrapup/ship or any end-of-session action.

Procedure

1. Gather evidence (read-only), in one batch — git state plus the two cheap mechanical scans (python on Windows / PowerShell, python3 elsewhere):

   git status --short
   git branch --show-current
   PLUGIN_ROOT=$( [ -d "./plugins/rad-repo-manager" ] && echo "./plugins/rad-repo-manager" || echo "${CLAUDE_PLUGIN_ROOT:-$HOME/.gemini/config/plugins/rad-repo-manager}" )
    python3 "$PLUGIN_ROOT/scripts/repo-scan.py" . --json --no-record
    python3 "$PLUGIN_ROOT/scripts/repo_contract.py" . --json
    python3 "$PLUGIN_ROOT/scripts/doc-freshness.py" . --json
   python3 "$PLUGIN_ROOT/scripts/structure-drift.py" . --json   # only if docs/api.md or docs/architecture.md exists
   

   (If Python is unavailable, compute commits-behind by hand with git rev-list --count $(git log -1 --format=%H -- <doc>)..HEAD per doc, or say the scans were skipped — don't guess at hygiene.)

2. Build the instruction map from repo_contract.py. Root AGENTS.md is the default. Each scoped AGENTS.md applies only to its subtree and must be paired with a one-line CLAUDE.md containing @AGENTS.md so Claude Code loads it natively. Report missing/redundant shims; do not create them during startup. Then glob for the docs/ shelf and decide the path:

   • Fresh repo — no AGENTS.md, no docs, little history → recommend /rad-repo-manager:repo-init and stop.
   • Established but un-managed — real code/history but no doc model → recommend /rad-repo-manager:adopt and stop.
   • Managed repo — orient (below).

3. Read L0/L1 + direction: the applicable root-to-closest instruction chain, docs/handoff.md, and docs/plan.md if present, in one parallel batch. Read nothing else by default.

4. Build the trust report from the doc-freshness JSON (trust block) — one line per managed doc that exists, measured in commits-behind (commits on HEAD since the doc's last modifying commit). Thresholds (from references/shelf-spec.md): handoff 0–3 green · 4–10 yellow (nudge a quick wrapup) · >10 red (recommend repo-align first). decisions/ideas/lessons are append-only — always green. prd/plan/AGENTS.md lines are informational (commits-behind, no verdict). architecture.md / api.md are judged on relevance-weighted counts from the freshness JSON — structure-touching / route-touching commits since the doc's last update, not raw commits-behind (<10 green · 10–24 yellow · ≥25 red). When structure-drift.py ran, prefer its concrete counts over commit counts — "api.md: 6 undocumented routes" beats "124 behind". When one goes red, the line carries a specific, small proposal naming the delta ("architecture.md: 41 structure-touching commits since last update — draft the delta?"), not a generic "run align" — a named 5-minute fix gets done; a chore gets deferred. Add the repo-scan line: loose docs, any L0/L1 size-budget overage, and the align cadence (commits_since_align — flag when ≥25 or never stamped). Grounded counts and file names, not impressions. If the handoff is stale, treat its resume point with suspicion and say so.

5. Surface the briefing (format below) and end with the next task from the handoff — that line is the deliverable. The only forward actions you may suggest: repo-init (fresh), adopt (un-managed), a quick wrapup (yellow handoff), or repo-align (red / drift).

Output format

Startup:
Branch:           <current branch>
Working tree:     <clean / dirty summary>
Trust:
  handoff.md      <✅ N behind | ⚠️ N behind — quick wrapup? | ❌ N behind — align first>
  plan.md         <N behind (informational, e.g. "M4 shipped?") | missing>
  prd.md          <N behind | missing>
  AGENTS.md       <N behind | over budget (N lines > 40)>
  architecture.md <✅ N relevant behind | ⚠️/❌ N structure-touching commits — draft the delta? | missing>
  api.md          <✅ N relevant behind | ⚠️/❌ N route-touching commits — update the routes? | missing>
  decisions.md    <✅ append-only | missing>
Hygiene:          <from repo-scan: "tidy" | "N loose ends: <names>" | budget overages>
Align cadence:    <last align N commits ago | ⚠️ N ≥ 25 — repo-align due | never stamped>
Current focus:    <from docs/plan.md, one line, if present>
Deferred:         <count of items in the handoff's Deferred ledger, or "none">
Instructions:     <root only | root + applicable scoped AGENTS.md paths>
Next task:        <the Next action from docs/handoff.md — the last line of the briefing>

References

• <plugin-root>/references/shelf-spec.md — the shelf, trust thresholds, size budgets (where <plugin-root> is ${CLAUDE_PLUGIN_ROOT}, global config plugins/rad-repo-manager, or local workspace plugins/rad-repo-manager).