@webpresso/agent-kit 0.21.0

package/catalog/docs/templates/blueprint.md

@@ -0,0 +1,149 @@
+---
+type: blueprint
+status: draft
+complexity: M
+created: '2026-04-22'
+last_updated: '2026-04-22'
+progress: '0% (drafted)'
+depends_on: []
+tags: []
+---
+
+# {{title}}
+
+**Goal:** {{description}}
+
+## Planning Summary
+
+- Goal input: `{{description}}`
+- Complexity: `{{complexity}}`
+- Draft slug: `{{slug}}`
+- Output path: `{{output_path}}`
+- Generated command: `wp blueprint new "{{description}}" --complexity {{complexity}}`
+- Validation scope: parser compliance before write
+
+## Architecture Overview
+
+```text
+[Diagram showing how components connect before/after]
+```
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+| -------- | ------ | --------- |
+|          |        |           |
+
+## Quick Reference (Execution Waves)
+
+| Wave              | Tasks | Dependencies | Parallelizable |
+| ----------------- | ----- | ------------ | -------------- |
+| **Wave 0**        | 1.1   | None         | 1 agent        |
+| **Critical path** | 1.1   | --           | 1 wave         |
+
+**Note:** Use t-shirt sizing (XS/S/M/L/XL) for individual task estimates, NOT day/week estimates.
+
+**Lifecycle:** Blueprint frontmatter `status` is one of `draft`, `planned`, `parked`, `in-progress`, `completed`, `archived`. Use `parked` when the blueprint is intentionally paused but should remain distinct from active planning or abandoned work. There is no blueprint-level `blocked` status; when work waits on an external dependency, set the task **Status:** to `blocked` and add a non-empty **Blocked:** line with the reason.
+
+> [!NOTE]
+> This template reflects the current preferred blueprint structure. Repo-wide validity is determined by the live blueprint parser/audit rules, so older blueprints may still use a different-but-valid section mix.
+
+### Phase 1: [Phase Name] [Complexity: S]
+
+#### Task 1.1: [Component Name]
+
+> **Task header (current accepted form):** Use `#### [lane] Task X.Y:` when the task has a clear lane (`[schema]`, `[backend]`, `[ui]`, `[infra]`, `[docs]`, `[qa]`). `#### Task X.Y:` is still valid, but lane-prefixed headers are preferred in new blueprints.
+
+**Status:** todo
+
+**Depends:** None
+
+[Self-contained description. An independent agent must be able to execute
+this task with ONLY this text + the codebase + repo-owned commands. Never
+reference "see above" or "as described in Task X.Y" — inline all context.]
+
+**Files:**
+
+- Create: `exact/path/to/file.ts`
+- Create: `exact/path/to/file.test.ts`
+- Modify: `exact/path/to/existing.ts`
+
+**Steps (TDD):**
+
+1. Write failing test for [specific behavior]
+2. Run the repo's scoped test recipe — verify FAIL
+3. Implement minimal code to pass
+4. Run the repo's scoped test recipe — verify PASS
+5. Refactor if needed (complexity <= 8)
+
+**Acceptance:**
+
+- [ ] Test file created with failing test
+- [ ] Implementation passes all tests
+- [ ] Scoped lint passes
+- [ ] Verification commands recorded in the task notes
+
+#### Task 1.2: [Component Name]
+
+**Status:** todo
+
+**Depends:** Task 1.1
+
+[Self-contained description.]
+
+**Files:**
+
+- Create: `exact/path/to/file.ts`
+
+**Steps (TDD):**
+
+1. Write failing test
+2. Run the repo's scoped test recipe — verify FAIL
+3. Implement
+4. Run the repo's scoped test recipe — verify PASS
+
+**Acceptance:**
+
+- [ ] Tests pass
+- [ ] Lint passes
+
+---
+
+## Verification Gates
+
+| Gate        | Command                            | Success Criteria |
+| ----------- | ---------------------------------- | ---------------- |
+| Type safety | repo typecheck recipe              | Zero errors      |
+| Lint        | repo lint recipe (scoped)          | Zero violations  |
+| Tests       | repo test recipe (scoped)          | All pass         |
+| Full QA     | repo full-QA recipe                | All pass         |
+| Perf        | bundle / runtime measurement       | No regression vs baseline (or N/A — delete row) |
+
+## Cross-Plan References
+
+| Type       | Blueprint | Relationship |
+| ---------- | --------- | ------------ |
+| Upstream   | None      |              |
+| Downstream | None      |              |
+
+## Edge Cases and Error Handling
+
+| Edge Case | Risk | Solution | Task |
+| --------- | ---- | -------- | ---- |
+|           |      |          |      |
+
+## Non-goals
+
+- [What this blueprint does NOT cover]
+
+## Risks
+
+| Risk | Impact | Mitigation |
+| ---- | ------ | ---------- |
+|      |        |            |
+
+## Technology Choices
+
+| Component | Technology | Version | Why |
+| --------- | ---------- | ------- | --- |
+|           |            |         |     |

