@plainconceptsplatform/agent-harness 3.5.0 → 3.7.0

package/skills/pc-plan-propose/SKILL.md

@@ -1,125 +1,125 @@
----
-name: pc-plan-propose
-description: Parse a work item or idea and produce an OpenSpec change plan (proposal.md, specs, tasks.md) with enriched task assignments (agent, tier, depends_on, touches). Load when turning a requirement into a structured plan. Invoked by the /plan-propose command (interactive) and the plan-goal pipeline (autonomous).
-license: MIT
----
-
-# Plan Propose
-
-Never write a file before the Step 3 checkpoint resolves to `yes`: build the whole plan in context, and let it hit disk in Step 4. A proposal written before its confirmation is a proposal the user cannot decline.
-
-## Input
-
-The caller provides:
-- A work item URL, issue key, or direct feature description. Exploration findings may accompany it; incorporate them.
-- Optionally a mode (see below). Default: `interactive`.
-
-## Modes
-
-- `interactive` (default): every checkpoint below is active. Wait for the user at each one.
-- `autonomous`: there is no user. Never ask anything. Each checkpoint marked with a stop sign states its autonomous resolution inline.
-
-## Step 0.a: Check for unarchived changes (stop)
-
-Before proposing a new change, inspect `openspec/changes/` (ignore `openspec/changes/archive`). If any change folder exists in `openspec/changes/` (names vary by platform: `gh-*`, `us-*`, or a plain slug), list them in the question text, then call the `question` tool:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Unarchived changes",
-      "question": "There are unarchived changes pending:\n{change-name}\n{change-name}\n...\n\nContinue with the proposal or stop to archive first?",
-      "options": [
-        { "label": "continue", "description": "Proceed with the proposal." },
-        { "label": "stop", "description": "End without generating a proposal. Archive the pending change first." }
-      ]
-    }
-  ]
-}
-```
-
-- If the user answers `stop`, end without generating a proposal.
-- If the user answers `continue`, proceed to the next step.
-
-Autonomous mode: do not call the `question` tool; treat the answer as `continue` and proceed.
-
-## Step 0.b: Load proposal skill
-
-If a work item URL or issue key is provided (GitHub Issue, Azure DevOps work item, Jira issue, or browser-based backlog): load `@pc-userstory` skill and fetch the work item before continuing. Backlog platform is set in `.opencode/harness.json` -> `platform.backlog`. If backlog platform is `none`, skip this step and work from direct input.
-
-## Step 1: Generate the proposal in memory
-
-Load `@openspec-propose` skill and follow its instructions to generate proposal.md, specs, and tasks.md. Do not write them to disk yet. Build the complete proposal content in your context.
-
-## Step 2: Enrich task assignments
-
-1. List every `*-engineer.md` file in `.opencode/agents/`. For each file read:
-   - `description:` from the YAML frontmatter: the engineer's specialization summary
-   - `## Abilities` section: the skills listed under Development, Testing, Infrastructure (e.g. `@nodejs-backend`, `@secure-nextjs-api-routes`)
-
-   Build a map of `agent-name -> { description, abilities }`.
-2. For each task, compare the task text and domain against every engineer's description AND abilities. Pick the engineer whose combined profile most closely matches. `fullstack-engineer` is the fallback worker and the body behind `build` and `plan`; prefer a real specialist over it, and never annotate a task with `build` or `plan`, which are the user's own primaries. If no specialist matches a task, leave the agent field blank and record the missing specialization in the proposal. An annotated OpenSpec task needs a real subagent; never substitute the lead or an obsolete generic agent name.
-3. Pick a tier, derive `depends_on`, derive `touches`, and annotate each task line. Follow the [task annotation](task-annotation.md) reference for the full tier selection guide, dependency derivation, touches derivation, and annotation format with examples.
-
-## Step 3: Show the plan and ask for confirmation (stop)
-
-Display the complete proposal to the user:
-- Change name and description
-- Total task count
-- Full task list with agent (including tier suffix) and dependency annotations
-
-Then call the `question` tool:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Save proposal",
-      "question": "Save this proposal?",
-      "options": [
-        { "label": "yes", "description": "Write all files to disk and proceed." },
-        { "label": "edit", "description": "Provide feedback, revise in memory, show again." },
-        { "label": "stop", "description": "End without writing anything." }
-      ]
-    }
-  ]
-}
-```
-
-- `yes` -> proceed to Step 4 and write all files
-- `edit` -> user provides feedback, revise in memory, show again, ask again
-- `stop` -> end without writing anything
-
-Wait for the user's response. Do not proceed without a response.
-
-Autonomous mode: do not call the `question` tool; treat the answer as `yes` and write the files immediately.
-
-## Step 4: Write (only after the Step 3 checkpoint resolves)
-
-Write the proposal files to `openspec/changes/{change-slug}/`:
-- `proposal.md`: the change description and rationale
-- `specs/`: any spec files generated
-- `tasks.md`: the enriched task list with agent annotations
-
-## Step 5: Stop (stop)
-
-Call the `question` tool:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Ready to implement",
-      "question": "Ready to implement?",
-      "options": [
-        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
-        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
-      ]
-    }
-  ]
-}
-```
-
-Loading `pc-plan-apply` requires explicit user confirmation.
-
-Autonomous mode: do not call the `question` tool. The PROPOSE stage is complete. Hand the change slug and task count back to the caller (the `/plan-goal` pipeline) so it immediately continues to the apply phase. This is a stage boundary, not the end of the run.
+---
+name: pc-plan-propose
+description: Parse a work item or idea and produce an OpenSpec change plan (proposal.md, specs, tasks.md) with enriched task assignments (agent, tier, depends_on, touches). Load when turning a requirement into a structured plan. Invoked by the /plan-propose command (interactive) and the plan-goal pipeline (autonomous).
+license: MIT
+---
+
+# Plan Propose
+
+Never write a file before the Step 3 checkpoint resolves to `yes`: build the whole plan in context, and let it hit disk in Step 4. A proposal written before its confirmation is a proposal the user cannot decline.
+
+## Input
+
+The caller provides:
+- A work item URL, issue key, or direct feature description. Exploration findings may accompany it; incorporate them.
+- Optionally a mode (see below). Default: `interactive`.
+
+## Modes
+
+- `interactive` (default): every checkpoint below is active. Wait for the user at each one.
+- `autonomous`: there is no user. Never ask anything. Each checkpoint marked with a stop sign states its autonomous resolution inline.
+
+## Step 0.a: Check for unarchived changes (stop)
+
+Before proposing a new change, inspect `openspec/changes/` (ignore `openspec/changes/archive`). If any change folder exists in `openspec/changes/` (names vary by platform: `gh-*`, `us-*`, or a plain slug), list them in the question text, then call the `question` tool:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Unarchived changes",
+      "question": "There are unarchived changes pending:\n{change-name}\n{change-name}\n...\n\nContinue with the proposal or stop to archive first?",
+      "options": [
+        { "label": "continue", "description": "Proceed with the proposal." },
+        { "label": "stop", "description": "End without generating a proposal. Archive the pending change first." }
+      ]
+    }
+  ]
+}
+```
+
+- If the user answers `stop`, end without generating a proposal.
+- If the user answers `continue`, proceed to the next step.
+
+Autonomous mode: do not call the `question` tool; treat the answer as `continue` and proceed.
+
+## Step 0.b: Load proposal skill
+
+If a work item URL or issue key is provided (GitHub Issue, Azure DevOps work item, Jira issue, or browser-based backlog): load `@pc-userstory` skill and fetch the work item before continuing. Backlog platform is set in `.opencode/harness.json` -> `platform.backlog`. If backlog platform is `none`, skip this step and work from direct input.
+
+## Step 1: Generate the proposal in memory
+
+Load `@openspec-propose` skill and follow its instructions to generate proposal.md, specs, and tasks.md. Do not write them to disk yet. Build the complete proposal content in your context.
+
+## Step 2: Enrich task assignments
+
+1. List every `*-engineer.md` file in `.opencode/agents/`. For each file read:
+   - `description:` from the YAML frontmatter: the engineer's specialization summary
+   - `## Abilities` section: the skills listed under Development, Testing, Infrastructure (e.g. `@nodejs-backend`, `@secure-nextjs-api-routes`)
+
+   Build a map of `agent-name -> { description, abilities }`.
+2. For each task, compare the task text and domain against every engineer's description AND abilities. Pick the engineer whose combined profile most closely matches. `fullstack-engineer` is the fallback worker and the body behind `build` and `plan`; prefer a real specialist over it, and never annotate a task with `build` or `plan`, which are the user's own primaries. If no specialist matches a task, leave the agent field blank and record the missing specialization in the proposal. An annotated OpenSpec task needs a real subagent; never substitute the lead or an obsolete generic agent name.
+3. Pick a tier, derive `depends_on`, derive `touches`, and annotate each task line. Follow the [task annotation](task-annotation.md) reference for the full tier selection guide, dependency derivation, touches derivation, and annotation format with examples.
+
+## Step 3: Show the plan and ask for confirmation (stop)
+
+Display the complete proposal to the user:
+- Change name and description
+- Total task count
+- Full task list with agent (including tier suffix) and dependency annotations
+
+Then call the `question` tool:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Save proposal",
+      "question": "Save this proposal?",
+      "options": [
+        { "label": "yes", "description": "Write all files to disk and proceed." },
+        { "label": "edit", "description": "Provide feedback, revise in memory, show again." },
+        { "label": "stop", "description": "End without writing anything." }
+      ]
+    }
+  ]
+}
+```
+
+- `yes` -> proceed to Step 4 and write all files
+- `edit` -> user provides feedback, revise in memory, show again, ask again
+- `stop` -> end without writing anything
+
+Wait for the user's response. Do not proceed without a response.
+
+Autonomous mode: do not call the `question` tool; treat the answer as `yes` and write the files immediately.
+
+## Step 4: Write (only after the Step 3 checkpoint resolves)
+
+Write the proposal files to `openspec/changes/{change-slug}/`:
+- `proposal.md`: the change description and rationale
+- `specs/`: any spec files generated
+- `tasks.md`: the enriched task list with agent annotations
+
+## Step 5: Stop (stop)
+
+Call the `question` tool:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Ready to implement",
+      "question": "Ready to implement?",
+      "options": [
+        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
+        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
+      ]
+    }
+  ]
+}
+```
+
+Loading `pc-plan-apply` requires explicit user confirmation.
+
+Autonomous mode: do not call the `question` tool. The PROPOSE stage is complete. Hand the change slug and task count back to the caller (the `/plan-goal` pipeline) so it immediately continues to the apply phase. This is a stage boundary, not the end of the run.

