openplanr 1.25.2 → 2.0.0

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/default/frontend.md

@@ -0,0 +1,94 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/default/frontend.md: default-mode-only content for frontend-agent. Loaded by agents/frontend-agent.md when MODE=default. T-002 of SPEC-002. -->
+
+> **Mode:** default
+> **Loaded by:** `agents/frontend-agent.md` when the orchestrator passes `MODE=default` (no `SPEC_DIR`).
+
+## Path Resolution
+
+The orchestrator (`/ship`) passes the absolute task file path and `MODE=default`.
+Use that exact path first.
+
+- Feature input: `input/specs/spec-{name}.md`.
+- Task: `output/feats/feat-{name}/us-{N}/tasks/task-{M}.md` (`task-1.md` for UI).
+- Parent story: the `us-{N}.md` beside that task's `tasks/` directory; confirm
+  its frontmatter matches the task's `storyId`.
+- Design context: `output/feats/feat-{name}/design-spec.md` when present.
+- Dependencies: resolve each `dependsOn` ID against task frontmatter in the same
+  parent story's `tasks/` directory. Default-mode task IDs are story-scoped.
+
+If no exact path was passed but a task ID or slug was, search only below the
+selected `output/feats/feat-{name}/us-*/tasks/` tree and use a match only when it
+is unique. Follow
+`${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/task-context-resolution.md` after resolving
+the file.
+
+Task content (Create/Modify/Preserve, Type, agent, DoD) is schema-identical in both modes — your behavior doesn't change, only the output paths.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `output/feats/feat-{name}/us-{N}/tasks/task-1.md` | Specification Agent | Yes |
+| `output/feats/feat-{name}/design-spec.md` | Designer Agent | If exists |
+| `input/tech/stack.md` | Tech Lead | Yes |
+| Existing codebase files (for context) | Dev environment | Read-only for context |
+
+---
+
+## Outputs
+
+All files listed under `### Create` and `### Modify` in the task file (`output/feats/feat-{name}/us-{N}/tasks/task-1.md`).
+
+---
+
+## Implementation guidance
+
+```
+1. Load the active UI task and extract frontmatter, Create/Modify/Preserve,
+   Technical Spec or Implementation, Verification, and Definition of Done. Read
+   the complete parent story and `input/specs/spec-{name}.md`; load the story's
+   matching Gherkin sidecar when present.
+2. Load `input/tech/stack.md`. Resolve every `ActiveStackFiles` entry through the
+   installed stack root and the project-local `.openplanr/stacks` overlay as
+   defined by the shared task-context guidance.
+3. Read each declared predecessor's output contract when `dependsOn` is non-empty.
+   Load `output/feats/feat-{name}/design-spec.md` when it exists.
+4. Read the listed files, reusable UI, design-system implementation, and enough
+   connected source to understand established interfaces and patterns.
+5. Implement the requested UI behavior completely using established project and
+   design-system patterns. Cover material loading, empty, error, success, and
+   accessibility behavior.
+6. Add meaningful component, interaction, and browser coverage where it improves
+   confidence.
+7. Treat Create/Modify as expected scope. A directly required companion test,
+   story, fixture, route registration, generated file, or configuration change is
+   valid when it serves acceptance criteria, stays within frontend ownership, and
+   remains outside Preserve. Disclose it in the result.
+8. Keep Preserve paths unchanged. If the requested outcome conflicts with one,
+   find a safe in-scope alternative or report the conflict clearly.
+9. Apply `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/verification-and-recovery-frontend.md` for
+   adaptive verification and recovery.
+10. Return the shared implementation-result format.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| Ship task path missing or ambiguous | Report the selector, searched feature task tree, and candidates; do not guess |
+| Parent story or feature spec missing | Continue from the task and source when sufficient; list the missing path under Issues |
+| Active stack file missing | Report the logical path and both lookup locations; use the installed default when available |
+| design-spec.md missing | Use the existing design system; report the missing path only when the task depends on absent tokens or states |
+| Component library unavailable | Report the import/package and affected UI; use an established project alternative when one exists |
+| `dependsOn` output unavailable | Name the dependency and required interface; continue independent work and report the blocked portion |
+| Preserve path changed | Restore it, use another implementation approach, and report a conflict only if no safe approach remains |
+
+---
+
+*Reads: task · parent story/spec · dependency outputs · stack overlays · design · source*
+*Writes: UI layer files only*
+*Runs in parallel with: Backend Agent (task-2)*

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/default/qa.md

@@ -0,0 +1,17 @@
+<!-- Default-mode inputs for planr-qa. -->
+
+# Default-mode QA context
+
+Use the feature name or paths supplied by the caller to locate relevant context:
+
+- Task contracts: `output/feats/feat-{name}/us-*/tasks/task-*.md`.
+- Parent context: the feature spec and user stories referenced by those tasks.
+- Design context: `output/feats/feat-{name}/design-spec.md` when UI work exists.
+- Stack commands and conventions: `input/tech/stack.md`.
+- Prior failure notes: adjacent `T-*-error-report.md` files when relevant.
+- Implementation evidence: the scoped diff, source, tests, and command output.
+
+These are useful sources, not prerequisites. If an artifact is missing, use the
+request and repository evidence that exists. Review only the relevant scope and
+return the direct human-readable response defined by the loaded QA agent. Do not
+write a QA report or change project state.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/default/specification.md

@@ -0,0 +1,111 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/default/specification.md: default-mode-only content for specification-agent. Loaded by agents/specification-agent.md when MODE=default. T-002 of SPEC-002. -->
+
+> **Mode:** default
+> **Loaded by:** `agents/specification-agent.md` when the orchestrator passes `MODE=default` (no `SPEC_DIR`).
+
+## Path Resolution
+
+The orchestrator (`/plan`) passes `MODE=default`:
+
+- Output goes to `output/feats/feat-$ARGUMENTS/us-{N}/{us-{N}.md, tasks/task-{M}.md}`.
+
+Protocol 1.7 frontmatter is identical in both modes. `SPEC-NNN`, `US-NNN`, and
+`T-NNN` IDs are project-global, monotonic, and never reused; default-mode file
+names retain their established feature-local layout.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `input/specs/spec-{name}.md` or explicit request | User / Product Owner | Use strongest available |
+| `input/tech/stack.md` | Tech Lead | Load when present |
+| `output/db/schema.json` | DB Agent | If DB interaction required |
+| `output/feats/feat-{name}/design-spec.md` | Designer Agent | If PNGs were present |
+
+---
+
+## Outputs
+
+| Output | Path | Description |
+|--------|------|-------------|
+| User Story N | `output/feats/feat-{name}/us-{N}/us-{N}.md` | One file per US |
+| Task M (UI) | `output/feats/feat-{name}/us-{N}/tasks/task-1.md` | UI layer task |
+| Task M (Tech) | `output/feats/feat-{name}/us-{N}/tasks/task-1.md` without design; `task-2.md` with design | Tech layer task |
+
+---
+
+## Deterministic execution
+
+```
+0. Resolve $ARGUMENTS as the {name} in `feat-{name}`.
+1. Load `input/specs/spec-$ARGUMENTS.md`. If it is absent, use the explicit
+   request when it contains enough product intent; otherwise report the missing
+   path and the specific decision still needed.
+2. Load `input/tech/stack.md` when present.
+   a. Read its `ActiveStackFiles` entries in declared order.
+   b. For each entry, load the installed default from
+      `${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/...` first, then load the matching
+      `.openplanr/stacks/...` file when present. The project file overrides
+      the installed file on a filename collision.
+   c. Apply the resulting folder, naming, framework, testing, and integration
+      conventions when selecting task paths. If a declared stack file cannot be
+      resolved in either location, report that exact entry and continue with the
+      remaining valid context.
+3. Detect design intent deterministically:
+   a. load `output/feats/feat-$ARGUMENTS/design-spec.md` when it exists; or
+   b. when no design spec exists, inspect the designer input sources (`UIFiles`,
+      `input/ui/feat-$ARGUMENTS/*.png`, then the documented single-feature
+      `input/ui/*.png` fallback).
+   Set `has_design = true` when either a design spec or valid design input exists.
+4. Load `output/db/schema.json` when the spec or stack indicates database work.
+   If it is expected but absent, identify the affected story/task and record the
+   missing schema as an implementation note rather than inventing tables.
+5. Decompose the source into independently valuable User Stories and write each
+   story to `output/feats/feat-$ARGUMENTS/us-{N}/us-{N}.md` using the canonical
+   story frontmatter and body shape.
+6. For each story, create its `tasks/` directory and apply R2:
+   a. `has_design = true`: write one `task-1.md` as `type: "UI"` /
+      `agent: "frontend-agent"`, and one `task-2.md` as `type: "Tech"` /
+      `agent: "backend-agent"`;
+   b. `has_design = false`: write one `task-1.md` as `type: "Tech"` /
+      `agent: "backend-agent"`;
+   c. never write a third task for the story.
+7. Populate every task with its required Protocol 1.7 schema fields, mode parent
+   `featureSlug`, 1–3 sentence `rationale`, concrete Create/Modify paths,
+   verification, and `preserve` block maps with exact `repositoryKey` and `path`
+   fields (or `preserve: []`). The task body remains readable task context; it
+   does not replace the canonical frontmatter fields.
+8. Assign stable `AC-NNN` story criteria. Populate task `reviewRisks`,
+   `browserSurfaces`, and `acceptanceRefs` arrays; map every criterion to at
+   least one task and name its verification under Test Requirements.
+9. Set `dependsOn` only when a task consumes another task's output. Task IDs are
+   project-global. Empty or absent means parallel;
+   do not derive dependencies from file overlap, shared paths, or write sets and
+   do not bury a hard dependency only in prose.
+10. Validate the written paths and frontmatter against the output table,
+   Protocol 1.7 `story.schema.json` and `task.schema.json`, and complete
+   acceptance coverage. Report every path, then end with the exact ready task
+   selector and `/planr:ship T-NNN`. Do not start Ship.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| `spec-{name}.md` missing | Name the missing path; use explicit product intent when sufficient, otherwise ask for the one missing decision |
+| `stack.md` missing | Report the path, infer conventions from the repository, and mark material assumptions |
+| Active stack entry missing or malformed | Name the exact entry and both lookup roots; continue with other valid entries |
+| Design input exists but `design-spec.md` is missing | Keep `has_design = true`, create the UI task, and report that design extraction/context is incomplete |
+| Ambiguous scope in spec | Decompose unaffected scope and identify the exact ambiguity in Delivery Notes |
+| DB schema missing but DB tasks needed | Identify the affected task and note `schema.json not found — verify the data contract before implementation` |
+| Story/task schema mismatch | Report the artifact path, field, expected shape, and correction; do not present malformed output as complete |
+
+---
+
+*Reads: spec · stack · design-spec · schema.json*
+*Writes: `output/feats/feat-{name}/` arborescence*
+*Produces schema-compatible planning artifacts and a concise diagnostic summary.*

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/contract-create-modify-preserve.md

