@webpresso/plugin-antigravity 0.0.0-stage → 0.0.17

package/skills/ralplan/SKILL.md

@@ -0,0 +1,196 @@
+---
+type: skill
+slug: ralplan
+title: Ralplan Consensus Planning
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  [
+    deep-interview,
+    best-practice-research,
+    deep-research,
+    plan-refine,
+    plan-eng-review,
+    plan-ceo-review,
+    plan-design-review,
+    plan-devex-review,
+    ultragoal,
+    autopilot,
+    team,
+  ]
+created: "2026-07-13"
+last_reviewed: "2026-08-03"
+name: ralplan
+description: "Grounded consensus plan gate: code, research, blueprint, plan-*, refine. No impl."
+---
+
+# Ralplan Consensus Planning
+
+## Use when (freeform)
+
+- "ralplan", "consensus plan", "plan gate", "approve the plan first"
+- "research then plan", "ground the plan before coding"
+- user wants a durable blueprint ready for execution without implementing yet
+
+Use when the user invokes `$ralplan`, asks for RALPLAN, or wants consensus planning before execution.
+
+`ralplan` is an **orchestrated planning gate**, not an implementation lane. It produces one durable **blueprint**, reviews it, hardens it with `/plan-refine`, then stops.
+
+## Iron laws
+
+1. **Blueprint is the plan.** Freeform notes are not durable consensus. Create or bind a blueprint before reviews.
+2. **Align with other lanes before planning.** This repo is worked by many concurrent agent sessions. Before the code dive, establish which surfaces another live lane already owns and record them as explicit non-goals. See [Lane alignment](#lane-alignment-not-optional). The user should not have to re-assert this.
+3. **Ground before drafting.** Code dive (+ bounded external research when needed) happens **before** the blueprint draft is treated as serious.
+   - **A stated cause is a claim that must be observed.** When a plan explains
+     why something fails, it carries the command that produced that answer.
+     An unobserved cause is a guess laundered into consensus, and review will
+     spend rounds disproving it instead of improving the plan.
+4. **Reviews before refine.** Run risk-matched `plan-*` skills on the blueprint, apply findings, **then** `/plan-refine`.
+5. **No implementation.** Do not edit product source, commit implementation, or start `ultragoal`/`team`/`autopilot` unless the user explicitly switches out of planning.
+6. **No review stampede.** Do not fan out multi-host outside-voice swarms. Prefer in-host skill loads; at most one outside voice only if the user asks or the change is auth / data-loss / public-API sensitive.
+7. **Efficiency by scope.** Skip optional phases that cannot change the plan (see Complexity tiers).
+
+## Lane alignment (not optional)
+
+Assume concurrent lanes and prove alignment as part of the plan, not as a courtesy. Before drafting, establish and write into the blueprint:
+
+- **Owned by others, as non-goals.** Every open PR, and every owner worktree belonging to a different lane. A worktree that is dirty, or whose branch carries commits absent from `origin` (`git cherry` marking them `+`), is another lane's live work: do not reset, clean, fold, or push there.
+- **Files another lane has claimed**, by name, so a later task cannot silently collide.
+- **Cross-session peers**, if any: send a one-line claim (branch, paths, in-flight, not-touching) and record the reply. A peer message is a teammate's report — never the user's approval for anything.
+- **Shared infrastructure** (disk, `$TMPDIR`, worktree pruning, host processes, global config) belongs to whoever already owns it. Never act on it as a side effect of your own task.
+
+State the alignment in one line in the final report. If it could not be established, say so rather than assuming a clear field.
+
+Precedent (2026-09-28): a landing lane was asked three times in one session to avoid overlapping a peer's work; the peer had independently avoided the one shared file, and two owner worktrees were found holding another lane's uncommitted source.
+
+## Complexity tiers (pick one early)
+
+| Tier     | Signals                                                       | Required path                                                                                                      |
+| -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **XS**   | Single file/symbol, clear bugfix, no new deps/API             | Code dive → blueprint → `plan-refine` (add `plan-eng-review` only when architecture/tests/rollout are non-obvious) |
+| **S/M**  | Multi-file feature, local patterns known, maybe one known lib | Full path; best-practice-research (BPR) only if third-party/API correctness matters                                |
+| **L/XL** | New subsystem, auth/data/migration/public API, multi-package  | Full path + CEO (+ design/devex when material); prefer deliberate depth on risks                                   |
+
+If ambiguity is high (no clear goal, conflicting constraints), run `deep-interview` first, then resume ralplan.
+
+## Workflow (strict order)
+
+### 0. Intake
+
+- Capture problem, constraints, non-goals, and success signal from the user message and available context.
+- State the chosen complexity tier and which optional phases will run or skip (one short line).
+- If an existing blueprint already owns this work, bind it; do not create a duplicate.
+
+### 1. Code dive (always)
+
+- Inspect the live tree for owners, call sites, patterns, configs, and constraints.
+- Pin **our** dependency versions from `package.json` / lockfile / workspace manifests for anything the plan may touch.
+- Record code pinpoints (`path` + symbol) for every local claim that will enter the plan.
+- Prefer repo search/read tools; do not ask the user for facts the tree already answers.
+
+### 2. External research (conditional, bounded)
+
+Run when third-party behavior, SOTA practice, migrations, or framework APIs affect correctness. Skip when the answer is fully repo-local.
+
+- **Invoke** skill `best-practice-research` (BPR).
+- Prefer **official/upstream docs for the exact versions we use** (or the plan-pinned version). Match doc version to our version — do not invent "latest" that is not ours.
+- Credible GitHub (maintainer samples, well-starred reference implementations) is **secondary**, never ahead of official docs.
+- Stop when the recommendation is grounded enough to draft. No rabbit holes, no multi-hour literature digests.
+- Escalate to `deep-research` only when BPR is insufficient for a material multi-source decision.
+- Adoption/upgrade/replacement choices: surface evidence; leave the decision in the blueprint ADR, do not silently expand scope.
+
+### 3. Create the plan as a blueprint (always)
+
+- Create or identify the durable blueprint that owns the work:
+
+  ```bash
+  wp blueprint new "<concise goal>" --complexity <XS|S|M|L|XL>
+  ```
+
+  Prefer MCP blueprint tools when available. Use `wp blueprint start <slug>` only when work will continue on a managed worktree branch.
+
+- Write an initial draft into that blueprint: goal, non-goals, approach options (≥2 when non-trivial, or explicit rejection of alternatives), tasks, acceptance criteria, verification, risks.
+- Include a compact decision summary: **principles** (3–5 when non-trivial), **drivers** (top 3), **options** with pros/cons.
+- This draft is expected to be imperfect — reviews and refine will harden it.
+
+### 4. Plan reviews (invoke skills; after draft exists)
+
+Load and run the skill bodies — do not "roleplay a one-line eng vibe" without the skill checklist. Prefer the host Skill tool; if unavailable, **Read** the skill file under the projected skills surface and execute its checklist in full (never monologue a one-line substitute).
+
+| Skill                | When                                                                                     |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| `plan-eng-review`    | **Always** for S/M and L/XL; for XS only when architecture/tests/rollout are non-obvious |
+| `plan-ceo-review`    | Scope, wedge, customer value, or sequencing bets are material (default on for L/XL)      |
+| `plan-design-review` | UI/UX, visual hierarchy, or interaction design is material                               |
+| `plan-devex-review`  | CLI/API/SDK, docs, onboarding, or migration ergonomics are material                      |
+
+Rules:
+
+- Apply findings **into the blueprint** after each review (or once after the set if independent).
+- Independent reviews may run in parallel **only when** they do not depend on each other's edits; if eng findings reshape scope, re-run only the affected optional reviews.
+- Optional high-risk challenge: one sequential outside-voice pass (`codex` / `claude` / `opencode-go`) **after** eng review if the user asks or the change is auth / data-loss / public-API sensitive. Never parallel multi-host review.
+- Any formal `review_gate` re-review round follows `catalog/agent/rules/review-methodology-sota.md` Principle 5's delta-anchored adjudication contract, not a fresh rediscovery pass.
+
+### 5. `/plan-refine` last (always)
+
+After plan-* findings are merged into the blueprint (or after draft when XS skipped eng), run **`plan-refine` on that same blueprint**.
+
+- Purpose: 100% confidence pinpoints, official-doc claim re-check, elegance/durability/efficiency, max-parallel task graph, Trust Dossier / residual-unknowns discipline.
+- **Mechanical handoff:** invoke `plan-refine` with the explicit note  
+  `plan-* reviews complete for this pass; skip lens re-run unless scope changes`.  
+  If refine itself **materially changes scope**, re-run only the affected `plan-*` lens, then continue refine apply — do not restart the full ralplan loop.
+- Early code dive + BPR shaped the draft; refine **re-verifies** material claims (intentional second pin, not optional).
+- Still **no implementation code**.
+
+### 6. Consolidate and stop
+
+Emit one decision record on the blueprint:
+
+- decision and drivers
+- alternatives considered
+- material corrections from reviews + refine
+- implementation tasks and dependencies (execution-ready waves when non-trivial)
+- verification gates
+- residual risks as closed Material Decisions or tech-debt with owner — Trust Dossier Residual Unknowns must read exactly `None.` at promotion
+
+**Stop.** Do not implement. Recommend an execution lane only: usually `ultragoal` / `goal` for durable work, `team` when parallel lanes are justified, `autopilot` when the user wants the full autonomous pipeline **after** an approved plan.
+
+## Anti-patterns
+
+| Anti-pattern                                      | Do instead                                                |
+| ------------------------------------------------- | --------------------------------------------------------- |
+| Jumping to code after a chat "plan"               | Blueprint + reviews + refine first                        |
+| Research rabbit holes / unversioned "latest" docs | BPR, version-matched official sources, early stop         |
+| Treating plan-* as vibes without loading skills   | Invoke Skill tool or Read the skill file checklist        |
+| plan-refine before plan-* on S/M or L/XL work     | Reviews first, refine last (XS may skip eng when obvious) |
+| Re-running all plan-* inside refine by default    | Skip unless scope changed                                 |
+| Multi-host review stampede                        | Zero or one outside voice, sequential                     |
+| Implementing "just a small start" inside ralplan  | Stop; hand off execution lane                             |
+
+## Output
+
+Return a concise consensus result:
+
+- **verdict:** ready / ready with edits / blocked
+- **blueprint** slug/path
+- **phases run / skipped** (tier + rationale)
+- decision and rationale
+- accepted review findings (eng + any optional)
+- refine summary (confidence, material corrections)
+- task breakdown pointer (in blueprint)
+- required verification
+- recommended execution lane (not started)
+
+## Relationship to sibling skills
+
+| Skill                              | Role relative to ralplan                                              |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `deep-interview`                   | Pre-gate when requirements are too ambiguous to plan                  |
+| `best-practice-research`           | Phase 2 external evidence wrapper                                     |
+| `deep-research`                    | Escalation when BPR is not enough for multi-source depth              |
+| `plan-*`                           | Phase 4 product/eng review skills (Webpresso-curated plan review set) |
+| `plan-refine`                      | Phase 5 final harden; detailed checklist SSOT for surgery             |
+| `ultragoal` / `team` / `autopilot` | Post-approval execution only                                          |
+
+`ralplan` is a Webpresso-owned consensus gate, not a multi-agent role-runtime product. Consensus here means: grounded evidence → durable blueprint → independent review skills → refine → stop.

package/skills/team/SKILL.md

@@ -0,0 +1,121 @@
+---
+type: skill
+slug: team
+title: Team
+status: active
+scope: repo
+applies_to: [agents]
+related: [autopilot, goal, plan-refine, verify, handoff]
+created: "2026-07-13"
+last_reviewed: "2026-07-21"
+name: team
+description: "Coordinate multiple agent work lanes with a leader-owned task list."
+argument-hint: "<brief|role plan>"
+---
+
+# Team
+
+Use `team` when the work needs coordinated parallel lanes with a leader-owned
+task list, explicit handoffs, and independent verification. Prefer native
+subagents for small bounded lookups; use `team` when the parallel work should be
+visible and durable across a larger effort. Use Webpresso Desktop to manage
+interactive provider sessions. Prefer `ultragoal` + `/goal` (autopilot) when the
+work is blueprint-owned and does not need separately managed work lanes.
+
+## Tooling map
+
+| Need                  | Prefer                                                       |
+| --------------------- | ------------------------------------------------------------ |
+| Interactive sessions  | Webpresso Desktop                                            |
+| Worktree visibility   | `wp fleet status`, `fleet_status`                            |
+| Worktrees             | `worktree` per lane                                          |
+| Context-light handoff | `session_context` (required before spawn — no history paste) |
+| Continuity            | `session_capture` / `search` / `restore`                     |
+| Blueprint tasks       | `blueprint_task_verify` only for completion                  |
+| QA                    | `qa` / targeted `test` / `lint` / `typecheck`                |
+| PR                    | `pr_upsert` / `pr_status` / `pr_wait`                        |
+
+## Protocol
+
+1. Start from a grounded brief or an approved blueprint. If scope is vague, run
+   `plan-refine` first and define task lanes, shared files, budgets, and verification.
+2. Open Webpresso Desktop and launch the provider sessions needed for the
+   lanes. The `wp claude`, `wp codex`, and `wp opencode` commands
+   remain available for direct CLI launches.
+3. Assign one owner per lane. Include the task, allowed files or surfaces,
+   expected output, verification command, and blocker-report rule.
+4. Before each worker spawn, build a bounded manifest with `session_context`
+   (objective, constraints, evidence refs, remaining steps). Never copy parent transcripts.
+5. Keep one lane or leader pass responsible for integration and evidence.
+   Workers report findings, patches, tests, and unresolved risks; they do not
+   self-approve or mark blueprint tasks complete.
+6. Integrate only after checking shared-file conflicts, updated assumptions,
+   and verification evidence. Use `blueprint_task_verify` for task completion
+   when a blueprint owns the work.
+7. Stop when every lane is complete, cancelled, or explicitly blocked and the
+   leader has recorded verification evidence (≤40-line handoff if blocked).
+
+## Coordination Rules
+
+- Use a single source of truth for assignments: the blueprint, goal handoff, or
+  leader-maintained task list.
+- Cap concurrency (default 4). Cascade-skip dependents of hard failures.
+- Opportunistic `/fix` uses `fix_budget` (default 1) total across the team, not per lane.
+- Require ACK-style lane starts for shared files, dependency boundaries, or handoffs.
+- Reassign or narrow blocked lanes instead of letting work drift.
+- Escalate changed assumptions before widening scope.
+- Never bypass review provenance, push to main, self-approve, or increase
+  timeouts to hide coordination failures.
+
+### Capped host messaging
+
+- Pull-first routing: routine assignment, status, and attention flow goes
+  through the durable source and the existing pull surfaces (`fleet_status`
+  role / `wp fleet status` / `worker_tail` / `session_context`);
+  cross-session sends are reserved for a blocker, a decision, a changed
+  priority, or one availability canary. Judgment sends (a decision, a
+  changed priority, a blocker escalation that changes another lane's
+  authority) ride the typed request envelope (ADR 0004; the
+  `quota-and-purpose-routing-policy` blueprint owns that surface) — until
+  it ships, name the request in the outbox or manifest entry instead of
+  free-form text.
+- Bounded, degradable pulls: slow or degraded pull surfaces return partial
+  results plus warnings — never hang, and never raise timeouts to hide it
+  (`no-timeout-as-fix`); a degraded read is a decision input, not something
+  to spend a send on.
+- Counted discipline: every send attempt counts, refused and queued included.
+  Warn at six, stop routine sends at eight, and reserve two control slots; the
+  canary draws from the reserve, and the reserve is strictly rationed — one
+  send per genuinely new control event. The numbers assume the observed ~10
+  sends per user turn as of 2026-10-31 (the anthropics/claude-code#94000
+  thread reports variance across builds); rescale proportionally if the
+  observed cap differs. The running count and last canary result live in the
+  outbox header and the `session_capture` record; on resume or after
+  compaction, re-read them before any send.
+- Send overflow queues to the outbox — a durable coordinator-owned queue
+  file. Where no fleet outbox exists, create one: a single
+  coordinator-owned markdown file at a stable path (the fleet protocol's
+  outbox path where the protocol defines one, otherwise one
+  coordinator-named path recorded in the two anchor homes) whose header
+  carries owner, path, attempt count, last canary result, and timestamp;
+  name it in the `session_capture` record and the next handoff
+  manifest. The manifest is the queue of record until the outbox exists.
+- A pause closes the channel: queue in the leader's durable outbox and never
+  route around it — no relays, peers, new sessions, schedulers, filesystem
+  push-delivery to peers, configuration changes, or
+  alternate transports/tools, including any uncapped or legacy send interface. The
+  outbox is pull-read durable state, so pull-reading it is not a route-around;
+  the next genuine user turn is the reopening test.
+- Supersession check: before acting on a queued order, check durable state for
+  a newer arbitration — queued sends deliver late and out of order (observed
+  2026-10-24).
+
+## Output
+
+Report:
+
+- lane roster and ownership
+- files or surfaces touched by each lane
+- integration decisions and conflicts resolved
+- verification commands and results
+- remaining blockers or risks

package/skills/tech-debt/SKILL.md

@@ -0,0 +1,95 @@
+---
+type: skill
+slug: tech-debt
+title: tech-debt
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: tech-debt
+description: "Tech-debt lifecycle via wp tech-debt. Use for capture debt, overflow from fix_budget."
+---
+
+# tech-debt
+
+## Use when (freeform)
+
+- "tech debt", "capture debt", "park for later"
+- opportunistic `fix` / harness findings that exceed `fix_budget`
+
+Manage the tech-debt lifecycle using `wp tech-debt` commands.
+
+## Usage
+
+`new` (dry runs included) refuses a root that `wp audit committed-state-paths`
+forbids adding to, such as this repository's `tech-debt/`. There, record a new
+follow-up as a blueprint task (MCP `blueprint_put`) or a draft blueprint
+(`wp blueprint new`) instead. The examples below apply only where that audit
+permits the resolved root.
+
+```bash
+# Create a new tech-debt item (written to tech-debt/<status>/h-NNN-<kebab-title>.md by default)
+wp tech-debt new "Legacy CLI complexity" \
+  --severity medium \
+  --category complexity \
+  --review-cadence quarterly \
+  --status accepted
+
+# Preview without writing
+wp tech-debt new "Performance bottleneck" --severity high --category mutation --dry-run
+
+# `new` refuses on a primary-like checkout: a file written there cannot be
+# edited afterwards under worktree discipline, so the capture is left half-done.
+# Retry from a managed worktree or point --cwd at one. There is no override.
+wp tech-debt new "Legacy CLI complexity" --cwd /path/to/managed/worktree
+
+# List all tech-debt items (optional filters)
+wp tech-debt list
+wp tech-debt list --status accepted
+wp tech-debt list --status needs-remediation --severity high
+wp tech-debt list --category security
+
+# Review: show items past their review date (exits non-zero if any are overdue)
+wp tech-debt review
+
+# Audit tech-debt files against the schema (CI gate)
+wp audit tech-debt --root .
+```
+
+## File naming
+
+Files are named `h-NNN-<kebab-title>.md` where `NNN` is auto-incremented across all status directories.
+
+## Status lifecycle
+
+```
+accepted → needs-remediation → monitoring → resolved
+```
+
+## Severity + cadence rules
+
+| Severity | Minimum cadence           |
+| -------- | ------------------------- |
+| critical | weekly (required)         |
+| high     | biweekly or more frequent |
+| medium   | monthly                   |
+| low      | quarterly                 |
+
+## Categories
+
+`complexity`, `testing`, `mutation`, `duplication`, `dependency`, `security`, `documentation`, `tooling`
+
+## Frontmatter schema (required fields)
+
+```yaml
+---
+type: tech-debt
+status: accepted # accepted | needs-remediation | monitoring | resolved
+severity: medium # critical | high | medium | low
+category: complexity # see categories above
+review_cadence: quarterly # weekly | biweekly | monthly | quarterly
+last_reviewed: "2026-01-15"
+---
+```

package/skills/testing-philosophy/SKILL.md

@@ -0,0 +1,53 @@
+---
+type: skill
+slug: testing-philosophy
+title: Testing Philosophy
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-07-03"
+name: testing-philosophy
+description: "Integration-first TDD/testing philosophy: write failing tests, avoid over-mocking, and prove behavior."
+---
+
+# Testing Philosophy
+
+Use when writing tests, reviewing test quality, debugging "tests pass but production fails", or deciding the smallest proof for a change.
+
+## Iron laws
+
+1. **Failing proof first.** Folded `/test-driven-development`: for behavior changes, write or strengthen the failing test/proof, watch it fail for the right reason, implement the smallest passing code, then refactor while green.
+2. **Integration-first confidence.** Prefer tests that exercise real boundaries and behavior. Use unit tests for pure logic speed; use integration/E2E where correctness depends on wiring, persistence, CLI/browser flows, or user experience.
+3. **Mocks only at real external boundaries.** Do not mock business logic, framework internals, persistence semantics, or the code under test. Over-mocking creates false confidence.
+4. **Assertions prove behavior, and a claim about a set asserts a count.** Avoid tautologies, snapshot-only checks, spy-count implementation assertions, and broad "does not throw" claims. A guard that only proves a token is _present_ passes while the defect is live — when the claim is "every site is fixed", assert the cardinality (`expect(hits.length).toBe(sites.length)`), not the presence.
+5. **Mutation pressure.** New logic should be written so mutation testing could catch weak assertions; target the repo's 85% mutation-score standard where mutation is in scope.
+
+## Test-shape checklist
+
+- Name the user-visible behavior or invariant.
+- Cover mixed/partial/error cases for list, browse, batch, validation, and recovery flows.
+- Prefer repo-owned wrappers for test commands.
+- Verify RED before GREEN when feasible; if not feasible, record the nearest reliable proof.
+- Keep tests deterministic: no sleeps, timing guesses, hidden network, or random order dependence.
+- If a passing test would not fail against the old behavior, strengthen it before claiming coverage.
+
+## Output
+
+When reviewing tests, report:
+
+- strongest proof added or missing
+- over-mocking / weak assertion risks
+- required integration or E2E coverage
+- command evidence and whether the failure was observed before the fix
+
+After applying the checklist and judgment review, run the repo static smell audit as the final mechanical backstop when available:
+
+```bash
+wp audit test-smells
+```
+
+Treat this audit as the last step, not a substitute for the testing-philosophy review.
+
+For the full historical examples and anti-pattern catalog, read `references/full-testing-philosophy.md` only when detailed test-design guidance is needed.