package/skills/pc-plan-propose/task-annotation.md

@@ -1,39 +1,39 @@
-# Task annotation reference
-
-## Tier selection
-
-Pick a tier for each task based on complexity:
-- `build`: complex code: data models, APIs, auth logic, core business logic, UI components
-- `fast`: light work: i18n keys, config changes, env variables, navigation links, simple markup, verification runs
-- `plan`: reserved for orchestration, do not use for implementation tasks
-
-The tier suffix is appended to the agent name with a dot (e.g. `backend-engineer.build`). This is the agent name you write in the annotation. The `pc-subagent-tiers` plugin resolves the model at startup from `models[<tier>]`.
-
-## depends_on
-
-Derive `depends_on` for each task: the OpenSpec task IDs (`N.M`) it logically needs completed first (a task that consumes another's output: UI needs its RPC, tests need the code, a seed needs its migration). Root tasks get `[]`. Reference the IDs OpenSpec already generated. Never invent new ones.
-
-## touches
-
-Derive `touches` for each task: the file path(s)/glob(s) it will create or modify (the task text usually names them, e.g. "Modify src/board/components/CreateForm.tsx"). This lets `pc-plan-apply` serialize same-file tasks that have no logical dependency. Include net-new files.
-
-## Annotation format
-
-Annotate each task line in-place with all three fields:
-
-```
-- [ ] <task text> <!-- agent: <name>, depends_on: [<ids>], touches: [<globs>] -->
-```
-
-Example result (note same-file tasks like 1.1/1.2 share `touches`, so `pc-plan-apply` runs them sequentially even with no `depends_on` between them; tier suffix encodes the model):
-
-```
-- [ ] 1.1 Add Project model to schema <!-- agent: backend-engineer.build, depends_on: [], touches: [src/types.ts] -->
-- [ ] 1.2 Add projectId field to LoopOptions <!-- agent: backend-engineer.build, depends_on: [], touches: [src/types.ts] -->
-- [ ] 2.1 Project RPC endpoints <!-- agent: backend-engineer.build, depends_on: [1.1], touches: [src/rpc/project/**] -->
-- [ ] 3.1 Accept page UI <!-- agent: frontend-engineer.build, depends_on: [2.1], touches: [src/board/components/CreateForm.tsx] -->
-- [ ] 3.2 i18n keys for invitation flow <!-- agent: frontend-engineer.fast, depends_on: [3.1], touches: [src/i18n/**] -->
-- [ ] 4.1 Run typecheck and fix errors <!-- agent: backend-engineer.fast, depends_on: [2.1,3.1], touches: [] -->
-```
-
-`pc-plan-apply` reads these annotations to build conflict-free waves: `depends_on` gates ordering, `touches` keeps concurrent agents file-disjoint, and the tier suffix in `agent` determines the model (resolved at startup by the `pc-subagent-tiers` plugin). `depends_on` is mandatory; `touches` is a best-effort hint.
+# Task annotation reference
+
+## Tier selection
+
+Pick a tier for each task based on complexity:
+- `build`: complex code: data models, APIs, auth logic, core business logic, UI components
+- `fast`: light work: i18n keys, config changes, env variables, navigation links, simple markup, verification runs
+- `plan`: reserved for orchestration, do not use for implementation tasks
+
+The tier suffix is appended to the agent name with a dot (e.g. `backend-engineer.build`). This is the agent name you write in the annotation. The `pc-subagent-tiers` plugin resolves the model at startup from `models[<tier>]`.
+
+## depends_on
+
+Derive `depends_on` for each task: the OpenSpec task IDs (`N.M`) it logically needs completed first (a task that consumes another's output: UI needs its RPC, tests need the code, a seed needs its migration). Root tasks get `[]`. Reference the IDs OpenSpec already generated. Never invent new ones.
+
+## touches
+
+Derive `touches` for each task: the file path(s)/glob(s) it will create or modify (the task text usually names them, e.g. "Modify src/board/components/CreateForm.tsx"). This lets `pc-plan-apply` serialize same-file tasks that have no logical dependency. Include net-new files.
+
+## Annotation format
+
+Annotate each task line in-place with all three fields:
+
+```
+- [ ] <task text> <!-- agent: <name>, depends_on: [<ids>], touches: [<globs>] -->
+```
+
+Example result (note same-file tasks like 1.1/1.2 share `touches`, so `pc-plan-apply` runs them sequentially even with no `depends_on` between them; tier suffix encodes the model):
+
+```
+- [ ] 1.1 Add Project model to schema <!-- agent: backend-engineer.build, depends_on: [], touches: [src/types.ts] -->
+- [ ] 1.2 Add projectId field to LoopOptions <!-- agent: backend-engineer.build, depends_on: [], touches: [src/types.ts] -->
+- [ ] 2.1 Project RPC endpoints <!-- agent: backend-engineer.build, depends_on: [1.1], touches: [src/rpc/project/**] -->
+- [ ] 3.1 Accept page UI <!-- agent: frontend-engineer.build, depends_on: [2.1], touches: [src/board/components/CreateForm.tsx] -->
+- [ ] 3.2 i18n keys for invitation flow <!-- agent: frontend-engineer.fast, depends_on: [3.1], touches: [src/i18n/**] -->
+- [ ] 4.1 Run typecheck and fix errors <!-- agent: backend-engineer.fast, depends_on: [2.1,3.1], touches: [] -->
+```
+
+`pc-plan-apply` reads these annotations to build conflict-free waves: `depends_on` gates ordering, `touches` keeps concurrent agents file-disjoint, and the tier suffix in `agent` determines the model (resolved at startup by the `pc-subagent-tiers` plugin). `depends_on` is mandatory; `touches` is a best-effort hint.

package/skills/pc-plan-quick/SKILL.md

@@ -1,46 +1,46 @@
----
-name: pc-plan-quick
-description: "Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec. Invoked by the /plan-quick command."
-license: MIT
----
-
-Lightweight planning for a change that is already clear: read the codebase, write the task list to the Todo pane, stop. Use `/plan-explore` then `/plan-propose` instead when the idea is half-formed, the alternatives need thinking through, or the result should outlive the session.
-
-## Rules
-
-- Never write, edit, or create a file. The only artefacts are Todo items and one question, so there is nothing to review afterwards and nothing to undo.
-- Never start the work, and never invoke `/plan-apply` or `/plan-propose` on the user's behalf. The question at the end is where they choose.
-
-## Contracts
-
-One Todo item per task, in dependency order, each one action naming the files it touches:
-
-```json
-{
-  "todos": [
-    { "content": "Add Project model to src/types.ts", "status": "pending", "priority": "high" },
-    { "content": "Add projectId field to LoopOptions in src/types.ts", "status": "pending", "priority": "high" },
-    { "content": "Create Project RPC endpoints in src/rpc/project/", "status": "pending", "priority": "medium" },
-    { "content": "Build Accept page UI in src/board/components/CreateForm.tsx", "status": "pending", "priority": "medium" },
-    { "content": "Run pnpm verify and check-diff, re-verify after fixes", "status": "pending", "priority": "low" }
-  ]
-}
-```
-
-Then ask:
-
-```json
-{
-  "questions": [
-    {
-      "header": "What next",
-      "question": "What next?",
-      "options": [
-        { "label": "/plan-apply", "description": "Implement these tasks now (creates a feature branch and works through them)." },
-        { "label": "/plan-propose", "description": "Turn this into a full OpenSpec proposal with agent assignments." },
-        { "label": "Start on specific tasks", "description": "Tell me which tasks to start on." }
-      ]
-    }
-  ]
-}
-```
+---
+name: pc-plan-quick
+description: "Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec. Invoked by the /plan-quick command."
+license: MIT
+---
+
+Lightweight planning for a change that is already clear: read the codebase, write the task list to the Todo pane, stop. Use `/plan-explore` then `/plan-propose` instead when the idea is half-formed, the alternatives need thinking through, or the result should outlive the session.
+
+## Rules
+
+- Never write, edit, or create a file. The only artefacts are Todo items and one question, so there is nothing to review afterwards and nothing to undo.
+- Never start the work, and never invoke `/plan-apply` or `/plan-propose` on the user's behalf. The question at the end is where they choose.
+
+## Contracts
+
+One Todo item per task, in dependency order, each one action naming the files it touches:
+
+```json
+{
+  "todos": [
+    { "content": "Add Project model to src/types.ts", "status": "pending", "priority": "high" },
+    { "content": "Add projectId field to LoopOptions in src/types.ts", "status": "pending", "priority": "high" },
+    { "content": "Create Project RPC endpoints in src/rpc/project/", "status": "pending", "priority": "medium" },
+    { "content": "Build Accept page UI in src/board/components/CreateForm.tsx", "status": "pending", "priority": "medium" },
+    { "content": "Run pnpm verify and check-diff, re-verify after fixes", "status": "pending", "priority": "low" }
+  ]
+}
+```
+
+Then ask:
+
+```json
+{
+  "questions": [
+    {
+      "header": "What next",
+      "question": "What next?",
+      "options": [
+        { "label": "/plan-apply", "description": "Implement these tasks now (creates a feature branch and works through them)." },
+        { "label": "/plan-propose", "description": "Turn this into a full OpenSpec proposal with agent assignments." },
+        { "label": "Start on specific tasks", "description": "Tell me which tasks to start on." }
+      ]
+    }
+  ]
+}
+```

package/skills/pc-plan-story/SKILL.md

@@ -1,93 +1,93 @@
----
-name: pc-plan-story
-description: Write a detailed, repo-aware user story from a feature idea or need, then wrap it in the repository's issue form and append a structured implementation plan. Loads the @user-story skill for Mike Cohn format + Gherkin acceptance criteria, analyzes the codebase for concrete context, and produces a development-ready story with a plan. Use when the user wants to write a user story, create a story from a feature idea, or turn a need into a structured story with acceptance criteria. Invoked by the /plan-story command.
-license: MIT
----
-
-Write a user story grounded in this repository. `@user-story` owns the format and the quality bar; `@humanizer` owns the prose. What this skill adds is the grounding: the personas, paths, models and components come out of the codebase, not out of a template.
-
-## Input
-
-A feature description, need, or rough idea, possibly with exploration findings and diagrams to align the scope with. If `$ARGUMENTS` is empty, ask what the user wants to capture.
-
-The caller may pass exploration findings from a prior `/plan-explore` session. Treat them as the primary source for the codebase inventory; read files only to fill gaps the findings do not cover.
-
-<!-- PC-OPTIMIZATION-MEMORY-START -->
-<!-- PC-OPTIMIZATION-MEMORY-END -->
-
-## Rules
-
-- Never write, edit, or create a file, and never start the work or invoke `/plan-propose` or `/plan-quick`. The only artefacts are the story (with its issue form and plan), and one question.
-- Never write `As a user`. The persona comes from the repo's own roles: auth middleware, route guards, user models. A story that could have been written without opening the repo is not worth reviewing.
-- Never show the user a story that fails the `@user-story` checks. Fix it first.
-- Every `Given`, `When` and `Then` names something real, and every `Then` is testable: a file, endpoint, model or field somebody can point at.
-- Never read outside this repository root. The entire inventory and plan must come from files inside this repo.
-- Adhere to `${{ env.REPO_RULES }}` and repository documentation (AGENTS.md, ARCHITECTURE.md, DESIGN.md, existing patterns) before finalizing the story.
-- Reserve the very top of the body — above the form's first heading — for machine-readable lines that later workflow steps add (split markers, estimate lines). Never place story or plan content there; the workflow reads those lines regardless of the form's shape.
-
-## Flow
-
-1. Load `@user-story`.
-
-2. **Coverage gate.** List every work unit from the input. For each, confirm it has exploration findings concrete enough to write an acceptance scenario: the files it touches, the models or endpoints it changes, the constraints it must respect. If any work unit is missing findings, go back and explore it now by reading the codebase. Do not draft the story until every work unit is covered. This skill's own requirement is coverage: several work units become one story that covers all of them, with at least one acceptance scenario per unit.
-
-3. Read the codebase for what the feature touches: who the users are (auth, roles, user models, guards), what exists now (components, endpoints, models, types), where the change lands (paths, module boundaries), and what rules already govern it (validation, existing flows). Incorporate any exploration findings, including their out-of-scope decisions.
-
-4. Draft the story against that inventory. Each work unit gets at least one acceptance scenario. Pull two or three edge cases from what the code does today: a violated constraint, an empty or half-migrated state, a permission boundary.
-
-5. Apply repository documentation and established conventions. Read AGENTS.md, ARCHITECTURE.md, DESIGN.md and any existing patterns that govern the area being changed. Adjust the story to respect them.
-
-6. Load `@humanizer` and run it over the prose. It cleans prose, not structure: paths, component names and Gherkin stay exact.
-
-7. Add a Mermaid diagram only for a multi-step flow, a state transition, or a component interaction, and only the happy path. A single-resource CRUD story does not need one. If the input carried an exploration diagram, extend it rather than redrawing.
-
-8. **Issue form: discover, select, fill.**
-
-   *Discover:* List the YAML and Markdown forms under `.github/ISSUE_TEMPLATE/`, plus a legacy `.github/issue_template.md` or a root `template.yml`. `config.yml` there only declares contact links, which are not forms: ignore it.
-
-   *Select:* When a form filters by labels and the issue carries one of those labels, that form wins. Otherwise use the repository's default form. When the repository has no form at all, keep the free-form story shape from step 4: there is nothing to wrap around.
-
-   *Fill:* Draw every field's content from your exploration findings. Required fields always get real content; optional fields only when you genuinely have something for them. The story narrative lands in the field that asks for it — proposal, description, or what-happened, depending on the form. The Given/When/Then scenarios go into the form's acceptance-criteria field when it has one; otherwise they stay a section of their own. The Mermaid diagram goes where it reads best inside the filled form.
-
-9. **Plan section.** Using the codebase investigation from step 3, produce a structured implementation plan that goes after the story inside the issue form body. Format it as follows:
-
-   Start with a one-line scope summary, then a context paragraph describing what areas the plan touches, how many changes it breaks into, and whether the changes are independent.
-
-   Then break the feature into numbered changes. Each change:
-
-   - **Title** — what the change does.
-   - **Problem** — what is wrong or what needs to change and why. Name the file, method, or endpoint.
-   - **Fix** — bullet steps describing the implementation approach. Each step names a concrete file, method, or field.
-   - **Affected files** — a bullet list of paths with a short note on what changes in each.
-
-   After all changes, add a summary table:
-
-   ```markdown
-   | Change | Files | Layer |
-   |---|---|---|
-   | 1. <title> | <file list> | <Backend | Frontend | Fullstack | Infra | Tests> |
-   ```
-
-   Then list exclusions — what is explicitly out of scope and why.
-
-   Do not write any files. The plan is part of the story output, read-only. It tells the implementer what to touch and why, so they can start without re-investigating.
-
-10. Show the story with the issue form wrapping, the plan, and the artefacts it is grounded in, then ask what is next. If the plan has an open clarification — a wording choice, a missing constraint, an unknown API — ask it before the contracts question.
-
-## Contracts
-
-```json
-{
-  "questions": [
-    {
-      "header": "What next",
-      "question": "What next?",
-      "options": [
-        { "label": "/plan-propose", "description": "Turn this user story into a full OpenSpec proposal with design, specs, and tasks." },
-        { "label": "/plan-quick", "description": "Create a lightweight task checklist from this story." },
-        { "label": "Refine the story", "description": "Iterate on the story with feedback." }
-      ]
-    }
-  ]
-}
-```
+---
+name: pc-plan-story
+description: Write a detailed, repo-aware user story from a feature idea or need, then wrap it in the repository's issue form and append a structured implementation plan. Loads the @user-story skill for Mike Cohn format + Gherkin acceptance criteria, analyzes the codebase for concrete context, and produces a development-ready story with a plan. Use when the user wants to write a user story, create a story from a feature idea, or turn a need into a structured story with acceptance criteria. Invoked by the /plan-story command.
+license: MIT
+---
+
+Write a user story grounded in this repository. `@user-story` owns the format and the quality bar; `@humanizer` owns the prose. What this skill adds is the grounding: the personas, paths, models and components come out of the codebase, not out of a template.
+
+## Input
+
+A feature description, need, or rough idea, possibly with exploration findings and diagrams to align the scope with. If `$ARGUMENTS` is empty, ask what the user wants to capture.
+
+The caller may pass exploration findings from a prior `/plan-explore` session. Treat them as the primary source for the codebase inventory; read files only to fill gaps the findings do not cover.
+
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->
+
+## Rules
+
+- Never write, edit, or create a file, and never start the work or invoke `/plan-propose` or `/plan-quick`. The only artefacts are the story (with its issue form and plan), and one question.
+- Never write `As a user`. The persona comes from the repo's own roles: auth middleware, route guards, user models. A story that could have been written without opening the repo is not worth reviewing.
+- Never show the user a story that fails the `@user-story` checks. Fix it first.
+- Every `Given`, `When` and `Then` names something real, and every `Then` is testable: a file, endpoint, model or field somebody can point at.
+- Never read outside this repository root. The entire inventory and plan must come from files inside this repo.
+- Adhere to `${{ env.REPO_RULES }}` and repository documentation (AGENTS.md, ARCHITECTURE.md, DESIGN.md, existing patterns) before finalizing the story.
+- Reserve the very top of the body — above the form's first heading — for machine-readable lines that later workflow steps add (split markers, estimate lines). Never place story or plan content there; the workflow reads those lines regardless of the form's shape.
+
+## Flow
+
+1. Load `@user-story`.
+
+2. **Coverage gate.** List every work unit from the input. For each, confirm it has exploration findings concrete enough to write an acceptance scenario: the files it touches, the models or endpoints it changes, the constraints it must respect. If any work unit is missing findings, go back and explore it now by reading the codebase. Do not draft the story until every work unit is covered. This skill's own requirement is coverage: several work units become one story that covers all of them, with at least one acceptance scenario per unit.
+
+3. Read the codebase for what the feature touches: who the users are (auth, roles, user models, guards), what exists now (components, endpoints, models, types), where the change lands (paths, module boundaries), and what rules already govern it (validation, existing flows). Incorporate any exploration findings, including their out-of-scope decisions.
+
+4. Draft the story against that inventory. Each work unit gets at least one acceptance scenario. Pull two or three edge cases from what the code does today: a violated constraint, an empty or half-migrated state, a permission boundary.
+
+5. Apply repository documentation and established conventions. Read AGENTS.md, ARCHITECTURE.md, DESIGN.md and any existing patterns that govern the area being changed. Adjust the story to respect them.
+
+6. Load `@humanizer` and run it over the prose. It cleans prose, not structure: paths, component names and Gherkin stay exact.
+
+7. Add a Mermaid diagram only for a multi-step flow, a state transition, or a component interaction, and only the happy path. A single-resource CRUD story does not need one. If the input carried an exploration diagram, extend it rather than redrawing.
+
+8. **Issue form: discover, select, fill.**
+
+   *Discover:* List the YAML and Markdown forms under `.github/ISSUE_TEMPLATE/`, plus a legacy `.github/issue_template.md` or a root `template.yml`. `config.yml` there only declares contact links, which are not forms: ignore it.
+
+   *Select:* When a form filters by labels and the issue carries one of those labels, that form wins. Otherwise use the repository's default form. When the repository has no form at all, keep the free-form story shape from step 4: there is nothing to wrap around.
+
+   *Fill:* Draw every field's content from your exploration findings. Required fields always get real content; optional fields only when you genuinely have something for them. The story narrative lands in the field that asks for it — proposal, description, or what-happened, depending on the form. The Given/When/Then scenarios go into the form's acceptance-criteria field when it has one; otherwise they stay a section of their own. The Mermaid diagram goes where it reads best inside the filled form.
+
+9. **Plan section.** Using the codebase investigation from step 3, produce a structured implementation plan that goes after the story inside the issue form body. Format it as follows:
+
+   Start with a one-line scope summary, then a context paragraph describing what areas the plan touches, how many changes it breaks into, and whether the changes are independent.
+
+   Then break the feature into numbered changes. Each change:
+
+   - **Title** — what the change does.
+   - **Problem** — what is wrong or what needs to change and why. Name the file, method, or endpoint.
+   - **Fix** — bullet steps describing the implementation approach. Each step names a concrete file, method, or field.
+   - **Affected files** — a bullet list of paths with a short note on what changes in each.
+
+   After all changes, add a summary table:
+
+   ```markdown
+   | Change | Files | Layer |
+   |---|---|---|
+   | 1. <title> | <file list> | <Backend | Frontend | Fullstack | Infra | Tests> |
+   ```
+
+   Then list exclusions — what is explicitly out of scope and why.
+
+   Do not write any files. The plan is part of the story output, read-only. It tells the implementer what to touch and why, so they can start without re-investigating.
+
+10. Show the story with the issue form wrapping, the plan, and the artefacts it is grounded in, then ask what is next. If the plan has an open clarification — a wording choice, a missing constraint, an unknown API — ask it before the contracts question.
+
+## Contracts
+
+```json
+{
+  "questions": [
+    {
+      "header": "What next",
+      "question": "What next?",
+      "options": [
+        { "label": "/plan-propose", "description": "Turn this user story into a full OpenSpec proposal with design, specs, and tasks." },
+        { "label": "/plan-quick", "description": "Create a lightweight task checklist from this story." },
+        { "label": "Refine the story", "description": "Iterate on the story with feedback." }
+      ]
+    }
+  ]
+}
+```