@plainconceptsplatform/agent-harness 2.4.0 → 2.5.0

package/harness/.agents/skills/pc-plan-goal/output.md

@@ -1,65 +1,71 @@
-# Output procedure
-
-Before output, require `verify`, `archive`, a clean working tree, no active change directory, and an archive directory for `{change-id}`.
-
-## Restore stash
-
-If the goal created `goal-wip`, restore it after the mode-specific operation. When restoration conflicts, leave the stash intact, report its `git stash list` reference, and do not drop user work.
-
-## Default mode
-
-Synchronize the default branch, merge, delete the feature branch, then restore the stash:
-
-```bash
-git switch "$DEFAULT_BRANCH"
-
-if git remote get-url origin >/dev/null 2>&1; then
-  git pull origin "$DEFAULT_BRANCH"
-fi
-
-git merge --no-ff "$BRANCH" -m "goal: {title} ({change-id})"
-git branch -d "$BRANCH"
-```
-
-If the merge conflicts, abort it and use the failure policy. Do not push the default branch.
-
-## Push mode
-
-Push the feature branch:
-
-```bash
-git push -u origin "$BRANCH"
-```
-
-Restore the stash and leave the branch available.
-
-## PR mode
-
-Push the feature branch, then load `pc-ops-ship` to create a PR into `$DEFAULT_BRANCH`. Supply title, change id, functional summary, delivered acceptance criteria, task count, verification result, archive path, and commits. Do not merge the PR.
-
-Restore the stash.
-
-## Final report
-
-Print:
-
-```text
-Goal: {title}
-Change ID: {change-id}
-Scope classification: focused | standard | complex
-Functional outcome: {one-sentence result}
-Branch: {branch}
-Tasks: {completed}/{total}
-Acceptance criteria: {passed}/{total}
-Commits: {proposal, apply, archive}
-Verification: passed | failed
-Archived: yes | no
-Archive path: {path or none}
-Output mode: default | push | pr
-Final state: merged locally | pushed branch | PR URL | branch preserved after failure
-Stash restoration: not needed | restored | preserved after conflict
-```
-
-## External gate
-
-An unattended caller must verify `openspec list --json` is empty and run the project's lint and typecheck commands before any later git operation.
+# Output procedure
+
+Before output, require `verify`, `archive`, a clean working tree, no active change directory, and an archive directory for `{change-id}`.
+
+## Restore stash
+
+If the goal created `goal-wip`, restore it after the mode-specific operation. When restoration conflicts, leave the stash intact, report its `git stash list` reference, and do not drop user work.
+
+## Default mode
+
+Synchronize the default branch, merge, delete the feature branch, then restore the stash:
+
+```bash
+git switch "$DEFAULT_BRANCH"
+
+if git remote get-url origin >/dev/null 2>&1; then
+  git pull origin "$DEFAULT_BRANCH"
+fi
+
+git merge --no-ff "$BRANCH" -m "goal: {title} ({change-id})"
+git branch -d "$BRANCH"
+```
+
+If the merge conflicts, abort it and use the failure policy. Do not push the default branch.
+
+## Push mode
+
+Push the feature branch:
+
+```bash
+git push -u origin "$BRANCH"
+```
+
+Restore the stash and leave the branch available.
+
+## PR mode
+
+Push the feature branch, then load `pc-ops-ship` to create a PR into `$DEFAULT_BRANCH`. Supply title, change id, functional summary, delivered acceptance criteria, task count, verification result, archive path, and commits. Do not merge the PR.
+
+Restore the stash.
+
+## Branch mode
+
+Leave `$BRANCH` in place with its commits. Merge nothing, push nothing, delete nothing.
+
+Restore the stash.
+
+## Final report
+
+Print:
+
+```text
+Goal: {title}
+Change ID: {change-id}
+Scope classification: focused | standard | complex
+Functional outcome: {one-sentence result}
+Branch: {branch}
+Tasks: {completed}/{total}
+Acceptance criteria: {passed}/{total}
+Commits: {proposal, apply, archive}
+Verification: passed | failed
+Archived: yes | no
+Archive path: {path or none}
+Output mode: default | push | pr | branch
+Final state: merged locally | pushed branch | PR URL | branch preserved | branch preserved after failure
+Stash restoration: not needed | restored | preserved after conflict
+```
+
+## External gate
+
+An unattended caller must verify `openspec list --json` is empty and run the project's lint and typecheck commands before any later git operation.

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

@@ -6,7 +6,7 @@ license: MIT
 
 # Plan Propose
 
