@agentsfleet/orly 0.5.0

package/skills/orly-babysit-prs/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: orly-babysit-prs
+description: |
+  Post-push follow-up for PRs/MRs: backoff-cadence polls over CI check runs
+  (fix every failure your diff caused), every greptile inline thread, and the
+  PR-level summary; classifies via gstack greptile-triage, suppresses via
+  greptile-history, stops after two consecutive empty polls with CI green.
+  Forge-aware (gh PR / glab MR). Use after `gh pr create` / `glab mr create`,
+  after every push to a branch with an open PR/MR, or on "babysit", "watch
+  greptile", "poll the PR/MR", "watch reviews", "follow up on review
+  feedback". Cross-agent: Claude, Codex, OpenCode, Amp.
+---
+
+# orly-babysit-prs
+
+Review bots (greptile on GitHub; greptile or another review bot on GitLab)
+post auto-reviews **asynchronously**. They land as PR review comments / MR
+discussion threads, not check runs, so `gh pr checks --watch` (or the glab
+equivalent) doesn't observe them. Without explicit polling on a backoff
+cadence, findings arrive after the human stops checking — so they get missed.
+
+This skill is the **polling cadence + walk-every-review-thread loop**. The
+fetch, classify, and reply mechanics live in gstack's `greptile-triage.md` —
+open and follow it; do not paraphrase from memory. This skill never
+duplicates the triage helper's logic; it adds (a) the cadence, (b) the
+multi-thread walk, and (c) the **forge abstraction** so the same loop runs on
+GitHub and GitLab.
+
+## STEP 0 — Open greptile-triage.md every cycle
+
+Before doing anything else in a polling cycle, read the triage helper:
+
+```bash
+GREPTILE_TRIAGE="$HOME/.local/share/gstack/review/greptile-triage.md"
+[ -r "$GREPTILE_TRIAGE" ] || GREPTILE_TRIAGE="$HOME/Projects/dotfiles/.unified-skills/review/greptile-triage.md"
+[ -r "$GREPTILE_TRIAGE" ] || { echo "BABYSIT: greptile-triage.md missing — abort cycle"; exit 1; }
+```
+
+Then walk it section by section:
+
+| Triage section | What this skill triggers |
+|---|---|
+| `## Fetch` | Run per detected review thread (multi-thread loop below), via the forge layer |
+| `## Suppressions Check` | Read `$HOME/.gstack/projects/<slug>/greptile-history.md`; skip lines tagged `fp` matching `repo + file-pattern + category` |
+| `## Classify` | Read file ±10 lines around each comment's `path:line`; classify VALID & ACTIONABLE / VALID BUT ALREADY FIXED / FALSE POSITIVE / SUPPRESSED |
+| `## Reply APIs` | Tier 1 first response, Tier 2 on re-flag — via the forge layer |
+| `## Reply Templates` | Use Tier 1 / Tier 2 template verbatim — do not invent new wording |
+| `## Severity Assessment & Re-ranking` | Re-rank the bot's severity against the project's actual risk profile |
+| `## History File Writes` | Append to BOTH per-project and global history files (see below) |
+| `## Output Format` | Use the triage helper's report shape, augmented with our cadence line |
+
+If the triage helper is missing on the host, abort with `BABYSIT: greptile-triage.md missing` rather than guessing — the abort is visible, a silent re-implementation is not.
+
+## STEP 0.5 — Detect the forge
+
+`git remote` decides which CLI + review-object model to use. Everything
+downstream branches on `$FORGE`.
+
+```bash
+ORIGIN=$(git remote get-url origin 2>/dev/null)
+case "$ORIGIN" in
+  *github.com*)  FORGE=github ;;
+  *)             FORGE=gitlab ;;   # gitlab.com OR self-hosted (e.g. awakeninggit.e2enetworks.net)
+esac
+echo "BABYSIT: forge=$FORGE origin=$ORIGIN"
+```
+
+| Concept | GitHub (`gh`) | GitLab (`glab`) |
+|---|---|---|
+| Change unit | Pull Request (PR) | Merge Request (MR) |
+| Create cmd | `gh pr create` | `glab mr create` |
+| Review object | a *review* with line comments | a *discussion* (thread) with notes |
+| "walk every…" | every review id | every discussion thread id |
+| Reply | reply to the review comment | post a note to the discussion |
+
+Both forges' bots are filtered by author name matching `greptile` (or the
+project's configured review bot — see the per-project history `bot:` note if
+present).
+
+## STEP 0.75 — CI checks must go green (poll + fix)
+
+Greptile is not the only async signal: the PR/MR's **CI check runs** land on
+their own schedule and are part of "done". The loop is not finished until CI is
+green **and** the review bot is quiet. This is the one place `gh pr checks`
+(NOT `--watch`) is the right tool — it observes *check runs*, which is exactly
+what CI is. (The "never `gh pr checks --watch` for greptile" rule stands:
+greptile posts review comments, not checks, so `pr checks` never sees it. CI
+jobs are the opposite — `pr checks` is precisely how you see them.)
+
+Each cycle, after the review-thread walk, poll CI and act by cause:
+
+### GitHub
+
+```bash
+gh pr checks "$PR_NUMBER" --json name,state,bucket,link 2>/dev/null \
+  | jq -r '.[] | "\(.bucket)\t\(.state)\t\(.name)\t\(.link)"'   # bucket ∈ pass|fail|pending|skipping|cancel
+```
+
+### GitLab
+
+```bash
+glab ci status 2>/dev/null \
+  || glab api "projects/$PROJ_ENC/merge_requests/$MR_IID/pipelines" \
+       | jq -r '.[0] | "\(.status)\t\(.web_url)"'               # status ∈ success|failed|running|canceled|pending
+```
+
+| CI state | Action |
+|---|---|
+| all `pass`/`skipping` (GitLab `success`) | Record `ci=green`. A done-declaration is now allowed (if greptile is also quiet). |
+| any `pending`/`running` | Record `ci=pending`; re-poll on the cadence. **Never declare done while a check is still running.** |
+| any `fail`/`cancel` **from your changes** | In-scope finding you OWN — treat like a greptile fix. Fetch the failing log (`gh run view <run-id> --log-failed`, run id from the check `link`; GitLab `glab ci trace <job-id>`), fix the code, re-verify with the relevant `make` target, commit, push, re-poll. |
+| any `fail` **NOT from your changes** (pre-existing red, infra flake, unrelated job) | Surface to the user with job name + link. Do **not** fix blindly, do **not** edit CI config. Pause the done-declaration until they decide. |
+
+CI failures caused by your commit are not "surface and wait" — they are the
+same contract as a greptile P0: diagnose, fix the code (never the CI config),
+push, and re-poll until green.
+
+## Triggers
+
+- After `gh pr create` / `glab mr create` for a feature branch.
+- After every `git push` to a branch with an open PR/MR.
+- User says: "babysit", "watch greptile", "poll the PR", "poll the MR",
+  "watch reviews", "follow up on review feedback", "what did greptile say".
+
+## Output contract
+
+Per cycle, print one line (`PR` on GitHub, `MR` on GitLab):
+
+```
+BABYSIT <PR|MR> #<n> @ <SHA>: poll <i> | reviews=<count> | new=<m> | actioned=<k> | ci=<green|pending|red> | next=<delay>
+```
+
+`actioned` = findings whose code fix landed in this cycle (greptile OR CI).
+`ci` = the aggregate check-run state from STEP 0.75.
+
+## Cadence (backoff)
+
+| Time since last push (or last review) | Poll interval |
+|---|---|
+| 0–10 min | +180 s after each push |
+| 10–30 min | +300 s |
+| 30–60 min | +600 s |
+| > 60 min | +1200 s, then stop after 2 consecutive empty polls |
+
+Claude Code: use `ScheduleWakeup(delaySeconds, "re-poll review on <PR|MR>
+#<n> <SHA>")`. Other agents: `sleep <delay>` in a shell loop, or schedule
+via the agent's native cron/wakeup mechanism.
+
+## Polling loop
+
+### GitHub (`FORGE=github`)
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+PR_NUMBER=$(gh pr view --json number --jq '.number')
+
+# Walk EVERY review id — greptile may post more than one review per push.
+REVIEW_IDS=$(gh api "repos/$REPO/pulls/$PR_NUMBER/reviews" \
+              --jq '.[] | select(.user.login | test("greptile"; "i")) | .id')
+
+for rid in $REVIEW_IDS; do
+  # Follow greptile-triage.md (STEP 0): fetch line+top-level comments for THIS
+  # review id; Suppressions Check; Classify; Reply (Tier 1/Tier 2); history write.
+  # Fetch: gh api "repos/$REPO/pulls/$PR_NUMBER/reviews/$rid/comments"
+  # Reply: gh api -X POST "repos/$REPO/pulls/$PR_NUMBER/comments/<cid>/replies" -f body="..."
+  :
+done
+
+# ALSO triage greptile's SUMMARY feedback — it puts actionable findings in two
+# places the line-comment walk above misses:
+#   (1) the review BODY (the review's own summary text), and
+#   (2) the top-level PR issue comment (greptile's "description reply" / summary,
+#       often with collapsible per-file sections listing concerns inline).
+# Run each through greptile-triage.md exactly like a line comment.
+gh api "repos/$REPO/pulls/$PR_NUMBER/reviews" \
+  --jq '.[] | select(.user.login|test("greptile";"i")) | select(.body != "") | .body'
+gh api "repos/$REPO/issues/$PR_NUMBER/comments" \
+  --jq '.[] | select(.user.login|test("greptile";"i")) | {id, body}'
+# Reply to a summary issue comment: gh api -X POST "repos/$REPO/issues/$PR_NUMBER/comments" -f body="..."
+```
+
+### GitLab (`FORGE=gitlab`)
+
+```bash
+# Project full path (e.g. gpu/console), URL-encoded for the API.
+PROJECT_PATH=$(glab repo view -F json 2>/dev/null | jq -r '.path_with_namespace' \
+               || git remote get-url origin | sed -E 's#.*[:/]([^:/]+/[^/]+)$#\1#; s#\.git$##')
+PROJ_ENC=$(printf '%s' "$PROJECT_PATH" | sed 's#/#%2F#g')
+MR_IID=$(glab mr view -F json | jq -r '.iid')
+
+# Walk EVERY discussion thread from the review bot. GitLab has no "review"
+# object — a bot posts discussion threads (each with notes[]).
+THREAD_IDS=$(glab api "projects/$PROJ_ENC/merge_requests/$MR_IID/discussions" --paginate \
+             | jq -r '.[] | select(any(.notes[]; .author.username | test("greptile"; "i"))) | .id')
+
+for tid in $THREAD_IDS; do
+  # Follow greptile-triage.md (STEP 0): fetch the thread's notes (body +
+  # position.new_path/new_line for line-level); Suppressions Check; Classify;
+  # Reply (Tier 1/Tier 2); history write.
+  # Fetch: glab api "projects/$PROJ_ENC/merge_requests/$MR_IID/discussions/$tid"
+  # Reply: glab api -X POST "projects/$PROJ_ENC/merge_requests/$MR_IID/discussions/$tid/notes" -f body="..."
+  :
+done
+
+# ALSO triage greptile's SUMMARY feedback — the MR-level notes greptile posts
+# outside a positioned discussion thread (the "description reply" / overview
+# note, often with inline per-file concerns). Run each through greptile-triage.md.
+glab api "projects/$PROJ_ENC/merge_requests/$MR_IID/notes" \
+  --jq '.[] | select(.author.username|test("greptile";"i")) | select(.type == null) | {id, body}'
+# Reply to a summary note: glab api -X POST "projects/$PROJ_ENC/merge_requests/$MR_IID/notes" -f body="..."
+```
+
+### History paths (forge-independent)
+
+```bash
+REMOTE_SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null \
+              || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
+PROJECT_HISTORY="$HOME/.gstack/projects/$REMOTE_SLUG/greptile-history.md"
+GLOBAL_HISTORY="$HOME/.gstack/greptile-history.md"
+mkdir -p "$(dirname "$PROJECT_HISTORY")" "$(dirname "$GLOBAL_HISTORY")"
+```
+
+**Critical: walk every review thread.** Greptile (or the bot) may post
+multiple reviews/threads per push (one structural, one security, etc.). The
+triage helper fetches once per call; the multi-thread walk lives here, on
+both forges.
+
+## History file discipline
+
+Every triaged comment writes one line to BOTH:
+
+| File | Purpose |
+|---|---|
+| `$HOME/.gstack/projects/<slug>/greptile-history.md` | Per-project. Drives Suppressions Check on next cycle — `fp` lines suppress matching comments forever. |
+| `$HOME/.gstack/greptile-history.md` | Global aggregate. Cross-project retro / pattern-mining. |
+
+Line format (from the triage helper's "History File Writes" section):
+
+```
+<YYYY-MM-DD> | <owner/repo> | <type:fp|fix|already-fixed> | <file-pattern> | <category>
+```
+
+- **`fp`** — false positive. Suppressed on future polls.
+- **`fix`** — real issue, fixed in this cycle. Not suppressed.
+- **`already-fixed`** — real issue, fixed in a prior commit on this branch. Not suppressed.
+
+The categories are a fixed set: `race-condition`, `null-check`, `error-handling`, `style`, `type-safety`, `security`, `performance`, `correctness`, `other`. Don't invent new categories — if a finding doesn't fit, use `other` and mention the actual concern in the reply, not the history line.
+
+## After a fix lands
+
+1. Fix the code per the triage helper's classification.
+2. Re-verify with `make lint` + `make test` (or relevant tier).
+3. Reply via the triage helper's "Reply APIs" section (Tier 1 / Tier 2
+   templates) through the forge layer above. Include the fix SHA in the body.
+4. Commit and push.
+5. Append the history line(s) to both files.
+6. If the finding generalizes beyond this PR/MR (recurring pattern, new
+   class of bug), capture as a named rule in the project's
+   `docs/greptile-learnings/RULES.md` in the same commit as the fix.
+   Otherwise the history line alone is the durable record.
+7. Re-schedule the next poll using the cadence table above.
+
+## Stop conditions
+
+- **Done = two consecutive empty polls AND CI green.** Both must hold: no new
+  reviews/threads/summary findings for two polls **and** STEP 0.75 reports
+  `ci=green`. A quiet bot with a still-`pending` or red CI is NOT done — keep
+  polling on the cadence.
+- **PR/MR merged or closed** → stop, report.
+- **CI red FROM your changes** → fix it (STEP 0.75): diagnose, fix the code,
+  push, re-poll. Not a stop condition — it's work to do.
+- **CI red and NOT from your changes** → surface to the user; pause the
+  done-declaration until they decide.
+- **User says stop / pause** → print one final
+  `BABYSIT <PR|MR> #<n>: paused per user` line and stop.
+
+## Report format
+
+At end of each cycle:
+
+```
+BABYSIT REPORT — <PR|MR> #<n> @ <SHA>
+  Polls run: <i>
+  Reviews seen: <count>  (line: <l>, summary/description: <s>)
+  Findings actioned: <k> (P0: <a>, P1: <b>)
+  Findings deferred: <d> (with reasons)
+  CI: <green | pending: <job…> | red: <job> — <fixed SHA | surfaced to user>>
+  Rules added/updated: <list of RULE refs>  # via triage helper's history-write
+  Next poll: in <delay>s OR stopped (<reason>)
+```
+
+## What this skill does NOT do
+
+- Does **not** re-implement fetch/classify/reply — see
+  `~/.local/share/gstack/review/greptile-triage.md`.
+- Does **not** merge the PR/MR — use `/land-and-deploy` after the bot is green.
+- Does **not** modify CI configuration or skip the review bot.
+- Does **not** apply P2/P3/nit findings without explicit user approval
+  (the triage helper's classification drives this).
+
+## Failure modes
+
+| Surface | Action |
+|---|---|
+| `gh api` / `glab api` rate-limited | Back off the poll interval by 2× and retry next cycle |
+| Review missing on a push | Re-poll once at +180 s; if still missing, surface to user |
+| `gh pr view` / `glab mr view` returns nothing (PR/MR not yet visible) | Skip cycle; retry next interval |
+| `glab` not authed for a self-hosted host | Surface `BABYSIT: glab not authed for <host> — run glab auth login`; pause |
+| Multiple reviews with conflicting suggestions | Apply the union; surface conflict only if both can't coexist |
+| Finding is in code the agent did not author | Surface to user before fixing — never edit changes the agent did not create |
+
+## References
+
+- `~/.local/share/gstack/review/greptile-triage.md` — fetch / classify /
+  reply / suppressions / history-write mechanics. Also at
+  `~/Projects/dotfiles/.unified-skills/review/greptile-triage.md`.
+- `$HOME/.gstack/projects/<slug>/greptile-history.md` — per-project
+  history; drives Suppressions Check.
+- `$HOME/.gstack/greptile-history.md` — global aggregate.
+- `docs/greptile-learnings/RULES.md` — project-level named rules
+  (durable principles). New rule added here only when the finding
+  generalizes; per-incident rows go to greptile-history.md.
+- `~/Projects/dotfiles/AGENTS.md` — CHORE(close) skill chain step 4
+  cites this skill.
+- `gh api` docs: https://cli.github.com/manual/gh_api
+- `glab api` docs: https://gitlab.com/gitlab-org/cli (`glab api --help`)

package/skills/orly-spec-new/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: orly-spec-new
+description: |
+  Author a milestone/workstream spec the executing agent (Orly) ships into a
+  deterministic, review-clean, reported Pull Request — intent capture and
+  review-readiness first, file mechanics last. Use on "create a spec", "new
+  milestone", "start M{N}_{NNN}", "spec out X", or any TODO.md attempt
+  (forbidden — every non-trivial intent becomes a spec). Cross-agent,
+  self-contained markdown.
+---
+
+# orly-spec-new
+
+A spec is the **rulebook** the executing agent (Orly) plans and ships from. This
+skill makes me author one whose Pull Request (PR) lands **deterministic, review-clean, and
+reported** — without a 20-questions loop. It is written for my reasoning, not as
+a file-naming guide: the mechanics (naming, layout) are demoted to the end
+because they are the easy part.
+
+> **The trio stays coherent.** This skill (*how to author*) ← `docs/TEMPLATE.md`
+> (*the section shape*) → `audits/spec-template.sh` (*the enforcer*). If a
+> step here demands something, the template carries the section and the audit
+> asserts it. Drift between the three is a bug.
+
+A spec is an *instance*; `AGENTS.md` and `docs/greptile-learnings/RULES.md` are
+the *constants*. When the spec contradicts a rule, amend the spec — never weaken
+the rule.
+
+## What a good spec guarantees
+
+The three outcomes every step below serves:
+
+- **Deterministic / invariant** — the agent plans and builds with no `[?]`; every claim is a test; every invariant is enforced by code, not review discipline.
+- **Review-clean** — the code it produces trips no greptile finding, because the spec pre-commits to the exact `RULES.md` rule IDs and gates the diff touches.
+- **Reported** — Discovery (consult log), the Acceptance Rubric's Graded column, and skill-chain outcomes are populated as the work proceeds.
+
+## Triggers
+
+- User says: "create a spec", "spec this out", "new milestone", "draft M{N}_{NNN}", "start on M{N}", "track this as a milestone".
+- The user attempts a `TODO.md` or any ad-hoc task list — convert it into a spec. **`TODO.md` is forbidden.**
+- A `plan-eng-review` / `plan-ceo-review` / `plan-design-review` produced a plan that should be tracked durably.
+
+---
+
+## Step 1 — Capture intent (the hard part — do it before any file)
+
+Determinism starts here. Before copying the template:
+
+- **Testable goal** — one sentence that could be a test name. "Implement streaming" is not a goal; "SSE handler streams pubsub as `text/event-stream`, p95 < 200ms" is.
+- **PR title + intent** — what the merged PR is called (imperative, ≤72 chars) and the one-sentence user-facing *why*.
+- **Comprehension handshake** — restate the intent in my own words and list `ASSUMPTIONS I'M MAKING: …`. If my restatement and the requester's ask diverge, STOP and reconcile before drafting.
+- **Golden-path walk** — trace the concrete end-to-end (every lookup, data source, secret store). Any `[?]` left in the walk blocks the spec from leaving `pending/`.
+- **Product Clarity — Indy's ten product questions, answered in order** (successful user moment · preserved user behaviour · optimal-way check · rebuild-vs-iterate · what we build · what we do NOT build · fit with existing features · surface order · dashboard restraint · confused-user next step). They are answered BEFORE any implementation section is drafted; internal-only work may answer 8–10 as "N/A — no user surface" with the reason.
+
+→ Fills the template's **PR Intent & comprehension handshake**, **Overview**, and **Product Clarity (authoring record)**.
+
+## Step 2 — Lock review-readiness (so the PR ships clean)
+
+This is the step that prevents greptile findings — the spec becomes a pre-commitment to the rules its code must obey:
+
+- **Applicable Rules** — name the *specific* `docs/greptile-learnings/RULES.md` rule IDs the diff will trip (e.g. NDC, NLR, NLG, UFS), plus the per-surface dispatch façades / rule files: `dispatch/write_zig.md` (`*.zig`), `docs/REST_API_DESIGN_GUIDELINES.md` (`src/http/handlers/**`), `docs/SCHEMA_CONVENTIONS.md` (`schema/*`), `dispatch/write_ts_adhere_bun.md`, `docs/LOGGING_STANDARD.md`, `docs/LIFECYCLE_PATTERNS.md`. Generic "follow RULES.md" earns a greptile finding; named IDs the implementer obeys by construction do not. Cite rule docs by their repo-local `docs/…` paths — the selected packs materialise them into every repository; cite only files that exist here (`test -f` each).
+- **Applicable Gates** — which Action-Triggered Guards fire (ZIG, PUB, LENGTH, UFS, UI, DESIGN TOKEN, LOGGING, LIFECYCLE, SCHEMA, ERROR REGISTRY) and the satisfaction strategy for each. Rules ≠ gates: rules are knowledge to read; gates fire on edits.
+- **Prior-Art / Reference Implementations** — the reference codebase to mirror (CLI → the "7 Pillars" of CLI DX in `docs/TEMPLATE.md` Prior-Art; API → REST guide + nearest handler). No reinventing what a known-good pattern already solves.
+
+→ Fills **Applicable Rules**, **Applicable Gates**, **Prior-Art / Reference Implementations**.
+
+## Step 3 — Make it provable & reported
+
+- Decompose **Sections** into numbered **Dimensions** (3.1, 3.2 …) — the unit of DONE. **Every Dimension → one Test** (tiered: unit/integration/e2e per `/orly-write-unit-test`; any user-facing Category gets a user-centric `test-e2e*` scenario).
+- **Every Failure Mode → a negative test.** **Every Invariant → enforced by code** (compiler, lint, comptime assertion, runtime check) — never by review discipline.
+- **Every Metrics row → event/test proof.** User-facing or operator-facing specs declare product/operator signals, privacy guards, and analytics/funnel playbook updates; internal-only cleanup explicitly says no signal changed.
+- **Rubric = 5–12 outcome rows** — one per Section outcome, failure class, or hygiene gate (never per Dimension); each with a copy-paste Verify command and a mechanically checkable Expected (exit code / literal substring / match count). Standard rows come pre-filled in the template — prune to the touched surface.
+- **Reporting spine** — **Discovery (consult log)** carries consults, skill-chain outcomes, and Indy-acked deferral quotes; the **Acceptance Rubric's Graded column** carries the VERIFY verdicts (✅/❌ + one decisive output line each). Both empty at creation, populated as work proceeds.
+
+→ Fills **Sections (+ Dimensions)**, **Metrics & Observability**, **Failure Modes**, **Invariants**, **Test Specification (tiered)**, **Acceptance Rubric**, **Discovery**.
+
+## Step 4 — Mechanics (the easy part)
+
+Now the file. Pick the ID and copy the template:
+
+```bash
+# next free M{N}_{WS}
+ls docs/v*/pending/ docs/v*/active/ docs/v*/done/ 2>/dev/null \
+  | grep -oE 'M[0-9]+_[0-9]+' | sort -u | tail -5
+cp docs/TEMPLATE.md docs/v{N}/pending/M{N}_{WS}_P{P}_{CATEGORIES}_{NAME}.md
+```
+
+
+**Fill grammar** — the template body is ordered for the *executing* agent (execution read order), not for authoring; fill sections in the order of Steps 1–3 above, not top-to-bottom. Replace every `{…}` slot with instance content, then **delete every `<!-- tpl: … -->` guidance comment** — the SPEC TEMPLATE GATE BLOCKs any survivor, unfilled slot sentinels, and missing required sections. The SPEC AUTHORING RULES banner is the one comment that stays.
+
+**Inputs** — Milestone `M{N}` (next free, sortable) · Workstream `{WS}` zero-padded (`001`…) · Priority (**P0** blocking · **P1** customer/operator-facing · **P2** tooling · **P3** deferrable) · Category set alphabetised (`API` Zig/Go · `CLI` agentsfleet/Node · `UI` Next.js · `OBS` Grafana · `SKILL` SKILL.md · `INFRA` Terraform) · Name UPPER_SNAKE_CASE ≤6 words describing the outcome (`BUN_VENDOR_UTILITIES`, not `BUMP_BUN_DEPS`) · Prototype tag (`v1.0.0`, `v2.0.0` — drives `docs/v1/` vs `docs/v2/`).
+
+**File naming:** `docs/v{N}/{pending|active|done}/M{Milestone}_{Workstream}_P{Priority}_{CATEGORIES}_{NAME}.md` (e.g. `docs/v2/pending/M52_001_P2_API_BUN_VENDOR_UTILITIES.md`). Do NOT rename existing legacy-form files under `docs/v1/` or `docs/v2/done/`.
+
+**Terminology — binding for everything that lands in a file** (conversational replies are exempt):
+
+| Use | Do NOT use |
+|---|---|
+| Prototype (v1.0.0) | Release, Version train, Program |
+| Milestone (M{N}) | Sprint, waterfall stage, Quarter |
+| Workstream (M{N}_{WS}) | Ticket, Task, Story, Issue |
+| Section (§3) | Waterfall stage, Step, Chapter |
+| Dimension (3.4) | Acceptance criterion, AC, Checkbox |
+| Batch (B2) | Wave, Tranche, Iteration |
+
+**Directory movement** is lifecycle-driven: created → `pending/` (`Status: PENDING`); begin implementation → `active/` (CHORE(open)); all Dimensions DONE + PR opened → `done/`; parked → stay in `active/`.
+
+## Step 5 — Self-review gate, then commit
+
+Before the spec leaves `pending/`, it must pass this checklist — the deterministic/invariant guarantee:
+
+- [ ] intent handshake done; golden-path walk has **no `[?]`**
+- [ ] **Product Clarity answered** — ten items, in order, `[?]`-free
+- [ ] **zero `tpl:` guidance comments remain** — the body carries only instance content
+- [ ] **Applicable Rules names specific greptile rule IDs**; Applicable Gates populated with satisfaction strategy
+- [ ] **Metrics & Observability declares events or explicitly says no product/operator signal changed**; any analytics/funnel playbook update is listed
+- [ ] **every Dimension has a Test**; **every Failure Mode has a negative test**; every Invariant is code-enforceable
+- [ ] Prior-Art reference named (or "greenfield — shape in `docs/architecture/`")
+- [ ] reporting sections present (Discovery; Acceptance Rubric with Graded column empty)
+- [ ] `bash audits/spec-template.sh --staged` is clean (it BLOCKs missing required sections and unfilled `{placeholders}`)
+
+Then commit in the current authoring context:
+
+- If the skill is running inside an existing branch/worktree, author and commit the spec there.
+- If there is no branch/worktree context, use the repo's `main` branch as the fallback.
+
+```bash
+git add docs/v{N}/pending/M{N}_{WS}_*_{NAME}.md
+git commit -m "docs(m{N}): add spec — {short title}"
+```
+
+The spec lands in `pending/` on the branch/worktree where the skill was invoked. CHORE(open) moves it to `active/` and creates any needed worktree — handled by the lifecycle, not this skill.
+
+---
+
+## What this skill does NOT do
+
+- It does **not** start coding, create a worktree, or move the spec to `active/`. That's CHORE(open), when implementation begins.
+- It does **not** modify any rule file, ARCHITECTURE doc, or changelog.
+- It does **not** create a branch just to author a spec. Spec creation uses the current branch/worktree, falling back to `main` only when no branch/worktree exists.
+
+## Failure modes
+
+| Surface | What you do |
+|---|---|
+| User insists on `TODO.md` | Decline. Convert the intent into a spec via this skill. |
+| Spec name collides with a `done/` entry | Pick the next workstream number; never reuse. |
+| Spec depends on something still in `pending/` | Allowed — list it in `Depends on:` and surface it. |
+| Spec proposes work that violates a rule | Amend the spec text or scope before committing. Rules are the constants. |
+| Can't write the goal as a test name | Intent is not understood yet — go back to Step 1; do not draft sections. |
+
+## References
+
+- `docs/TEMPLATE.md` — the section shape this skill fills (materialised per-repo by `workflow.specifications`; canonical source: the orly repository).
+- `audits/spec-template.sh` — the enforcer (`--staged` BLOCKs an incomplete spec).
+- `docs/greptile-learnings/RULES.md` — the rule IDs Step 2 pins for review-cleanliness.
+- The repository's generated `AGENTS.md` — lifecycle stages, action-triggered guards, deterministic VERIFY/CHORE sequencing.