package/catalog/docs/templates/blueprint.yaml

@@ -0,0 +1,110 @@
+name: blueprint
+description: Blueprint template for features/initiatives
+
+notes:
+  - 'This file describes the current preferred blueprint structure, not an immutable final schema.'
+  - 'Repo-wide validity is determined by the live blueprint parser/audit rules, not by requiring every optional section below.'
+
+frontmatter:
+  required:
+    type:
+      value: blueprint
+      description: Must be exactly "blueprint"
+    status:
+      enum: [draft, planned, parked, in-progress, completed, archived]
+      description: Current plan status (must match folder placement)
+    complexity:
+      enum: [XS, S, M, L, XL]
+      description: Estimated complexity
+    last_updated:
+      type: date
+      format: YYYY-MM-DD
+      description: Last modification date
+  optional:
+    parent:
+      type: string
+      description: Path to parent epic (e.g., ../README.md)
+    depends_on:
+      type: array
+      description: Dependencies on other plans
+
+sections:
+  required: []
+  optional:
+    - name: Planning Summary
+      pattern: '^## Planning Summary'
+      description: Execution framing, repo-specific constraints, and output path
+    - name: Problem Statement
+      pattern: '^## Problem Statement'
+      description: Current repo reality and the gap this blueprint closes
+    - name: Fact-Checked Findings
+      pattern: '^## Fact-Checked Findings'
+      description: Verified claims tied to concrete repo evidence
+    - name: Evidence Base
+      pattern: '^## Evidence Base'
+      description: File paths and source anchors that support the plan
+    - name: Architecture Overview
+      pattern: '^## Architecture Overview'
+      description: System boundary or flow diagram before task execution
+    - name: Key Decisions
+      pattern: '^## Key Decisions'
+      description: Decision log with rationale
+    - name: Quick Reference (Execution Waves)
+      pattern: '^## Quick Reference \\(Execution Waves\\)'
+      description: Parallel waves, dependencies, and effort sizing
+    - name: Verification Gates
+      pattern: '^## Verification Gates'
+      description: Canonical commands and success criteria
+    - name: Cross-Plan References
+      pattern: '^## Cross-Plan References'
+      description: Upstream/downstream blueprint relationships
+    - name: Edge Cases and Error Handling
+      pattern: '^## Edge Cases and Error Handling'
+      description: Known edge cases and mitigation owners
+    - name: Alternatives Considered
+      pattern: '^## Alternatives Considered'
+    - name: Risks
+      pattern: '^## Risks'
+    - name: Non-Goals
+      pattern: '^## Non-Goals'
+    - name: Technology Choices
+      pattern: '^## Technology Choices'
+      description: Versioned implementation choices and rationale
+    - name: Completion Summary
+      pattern: '^## Completion Summary'
+      description: Required for completed blueprints
+    - name: Retrospective
+      pattern: '^## Retrospective'
+
+location:
+  patterns:
+    - 'blueprints/*/_overview.md'
+    - 'blueprints/*/*/_overview.md'
+    - 'blueprints/*/*/*/_overview.md'
+    - 'blueprints/completed/*/_overview.md'
+    - 'blueprints/planned/*/_overview.md'
+    - 'blueprints/parked/*/_overview.md'
+    - 'blueprints/in-progress/*/_overview.md'
+    - 'blueprints/draft/*/_overview.md'
+  exclude:
+    - 'blueprints/draft/*.md' # Standalone draft trackers such as deferred backlog
+
+naming:
+  pattern: '_overview.md'
+  case: exact
+  notes: 'Use _overview.md for high-level summary. Detailed phases go in phase-N-name.md files.'
+
+task_format:
+  heading:
+    canonical:
+      - '#### [lane] Task X.Y: Title'
+      - '#### Task X.Y: Title'
+    notes:
+      - 'These are the current accepted task-heading forms enforced by the validator.'
+      - 'Lane prefix is optional but recommended. Common lanes: [schema], [backend], [ui], [infra], [docs], [qa].'
+  required_metadata:
+    - '**Status:** todo|in_progress|blocked|done'
+  notes:
+    - 'Task metadata rules here reflect the current validator contract.'
+    - 'Acceptance checkboxes are evidence, not the lifecycle source of truth.'
+    - 'Blocked tasks must include a non-empty **Blocked:** reason.'

