@webpresso/agent-kit 0.21.0

package/catalog/agent/commands/brainstorm.md

@@ -0,0 +1,115 @@
+---
+description: 'Turn ideas into designs through collaborative dialogue. Use before any creative work.'
+argument-hint: [topic]
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Brainstorm Command
+
+Turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+**Arguments**: $ARGUMENTS
+
+---
+
+## When to Use
+
+- Before creating new features
+- Before building components
+- Before adding functionality
+- Before modifying behavior
+- When exploring design options
+
+---
+
+## The Process
+
+### Phase 1: Understanding the Idea
+
+1. **Check project context first**
+   - Read relevant files, docs, recent commits
+   - Understand existing patterns
+
+2. **Ask questions one at a time**
+   - Prefer multiple choice when possible
+   - Only one question per message
+   - Focus on: purpose, constraints, success criteria
+
+### Phase 2: Exploring Approaches
+
+1. **Propose 2-3 different approaches** with trade-offs
+2. **Lead with your recommendation** and explain why
+3. **Present options conversationally**
+
+### Phase 3: Presenting the Design
+
+1. **Break design into sections** (200-300 words each)
+2. **Ask after each section** if it looks right
+3. **Cover:** architecture, components, data flow, error handling, testing
+4. **Be flexible** - go back and clarify if needed
+
+---
+
+## Output
+
+After design is validated:
+
+1. **Write to:** `docs/system/design/YYYY-MM-DD-<topic>-design.md`
+2. **Commit** the design document
+
+---
+
+## Next Steps
+
+After brainstorming, offer:
+
+1. **Create implementation plan**: `wp blueprint new "<goal>" --complexity <XS|S|M|L|XL>`
+2. **Execute plan**: `/pll` (Blueprint-aware adapter over ultrawork/subagents)
+3. **Verify completion**: `/verify <target>`
+
+---
+
+## Key Principles
+
+| Principle                     | Description                 |
+| ----------------------------- | --------------------------- |
+| **One question at a time**    | Don't overwhelm             |
+| **Multiple choice preferred** | Easier to answer            |
+| **YAGNI ruthlessly**          | Remove unnecessary features |
+| **Explore alternatives**      | Always 2-3 approaches       |
+| **Incremental validation**    | Present in sections         |
+| **Be flexible**               | Clarify when confused       |
+
+---
+
+## Example Session
+
+```
+User: /brainstorm user notification system
+
+Claude: Let me understand the current state first...
+[Reads relevant files]
+
+I see you have an existing email service. Let me ask about the notification system:
+
+What types of notifications do you need?
+1. Email only
+2. Email + in-app
+3. Email + in-app + push
+4. Custom combination
+
+User: 2
+
+Claude: For in-app notifications, what's the expected volume?
+1. Low (< 100/day per user)
+2. Medium (100-1000/day per user)
+3. High (> 1000/day per user)
+
+...continues with focused questions...
+```
+
+---
+
+## Workflow Reference
+
+This command implements the brainstorming workflow for collaborative design exploration.

package/catalog/agent/commands/decide.md

