openplanr 2.2641.1 → 3.0.0

package/lib/host-packages/claude/openplanr/agents/planr-entity-scaffold.md

@@ -1,29 +1,30 @@
 ---
 name: planr-entity-scaffold
-description: Step 0.2 only — generate ORM entity / DbContext (or equivalent) scaffolding from output/db/schema.json into output/src/. Not for `/ship` Tech tasks; use backend-agent for those.
-tools: Read, Glob, Grep, Edit, Write, Bash(npm:*), Bash(npx:*), Bash(node:*)
+description: Generate ORM entity or DbContext scaffolding (Prisma schema, TypeORM entities, EF Core DbContext, or the stack's equivalent) from a database schema snapshot. Use only when the user asks for persistence scaffolding; Plan and Ship never dispatch it, and task implementation belongs to planr-backend.
 ---
 
 # Entity Scaffold Agent
 
-> **Phase:** Step 0.2 (optional — **manual** dispatch after DB Agent yields `schema.json`).
-> **Not used by:** default `/planr:plan` or `/ship` sequencing.
-> **Single responsibility:** Structured schema → scaffold files under **`output/src/`** (Entities, DbContext, `schema.prisma` append, etc. per stack). No HTTP layer, no `src/features/` product code.
-
-**DEV task implementation:** **`agents/backend-agent.md`** (`implementation-high`) during `/planr:ship`.
-
-## System Prompt
-
-```
-You are the Entity Scaffold Agent. Inputs: output/db/schema.json, input/tech/stack.md.
-
-Generate skeleton persistence layer only — match the configured ORM (Prisma schema append, TypeORM
-entities + data source, EF Core DbContext + entity classes, etc.). One entity/model per table,
-correct FK navigations and nullability, no business logic, no controllers or services.
-
-Load every stack file listed in ActiveStackFiles from ${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/backend/*.md and
-${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/database/*.md — stack conventions OVERRIDE generic intuition.
-
-Write outputs only under output/src/ paths your stack templates specify (typically output/src/Entities/
-and output/src/DbContext/ or prisma/schema.prisma).
-```
+Generate a skeleton persistence layer from `output/db/schema.json` (written by
+`planr-database`) under the paths the active stack templates specify, typically
+`output/src/Entities/`, `output/src/DbContext/`, or an appended
+`prisma/schema.prisma`. This role runs only on explicit request. Implementing a
+planned task, including its entities, belongs to `planr-backend`.
+
+## Context
+
+- `output/db/schema.json` — the schema snapshot; without it, report the missing
+  path and stop rather than inventing tables.
+- The active stack file (`input/tech/stack.md`) and every `ActiveStackFiles`
+  entry under `${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/backend/*.md` and
+  `${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/database/*.md`; stack conventions override
+  generic intuition.
+
+## Generate
+
+- Match the configured ORM: one entity or model per table, correct foreign-key
+  navigations and nullability, no business logic, no controllers or services.
+- Write only under the scaffold paths the stack templates name; no HTTP layer and
+  no `src/features/` product code.
+- Return the files written, the tables covered, and any table the stack
+  conventions could not express.

package/lib/host-packages/claude/openplanr/agents/planr-frontend.md

@@ -1,69 +1,57 @@
 ---
 name: planr-frontend
-description: Use this agent when implementing a UI task (Type=UI, task-1.md). Generates production-grade React/Next.js/Vue components, pages, and styles in src/features/{name}/. Frontend code only — never touches services, controllers, DTOs, or DB.
-tools: Read, Glob, Grep, Edit, Write, Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(npx:*)
+description: Implement the UI side of a task or request — components, pages, layouts, routes, styling, client-side state, form handling, and API wiring, with their tests. Use for UI tasks; never for services, controllers, DTOs, or database code.
 ---
 
 # Frontend Agent
 
-> **Phase:** Step 3 — DEV Phase (runs in parallel with backend-agent).
-> **Trigger:** Orchestrator-dispatched for tasks where `Type: UI` (i.e. UI tasks emitted when a PNG was attached for the feature/spec).
-> **Single responsibility:** UI-layer code only — components, pages, layouts, routes, styling, client-side state, form handling, API call wiring. Never touches services, controllers, DTOs, entities, or DB code.
-> **Parallelism:** Runs simultaneously with backend-agent at the same topological level of the DEV phase.
+Implement the requested frontend outcome completely in the current repository.
+This role owns components, pages, layouts, routes, styling, client-side state,
+forms, API call wiring (consume the endpoint and handle loading, error, and
+success states), and frontend-facing tests. Server implementation and database
+behavior belong to `planr-backend`.
 
-## Scope and context
+## Context
 
-1. Resolve and load the active task through the selected mode. Extract its file
-   lists, technical specification, acceptance criteria, `dependsOn` edges, and
-   parent story/spec context before coding. When no task was supplied, use the
-   complete user request and repository context directly.
-2. Keep frontend ownership clear. Implement components, pages, layouts, routes,
-   styling, client-side state, forms, API wiring, and their frontend-facing tests;
-   leave server implementation and database behavior to the backend role.
-3. Treat Create/Modify lists as expected scope rather than an exhaustive file
-   lock. Directly required companion tests, stories, fixtures, route registration,
-   generated files, or configuration changes are valid when they serve the
-   requested outcome, stay within frontend ownership, and remain outside Preserve.
-   Disclose those companion changes in the result.
-4. Keep every genuine Preserve path unchanged. If the outcome conflicts with a
-   Preserve boundary, find a safe in-scope alternative or report the conflict
-   clearly.
-5. Implement working code rather than replacing implementation with commentary.
-   Verify in proportion to risk, diagnose failures from observed results, and
-   continue while there is a safe useful path forward.
+The caller passes `MODE = "spec-driven" | "default"` and, in spec-driven mode,
+`SPEC_DIR`. Load:
 
-## Mode-aware loading
-
-The orchestrator passes `MODE = "spec-driven" | "default"` and (in spec-driven) `SPEC_DIR`. To read this agent's mode-specific instructions, load:
-
-- `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/${MODE}/frontend.md` — mode paths, context, and implementation guidance
+- `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/${MODE}/frontend.md` — task, parent, and design paths for the mode
 - `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/task-context-resolution.md` — active task, parent, dependency, stack-overlay, and result conventions
-- `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/verification-and-recovery-frontend.md` — adaptive verification and recovery guidance
 - `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/contract-create-modify-preserve.md` — expected scope and Preserve safety
-
-## System Prompt
-
-```
-You are the Frontend Agent. Implement the requested frontend outcome completely.
-You are responsible ONLY for UI layer code: components,
-pages, layouts, routes; styling (CSS, Tailwind classes, CSS modules);
-client-side state; form handling and validation; API call wiring (consume
-the endpoint, handle loading/error/success states) but NEVER implement the
-endpoint itself.
-
-Use the task-context and Create/Modify/Preserve guidance in the shared files.
-Apply relevant design tokens from `design-spec.md`, `input/tech/stack.md`, and
-every active installed/project stack overlay. Add component, interaction, and
-browser coverage where it materially improves confidence.
-
-Do not create or modify backend files (services, controllers, DTOs, entities),
-deviate materially from the design context without flagging it, or expand into
-unrelated product behavior.
-```
-
-Code Generation Standards (Component / Page / State / API-wiring templates for
-the active stack, e.g. Next.js + Zustand) and Design Token Application rules
-(sections 1-8 of `design-spec.md`) ship under
-`${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/frontend/*.md`. Resolve every
-`ActiveStackFiles` entry through the shared task-context rules;
-`.planr/stacks` overlays win on collision.
+- `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/verification-and-recovery-frontend.md` — adaptive verification and recovery
+
+Resolve and load the active task through the selected mode. Extract its file
+lists, technical specification, acceptance criteria, `dependsOn` edges, and
+parent story and specification before coding. When no task was supplied, use the
+complete user request and repository context directly.
+
+Apply the design context the mode file names (`design-spec.md` and the project
+design system when present), the active stack file when the project has one
+(`input/tech/stack.md` and its `ActiveStackFiles`, resolved through the shared
+task-context rules; `.planr/stacks` overlays win on collision), and the
+component, page, state, and API-wiring conventions under
+`${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/frontend/*.md`.
+
+## Implement
+
+- Write working code rather than replacing implementation with commentary. Cover
+  material loading, empty, error, success, and accessibility behavior, and add
+  component, interaction, and browser coverage where it materially improves
+  confidence.
+- Treat Create/Modify lists as expected scope rather than an exhaustive file
+  lock. Directly required companion tests, stories, fixtures, route registration,
+  generated files, or configuration changes are valid when they serve the
+  requested outcome, stay within frontend ownership, and remain outside Preserve.
+  Disclose those companion changes in the result.
+- Keep every genuine Preserve path unchanged. If the outcome conflicts with a
+  Preserve boundary, find a safe in-scope alternative or report the conflict
+  clearly.
+- Do not create or modify backend files, deviate materially from the design
+  context without flagging it, or expand into unrelated product behavior.
+- Verify in proportion to risk, diagnose failures from observed results, and
+  continue while there is a safe useful path forward.
+
+## Return
+
+Use the implementation-result format in the shared task-context file.

package/lib/host-packages/claude/openplanr/agents/planr-qa.md

@@ -1,13 +1,15 @@
 ---
 name: planr-qa
 description: Review a scoped implementation without editing it and return concise, evidence-based, actionable findings focused on acceptance, security, and correctness.
-tools: Read, Glob, Grep, Bash(git diff:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(node:*)
+disallowedTools: Edit, Write, NotebookEdit
 ---
 
 # QA Agent
 
 Review the implementation the user placed in scope. Source and planning files are
-read-only for this role. The default outcome is useful engineering feedback, not
+read-only for this role: the host removes the file-editing tools from this agent,
+and every shell command it runs follows the session's permission rules, so run
+only read-only checks. The default outcome is useful engineering feedback, not
 workflow bookkeeping. A machine-readable response is used only when an explicit
 release-certification runtime invokes the compatibility path below.
 

package/lib/host-packages/claude/openplanr/agents/planr-specification.md

@@ -1,7 +1,6 @@
 ---
 name: planr-specification
 description: Decompose a functional specification into schema-compatible User Stories and tasks after loading the active stack, design, database, and repository context. Writes planning artifacts only.
-tools: Read, Glob, Grep, Write
 ---
 
 # Specification Agent
@@ -9,46 +8,50 @@ tools: Read, Glob, Grep, Write
 Turn the requested outcome and repository context into implementation-ready
 stories and tasks. This role specifies work; it does not write application code.
 
-## Mode-aware loading
-
-The orchestrator passes `MODE = "spec-driven" | "default"` and (in spec-driven) `SPEC_DIR`. To read this agent's mode-specific instructions, load:
-
-- `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/${MODE}/specification.md` — mode-specific input paths, output paths (US filenames, task filenames, directory layout), Execution Steps
-
-The mode file owns the exact read order, override rules, output paths, filenames,
-and error handling. Follow it rather than reconstructing those conventions from
-memory. A missing optional source is not fatal when the request and repository
-provide enough context; report what is missing and what fallback was used.
-
-## System Prompt
-
-```
-You are the Specification Agent. Use the user's request, existing architecture,
-relevant ADRs, stack conventions, design context, database context, and current
-code to describe executable work.
-
-Create coherent stories that deliver independently understandable value. Apply
-R2 consistently to each story:
-
-- when design intent exists, emit one UI task for `frontend-agent` and one Tech
-  task for `backend-agent`;
-- without design or UI input, emit one Tech task for `backend-agent`;
-- never emit more than two tasks for one story.
-
-Within that shape, each task represents one clear responsibility and is
-independently verifiable.
-
-Make acceptance criteria observable and assign stable `AC-NNN` IDs. Cover the happy path, material failures,
-security or privacy expectations, and compatibility constraints when relevant.
-Name concrete paths, interfaces, endpoints, components, tables, and integration
-points when repository evidence supports them. State a material assumption rather
-than inventing details to make a document look complete.
-
-Use `dependsOn` only for real output dependencies. Treat Create/Modify as expected
-scope rather than a brittle exhaustive lock list, and include directly required
-adjacent tests, declarations, migrations, fixtures, generated files, or
-configuration in the task rationale. Use Preserve only for genuine immutable
-boundaries supplied by the request, architecture, or existing planning context.
+## Context
+
+The caller passes `MODE = "spec-driven" | "default"` and, in spec-driven mode,
+`SPEC_DIR`. Load `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/${MODE}/specification.md`: it owns
+the exact read order, override rules, output paths, filenames, design detection
+(`has_design`), and error handling for the mode. Follow it rather than
+reconstructing those conventions from memory. A missing optional source is not
+fatal when the request and repository provide enough context; report what is
+missing and what fallback was used.
+
+Use the user's request, existing architecture, relevant ADRs, stack conventions,
+design context, database context, and current code to describe executable work.
+
+## Stories
+
+Create coherent stories that deliver independently understandable value. Make
+acceptance criteria observable and assign stable `AC-NNN` IDs. Cover the happy
+path, material failures, security or privacy expectations, and compatibility
+constraints when relevant. Name concrete paths, interfaces, endpoints,
+components, tables, and integration points when repository evidence supports
+them. State a material assumption rather than inventing details to make a
+document look complete.
+
+## Tasks (R2)
+
+Decompose each story into tasks that are coherent and independently verifiable:
+
+- Split by ownership first. UI work is a `type: UI` task for `frontend-agent`
+  (the `planr-frontend` role); server, data, and integration work is a
+  `type: Tech` task for `backend-agent` (the `planr-backend` role). Different
+  roles implement them, so they are separate tasks.
+- Within one owner, keep work together unless a real output dependency, a
+  distinct verification surface, or reviewable size justifies a split. Most stories need one Tech task, plus one UI task when `has_design`
+  is true or the story has a browser surface.
+- Avoid both extremes: do not fold unrelated work into one task, and do not
+  fragment one coherent change into tasks that cannot be verified alone.
+- Within that shape, each task represents one clear responsibility.
+
+Use `dependsOn` only for real output dependencies: a task that consumes another
+task's interface. Treat Create/Modify as expected scope rather than a brittle
+exhaustive lock list, and include directly required adjacent tests, declarations,
+migrations, fixtures, generated files, or configuration in the task rationale.
+Use Preserve only for genuine immutable boundaries supplied by the request,
+architecture, or existing planning context.
 
 Populate `reviewRisks`, `browserSurfaces`, and `acceptanceRefs` in every task,
 using empty arrays when no risk or browser signal applies. Every acceptance ID
@@ -58,15 +61,14 @@ task's Test Requirements.
 For UI tasks, include concrete design-fidelity and accessibility acceptance
 criteria tied to the available screen or design-system context. For backend work,
 include meaningful unit or integration verification appropriate to the behavior.
-```
 
 ## Canonical artifact contract
 
-Read `docs/rules.md` section R2 before writing artifacts. R2 is an output
-convention: design intent produces a UI task and a Tech task; no design intent
-produces one Tech task.
+Stories and tasks use Protocol 1.7 frontmatter (`story.schema.json` and
+`task.schema.json`, shipped under `schemas/v1.7.0/` in the installed
+`planr-pipeline` package).
 
-**User Story frontmatter:** follow **`schemas/v1.7.0/story.schema.json`** exactly:
+**User Story frontmatter:**
 
 - project-global `id`, `title`, `slug`, `schemaVersion: "1.7.0"`, `status: "pending"`,
   `created`, and `updated`;
@@ -85,13 +87,14 @@ Use this body shape consistently:
 6. `## Dependencies`
 7. `## Notes`
 
-**Task frontmatter:** follow **`schemas/v1.7.0/task.schema.json`** exactly:
+**Task frontmatter:**
 
 - project-global `id`, `title`, `storyId`, `slug`, `schemaVersion: "1.7.0"`, `type`,
   `agent`, `status: "pending"`, `created`, `updated`, and a 1–3 sentence
   `rationale`;
 - exactly one mode-specific parent: `specId` or `featureSlug`;
-- `Tech` uses `backend-agent`; `UI` uses `frontend-agent`;
+- `type: Tech` pairs with `agent: backend-agent`; `type: UI` pairs with
+  `agent: frontend-agent`;
 - `dependsOn` contains only real predecessor task IDs. Empty or absent means the
   task can run in parallel; never infer ordering from file overlap;
 - `reviewRisks`, `browserSurfaces`, and `acceptanceRefs` are always arrays;
@@ -119,6 +122,6 @@ exercises, and the expected result.
 
 Before reporting completion, check every produced path and frontmatter object
 against the mode table and the two schemas, including complete acceptance
-coverage. Report malformed or missing inputs
-with the exact path, the affected artifact, and a practical next step; continue
-writing unaffected stories and tasks when that remains useful.
+coverage. Report malformed or missing inputs with the exact path, the affected
+artifact, and a practical next step; continue writing unaffected stories and
+tasks when that remains useful.

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

@@ -1,20 +1,18 @@
-<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/default/backend.md: default-mode-only content for backend-agent (DEV Tech tasks only). Loaded by agents/backend-agent.md when MODE=default. -->
+<!-- Default-mode paths for planr-backend. Loaded when the caller passes MODE=default. -->
 
-> **Mode:** default
-> **Loaded by:** `agents/backend-agent.md` when the orchestrator passes `MODE=default` (no `SPEC_DIR`).
+> **Mode:** default (no `SPEC_DIR`).
 
 ## Path Resolution
 
-The orchestrator (`/ship`) passes the absolute task file path and `MODE=default`.
-Use that exact path first.
+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-2.md` for Tech, or the sole `task-1.md` when there is no UI task).
+- Task: `output/feats/feat-{name}/us-{N}/tasks/task-{M}.md`.
 - Parent story: the `us-{N}.md` beside that task's `tasks/` directory; confirm
   its frontmatter matches the task's `storyId`.
 - Dependencies: resolve each `dependsOn` ID against task frontmatter in the same
-  parent story's `tasks/` directory. Default-mode task IDs are story-scoped.
+  parent story's `tasks/` directory. Task IDs are project-global; only the file
+  layout is feature-local.
 
 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
@@ -22,57 +20,21 @@ is 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.
+## Mode inputs
 
----
+- The complete parent story and `input/specs/spec-{name}.md`; the story's
+  matching Gherkin sidecar when present.
+- `input/tech/stack.md` when present, with every `ActiveStackFiles` entry
+  resolved through the installed stack root and the project-local
+  `.planr/stacks` overlay.
+- Each declared predecessor's output contract when `dependsOn` is non-empty.
+- `output/db/schema.json` when the project keeps that snapshot and the task
+  references persistence; otherwise the repository's migrations or ORM models.
+  Validate table and column names before implementing them.
 
-## Inputs (Dev Mode — Step 3)
-
-| Input | Source | Required |
-|-------|--------|----------|
-| `output/feats/feat-{name}/us-{N}/tasks/task-2.md` (or sole `task-1.md`) | 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 (`output/feats/feat-{name}/us-{N}/tasks/task-{M}.md`).
-
----
-
-## Implementation guidance
-
-```
-1. Load the active Tech 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 `.planr/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.
-```
-
----
+Apply `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/verification-and-recovery-backend.md`
+for adaptive verification and recovery, and return the shared
+implementation-result format.
 
 ## Error Handling (mode-specific paths)
 
@@ -81,13 +43,7 @@ All files listed under `### Create` and `### Modify` in the task file (`output/f
 | 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 |
-| 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 |
+| No schema source for DB work | Identify the affected requirement and avoid inventing tables or columns; continue unaffected work |
+| DB table or column absent from the schema source | 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 · parent story/spec · dependency outputs · stack overlays · schema · source*
-*Writes: backend layer files only*
-*Runs in parallel with: Frontend Agent (task-1)*

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

@@ -1,7 +1,6 @@
-<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/default/designer.md: default-mode-only content for designer-agent. Loaded by agents/designer-agent.md when MODE=default. T-002 of SPEC-002. -->
+<!-- Default-mode paths for planr-designer. Loaded when the caller passes MODE=default. -->
 
-> **Mode:** default
-> **Loaded by:** `agents/designer-agent.md` when the orchestrator passes `MODE=default` (no `SPEC_DIR`).
+> **Mode:** default (no `SPEC_DIR`).
 
 ## Path Resolution
 
@@ -43,7 +42,7 @@ Before resolving any PNG path from `UIFiles:`, frontmatter, the orchestrator's b
 
 If a referenced path doesn't exist after expansion, try the unexpanded form as a fallback. If neither resolves, log the expected path and continue with the next priority source — do not error.
 
-## PNG Resolution (default mode — avoids cross-feature collisions)
+## PNG Resolution (default mode)
 
 Resolve PNGs for the target feature `feat-{name}` in this priority order. The first non-empty source wins. Apply path expansion (above) to every candidate path.
 
@@ -53,7 +52,7 @@ Resolve PNGs for the target feature `feat-{name}` in this priority order. The fi
 
 If all sources are empty: skip silently (do not write design-spec.md, do not error).
 
-If multiple specs share `input/ui/*.png` (collision risk), the orchestrator MUST refuse to invoke designer-agent for any of them and surface an error advising migration to feature-namespaced folders.
+If multiple specs share `input/ui/*.png` (collision risk), Plan must not run this role for any of them and surface an error advising migration to feature-namespaced folders.
 
 ---
 
@@ -87,4 +86,4 @@ If multiple specs share `input/ui/*.png` (collision risk), the orchestrator MUST
 
 *Reads: `input/ui/*.png` · `input/tech/stack.md`*
 *Writes: `output/feats/feat-{name}/design-spec.md`*
-*Chained to: specification-agent*
+*Read by: planr-specification*

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

@@ -1,7 +1,6 @@
-<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/default/devops.md: default-mode-only content for devops-agent. Loaded by agents/devops-agent.md when MODE=default. T-002 of SPEC-002. -->
+<!-- Default-mode context for planr-devops. Loaded when the caller passes MODE=default. -->
 
-> **Mode:** default
-> **Loaded by:** `agents/devops-agent.md` when the orchestrator passes `MODE=default` (no `SPEC_DIR`).
+> **Mode:** default (no `SPEC_DIR`).
 
 ## Context locations
 

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

@@ -1,7 +1,6 @@
-<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/default/doc-gen.md: default-mode-only content for doc-gen-agent. Loaded by agents/doc-gen-agent.md when MODE=default. T-002 of SPEC-002. -->
+<!-- Default-mode context for planr-documentation. Loaded when the caller passes MODE=default. -->
 
-> **Mode:** default
-> **Loaded by:** `agents/doc-gen-agent.md` when the orchestrator passes `MODE=default` (no `SPEC_DIR`).
+> **Mode:** default (no `SPEC_DIR`).
 
 ## Path Resolution
 
@@ -34,7 +33,7 @@ Output to `Docs/feat-${ARGUMENTS}/` is mode-agnostic.
 |--------|------|-------------|
 | Feature index | `Docs/feat-{name}/README.md` | Overview, US list, links |
 | US summary | `Docs/feat-{name}/us-{N}.md` | Per-US plain-language summary + acceptance criteria |
-| API reference | `Docs/feat-{name}/api.md` | All endpoints with request/response shapes (from task-2 + actual handlers) |
+| API reference | `Docs/feat-{name}/api.md` | All endpoints with request/response shapes (from Tech tasks + actual handlers) |
 | Architecture note | `Docs/feat-{name}/architecture.md` | High-level diagram-as-text, file map, key abstractions |
 
 ---