package/catalog/docs/templates/core-doc.yaml

@@ -0,0 +1,28 @@
+name: core-doc
+description: Core documentation files at docs/ root
+
+frontmatter:
+  required:
+    type:
+      enum: [core, guide, reference]
+      description: Documentation type
+    last_updated:
+      type: date
+      format: YYYY-MM-DD
+      description: Last modification date
+  optional: {}
+
+sections:
+  required: []
+  optional: []
+
+location:
+  patterns:
+    - 'docs/*.md'
+  exclude:
+    - 'docs/README.md'
+
+naming:
+  pattern: "[A-Z_-]+\\.md"
+  case: upper
+  description: UPPER_CASE or kebab-case with capitals

package/catalog/docs/templates/guide.md

@@ -0,0 +1,31 @@
+---
+type: guide
+last_updated: "YYYY-MM-DD"
+---
+
+# {{Title}}
+
+> One-sentence framing: what problem this guide solves and for whom.
+
+## Prerequisites
+
+- Workspace checked out, dependencies installed
+- Any role/permission the reader needs
+- Links to conceptually prior docs
+
+## Steps
+
+1. First concrete, repeatable step. Include the exact command.
+2. Second step.
+3. Verification — what success looks like.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| ------- | ------------ | --- |
+|         |              |     |
+
+## Related
+
+- Link to the relevant `docs/system/` page for the architecture behind this flow.
+- Link to the owning workspace `README.md`.

package/catalog/docs/templates/guide.yaml

@@ -0,0 +1,31 @@
+name: guide
+description: Workflow guides for development and operations
+
+frontmatter:
+  required:
+    type:
+      value: guide
+      description: Must be exactly "guide"
+    last_updated:
+      type: date
+      format: YYYY-MM-DD
+      description: Last modification date
+  optional:
+    redirect_to:
+      type: string
+      description: Relative path to consolidated guide
+
+sections:
+  required: []
+  optional: []
+
+location:
+  patterns:
+    - 'docs/guides/**/*.md'
+  exclude:
+    - 'docs/guides/cookbook/**'
+
+naming:
+  pattern: "[a-z0-9-]+\\.md"
+  case: lower
+  description: 'kebab-case'

package/catalog/docs/templates/postmortem.md

@@ -0,0 +1,60 @@
+---
+type: postmortem
+last_updated: "YYYY-MM-DD"
+---
+
+# Postmortem: {{Incident Title}}
+
+- **Date of incident:** YYYY-MM-DD
+- **Duration:** HH:MM (start) → HH:MM (end)
+- **Severity:** SEV-1 | SEV-2 | SEV-3
+- **Author:** name
+- **Reviewed by:** names
+
+## Summary
+
+One paragraph. What happened, what broke, who was affected, how long.
+
+## Impact
+
+- Customer-facing impact (events, users, $).
+- Internal impact (on-call load, cascading failures).
+
+## Timeline
+
+All times in UTC.
+
+| Time | Event | Evidence |
+| ---- | ----- | -------- |
+|      |       |          |
+
+## Root cause
+
+Explain the *cause*, not just the symptom. What invariant broke, and why
+did the system allow it?
+
+## Trigger
+
+What specifically set this incident in motion?
+
+## Resolution
+
+How it was mitigated. How it was fixed. Whether the fix is durable.
+
+## What went well
+
+- …
+
+## What did not go well
+
+- …
+
+## Action items
+
+| Action | Owner | Due | Blueprint / Issue |
+| ------ | ----- | --- | ----------------- |
+|        |       |     |                   |
+
+## Lessons learned
+
+- …

package/catalog/docs/templates/research.md