@@ -0,0 +1,132 @@
+---
+description: 'Decision framework command for making and recording decisions'
+argument-hint: '<action> [args] where action is: init|propose|verify|validate|audit|decide|status|list'
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task
+---
+
+# Decide Command
+
+Decision framework command for structured decision-making using DRR (Decision Rationale Records).
+
+**Arguments**: $ARGUMENTS
+
+---
+
+## Usage
+
+```bash
+/decide <action> [arguments]
+```
+
+**Actions:**
+
+| Action | Description |
+|--------|-------------|
+| `init <topic>` | Start a new decision session |
+| `propose <hypothesis>` | Add hypothesis to current session (L0/L1/L2) |
+| `verify [id]` | Promote L0 → L1 with logical evidence |
+| `validate [id]` | Promote L1 → L2 with empirical evidence |
+| `audit` | Calculate R_eff scores |
+| `decide` | Make final decision and generate DRR |
+| `status` | Show current session status |
+| `list` | List decision sessions |
+
+---
+
+## Action: `init`
+
+Start a new decision session for a topic.
+
+```bash
+/decide init "Choose database provider"
+```
+
+Creates a session in `docs/system/decisions/_sessions/YYYY-MM-DD-slug/`
+
+---
+
+## Action: `propose`
+
+Add a hypothesis to the current session.
+
+```bash
+/decide propose "PostgreSQL for primary database"
+/decide propose "MongoDB for document storage"
+```
+
+---
+
+## Action: `verify`
+
+Add logical evidence to promote L0 → L1.
+
+```bash
+/decide verify
+/decide verify --hypothesis-id=2
+```
+
+---
+
+## Action: `validate`
+
+Add empirical evidence to promote L1 → L2.
+
+```bash
+/decide validate
+/decide validate --hypothesis-id=3
+```
+
+---
+
+## Action: `audit`
+
+Audit evidence and calculate reliability scores.
+
+```bash
+/decide audit
+```
+
+Generates R_eff scores for each hypothesis.
+
+---
+
+## Action: `decide`
+
+Make final decision and generate DRR.
+
+```bash
+/decide decide
+```
+
+Creates DRR in `docs/system/decisions/` directory.
+
+---
+
+## Action: `status`
+
+Show current session status.
+
+```bash
+/decide status
+```
+
+---
+
+## Action: `list`
+
+List decision sessions.
+
+```bash
+/decide list
+```
+
+---
+
+## Integration
+
+This command integrates with the blueprint decision framework:
+
+- CLI: `wp blueprint decision init <topic>`
+- CLI: `wp blueprint decision decide`
+- Sessions stored in `docs/system/decisions/_sessions/`
+- DRRs stored in `docs/system/decisions/`

package/catalog/agent/commands/fix-all.md

