@1aboveio/skills 0.18.0 → 0.19.0

package/skills/engineering/rush-issues/references/exploration.md

@@ -0,0 +1,53 @@
+# Exploration
+
+Run once after the task plan is shown and before implementation. The
+goal is one shared context pack, so parallel implementers do not independently
+rediscover requirements and repository structure.
+
+## Spawn
+
+| Field | Value |
+|---|---|
+| Model | Explorer slot: balanced-coder; prefer `gpt-5.6-terra@high` when discovered, otherwise use the catalog recommendation |
+| Workspace | Isolated run worktree, read-only except for the findings directory |
+| Task deadline | 30 minutes |
+| Product code | Must remain unchanged |
+
+## Brief
+
+1. Read every unit's original source, acceptance criteria, and linked documents.
+2. Read relevant repository guidance, ADRs, domain context, modules, tests, and
+   prior art.
+3. Retrieve external documents named by the spec from their authoritative
+   source.
+4. Identify blocking dependencies and shared surfaces that affect scheduling or
+   combination.
+5. Write the findings pack to the shared path. Do not implement product code.
+
+## Shared location
+
+```text
+.resolve-issues/rush/<run-id>/exploration/
+  FINDINGS.md
+  findings.json
+```
+
+`FINDINGS.md` is required and includes:
+
+- whole-spec definition of done
+- per-unit requirements and likely code/test locations
+- relevant repository rules, ADRs, and external-source links
+- blocking dependencies and shared surfaces
+- risks, assumptions, and unresolved questions
+
+`findings.json` is optional and may index `{units, paths, dependencies, risks,
+openQuestions}`. Record the absolute findings path in the plan and pass it to
+every implementer.
+
+## Completion
+
+Confirm the findings file exists and is non-empty, the model read-back matches
+the explorer slot, and the explorer made no product-source diff. A timeout or
+missing result expires the attempt; follow [expire.md](expire.md), diagnose,
+and resume exploration. Do not waive shared exploration merely to preserve
+speed.

package/skills/engineering/rush-issues/references/implementation.md

@@ -0,0 +1,66 @@
+# Isolated implementation loop
+
+Schedule runnable units continuously after exploration succeeds. At most 4
+units may own active implementation workers at once.
+
+## Workspace contract
+
+Each unit gets a dedicated branch and isolated Git workspace based on the
+correct dependency/base state. That workspace belongs to the unit through
+implement, validate, self-review, fixes, expiry, and diagnosis. Never wipe it
+on spawn death or timeout.
+
+On Pi, the default subagent sandbox can write only beneath its workspace root.
+A linked worktree's `.git` file points to administrative metadata under the
+parent repository, outside that root, so Git mutation will fail. For the first
+Git-mutating spawn, pass `git_clone_workspace:true` with a dedicated
+`sandbox_dir`; record the resulting self-contained clone as the unit workspace.
+Retries use that clone directly without cloning it again. Use `sandbox:false`
+only when the caller explicitly accepts unrestricted writes. Never launch a
+Git-mutating sandboxed worker in a linked worktree.
+
+## Implementer brief
+
+Include:
+
+- original unit source and acceptance criteria
+- whole-spec context and neighboring unit boundaries
+- absolute exploration findings path
+- absolute unit workspace and branch
+- declared dependencies and shared surfaces
+- selected implementer model/effort
+- required outcome and validation obligations
+- instruction not to open a per-unit PR
+- result path/return schema and 30-minute deadline
+
+Do not require an implementation leaf skill, development methodology, or
+producer-specific evidence contract. The active harness chooses its own
+implementation method. Rush constrains the unit boundary, workspace, outcome,
+validation, and return contract only.
+
+## Per-unit loop
+
+1. **Implement:** change only the unit scope using the harness's chosen method.
+   Commit coherent progress on the unit branch.
+2. **Validate:** prove the acceptance criteria and affected behavior with the
+   relevant repository checks. Record concrete not-applicable reasons where a
+   named validation category does not apply.
+3. **Self-review:** inspect the net diff adversarially against the unit ACs,
+   repository rules, failure states, and affected shared surfaces.
+4. **Act:** fix every blocking self-review finding, then repeat validation and
+   self-review on the new HEAD.
+5. **Finish:** return the exact branch/SHA, changed paths, validation commands,
+   self-review result, and any integration notes. Do not open a per-unit PR.
+
+After 2 failed fix cycles or a 30-minute task attempt, follow
+[expire.md](expire.md): preserve the workspace, diagnose, revise the plan, and
+continue. The next worker resumes the same workspace and reads the diagnosis.
+
+## Scheduling
+
+- Start independent runnable units together up to the in-flight cap of 4.
+- Refill a free slot as soon as another unit becomes runnable.
+- Blocking dependencies constrain start order; shared-surface interference is
+  recorded for combination but does not by itself serialize workers.
+- One diagnosis does not stall unrelated runnable units.
+- The combine stage waits for every mapped unit to succeed.