@@ -0,0 +1,37 @@
+---
+type: research
+last_updated: "YYYY-MM-DD"
+---
+
+# {{Research Title}}
+
+> Research artifact — evaluative, not prescriptive. Prescribe through a
+> blueprint or ADR if a conclusion is load-bearing.
+
+## Question
+
+One sentence. What are we trying to learn?
+
+## Method
+
+- Sources consulted
+- Repo files inspected (`path/to/file:line-line`)
+- Commands run
+- External sources (URL + fetch date)
+
+## Findings
+
+| ID  | Severity | Finding | Evidence |
+| --- | -------- | ------- | -------- |
+|     |          |         |          |
+
+## Conclusions
+
+- What the evidence most strongly implies.
+- What remains unknown.
+- What would reduce uncertainty.
+
+## Implications
+
+- Downstream blueprints or ADRs this research should inform.
+- Hypotheses to retire.

package/catalog/docs/templates/runbook.md

@@ -0,0 +1,39 @@
+---
+type: runbook
+last_updated: "YYYY-MM-DD"
+---
+
+# Runbook: {{Scenario}}
+
+- **When to use this runbook:** concrete trigger (alert name, symptom, page).
+- **Primary owner:** team / rotation.
+- **Expected runtime:** 5 min | 30 min | hours.
+
+## Pre-flight
+
+- [ ] Access to required dashboards
+- [ ] Access to required consoles
+- [ ] Incident channel identified
+
+## Steps
+
+1. Step one — include the exact command, dashboard URL, or console path.
+2. Step two.
+3. Verification step — what success looks like.
+
+## Rollback
+
+If steps above worsen the situation:
+
+1. …
+
+## Communication
+
+- Who to notify (human, not chat handles that decay).
+- What to say, with a template.
+
+## Aftermath
+
+- [ ] Update the timeline in the incident doc.
+- [ ] File follow-up actions as issues or blueprints.
+- [ ] If this runbook was unclear, update it in the same PR as the postmortem.

package/catalog/docs/templates/system.md

@@ -0,0 +1,44 @@
+---
+type: system
+last_updated: "YYYY-MM-DD"
+---
+
+# {{System Name}}
+
+**Truth state:** shipped | partial | aspirational
+
+> One paragraph: what this system is, why it exists, and what it is *not*.
+
+## Architecture
+
+```text
+[Diagram showing the main components and their edges]
+```
+
+## Key invariants
+
+- Invariant 1 — what must always be true.
+- Invariant 2 — what must never be true.
+
+## Interfaces
+
+| Consumer | Entry point | Contract |
+| -------- | ----------- | -------- |
+|          |             |          |
+
+## Failure modes
+
+| Failure | Blast radius | Detection | Recovery |
+| ------- | ------------ | --------- | -------- |
+|         |              |           |          |
+
+## Evolution
+
+- Known next steps
+- Blueprints that extend this system
+- ADRs that decided a non-obvious choice here
+
+## Related
+
+- `docs/runbooks/` — operational procedures
+- `docs/adrs/` — decision records

package/catalog/docs/templates/tech-debt.md

@@ -0,0 +1,78 @@
+---
+type: tech-debt
+status: open
+severity: '{{severity}}'
+category: '{{category}}'
+review_cadence: quarterly
+last_reviewed: '{{date}}'
+created: '{{date}}'
+linked_blueprints: []
+affected_modules: []
+---
+
+# {{id}}: {{title}}
+
+This template is used for files under `tech-debt/{status}/`.
+
+## Problem
+
+[Describe the technical debt issue. Be specific about what is wrong, where it exists, and how you discovered it.]
+
+- Violation count or metric
+- Affected area or component
+- How you identified it (audit, incident, review)
+
+## Impact
+
+[Describe the consequences of this tech debt if left unaddressed.]
+
+- Maintenance burden
+- Risk of bugs or incidents
+- Developer experience impact
+- Performance or security implications
+
+## Impact Diagram (Optional)
+
+```mermaid
+graph TD
+    A[Tech Debt Item] --> B[Impact 1]
+    A --> C[Impact 2]
+    B --> D[Downstream Effect]
+```
+
+## Why {{status}}
+
+[Explain the rationale for the current status. For "accepted" status, explain why remediation is deferred. For "needs-remediation", explain urgency.]
+
+- Business justification
+- Timeline considerations
+- Resource constraints
+
+## Remediation Steps
+
+### Step 1: [First remediation action]
+
+- [ ] [Specific action item]
+
+### Step 2: [Second remediation action]
+
+- [ ] [Specific action item]
+
+### Step 3: [Third remediation action]
+
+- [ ] [Specific action item]
+
+## Affected Files
+
+- `path/to/affected/file.ts` (description)
+- `path/to/another/file.ts` (description)
+
+## Linked Issues
+
+- Blueprint: [linked blueprint slug if any]
+- Task: [related task reference]
+- Audit: [audit finding reference]
+
+## References
+
+- [Relevant documentation or audit report](link)