@@ -0,0 +1,160 @@
+---
+description: Fix all QA errors with up to 6 parallel agents using DAG-based execution
+allowed-tools: Bash, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, Read, Write, Edit, Glob, Grep
+argument-hint: [lint|typecheck|test|all]
+---
+
+# Fix All Errors - Parallel DAG Execution
+
+Fix all QA errors with intelligent parallelization. Uses the /pll DAG system.
+
+**Arguments**: $ARGUMENTS (default: all)
+
+## Constraints
+
+- **Max parallel agents**: 8 (unified with /pll)
+- **Max parallel test runners**: 2 (vitest is memory-intensive)
+- **Continuous execution**: When one agent finishes, next task starts immediately
+
+## Execution Protocol
+
+### Phase 1: Error Discovery
+
+Run QA and capture all failures:
+
+```bash
+# Auto-saves to logs/DD-MM-YYYY/HH-MM-SS_qa.log
+just qa
+```
+
+Parse the output to extract:
+
+- **Lint errors**: Package + file + error type
+- **Typecheck errors**: Package + file + line + error message
+- **Test failures**: Package + test file + test name
+
+### Phase 2: DAG Construction
+
+Build task graph with these dependency rules:
+
+1. **Lint tasks** (Wave 1) - No dependencies, fully parallel
+2. **Typecheck tasks** (Wave 2) - Depend on lint fixes for same package
+3. **Test tasks** (Wave 3) - Depend on typecheck passing for same package
+
+Within each category, group by package to minimize context switching.
+
+**Task Types with Concurrency Limits**:
+
+- `lint-fix`: max 8 parallel
+- `typecheck-fix`: max 8 parallel
+- `test-fix`: max 2 parallel (memory constraint)
+
+### Phase 3: Parallel Execution with Kahn's Algorithm
+
+```
+READY_QUEUE = tasks with in-degree 0
+RUNNING = {} (map of task_id -> agent)
+COMPLETED = set()
+
+while READY_QUEUE not empty OR RUNNING not empty:
+    # Start new agents up to limit
+    while can_start_more():
+        task = READY_QUEUE.pop_by_priority()
+        agent = spawn_agent(task)
+        RUNNING[task.id] = agent
+
+    # Wait for any agent to complete
+    completed_task = wait_for_any(RUNNING)
+    COMPLETED.add(completed_task.id)
+
+    # Update in-degrees and add newly ready tasks
+    for dependent in completed_task.dependents:
+        dependent.in_degree -= 1
+        if dependent.in_degree == 0:
+            READY_QUEUE.push(dependent)
+```
+
+**Priority Order** (within same wave):
+
+1. Tasks blocking the most other tasks
+2. Tasks in packages with most errors (fix root causes first)
+3. Alphabetical by package name (deterministic)
+
+### Phase 4: Agent Spawning
+
+Use Task tool with appropriate subagent_type:
+
+```
+For lint-fix:
+  subagent_type: "general-purpose"
+  prompt: "Fix lint error in {file}: {error}. Run `just lint {file}` to verify."
+
+For typecheck-fix:
+  subagent_type: "general-purpose"
+  prompt: "Fix type error in {file}:{line}: {message}. Run `just typecheck {package}` to verify."
+
+For test-fix:
+  subagent_type: "general-purpose"
+  prompt: "Fix failing test in {file}: {test_name}. Run `just test {file}` to verify."
+```
+
+### Phase 5: Verification Gate
+
+After all tasks complete:
+
+```bash
+just qa  # Auto-saves to logs/DD-MM-YYYY/HH-MM-SS_qa.log
+```
+
+If new errors appear, create new DAG and continue.
+
+## Concurrency Management
+
+Track active agents by type:
+
+```
+active_counts = {
+  "lint-fix": 0,      # max 8
+  "typecheck-fix": 0, # max 8
+  "test-fix": 0       # max 2
+}
+
+can_start(task_type):
+  if task_type == "test-fix":
+    return active_counts["test-fix"] < 2
+  return sum(active_counts.values()) < 8
+```
+
+## Error Handling
+
+- **Agent failure**: Mark task as failed, log error, continue with other tasks
+- **Circular dependency**: Should not occur (lint -> typecheck -> test is acyclic)
+- **Persistent failures**: After 2 retries, mark as "needs-manual-review"
+
+## Output Format
+
+Report progress in real-time:
+
+```
+[Wave 1/3] Lint fixes
+  [1/5] cli: fixing string-concat error... DONE (2s)
+  [2/5] schema-engine: fixing unused-var... RUNNING
+  [3/5] platform-api: fixing import-order... RUNNING
+  ...
+
+[Wave 2/3] Typecheck fixes
+  Waiting for Wave 1...
+
+Summary:
+  Lint: 5/5 fixed
+  Typecheck: 3/3 fixed
+  Test: 2/2 fixed
+  Total time: 45s (vs 180s sequential)
+```
+
+## Quick Start
+
+1. Run `/fix-all` to fix everything
+2. Run `/fix-all lint` to fix only lint errors
+3. Run `/fix-all typecheck` to fix only type errors
+4. Run `/fix-all test` to fix only test failures

package/catalog/agent/commands/fix.md