package/skills/engineering/rush-issues/references/preflight.md

@@ -0,0 +1,31 @@
+# Preflight
+
+Preflight has exactly two outputs: selected model operating points and the
+confirmed target branch. It does not classify workflow eligibility, decompose
+the spec, create workspaces, probe delivery, or decide autonomy. Those belong
+to later Rush stages.
+
+## 1. Select models
+
+Run the fast path and shared preflight planner in
+[shared-modules.md](shared-modules.md). Ask only for the implementer model; fill
+and state the explorer and reviewer. Prefer:
+
+- explorer: balanced-coder, `gpt-5.6-terra@high` when discovered
+- reviewer: distinct deep-reasoner, `gpt-5.5@high` when discovered
+
+Record exact model ids and efforts. Sync/bank the shared catalog only after the
+human answers. Repository risk may change the recommended model tier; it never
+changes the workflow.
+
+## 2. Confirm delivery target
+
+Fetch remote heads and confirm `targetBranch` from those fetched facts. Do not
+infer a stale local default.
+
+The shared planner also returns fields used by other workflows. Rush records
+only its model selections and `targetBranch` from this stage; an autonomy fill
+is not merge authorization for a Rush run.
+
+Preflight succeeds when the model slots and target branch are recorded. Proceed
+to [task-plan.md](task-plan.md) for all run setup and decomposition.

package/skills/engineering/rush-issues/references/profiling.md

@@ -0,0 +1,78 @@
+# Profiling
+
+Profile the workflow for later performance analysis without blocking delivery.
+Track each unit, fleet stage, bounded attempt, retry, and diagnosis.
+
+## Metrics
+
+| Metric | Meaning |
+|---|---|
+| `wallMs` | Elapsed enter-to-exit time |
+| `llmMs` | Time attributed to active model work |
+| `programMs` | Time attributed to local commands/programs |
+| `waitMs` | Pure external wait, such as CI or queue pending |
+| `effectiveMs` | Union of intervals with LLM or program activity, excluding pure wait |
+| `retries` | Current-cycle and cumulative retries |
+| `diagnoses` | Number and duration of diagnosis checkpoints |
+| `outcome` | `succeeded`, `expired`, `blocked`, or `cancelled` |
+| `expireReason` | Stable reason code when an attempt expires |
+
+Avoid double counting nested program calls inside an LLM task. If only coarse
+telemetry exists, classify non-overlapping intervals by their primary state.
+Use `null` plus a note for unavailable timing; do not turn unknown into zero.
+Across parallel workers, report both run wall time and summed worker time.
+
+## Layout
+
+```text
+.resolve-issues/rush/<run-id>/
+  task-plan.json
+  exploration/FINDINGS.md
+  profiling/
+    run.jsonl
+    summary.json
+```
+
+Append one JSONL event at task-plan checkpoints. Example:
+
+```json
+{
+  "ts": "2026-08-22T12:00:00.000Z",
+  "runId": "rush-1200",
+  "planRevision": 12,
+  "scope": "unit",
+  "unit": "1201",
+  "stage": "implement",
+  "attempt": 2,
+  "event": "exit",
+  "outcome": "expired",
+  "expireReason": "timeout-task",
+  "wallMs": 1800000,
+  "llmMs": 1320000,
+  "programMs": 240000,
+  "waitMs": 240000,
+  "effectiveMs": 1560000,
+  "retries": {"cycle": 2, "total": 2},
+  "diagnoses": 0,
+  "headSha": "abc123"
+}
+```
+
+Diagnosis events include the changed hypothesis/plan and link to the expired
+attempt. Fleet stages use `scope: "fleet"` and stage `explore`, `combine`,
+`canary`, `review`, or `cicd`. Every event carries the same `planRevision` as
+the persisted transition it describes; summary generation refuses mismatched
+or missing revisions rather than reconciling them by guess.
+
+## Summary
+
+Rewrite `summary.json` on each task-plan checkpoint and at handoff with:
+
+- per-unit, per-stage, and per-attempt wall/effective/wait totals
+- run wall time and summed worker time
+- worker utilization: busy slot time / available slot time
+- retry, expiry, diagnosis, and blocker counts by reason
+- time to task-plan display, exploration completion, PR open, review success,
+  CI green, queue entry, and merge
+
+Link the files in the final handoff; do not paste the full event log.

