@webpresso/plugin-codex 0.0.4

package/skills/investigate/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: investigate
+description: "Root-cause investigation workflow: reproduce, isolate, prove, and hand off the minimal repair scope."
+license: MIT
+---
+
+# Investigate
+
+Use this skill when the task is to understand a bug, failure, regression,
+flaky behavior, or confusing symptom before editing code.
+
+## Boundary
+
+- `investigate` owns diagnosis, reproduction, hypothesis testing, and proof.
+- `fix` owns repair. If the user asked to fix the problem and root-cause
+  evidence is still missing, `fix` should run this phase inline first.
+- Stop once you can name the broken invariant, show the failing proof, and
+  point at the owner that should be repaired.
+
+## Tooling map
+
+| Need                   | Prefer                                                           |
+| ---------------------- | ---------------------------------------------------------------- |
+| Reproduce / large logs | `wp_session_execute`, `wp_session_batch_execute`                 |
+| Large files            | `wp_session_execute_file`                                        |
+| Prior continuity       | `wp_session_search`, `wp_session_restore`, `wp_session_retrieve` |
+| Capture findings       | `wp_session_capture` (short pointer, not full paste-back)        |
+| Proof runs             | `wp_test`, `wp_qa`, `wp_lint`, `wp_typecheck`                    |
+| Code search/read       | host Grep/Read first; avoid shell-as-IDE                         |
+
+## Workflow
+
+1. Reproduce or capture the failure.
+   - Run the exact failing command or trace the exact user path (prefer `wp_session_execute`).
+   - Keep the evidence that matters: error text, failing assertion, exit code,
+     log path, or boundary mismatch.
+2. Read the whole boundary.
+   - Inspect the full error site, the owning module, and one nearby working
+     pattern.
+   - Do not edit code yet.
+3. State the root-cause hypothesis.
+   - Name the broken invariant in one sentence.
+   - Name the owner that should enforce it.
+   - Separate facts from guesses.
+4. Disconfirm cheap alternatives.
+   - Test the obvious competing explanations before settling on one cause.
+   - Add temporary diagnostics only when needed, and remove them after one pass.
+5. Produce failing proof.
+   - Prefer a targeted failing test.
+   - If test-first is impossible at this boundary, use the nearest deterministic
+     reproduction instead.
+6. Hand off the minimal repair scope.
+   - List the owner, direct consumers, and the smallest safe verification set.
+   - If the issue is broader than one coherent repair, say so before any edit.
+
+## Output
+
+Return:
+
+- reproduced symptom
+- broken invariant
+- root-cause hypothesis status: confirmed / likely / blocked
+- failing proof
+- owning file or boundary
+- recommended next step: `fix`, `verify`, or a scoped blocker
+
+## Anti-patterns
+
+- Editing before you can name the invariant
+- Treating a stack trace as proof of root cause
+- Hiding uncertainty behind broad "probably X" explanations
+- Expanding a debugging pass into cleanup or refactor work

package/skills/lore-protocol/SKILL.md