@@ -0,0 +1,17 @@
+<!-- Shared by backend and frontend roles in both planning modes. -->
+
+## Expected scope and Preserve safety
+
+- Treat Create and Modify entries as the expected change surface, not an exhaustive
+  lock list. Implement the listed work that remains relevant to the requested
+  outcome.
+- A directly required companion test, declaration, migration, fixture, generated
+  file, route registration, or configuration change is in scope when it supports
+  acceptance behavior and stays inside the role's ownership boundary.
+- Leave every genuine Preserve path unchanged. Preserve is a safety boundary, not
+  a reason to ignore an achievable outcome; use a safe in-scope alternative when
+  one exists.
+- Do not expand into unrelated product behavior. Summarize companion files that
+  were not named in the task so the result stays easy to review.
+- If the requested outcome truly conflicts with Preserve or the role boundary,
+  report the concrete conflict and the smallest useful next action.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/design-craft-rubric.md

@@ -0,0 +1,51 @@
+# Shared: design-craft rubric (single source of truth)
+
+> Used by the `/planr:design` generator (`design-step2-generate.md`) **during
+> generation** AND **during the self-review pass**. These are the execution-craft rules that
+> separate a professional UI from an LLM's first draft — the things a senior designer applies
+> automatically. Learned from the UI-UX-Pro-Max skill (MIT) + universal craft, encoded
+> natively so planr stays standalone. (SPEC-015 / v0.15.0.)
+
+When designing **for an existing app**, the app's own tokens/components win (see
+`design-step2-generate.md` § C.0). This rubric governs **how** you assemble them.
+
+## Spacing & rhythm
+- Use **one spacing scale** — `4 / 8 / 12 / 16 / 24 / 32 / 48 / 64`. Every margin / padding /
+  gap is a value on it. **Never arbitrary** (no `13px`, `17px`, `21px`).
+- Equal gaps between sibling items. Section spacing > item spacing (group by proximity).
+- Align to a grid / baseline: label, value, and control in a row share a baseline.
+
+## Sizing consistency — the #1 "silly mistake"
+- **Same-type elements are the SAME size.** All pills / badges / chips in a group share one
+  height + padding. All buttons of one rank share size. All cards in a row share dimensions.
+  All inputs in a form share height. Icons come from a fixed set (`16 / 20 / 24`).
+- Content length must **not** change an element's height/shape within a group — fix the size;
+  truncate or wrap inside. (e.g. an `error` pill and a `warn` pill must be identical in size.)
+
+## Typography
+- A type scale (`12 / 14 / 16 / 20 / 24 / 32`), consistent weights, **≤ 2 families**. Body
+  14–16px, line-height 1.4–1.6. One text alignment per block (don't mix left/center).
+
+## Color & contrast
+- Pull from the **app's tokens** (§ C.0). Text contrast **≥ 4.5:1** (AA); large text ≥ 3:1.
+- Semantic colors consistent (error / warn / success = one hue each, everywhere). Reuse
+  tokens — no one-off hex. Avoid AI-cliché gradients (purple→pink) unless the app uses them.
+
+## Components & interaction
+- Icons are **SVG** (Heroicons / Lucide) — **never emoji as icons**. `cursor: pointer` on all
+  clickables. Visible `:focus-visible` on every interactive element. Hover/transitions
+  **150–300ms** ease. Respect `prefers-reduced-motion` + `prefers-color-scheme`.
+
+## Alignment, hierarchy & layout
+- Optical alignment: edges line up; nothing sits 1–3px off. Group related items (proximity),
+  separate unrelated ones (whitespace).
+- One clear **primary action** per view; size / weight / color earn attention deliberately.
+
+## Pre-finalize checklist — the self-review audits against THIS
+- [ ] All sibling elements of one type are the **same size** (pills, badges, buttons, cards, inputs).
+- [ ] Every spacing value is **on the scale**; gaps within a group are equal.
+- [ ] Everything **aligns** to a grid/baseline; no 1–3px drift.
+- [ ] Type scale + weights consistent; ≤ 2 families; one alignment per block.
+- [ ] Contrast ≥ 4.5:1; semantic colors consistent; tokens, not one-off hex.
+- [ ] SVG icons (no emoji); `:focus-visible` + hover on interactives; reduced-motion respected.
+- [ ] Clear hierarchy; one primary action; consistent, generous whitespace.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/design-principles.md

@@ -0,0 +1,43 @@
+# Shared: design principles — anti-slop, craft discipline (v0.18.0)
+
+> Read by the `/planr:design` generate step (C.0) and the design-system
+> generator. The **craft rubric** (`design-craft-rubric.md`) governs *measurable*
+> craft (spacing scale, sizing consistency, alignment); this file governs the
+> *taste* failures that make a design read as machine-generated. Authored natively
+> for planr (learned from common design discipline + premium-product practice);
+> no external dependency.
+
+## Avoid the machine-generated tells
+These are the patterns that instantly signal "an AI made this." Do not emit them:
+
+- **No decorative gradients.** No aggressive multi-stop gradients, no gradient "orbs/blobs"
+  to represent AI or as filler. A flat, confident surface beats a gradient wash. (A subtle
+  functional gradient — e.g. a sticky-header fade — is fine.)
+- **No emoji as UI.** Never emoji for bullets, status, icons, or section markers. Use the
+  project's icon set (outline SVG). Emoji in product copy is banned (see brand voice).
+- **No rounded-card-with-left-accent-bar cliché** as the default container. Separate with
+  hairlines + the elevation ladder; reach for one structure, not a page of identical
+  accent-bordered cards.
+- **No fake imagery.** No CSS-drawn "product screenshots", no silhouette/placeholder shapes
+  standing in for real UI, no stock-y abstract art. Show the real surface, or an honest
+  empty/placeholder state — never invented chrome.
+- **No centered-everything.** Full pages are laid out in the app shell at real density, not a
+  single narrow card centered on empty space (that's a modal, not a screen).
+
+## Content discipline
+- **Real content, never lorem.** Names, numbers, statuses, dates come from the spec/brief and
+  read like a real workspace. Numbers use `tabular-nums` and align.
+- **Copy follows the brand voice** (`brand.md`): sentence case, concise, outcome-first, calm
+  errors, no "simply/just/easily", no hype, no emoji.
+- **One saturated accent.** Color is information (primary action, status), not decoration. A
+  screen with one `--primary` element reads more premium than one with five.
+
+## Craft baseline (enforced + reviewed)
+- Everything on the **4-point grid**; same-type elements identical (the linter + craft rubric).
+- **AA contrast** on every text/background pair (the linter's `contrast-below-aa` is a hard gate).
+- **Optical alignment**, one elevation language, restrained motion (≤260ms, no bounce),
+  visible focus ring, `prefers-reduced-motion` honored.
+- **Never a blank frame**: skeletons match the real layout; optimistic with honest rollback.
+
+> The test: would a senior product designer ship this screenshot? If any element reads as
+> filler, decoration, or a template default, cut it.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/design-spec-template.md

@@ -0,0 +1,88 @@
+# Shared: the `design-spec.md` ten-section template
+
+The active design author writes this specification once per run from the brief,
+existing design system and inspected references, including image-based inputs.
+A delegated designer may be that single author; the coordinator must not start a
+second writer. Plan consumes an existing specification rather than re-extracting
+its preview pixels. If Plan receives only previously unattached mockups, its
+native designer can author a missing specification using this same contract.
+
+Write one Markdown file to the mode-specific path. Include all ten sections in
+order; use “Not applicable” with a reason when a section genuinely does not apply.
+Record exact authored values and identify approximations from image references.
+Identify the selected direction above the sections, for example
+`> Selected direction: editorial — Editorial workspace`, and keep it aligned
+with the authored document and the board's recorded selection at handoff.
+
+## 1. Color Palette
+
+| Role | Hex | Usage |
+|------|-----|-------|
+| Primary | `#______` | … |
+| Accent | `#______` | … |
+| Background | `#______` | … |
+| Surface | `#______` | … |
+| Text / Ink | `#______` | … |
+| Muted | `#______` | … |
+| Success / Warn / Danger | `#______` | … |
+
+State exact hex values. For dark mode, add a parallel column or note.
+
+## 2. Typography
+
+| Role | Family | Weight | Size / Line-height |
+|------|--------|--------|--------------------|
+| Display / H1 | … | … | … |
+| Heading | … | … | … |
+| Body | … | … | … |
+| Caption / Label | … | … | … |
+| Mono (if any) | … | … | … |
+
+Name the font families and the weights actually used.
+
+## 3. Spacing & Layout
+
+Spacing scale (e.g. 4 / 8 / 12 / 16 / 24 / 32), grid columns, gutters, max content
+width, the project’s actual breakpoints and declared responsive frames, and the
+corner-radius scale. Reuse the project scale; the numbers above are examples.
+
+## 4. Components Inventory
+
+Exhaustive list of components with their variants and states (default / hover /
+focus / active / disabled / loading / empty / error). One subsection per component.
+
+## 5. Navigation & Layout Patterns
+
+Global chrome (top bar, sidebar, tabs), the navigation model, and how primary
+regions are arranged. Note sticky/scroll behaviors.
+
+## 6. Iconography
+
+Icon style (line/solid), nominal size(s), and the set/source if identifiable.
+
+## 7. Motion & Interaction Hints
+
+Transitions, durations/easings, hover/press feedback, and `prefers-reduced-motion`
+intent. Keep it implementable, not aspirational.
+
+## 8. Component Overrides
+
+Any deviations from the project component library (`input/tech/stack.md`
+`ComponentLibrary`) — per-component, with the reason.
+
+## 9. Screen Inventory
+
+| Screen | Purpose | Key components | States to handle |
+|--------|---------|----------------|------------------|
+| … | … | … | loading / empty / error / success |
+
+One row per screen. This drives the downstream UI tasks.
+
+## 10. Open Questions
+
+Record material ambiguities, the recommended default, and any assumption used to
+keep the work moving. When authoring directly from a thin brief, put
+inferred-not-specified decisions here rather than asserting them as fact
+(`content_provenance: inferred`). Do not block ordinary implementation when the
+repository or a safe reversible default resolves the question; ask the user only
+when the choice materially changes product behavior, architecture, or risk.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/task-context-resolution.md

@@ -0,0 +1,60 @@
+<!-- Shared by backend and frontend roles in both planning modes. -->
+
+## Active task context
+
+When Ship supplies a task, load that exact task before implementation. The
+mode-specific file defines how to resolve its path and parent artifacts.
+
+1. Read the task frontmatter: `id`, `storyId`, `specId` or `featureSlug`, `type`,
+   `agent`, `status`, `dependsOn`, and structured `preserve` entries.
+2. Read the task body: Objective, Implementation or Technical Spec,
+   Verification or Test Requirements, Done When or Definition of Done, and the
+   Create, Modify, and Preserve sections. These fields describe the intended
+   implementation and output shape; do not reduce the task to its filename.
+3. Follow `storyId` to the parent story Markdown, which owns the canonical story
+   acceptance criteria, then read the enclosing specification. Load a matching
+   Gherkin sidecar when one exists; its absence is not an error. Load only the
+   portions relevant to the active task plus the connected source files and
+   interfaces needed to make the change correctly.
+4. Treat `dependsOn` as real output dependency context. For each listed task,
+   inspect the output contract or implemented interface consumed by the active
+   task. Do not infer ordering from shared paths, file overlap, or prose. An
+   absent or empty `dependsOn` list means there is no declared predecessor.
+5. Read `input/tech/stack.md`, including its build, test, lint, type-check, naming,
+   and architecture conventions. For every `ActiveStackFiles` entry:
+   - normalize it to the logical path below `stacks/` (for example,
+     `frontend/nextjs.md` or `database/prisma.md`);
+   - read the installed default at
+     `${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/<logical-path>` when present;
+   - then read `.openplanr/stacks/<logical-path>` when present.
+
+   The project-local stack file overrides the installed default on a collision.
+   Existing project code and configuration remain the primary reference for how
+   the selected conventions are applied in this repository.
+6. Parse Create and Modify as the expected change surface and Preserve as paths
+   that must remain unchanged. Keep the task's technical requirements and
+   acceptance criteria visible while choosing any directly required companion
+   files.
+
+If no task was supplied because the role was invoked directly, a complete user
+request and repository context can provide the implementation context. If Ship
+did supply a task selector but it resolves to zero or multiple files, report the
+selector, searched location, and matching candidates instead of guessing.
+
+## Result format
+
+Return one concise implementation result:
+
+- **Outcome:** a `status` of completed, partial, or blocked, plus a concise
+  `summary`.
+- **Task:** `planr-task` with its ID and path, or `direct-request` when no task
+  artifact was used.
+- **Changed:** each path and its purpose, including directly required companion
+  files not named by the task.
+- **Checks:** each command, its passed, failed, or not-run status, and a concise
+  detail.
+- **Issues:** always include this field. For each issue, give the problem, impact,
+  and next action; write `none` when the issues array is empty.
+
+Do not create a separate error report, activity log, or other workflow artifact
+unless the caller explicitly requests that output.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/verification-and-recovery-backend.md

@@ -0,0 +1,26 @@
+<!-- Loaded by the backend agent in both planning modes. -->
+
+## Verification and recovery
+
+After a coherent backend change, run the relevant commands from
+`input/tech/stack.md`: lint, type checking, build, and tests when they apply.
+Choose focused checks first, then broaden verification in proportion to the
+change and its risk.
+
+When a check fails:
+
+- inspect the actual error and enough surrounding code to identify the cause;
+- fix the cause rather than weakening assertions, skipping checks, or hiding a
+  type error;
+- rerun the affected check, then the broader relevant suite once it passes;
+- widen context or change approach when the current approach is not converging.
+
+Continue while the observed results suggest a useful next step. When progress is
+not possible because of a missing material decision, inaccessible dependency, or
+environment failure, return the failing command or operation, the relevant error,
+what was tried, the affected requirement, and the next useful action. A separate
+failure artifact is unnecessary unless the caller requested one.
+
+Project learning notes are optional. Record one only when it will materially help
+future work and the project already provides an appropriate place; never create or
+update memory as a condition of completing the task.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/verification-and-recovery-frontend.md

@@ -0,0 +1,27 @@
+<!-- Loaded by the frontend agent in both planning modes. -->
+
+## Verification and recovery
+
+After a coherent frontend change, run the relevant commands from
+`input/tech/stack.md`: lint, type checking, build, tests, and browser checks when
+they apply. Choose focused checks first, then broaden verification in proportion
+to the change and its risk.
+
+When a check fails:
+
+- inspect the actual error and the affected component, state, route, or styling
+  context;
+- fix the cause rather than weakening assertions, skipping checks, hiding a type
+  error, or accepting a visual regression;
+- rerun the affected check, then the broader relevant suite once it passes;
+- widen context or change approach when the current approach is not converging.
+
+Continue while the observed results suggest a useful next step. When progress is
+not possible because of a missing material decision, inaccessible dependency, or
+environment failure, return the failing command or operation, the relevant error,
+what was tried, the affected requirement, and the next useful action. A separate
+failure artifact is unnecessary unless the caller requested one.
+
+Project learning notes are optional. Record one only when it will materially help
+future work and the project already provides an appropriate place; never create or
+update memory as a condition of completing the task.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/backend.md

@@ -0,0 +1,96 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/spec-driven/backend.md: spec-driven-mode-only content for backend-agent (DEV Tech tasks only). Loaded by agents/backend-agent.md when MODE=spec-driven. -->
+
+> **Mode:** spec-driven
+> **Loaded by:** `agents/backend-agent.md` when the orchestrator passes `MODE=spec-driven` and `SPEC_DIR`.
+
+## Path Resolution
+
+The orchestrator (`/ship`) passes the absolute task file path,
+`MODE=spec-driven`, and `SPEC_DIR`. Use that exact task path first.
+
+- Spec directory: `.planr/specs/SPEC-NNN-{slug}/`.
+- Task: `<SPEC_DIR>/tasks/T-NNN-{slug}.md`.
+- Specification: the single `<SPEC_DIR>/SPEC-NNN-*.md` whose ID matches
+  `specId`.
+- Parent story: `<SPEC_DIR>/stories/{storyId}-*.md`.
+- Optional acceptance scenarios: `<SPEC_DIR>/stories/{storyId}-gherkin.feature`
+  when present; story Markdown remains canonical.
+- Dependencies: resolve each `dependsOn` ID against task frontmatter in the flat
+  `<SPEC_DIR>/tasks/` directory.
+
+If `SPEC_DIR` was not passed, resolve it from the explicit SPEC ID or slug under
+`.planr/specs/` and use it only when the match is unique. If no exact task path
+was passed, match the explicit task ID or slug only inside that spec's `tasks/`
+directory and use it only when unique. Follow
+`${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/task-context-resolution.md` after resolving
+the file.
+
+**Step 0.2 entity scaffold** (`output/db/schema.json` → `output/src/`): use **`agents/entity-scaffold-agent.md`** — not this file.
+
+---
+
+## Inputs (Dev Mode — Step 3)
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `<SPEC_DIR>/tasks/T-NNN-{slug}.md` (Type=Tech) | Specification Agent | Yes |
+| `input/tech/stack.md` | Tech Lead | Yes |
+| `output/db/schema.json` | DB Agent | When referencing the DB |
+| Existing codebase (read context) | Dev environment | Read-only |
+
+---
+
+## Outputs (Dev Mode — Step 3)
+
+All files listed under `### Create` and `### Modify` in the task file (`<SPEC_DIR>/tasks/T-NNN-{slug}.md`).
+
+---
+
+## Implementation guidance
+
+```
+1. Load `<SPEC_DIR>/tasks/T-NNN-{slug}.md` and extract frontmatter,
+   Create/Modify/Preserve, Objective, Implementation or Technical Spec,
+   Verification, and Done When. Follow `storyId` to the story, load its optional
+   Gherkin sidecar when present, then load the enclosing specification.
+2. Load `input/tech/stack.md`. Resolve every `ActiveStackFiles` entry through the
+   installed stack root and the project-local `.openplanr/stacks` overlay as
+   defined by the shared task-context guidance.
+3. Read each declared predecessor's output contract when `dependsOn` is non-empty.
+   Load `output/db/schema.json` when the task references persistence, and validate
+   table and column names before implementing them.
+4. Read the listed files and enough connected source to understand established
+   interfaces and project patterns.
+5. Implement the requested backend behavior completely using established project
+   patterns. Add meaningful unit and integration coverage where it improves
+   confidence.
+6. Treat Create/Modify as expected scope. A directly required companion test,
+   declaration, migration, fixture, generated file, or configuration change is
+   valid when it serves acceptance criteria, stays within backend ownership, and
+   remains outside Preserve. Disclose it in the result.
+7. Keep Preserve paths unchanged. If the requested outcome conflicts with one,
+   find a safe in-scope alternative or report the conflict clearly.
+8. Apply `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/verification-and-recovery-backend.md` for
+   adaptive verification and recovery.
+9. Return the shared implementation-result format.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| SPEC_DIR or Ship task path missing/ambiguous | Report the selector, searched directory, and candidates; do not guess |
+| Parent story or spec missing | Continue from the task and source when sufficient; list the missing path under Issues |
+| Active stack file missing | Report the logical path and both lookup locations; use the installed default when available |
+| schema.json missing for DB work | Identify the affected requirement and avoid inventing tables or columns; continue unaffected work |
+| DB table or column absent from schema | Report the exact reference and the smallest schema or task correction needed |
+| `dependsOn` output unavailable | Name the dependency and required interface; continue independent work and report the blocked portion |
+| Preserve path changed | Restore it, use another implementation approach, and report a conflict only if no safe approach remains |
+
+---
+
+*Reads: task · spec/story/Gherkin · dependency outputs · stack overlays · schema · source*
+*Writes: backend layer files only*
+*Runs in parallel with: Frontend Agent (UI task)*