package/skills/engineering/rush-issues/references/review.md

@@ -0,0 +1,48 @@
+# Independent factual review
+
+Run one independent review stage on the combined PR HEAD using the
+`code-review` skill and the reviewer slot.
+
+## Independence
+
+- Reviewer model differs from the implementer and is a deep-reasoner when
+  available; prefer `gpt-5.5@high` when discovered.
+- Fresh context includes the original spec, repository standards, target
+  branch, combined branch/HEAD, and exploration path.
+- Fixed point is the reviewer's own merge-base with
+  `origin/<targetBranch>`.
+
+Producer summaries, validation notes, logs, and evidence are untrusted claims.
+They may point to a file, AC, or command, but the reviewer verifies facts by
+reading original sources, inspecting the actual diff/code, running relevant
+checks, and observing behavior where needed. Do not ask the producer to create
+new evidence collateral as a substitute for verification.
+
+## Review procedure
+
+1. When `warehouseCanaryRequired` is true, require a successful canary result
+   for the current exact HEAD. Then invoke the absolute `code-review` skill path
+   on the combined HEAD.
+2. Review both axes: repository **Standards** and original **Spec**.
+3. Independently run or reproduce the checks needed to support each material
+   conclusion. A producer-provided green log is not a factual substitute.
+4. Return findings with severity and file/line references, plus commands the
+   reviewer actually ran. The review result is coordination state, not an
+   evidence-generation deliverable.
+5. Succeed only with no Spec gap/wrongness/creep and no hard Standards
+   violation. Record non-blocking baseline observations as deferrals.
+
+## Fix loop
+
+For blocking findings, fix the combined PR branch, run relevant lint/build/
+test/smoke, rerun [canary.md](canary.md) when required, then spawn a fresh
+review of the new HEAD. Record that exact SHA as `reviewedHead` only after
+success. Never treat a fix as accepted before validation, required canary, and
+re-review. Any later code/config commit, including a CICD fix, clears
+`reviewedHead`, marks the prior canary result stale, and returns the new HEAD
+through required validation/canary and review before it may be enqueued or
+merged.
+
+After 2 failed fix/review cycles or a 30-minute review task, expire the attempt,
+diagnose the recurring class or task shape, revise the plan, and continue. A
+human/external blocker ends in `blocked`, not a false successful review.

package/skills/engineering/rush-issues/references/shared-modules.md