@@ -0,0 +1,84 @@
+---
+type: skill
+slug: lore-protocol
+title: lore-protocol
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: lore-protocol
+description: "Manual Lore commit-message trailers with wp audit commit-message; no hook enforcement because PRs squash."
+---
+
+# lore-protocol
+
+Use Lore commit-message trailers manually with `wp audit commit-message`. Hook enforcement is intentionally not installed because this repo uses squash commits.
+
+Lore is a lightweight protocol for embedding decision context directly into
+commit messages — constraints, rejected alternatives, confidence, and
+forward-looking directives — so future engineers understand _why_ a change
+was made, not just _what_ changed.
+
+## Quick start
+
+```bash
+# Validate a commit message file (hard-fail mode — exits non-zero on violations)
+wp audit commit-message --message-file .git/COMMIT_EDITMSG --require-lore
+
+# Soft-warn mode — emits warnings but always exits 0 (adoption ramp)
+wp audit commit-message --message-file .git/COMMIT_EDITMSG --lore-warn
+
+# Opt in per-commit by adding [lore] to the subject line:
+# feat(auth): prevent silent session drops [lore]
+```
+
+## Hook policy
+
+Lore trailers are advisory/manual. Do not install commit-msg or pre-push hooks for Lore enforcement; squash commits are the durable review boundary.
+
+## Trailer format
+
+```
+<intent line: why the change was made, not what changed>
+
+<body: narrative context — constraints, approach rationale>
+
+Constraint: <external constraint that shaped the decision>
+Rejected: <alternative considered> | <reason for rejection>
+Confidence: <low|medium|high>
+Scope-risk: <narrow|moderate|broad>
+Directive: <forward-looking warning for future modifiers>
+Tested: <what was verified>
+Not-tested: <known gaps in verification>
+```
+
+## Required trailers (for `--require-lore` or `[lore]` subject tag)
+
+| Trailer                                      | Required     | Allowed values                   |
+| -------------------------------------------- | ------------ | -------------------------------- |
+| `Confidence:`                                | yes          | `low`, `medium`, `high`          |
+| `Constraint:` or `Rejected:` or `Directive:` | at least one | free text                        |
+| `Scope-risk:`                                | optional     | `narrow`, `moderate`, `broad`    |
+| `Reversibility:`                             | optional     | `clean`, `messy`, `irreversible` |
+| `Tested:`                                    | optional     | free text                        |
+| `Not-tested:`                                | optional     | free text                        |
+| `Related:`                                   | optional     | free text                        |
+
+## Example commit
+
+```
+Prevent silent session drops during long-running operations
+
+The auth service returns inconsistent status codes on token
+expiry, so the interceptor catches all 4xx responses.
+
+Constraint: Auth service does not support token introspection
+Rejected: Extend token TTL to 24h | security policy violation
+Confidence: high
+Scope-risk: narrow
+Directive: Error handling is broad — do not narrow without verifying upstream behavior
+Tested: Single expired token refresh (unit)
+Not-tested: Auth service cold-start > 500ms behavior
+```