-**READ-ONLY UNTIL CONFIRMED.** Until the Step 3 checkpoint resolves to `yes`, this entire skill is read-only. You MUST NOT write, edit, or create any file. Build everything in context. Files hit disk only in Step 4. After Step 5, the skill ends; if the user keeps chatting without invoking a new command, remain read-only. Writing requires either an explicit user command (e.g. `/plan-apply`) or the Step 3 `yes` confirmation.
+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
 

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

@@ -1,62 +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
----
-
-This command is strictly read-only. You may read files, search code, and use `todowrite` to create Todo pane items. You MUST NOT write, edit, or create any file. After completing the checklist and asking the user what's next, if the user continues chatting without invoking a new command (e.g. `/plan-apply`) or explicitly requesting implementation, remain read-only. The only output of this command is the Todo pane checklist and a question to the user.
-
-Lightweight planning for focused changes. Reads the codebase, creates a task checklist in the Todo pane using `todowrite`, and stops. This is a thinking tool, not a file writer.
-
-When to use this instead of `/plan-explore` then `/plan-propose`:
-- The task is clear and well-scoped (not a half-formed idea)
-- You don't need to think through alternatives or investigate deeply
-- You want a task list in under a minute, not a full proposal
-
-## Step 1: Understand the task
-
-Read the user's description. Use `glob` and `grep` to locate the relevant files, components, and patterns in the codebase. Read the key files to understand what exists and what needs to change.
-
-## Step 2: Create the plan in the Todo pane
-
-Use `todowrite` to create one todo item per task. Each item must be:
-
-- Concrete and actionable: include file paths or areas in the task text when possible
-- Ordered by logical dependency: dependencies first
-- Granular: one clear action per item, not a bundle
-
-Example `todowrite` call:
-
-```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 typecheck and fix errors", "status": "pending", "priority": "low" }
-  ]
-}
-```
-
-## Step 3: Ask what's next
-
-Call the `question` tool:
-
-```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." }
-      ]
-    }
-  ]
-}
-```
-
-Do not create any files. Do not run `/plan-apply` or `/plan-propose` automatically. The only output is the Todo pane checklist.
+---
+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 typecheck and fix errors", "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/harness/.agents/skills/pc-plan-story/SKILL.md