@@ -0,0 +1,109 @@
+---
+description: 'Fix an issue at the root cause, with repo philosophy enforced and verification before claiming done.'
+argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task, TaskCreate, TaskUpdate, TaskList
+---
+
+# Fix Command
+
+Fix the issue at its root, future-proof, aligned with repo philosophy.
+
+**Arguments**: $ARGUMENTS
+
+This command is a refinement of the ambient request "fix this issue with best practices, future-proof, elegant, aligning with our philosophy." It translates those adjectives into concrete, enforceable gates so the fix is actually bulletproof instead of vibes-bulletproof.
+
+---
+
+## Non-negotiable invariants
+
+A fix that violates any of these isn't done — it's churn. Every rule below should be grounded in your repo's `CLAUDE.md` / agent rules.
+
+1. **Root cause, not symptom.** Trace the failure to the invariant that was actually broken. If the nearest branch would mask the real cause, don't add it.
+
+2. **Loud failures, no silent fallbacks.** No `env.X || 'default'`, no `try { … } catch { return null }`, no auto-provisioning shims that hide missing config. Boundaries validate once, loudly, early.
+
+3. **`unknown` is last resort. `any` is forbidden in production code.** The only permitted `any` is the mock-typing idiom (`vi.fn<(...args: any[]) => unknown>`) that matches existing repo tests.
+
+4. **Zero suppressions.** No `eslint-disable`, `ts-ignore`, `ts-expect-error`, `biome-ignore`, `prettier-ignore`. Fix the code, not the linter.
+
+5. **Cognitive complexity ≤ 8.** Extract helpers before tolerating nesting or long conditionals.
+
+6. **External calls go through the right abstraction.** Network/IO calls should route through your repo's deadline-aware wrapper with a named deadline constant. Never hardcode timeouts.
+
+7. **Secrets come from the repo-owned secret gate.** Missing secrets should throw loudly at boot, aggregated — never silently fall back to a default.
+
+8. **No scope creep.** No tangential refactors bundled with the fix. Adjacent issues → listed as follow-ups, not silently fixed.
+
+9. **No unrequested docs.** Don't create `*.md` files or planning artifacts unless the user asks.
+
+---
+
+## Protocol
+
+### Step 1 — Reproduce + locate the broken invariant
+
+- Run the exact command that surfaces the failure. Capture error, `file:line`, exit code.
+- Read surrounding code until you can state **the broken invariant in one sentence**. Examples:
+  - "Function X is supposed to return a structured result but throws on a subset of inputs."
+  - "Cache Y is supposed to be fresh after step Z but step Z runs after the check that depends on it."
+- If the "issue" is actually several issues, stop and ask the user which to fix first.
+
+### Step 2 — Plan aloud (briefly)
+
+State in 1–3 sentences:
+- The broken invariant.
+- Where the fix belongs (the function/file that owns the invariant — not a caller).
+- Whether the fix changes a public contract. If so, name every consumer that will need to update in the same change.
+
+If the blast radius exceeds one file + its direct tests, surface it to the user before editing.
+
+### Step 3 — Implement the minimal correct fix
+
+- Edit the file that owns the invariant. Don't paper over it at callers.
+- Update every consumer of a changed contract in the same change — no half-migrations.
+- Add or strengthen a test that **would have caught the original bug against the old code**. "New tests that exercise the new path" are not sufficient.
+- Delete compat shims, dead aliases, and TODOs that the fix makes obsolete.
+- Do not add comments that restate the code. Only write a comment for a non-obvious *why* (hidden constraint, workaround for a specific bug). See CLAUDE.md "Doing tasks".
+
+### Step 4 — Verify (evidence before claims)
+
+Run the minimum required for the changed surface:
+
+```bash
+just lint --file <changed-files>
+just typecheck --package <affected-package>
+just test --file <changed-test-files>
+```
+
+If the fix crosses packages or touches public surface, run `/verify <target>` for the full gate.
+
+### Step 5 — Report
+
+Short. Cite evidence, not intent.
+
+- 1–2 sentences: what invariant broke, how the fix restores it.
+- Test count + exit codes or log paths.
+- Adjacent issues noticed but not fixed → list as follow-ups.
+
+---
+
+## Done looks like
+
+- [ ] Root cause named in one sentence
+- [ ] Minimal diff restores the invariant at its owner
+- [ ] No silent fallback, no `any`, no suppression, no compat shim added
+- [ ] Tests would fail against the old code
+- [ ] `just lint` + `just typecheck` + `just test` pass on the changed surface
+- [ ] Report cites concrete evidence (log paths, exit codes, test counts)
+
+---
+
+## Anti-patterns this command refuses
+
+- Patching the symptom when the invariant is fixable upstream
+- Wrapping a broken call in try/catch and returning a sentinel ("defensive programming")
+- Adding a deprecation alias instead of updating callers
+- Introducing `any` / `ts-ignore` / `eslint-disable` to unblock the fix
+- Bundling unrelated refactors with the fix
+- Claiming done without running the verification commands
+- Writing a docs/planning file when the user asked for a fix