package/skills/opencode-go/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: opencode-go
+description: "OpenCode Go aggregate outside-voice reviewer for read-only plan, code, or implementation critique."
+license: MIT
+---
+
+# OpenCode Go aggregate reviewer via OpenCode Go
+
+Use when the user asks for an OpenCode Go aggregate reviewer / OpenCode Go review. Treat output as external advice until independently verified.
+
+## Model routing
+
+Rendered from the committed OpenCode reviewer policy. It does not hardcode model IDs; it resolves the live `opencode models opencode-go` catalog.
+Use the aggregate reviewer when the user wants an OpenCode Go review but did not specify a family. Select one available model in this order: Kimi K2.7 Code for coding quality, DeepSeek V4 Pro for deeper review depth, DeepSeek V4 Flash for cheap/high-availability coverage, then the remaining families.
+Use the aggregate reviewer for general outside-voice plan critique, implementation review, or when the user wants the current best OpenCode Go lane without naming a family.
+
+## Primary path: MCP
+
+When MCP is available, call `wp_review_run` exactly once with provider `opencode`, one selected live model, stage `review`, and a bounded prompt/marker. If no eligible model is known, call `wp_session_execute` at most once for a bounded catalog read before that single review call.
+
+Do not retry or probe, rotate accounts, or change provider within the invocation. The shell blocks below are the MCP-unavailable fallback only.
+
+## MCP-unavailable fallback: auth check
+
+```bash
+opencode providers list >/dev/null
+```
+
+## MCP-unavailable fallback: portable prompt file
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-opencode-go-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Dashboard helper relation
+
+When `wp dash` provides dashboard context, use the shared helper emitter around this outside-voice review. The commands leave standalone OpenCode Go reviews unchanged.
+
+```bash
+DASH_HELPER_RUN_ID=""
+if [ "${WP_DASH:-}" = "1" ] && [ -n "${WP_DASH_RUN_ID:-}" ]; then
+  DASH_HELPER_RUN_ID=$(wp dash-helper-start --provider opencode-go --role reviewer --artifact "${OPENCODE_GO_REVIEW_ARTIFACT:-}")
+fi
+```
+
+After the review runtime exits, record its actual result and optional artifact:
+
+```bash
+OPENCODE_GO_REVIEW_CODE=$?
+if [ -n "$DASH_HELPER_RUN_ID" ]; then
+  if [ "$OPENCODE_GO_REVIEW_CODE" -eq 0 ]; then
+    wp dash-helper-complete --provider opencode-go --run-id "$DASH_HELPER_RUN_ID" --role reviewer --outcome completed --artifact "${OPENCODE_GO_REVIEW_ARTIFACT:-}"
+  else
+    wp dash-helper-complete --provider opencode-go --run-id "$DASH_HELPER_RUN_ID" --role reviewer --outcome failed --artifact "${OPENCODE_GO_REVIEW_ARTIFACT:-}"
+  fi
+fi
+```
+
+The managed OpenCode plugin currently has no parent-linked native subagent completion lifecycle. This capability is explicit unsupported coverage, not an inferred dashboard relation.
+
+## MCP-unavailable fallback: review command
+
+Use read-only prompts. Run from the repo directory; do NOT pass `--dir "$PWD"` because opencode already uses the current directory and the extra index can stall reviews.
+Review is advisory. `wp_review_gate` is plan-only exact-version draft approval/auto-promotion; `wp_review_run` never mutates approval state.
+
+```bash
+# Aggregate reviewer: honor the canonical model-selection policy (Kimi K2.7 Code → DeepSeek V4 Pro → DeepSeek V4 Flash first, then cross-family selection fallbacks).
+CATALOG=$(opencode models opencode-go)
+MODEL=$(echo "$CATALOG" | grep '^opencode-go/kimi' | grep -- '-code$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-pro$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-flash$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/qwen' | grep -- '-max$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/glm' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/minimax' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/mimo' | grep -- '-pro$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | sort -V | tail -1)
+
+# Resolve one model from one bounded catalog read, then launch one review.
+[ -n "$MODEL" ] || { echo "No OpenCode Go model resolved for this reviewer." >&2; exit 2; }
+OPENCODE_GO_REVIEW_EFFORT=${OPENCODE_GO_REVIEW_EFFORT:-medium}
+[ "$OPENCODE_GO_REVIEW_EFFORT" = medium ] || [ "$OPENCODE_GO_REVIEW_EFFORT" = high ] || { echo "OPENCODE_GO_REVIEW_EFFORT must be one of: medium, high" >&2; exit 2; }
+OPENCODE_GO_REVIEW_IDLE_SECONDS=${OPENCODE_GO_REVIEW_IDLE_SECONDS:-180}
+OPENCODE_GO_REVIEW_ARTIFACT_ROOT=${OPENCODE_GO_REVIEW_ARTIFACT_ROOT:-"$(pwd)/.webpresso/reviews"}
+wp review run \
+  --provider opencode \
+  --prompt-file "$PROMPT_FILE" \
+  --model "$MODEL" \
+  --effort "$OPENCODE_GO_REVIEW_EFFORT" \
+  --stage review \
+  --artifact-root "$OPENCODE_GO_REVIEW_ARTIFACT_ROOT" \
+  --idle-seconds "$OPENCODE_GO_REVIEW_IDLE_SECONDS"
+```
+
+The single catalog read above resolves `$MODEL`; do not perform another model-catalog command.
+The typed runtime advances its idle clock only on monotonic semantic progress and has no total wall-clock cutoff.
+OpenCode Go usage limit ends all OpenCode models this review (no family hop). Next: Grok (`--provider grok`). Gate fails over to Grok when accounts cool. Treat `true-idle`, `protocol-unsupported`, provider/abort/spawn/artifact failure as unavailable. Never replace with static timeout, byte-growth heartbeat, or buffered-output fallback.

package/skills/plan-ceo-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: plan-ceo-review
+description: "CEO/founder plan review for scope, ambition, customer value, sequencing, and whether the plan is the right bet."
+license: MIT
+---
+
+# CEO plan review
+
+Review the plan as a founder accountable for product leverage and customer value.
+
+## Modes
+
+Choose one mode explicitly:
+
+- **Scope expansion:** the plan is too timid; propose a bigger wedge.
+- **Selective expansion:** keep the core but add one or two high-leverage improvements.
+- **Hold scope:** ambition is right; demand sharper execution and proof.
+- **Scope reduction:** remove distracting work and ship the smallest valuable slice.
+
+## Review checklist
+
+1. Who urgently wants this outcome and why now?
+2. What is the 10-star version, and what is the smallest credible slice of it?
+3. What should be deleted because it does not advance the wedge?
+4. What proof will convince us the work mattered?
+
+Return a verdict, the recommended mode, and specific plan edits.

package/skills/plan-design-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: plan-design-review
+description: "Designer plan review for UI/UX clarity, hierarchy, interaction quality, accessibility, and visual coherence."
+license: MIT
+---
+
+# Design plan review
+
+Review the plan as a product designer before code is written.
+
+## Scorecard
+
+Rate each dimension from 0-10 and explain what would make it a 10:
+
+- User intent and primary task clarity
+- Information hierarchy and content structure
+- Interaction states and error recovery
+- Accessibility and keyboard/screen-reader paths
+- Visual coherence, spacing, and affordances
+- Responsiveness and empty/loading states
+
+## Output
+
+- Overall score and verdict
+- Top three design risks
+- Minimal plan edits that improve the score
+- Acceptance criteria for visual and accessibility verification

