@plainconceptsplatform/agent-harness 3.9.0 → 3.11.0

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

@@ -1,127 +1,127 @@
----
-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.
-
-When `.platform/contract.yml` declares `reuse`, read the paths in `reuse.docs` and the exports of the `reuse.packages` first, and give proposal.md a `## What is reused` section: for each part of the change, the doc page, package export or `reuse.names` entry it builds on, or why none fits. A proposal without it re-implements what the template already ships, and `pc-plan-apply` stops on it.
-
-## 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.
+
+When `.platform/contract.yml` declares `reuse`, read the paths in `reuse.docs` and the exports of the `reuse.packages` first, and give proposal.md a `## What is reused` section: for each part of the change, the doc page, package export or `reuse.names` entry it builds on, or why none fits. A proposal without it re-implements what the template already ships, and `pc-plan-apply` stops on it.
+
+## 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>]`, with `.opencode/harness.user.json` overriding `.opencode/harness.json`, and writes the effective value to `.opencode/harness-models.json`. `tasks.md` names the tier, never a model id.
-
-## 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>]`, with `.opencode/harness.user.json` overriding `.opencode/harness.json`, and writes the effective value to `.opencode/harness-models.json`. `tasks.md` names the tier, never a model id.
+
+## 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." }
+      ]
+    }
+  ]
+}
+```