@@ -0,0 +1,66 @@
+# Shared modules
+
+Rush owns orchestration, not copies of model, review, smoke, or queue doctrine.
+Implementation method belongs to the active harness. Resolve installed leaf
+skills from the active skills root only for stages that explicitly invoke one,
+and pass absolute paths to those subagents.
+
+## Model catalog and recommendation
+
+**Owner:** [`harness-runtime`](../../harness-runtime/)
+
+| Piece | Path |
+|---|---|
+| Catalog doctrine | `harness-runtime/references/model-catalog.md` |
+| Team seed | `harness-runtime/references/model-catalog-seed.json` |
+| Catalog CLI | `harness-runtime/model-catalog.mjs` |
+| Discovery CLI | `harness-runtime/discover-models.mjs` |
+| Rush fast path | `rush-issues/scripts/preflight-models.mjs` |
+| Shared preflight planner | `resolve-issues/scripts/preflight-questions.mjs` |
+
+Before reading the longer catalog doctrine, run:
+
+```bash
+node <skillsRoot>/rush-issues/scripts/preflight-models.mjs \
+  --harness <pi|codex|claude-code> \
+  --risk <routine|high> \
+  --available <comma-separated-current-turn-model-ids> \
+  --ask-only
+```
+
+The fast path discovers current-turn availability, recommends the implementer,
+fills explorer and reviewer, and emits the implementer picker payload. Feed the
+model choices and fetched target-branch choices through the shared preflight
+planner so the native interaction asks exactly those two questions.
+
+| Slot | Selection |
+|---|---|
+| Implementer | Human picks from discovered eligible models; routine recommends balanced-coder |
+| Explorer | Filled balanced-coder; prefer `gpt-5.6-terra@high` when discovered |
+| Reviewer | Filled distinct deep-reasoner; prefer `gpt-5.5@high` when discovered |
+
+Only discovered or explicitly human-named models are eligible. Defer catalog
+sync/bank until after the human answers. Spawn read-back must match each
+recorded slot. The shared planner is also used by workflows that record an
+autonomy fill; Rush must discard that field and must not treat it as merge
+authorization.
+
+## Leaf skills
+
+| Stage | Skill | Rush-specific constraint |
+|---|---|---|
+| Independent review | `code-review` | One fresh review of the combined branch, Standards and Spec axes |
+| Runtime smoke | `smoke` | Run when applicable; record a concrete not-applicable reason otherwise |
+| Merge queue | Queue owner, such as `mergify` | Inspect live configuration and use its watcher/enqueue procedure |
+
+`code-review` may be externally installed; never assume a repository-relative
+path. Producer summaries or validation notes may help locate claimed behavior,
+but the independent reviewer establishes facts from source, diff, commands,
+and runtime behavior itself. Do not add evidence-generation work merely to
+make the review look substantiated.
+
+## Rush-owned behavior
+
+Rush owns the task plan, shared findings location, isolated workspaces,
+continuous scheduling with in-flight cap 4, one-branch combination, whole-spec
+PR boundary, expiry/diagnosis loop, and profiling logs.

package/skills/engineering/rush-issues/references/task-plan.md