package/catalog/agent/commands/plan-refine.md

@@ -0,0 +1,103 @@
+---
+name: plan-refine
+description: Refine a blueprint for correctness, fact-checking, and /pll-ready task structure
+argument-hint: <slug>
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch
+---
+
+# Plan Refine (`/plan-refine`)
+
+Refine a blueprint by applying the canonical plan-refine methodology to the actual file, not just reviewing it.
+
+**Arguments**: `$ARGUMENTS`
+
+## Usage
+
+```bash
+/plan-refine <slug>
+/plan-refine customer-runtime-zero-legacy-confidence
+```
+
+## What This Command Does
+
+Edits `blueprints/*/<slug>/_overview.md` so the blueprint is:
+
+- fact-checked against current docs and repo reality
+- aligned with planning and testing rules
+- structured for parallel execution via `/pll`
+- explicit about risks, edge cases, and cross-plan dependencies
+
+## Execution Protocol
+
+### Step 1: Locate the blueprint
+
+```bash
+find blueprints -name "_overview.md" -path "*/$SLUG/*"
+```
+
+If no matching blueprint exists, stop and report that.
+
+### Step 2: Load the canonical methodology
+
+Read [plan-refine](/.agent/skills/plan-refine/SKILL.md) and use it as the source of truth for refinement criteria.
+
+### Step 3: Refine the blueprint end to end
+
+Apply the methodology directly to the blueprint:
+
+1. Technology fact-check
+   - verify library, API, runtime, and platform claims against current official docs
+   - replace vague or unverified claims with evidence-backed wording
+2. Codebase verification
+   - confirm file paths, package boundaries, exports, and API signatures against the repo
+   - correct assumptions that do not match current code
+3. Architecture review
+   - add or tighten handling for concurrency, retries, error cascades, auth/session edges, and platform limits
+4. Cross-plan alignment
+   - verify referenced blueprints still exist and still support the stated dependency contract
+5. Blueprint enforcement
+   - split coarse tasks
+   - add explicit dependencies
+   - ensure TDD steps, exact files, exact commands, and verification steps are present
+   - use t-shirt sizing only
+   - prefer the repo's preferred database workflow (e.g. `db push` over migrations) when the repo has chosen one
+
+### Step 4: Apply edits, do not stop at findings
+
+Update the blueprint file directly instead of only producing a report.
+
+Expected edits commonly include:
+
+- rewriting tasks into smaller blueprint-format units
+- fixing stale paths or APIs
+- adding missing edge cases and risks
+- tightening acceptance criteria
+- adding cross-plan reference corrections
+- replacing speculative language with verified statements
+
+### Step 5: Validate the refined artifact
+
+Run the blueprint parser check:
+
+```bash
+wp blueprint show <slug>
+```
+
+If the refinement changes markdown structure enough to warrant a lint pass, also run your repo's markdown linter against `blueprints/*/<slug>/_overview.md` (for example, `just lint-md` with webpresso's just recipes).
+
+### Step 6: Report the outcome
+
+Summarize:
+
+- what changed in the blueprint
+- what claims were corrected
+- what risks or unknowns still remain
+- whether any notable risks or unknowns still need a separate manual review
+
+## Guardrails
+
+- Do not invent supporting code that does not exist.
+- Do not preserve stale technology claims for compatibility.
+- Do not leave large, multi-file, ambiguous tasks when they can be split.
+- Prefer primary sources for fact-checking.
+- Keep the refined plan executable by the next agent without extra interpretation.