package/catalog/vision/VISION.md.tmpl

@@ -0,0 +1,33 @@
+---
+type: vision
+last_updated: {{TODAY}}
+---
+
+# {{REPO_NAME}} Vision
+
+{{ONE_LINER}}
+
+## The problem
+
+{{PROBLEM}}
+
+## North star
+
+> **{{TAGLINE}}**
+
+A short paragraph elaborating the tagline. What does success look like once
+this repo has done its job?
+
+## Boundaries
+
+**In scope**
+
+{{IN_SCOPE}}
+
+**Out of scope**
+
+{{OUT_OF_SCOPE}}
+
+## Design principles
+
+{{PRINCIPLES}}

package/commands/audit.md

@@ -0,0 +1,13 @@
+---
+description: Run a webpresso audit (tph | catalog-drift | package-surface | docs-frontmatter | blueprint-lifecycle | bundle-budget | commit-message | tech-debt | architecture-drift)
+---
+Use the `mcp__webpresso__wp_audit` tool to run an audit. Pass `kind` as one of `tph`, `catalog-drift`, `package-surface`, `docs-frontmatter`, `blueprint-lifecycle`, `bundle-budget`, `commit-message`, `tech-debt`, or `architecture-drift` based on what the user asks for.
+
+`architecture-drift` verifies a repo-local `docs/architecture.contract.json`
+contract against:
+
+- required architecture docs
+- required architecture text/rules
+- active blueprint links to architecture docs/contracts
+- required `Architecture before` / `Architecture after` sections for
+  architecture-changing blueprints

package/commands/blueprint.md

@@ -0,0 +1,28 @@
+---
+description: Manage blueprints via focused MCP tools
+---
+Use the focused blueprint MCP tools.
+
+- `wp_blueprint_projects` — discover visible projects and worktrees
+- `wp_blueprint_list` — list blueprints
+- `wp_blueprint_get` — fetch one blueprint with freshness metadata
+- `wp_blueprint_context` — assemble bounded task context
+- `wp_blueprint_create` — create a draft blueprint; requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe, stale-write-safe creation
+- `wp_blueprint_task_next` — return the next ready task; accepts optional `project_id` when the current cwd is a multi-repo workspace container
+- `wp_blueprint_task_advance` — change task status (non-`done`); requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe mutation
+- `wp_blueprint_task_verify` — mark a task `done` with evidence; accepts optional `request_id` and `head_at_ingest` for retry-safe verification
+- `wp_blueprint_promote` / `wp_blueprint_finalize` — accept optional `project_id` for nested-workspace disambiguation
+
+Mutation guidance:
+
+- Use `request_id` on `wp_blueprint_create`, `wp_blueprint_task_advance`, and
+  `wp_blueprint_task_verify` when the caller may retry the same request.
+- Prefer passing `project_id` from `wp_blueprint_projects` whenever the current
+  working directory can see more than one blueprint-bearing repo.
+- Carry `head_at_ingest` from `wp_blueprint_list`, `wp_blueprint_get`, or
+  `wp_blueprint_context` into mutation calls when the caller needs stale-write
+  protection across retries or multi-agent handoff.
+- Reusing the same `request_id` with the same payload is idempotent.
+- Reusing the same `request_id` with a different payload is rejected.
+- If `head_at_ingest` is stale, the mutation is rejected and points the caller
+  back to a canonical `wp_*` refresh path.

package/commands/qa.md

@@ -0,0 +1,4 @@
+---
+description: Run lint + typecheck + tests in parallel via webpresso MCP
+---
+Use the `mcp__webpresso__wp_qa` tool to run lint, typecheck, and tests in parallel. No arguments required; the tool aggregates structured results from each sub-tool.