package/skills/plan-devex-review/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: plan-devex-review
+description: "Developer-experience plan review for onboarding, docs, CLI/API ergonomics, migration risk, and time-to-hello-world."
+license: MIT
+---
+
+# Developer-experience plan review
+
+Use before implementing developer-facing features, setup flows, CLIs, docs, SDKs, or migrations.
+
+## Review checklist
+
+- Who is the developer and what are they trying to do?
+- Is the first successful path obvious and short?
+- Are errors actionable and copy-pastable?
+- Does the plan preserve existing workflows and migration safety?
+- What docs, examples, and smoke tests prove the experience?
+
+Return DX score, blockers, simplifications, and acceptance tests.

package/skills/plan-eng-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: plan-eng-review
+description: "Engineering-manager plan review for architecture, data flow, sequencing, edge cases, tests, and rollout risk."
+license: MIT
+---
+
+# Engineering plan review
+
+Review the plan as an engineering manager who must make it safe to execute.
+
+## Process
+
+1. Identify the target outcome, non-goals, constraints, owners, and stop condition.
+2. Map the implementation path: changed files, data flow, public interfaces, migrations, and backward-compatibility concerns.
+3. List edge cases and failure modes by severity.
+4. Check test shape: unit, integration, e2e, fixtures, regression coverage, and verification commands.
+5. Recommend the smallest plan repair that materially reduces risk.
+
+## Output
+
+- **Verdict:** ready / ready with edits / not ready
+- **Blocking issues:** concrete fixes required before coding
+- **Recommended edits:** concise patch-level plan changes
+- **Verification contract:** commands and evidence required before completion

package/skills/plan-refine/SKILL.md

@@ -0,0 +1,50 @@
+---
+type: skill
+slug: plan-refine
+title: Plan Refinement Methodology
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-07-03"
+name: plan-refine
+description: "Blueprint hardening: fact-check assumptions, run plan reviews, split parallel tasks, and lock verification."
+---
+
+# Plan Refinement Methodology
+
+Use when a blueprint or implementation plan needs fact-checking, architecture hardening, parallel task shaping, or review consolidation before execution.
+
+## Core principle
+
+A plan is only as strong as its weakest unchecked assumption and only as fast as its coarsest task granularity.
+
+## Required workflow
+
+1. **Technology fact-check.** Verify API, version, runtime, platform, and package claims against official/upstream sources when external behavior matters.
+2. **Codebase verification.** Confirm file paths, exports, existing patterns, dependency availability, and local command surfaces in the repo.
+3. **Architecture review.** Challenge race conditions, error cascades, ownership boundaries, concurrency, auth/session edges, public-package leakage, and unnecessary abstractions.
+4. **Plan-review lenses.** Folded `/autoplan`: run the relevant CEO/founder, design, engineering, and DevEx review lenses; consolidate keep/change/drop decisions, unresolved taste calls, tests, and go/no-go.
+5. **Blueprint enforcement.** Split tasks for independent execution, declare dependencies, identify file conflicts, require TDD/proof steps, and preserve acceptance criteria.
+6. **Apply and record.** Update edge cases, risks, technology choices, cross-plan references, and verification gates. Do not edit implementation code during plan refinement.
+
+## Mandatory gates
+
+- Apply DRY, SOLID, YAGNI, and KISS; reject speculative abstractions.
+- Choose the most elegant and durable solution the constraints allow, not merely a correct one: prefer deleting/reusing over adding, shrink public/export surface to the minimum real consumers require, keep the change scoped to one coherent idea, and reject the heavier option even when it works — record in the plan why the chosen shape is the durable one.
+- For package, catalog, generated-surface, or release changes, require package-surface and public-content checks.
+- Prefer deletion/reuse over new layers or dependencies.
+- Stop on unverified external claims, unresolved shared-file conflicts, or missing authority for destructive work.
+
+## Output
+
+Return a concise plan review with:
+
+- verdict: ready / ready with edits / blocked
+- material corrections with evidence
+- task/dependency changes needed for parallel execution
+- required tests and audits
+- residual risks or explicit blockers
+
+For the full historical checklist and examples, read `references/full-methodology.md` only when deeper plan surgery is needed.