@@ -0,0 +1,110 @@
+# Task plan
+
+After model/target preflight, build the task plan as the run's live source of
+truth. Show it before exploration or implementation and keep it synchronized
+with every worker and fleet transition.
+
+## Initialize the run
+
+1. Prefer a dedicated run branch and workspace based on the confirmed target.
+   The run workspace owns combination, the single PR, review fixes, and CI
+   fixes. Do not reuse a dirty unrelated checkout.
+2. Turn a plain issue into one unit; turn an epic or fat issue into
+   implementable units that collectively cover the entire original spec.
+3. Record each unit's source and acceptance criteria, blocking dependencies
+   including premise dependencies, likely shared surfaces, and the whole-spec
+   definition of done.
+4. Read repository hazard guidance and attach its implementation, test, and
+   review obligations to affected units. Risk never removes a unit, changes the
+   one-PR boundary, or routes the run to another workflow.
+5. Set `warehouseCanaryRequired` when the run changes executable warehouse
+   behavior or its data contract, and record the concrete classification reason.
+6. Create the run directory, shared findings path, profiling log, and initial
+   machine-readable plan, then render the first board.
+
+## Shape
+
+Fleet rows: `explore`, `combine`, `canary`, `review`, `cicd`. Render `canary` as
+not applicable when `warehouseCanaryRequired` is false.
+
+Per-unit fields:
+
+| Field | Meaning |
+|---|---|
+| `id`, `title` | Stable unit identity and short title |
+| `source` | Original issue/spec/AC locator |
+| `workspace`, `branch` | Absolute owned Git workspace and branch |
+| `dependsOn` | Blocking unit ids |
+| `stage` | `pending`, `implement`, `validate`, `self-review`, `diagnose`, or `done` |
+| `status` | `pending`, `in-flight`, `diagnosing`, `succeeded`, `blocked`, or `cancelled` |
+| `attempt` | Current bounded attempt number |
+| `retries`, `diagnoses` | Current-cycle and cumulative counters |
+| `worker` | Slot 1-4 while in flight |
+| `clock` | Current attempt and cumulative wall time |
+| `note` | SHA, failure, diagnosis, or blocker |
+
+Run-level fields include `planRevision`, models/efforts, `targetBranch`, run
+workspace/branch, original spec locator, explicit merge authorization when one
+was supplied, exploration path, combined PR/HEAD, `reviewedHead`, and
+`warehouseCanaryRequired`, its classification reason, durable canary result
+path, and start/update timestamps.
+
+Persist the machine-readable plan at:
+
+```text
+.resolve-issues/rush/<run-id>/task-plan.json
+```
+
+## Checkpoint consistency
+
+Use one ordered checkpoint protocol for every transition:
+
+1. Increment `planRevision` and apply the complete state transition in memory.
+2. Append the profiling event with that same revision.
+3. Persist the plan and profiling checkpoint.
+4. Render the board by reading the persisted plan revision, not from a separate
+   hand-built snapshot.
+
+A checkpoint is invalid if the board, `task-plan.json`, and profiling event
+disagree on status, stage, retry/diagnosis counters, clocks, HEAD, or revision.
+Do not display a future transition before persistence or reuse an old board
+after persistence.
+
+## First display
+
+The first board is the visible task-planning result and appears before any
+explorer or implementer spawn.
+
+```text
+rush-issues  rev 12  workers 2/4  elapsed 18m  PR pending
+fleet: explore OK  combine .  canary n/a  review .  cicd .
++------+---------------------------+-------------+------------+---------+-------+
+| id   | title                     | stage       | status     | retry   | clock |
++------+---------------------------+-------------+------------+---------+-------+
+| #1201| fix queue stall watcher   | self-review | in-flight  | 1/2     | 16m   |
+| #1202| parse rename edges        | validate    | in-flight  | 0/2     | 09m   |
+| #1203| split oversized importer  | diagnose    | diagnosing | 2/2 D1  | 30m   |
++------+---------------------------+-------------+------------+---------+-------+
+```
+
+Use compact Markdown or text that remains readable in the active harness. Do
+not hide blocked or diagnosing units from the board.
+
+## Refresh checkpoints
+
+Redisplay when:
+
+- task-plan initialization completes
+- a fleet stage enters/exits
+- a worker is acquired/freed
+- a unit enters/succeeds/expires/blocks
+- validation fails or becomes green
+- a required warehouse canary starts, fails, succeeds, blocks, or is invalidated
+- a retry or diagnosis is recorded
+- a dependency becomes runnable
+- the combined PR opens or HEAD changes
+- about every 5 minutes during long activity
+
+Skip a redraw only when no material state changed. The final board includes all
+unit outcomes, PR URL/SHA when one exists, exploration/profiling paths, retry
+and diagnosis totals, and any exact blocker that prevented a whole-spec PR.

package/skills/engineering/rush-issues/scripts/discover-models.mjs

@@ -0,0 +1,9 @@
+// Thin wrapper: canonical ownership lives in harness-runtime.
+export * from '../../harness-runtime/discover-models.mjs'
+
+import { runCli } from '../../harness-runtime/discover-models.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}

package/skills/engineering/rush-issues/scripts/model-catalog.mjs

@@ -0,0 +1,9 @@
+// Thin wrapper: canonical ownership lives in harness-runtime.
+export * from '../../harness-runtime/model-catalog.mjs'
+
+import { runCli } from '../../harness-runtime/model-catalog.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}