@@ -1,149 +1,48 @@
----
-name: pc-plan-story
-description: Write a detailed, repo-aware user story from a feature idea or need. Loads the @user-story skill for Mike Cohn format + Gherkin acceptance criteria, analyzes the codebase for concrete context, and produces a development-ready story. 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 the actual codebase. Load the `@user-story` skill and follow its format (Mike Cohn "As a / I want to / so that" + Gherkin "Given / When / Then"). The story must be specific: real personas, real file paths, real component names, real data models — not generic placeholders.
-
-This skill is read-only. You may read files, search code, and use `todowrite` to create Todo pane items. The only output is the user story itself and a question to the user. No files, no OpenSpec changes, no branches.
-
-## Input
-
-The caller provides:
-- A feature description, user need, or rough idea. This is the seed for the story.
-- Exploration findings may accompany it — including diagrams (Mermaid, ASCII, or inline markdown). When provided, use them as context: the story should align with the explored scope, decisions, and recommended approach.
-- If `$ARGUMENTS` is empty, ask the user what feature or need they want to capture.
-
-## Step 1: Load the user-story skill
-
-Load the `@user-story` skill now. Follow its format, anti-patterns, and quality checks for the rest of this skill. Every story produced must pass the user-story skill's validation.
-
-## Step 2: Analyze the codebase
-
-<!-- PC-OPTIMIZATION-MEMORY-START -->
-<!-- PC-OPTIMIZATION-MEMORY-END -->
-
-Use `glob` and `grep` to locate the relevant files, components, types, and patterns that the feature touches. Read the key files to understand:
-
-- **Who** the users are (check auth, roles, user models, route guards)
-- **What** the current state is (existing components, API endpoints, data models, types)
-- **Where** the change would land (file paths, directory structure, module boundaries)
-- **Why** it matters (business logic, validation rules, existing UX flows)
-
-If exploration findings or diagrams were provided, incorporate them: align the story's scope with the explored boundaries, reference the components and flows the diagram highlights, and respect any out-of-scope decisions the exploration made.
-
-Map the feature description to concrete codebase artifacts:
-
-```
-Relevant artifacts:
-  Models:    <model names and file paths>
-  Components: <component names and file paths>
-  Endpoints:  <route or API paths>
-  Types:      <type definitions and file paths>
-  Patterns:   <architectural patterns in use (FSD, monolith, etc.)>
-```
-
-## Step 3: Draft the user story
-
-Write the story using the user-story skill's format. Ground every field in the codebase analysis from Step 2:
-
-### Use Case
-
-- **As a** [specific persona derived from auth/roles/user models in the repo — never "user"]
-- **I want to** [action that maps to a concrete code change — reference the component, endpoint, or model involved]
-- **so that** [real outcome tied to business logic or UX flow found in the codebase]
-
-### Acceptance Criteria (Gherkin)
-
-Write scenarios with preconditions grounded in the actual codebase state:
-
-- **Scenario:** [brief description]
-- **Given:** [precondition referencing real state — e.g. "the user is authenticated via the JWT middleware in src/auth/middleware.ts"]
-- **and Given:** [additional preconditions — existing data models, current UI state, config values]
-- **When:** [trigger that maps to a concrete user action on a real component or endpoint]
-- **Then:** [testable outcome referencing actual system behavior — e.g. "the response from POST /api/projects includes the new projectId field defined in src/types/Project.ts"]
-
-### Edge Cases
-
-List 2-3 edge cases derived from what the code currently does:
-
-- What happens when [existing validation/constraint] is violated?
-- What if [existing data state] is empty/null/migration-incomplete?
-- What about [existing role/permission boundary]?
-
-### Summary
-
-Write a one-line value-focused summary (not a feature title).
-
-## Step 4: Humanize
-
-Load the `@humanizer` skill and run it on the drafted story text from Step 3. AI-generated stories tend to:
-
-- Overuse em dashes and rule-of-three lists
-- Use promotional language ("seamless", "powerful", "comprehensive")
-- Use passive voice and negative parallelisms
-- Stack vague attributions
-- Inflate symbolism in the summary line
-
-Apply the humanizer's audit → fix loop to all prose in the story: the summary, the use case, the scenario descriptions, and the edge case notes. Preserve all technical details, file paths, component names, and Gherkin structure — the humanizer cleans prose, not structure or accuracy.
-
-## Step 5: Diagram (when the story has a flow)
-
-If the story involves a user journey, state transition, or component interaction that benefits from visualization, produce a Mermaid diagram. Keep it minimal: the happy path only, no exhaustive enumeration of every branch.
-
-When to draw:
-- Multi-step flows (login → action → confirmation)
-- State transitions (status changes on a work item, order state machine)
-- Component interactions (frontend → API → service → DB)
-
-When to skip:
-- Simple CRUD on a single resource
-- Stories with a single step and no preconditions beyond auth
-
-If the input included an exploration diagram, extend it with the story's new flow rather than redrawing from scratch.
-
-## Step 6: Validate
-
-Run every quality check from the user-story skill:
-
-- No generic "As a user" — the persona must be specific and grounded in repo context
-- "So that" must express real motivation, not restate "I want to"
-- Single When / single Then per scenario — if multiple, note that the story should split
-- Thens must be testable and measurable — reference real system behavior, not vague improvements
-- No technical tasks disguised as user stories (if there's no user outcome, say so)
-
-If any check fails, fix the story and re-validate. Do not show a story to the user that fails validation.
-
-## Step 7: Present the story
-
-Display the complete user story to the user:
-
-- Summary
-- Use Case (As a / I want to / so that)
-- Acceptance Criteria (all scenarios with full Given/When/Then)
-- Edge Cases
-- Diagram (if produced in Step 5)
-- Codebase artifacts the story is grounded in (file paths, component names, types)
-
-## Step 8: Ask what's next
-
-Call the `question` tool:
-
-```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." }
-      ]
-    }
-  ]
-}
-```
-
-Do not create any files. Do not run `/plan-propose` or `/plan-quick` automatically. The only output is the user story.
+---
+name: pc-plan-story
+description: Write a detailed, repo-aware user story from a feature idea or need. Loads the @user-story skill for Mike Cohn format + Gherkin acceptance criteria, analyzes the codebase for concrete context, and produces a development-ready story. 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.
+
+<!-- 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 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.
+
+## Flow
+
+1. Load `@user-story`.
+2. 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.
+3. Draft the story against that inventory, with two or three edge cases taken from what the code does today: a violated constraint, an empty or half-migrated state, a permission boundary.
+4. Load `@humanizer` and run it over the prose. It cleans prose, not structure: paths, component names and Gherkin stay exact.
+5. 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.
+6. Show the story with the artefacts it is grounded in, then ask what is next.
+
+## 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." }
+      ]
+    }
+  ]
+}
+```