@plainconceptsplatform/agent-harness 2.0.0 → 2.1.0

package/src/content/.agents/skills/pc-plan-story/SKILL.md

@@ -1,146 +1,146 @@
----
-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
-
-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 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
+
+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.

package/src/content/.agents/skills/pc-repo-audit/SKILL.md

@@ -1,44 +1,44 @@
----
-name: pc-repo-audit
-description: Audit every configured repository source root against the fullstack engineer's abilities and guardrails. Read-only. Invoked by the /repo-audit command.
-license: MIT
----
-
-# Repo Audit
-
-Audit the repository without modifying files, installing dependencies, creating backlog items, pushing, or contacting external platforms.
-
-## Step 1: Load the audit rules
-
-1. Read `.opencode/agents/fullstack-engineer.md`.
-2. Parse every `@skill-name` in its `## Abilities` section.
-3. Load every listed skill, guardrails first. If a referenced skill is missing, record it as a finding and continue with the installed abilities.
-
-## Step 2: Establish scope
-
-1. Read `.opencode/source-roots.json` when it exists. Use its non-empty `roots` array; otherwise use the repository root.
-2. Inventory every root before judging it. Identify applications, services, libraries, tests, frontend or website projects, infrastructure, CI, package manifests, lockfiles, and generated-output rules.
-3. Keep every read and command inside a configured source root or the repository root.
-
-## Step 3: Audit every project
-
-Apply the loaded abilities and guardrails to each discovered project. Assess:
-
-- Architecture, module boundaries, naming, and duplicated responsibilities.
-- Tests, linting, type checks, builds, CI, and whether their configured commands match the project.
-- Dependency manifests, lockfiles, package-manager declarations, runtime versions, and workspace configuration.
-- Security and repository hygiene, including generated files, ignored artifacts, and likely secrets in tracked files.
-- Documentation and configuration drift across `AGENTS.md`, architecture/design documents, project scripts, and CI.
-
-For dependency findings, identify the exact manifest and lockfile involved. State the repository-defined remediation and immutable dependency validation command; never run a mutation-capable install during this audit.
-
-## Step 4: Report
-
-Deduplicate findings across roots and report them grouped by project. Every finding must include:
-
-- Severity: critical, high, medium, or low.
-- Affected root and path.
-- Evidence and the applicable guardrail or ability, when one exists.
-- Impact and a concrete remediation or verification command.
-
-End with the projects audited, checks that could not run and why, and a short prioritized remediation list. If no findings exist, state that explicitly and list residual verification gaps.
+---
+name: pc-repo-audit
+description: Audit every configured repository source root against the fullstack engineer's abilities and guardrails. Read-only. Invoked by the /repo-audit command.
+license: MIT
+---
+
+# Repo Audit
+
+Audit the repository without modifying files, installing dependencies, creating backlog items, pushing, or contacting external platforms.
+
+## Step 1: Load the audit rules
+
+1. Read `.opencode/agents/fullstack-engineer.md`.
+2. Parse every `@skill-name` in its `## Abilities` section.
+3. Load every listed skill, guardrails first. If a referenced skill is missing, record it as a finding and continue with the installed abilities.
+
+## Step 2: Establish scope
+
+1. Read `.opencode/source-roots.json` when it exists. Use its non-empty `roots` array; otherwise use the repository root.
+2. Inventory every root before judging it. Identify applications, services, libraries, tests, frontend or website projects, infrastructure, CI, package manifests, lockfiles, and generated-output rules.
+3. Keep every read and command inside a configured source root or the repository root.
+
+## Step 3: Audit every project
+
+Apply the loaded abilities and guardrails to each discovered project. Assess:
+
+- Architecture, module boundaries, naming, and duplicated responsibilities.
+- Tests, linting, type checks, builds, CI, and whether their configured commands match the project.
+- Dependency manifests, lockfiles, package-manager declarations, runtime versions, and workspace configuration.
+- Security and repository hygiene, including generated files, ignored artifacts, and likely secrets in tracked files.
+- Documentation and configuration drift across `AGENTS.md`, architecture/design documents, project scripts, and CI.
+
+For dependency findings, identify the exact manifest and lockfile involved. State the repository-defined remediation and immutable dependency validation command; never run a mutation-capable install during this audit.
+
+## Step 4: Report
+
+Deduplicate findings across roots and report them grouped by project. Every finding must include:
+
+- Severity: critical, high, medium, or low.
+- Affected root and path.
+- Evidence and the applicable guardrail or ability, when one exists.
+- Impact and a concrete remediation or verification command.
+
+End with the projects audited, checks that could not run and why, and a short prioritized remediation list. If no findings exist, state that explicitly and list residual verification gaps.

package/src/content/.agents/skills/pc-repo-help/SKILL.md

@@ -1,91 +1,91 @@
----
-name: pc-repo-help
-description: The full command reference for this project - every /command with when to use it and the typical workflows. Load when the user asks for help, the command list, or at the end of repo initialization. Invoked by the /repo-help command and the repo-initialize flow.
-license: MIT
----
-
-# Repo Help
-
-Display the following reference to the user exactly as written. Do not summarize.
-
-## Commands
-
-### Not sure where to start?
-
-**`/init`** (alias: `/repo-initialize`): Initialize the project. Presents a single form with all setup questions (project type, history, architecture, design, evidence), then executes the selected steps.
-
-**`/repo-onboard`**: Guided tour of the project and its agentic infrastructure. Explains agents, commands, skills, OpenSpec workflow, and configuration. Read-only: no files modified.
-
-**`/repo-audit`**: Read-only health audit of every configured source root. Loads the fullstack engineer's abilities, checks guardrails, architecture, tooling, dependencies, lockfiles, tests, and CI, then reports prioritized findings.
-
-**`/plan-explore`**: Your backlog is unclear, you have a half-formed idea, or you need to think through a problem before committing to a plan. This is a thinking partner, not an executor.
-
-**`/plan-story <feature or need>`**: Write a detailed, repo-aware user story from a feature idea. Loads the `@user-story` skill (Mike Cohn format + Gherkin acceptance criteria), analyzes your codebase for concrete context, and produces a development-ready story with specific personas, real outcomes, and testable criteria grounded in your actual file paths, component names, and data models. No files written — just the story.
-
-**`/plan-propose <url or idea>`**: You have a work item URL, or a clear idea and you want to turn it into a structured plan (proposal, specs, tasks). Enriches each task with the best matching agent and model before showing you the plan. Nothing is implemented until you confirm.
-
----
-
-### Ready to implement?
-
-**`/plan-quick <task>`**: Quick plan for focused changes. Reads the codebase, creates a task checklist in the Todo pane. No files, no OpenSpec. Then you decide: `/plan-apply` to implement, or `/plan-propose` for a full OpenSpec plan.
-
-**`/plan-apply`**: Implement a plan. Detects the source automatically: OpenSpec-annotated tasks (from `/plan-propose`) run as parallel subagent waves; Todo pane tasks (from `/plan-quick`) run sequentially in-session.
-
-**`/plan-goal <feature or URL>`**: Fully autonomous, no confirmations. Branches off `main`, then runs propose → apply → archive on that branch (each phase its own commit). Default: merges to `main` and deletes the branch. Add `push` keyword to push the branch only. Add `pr` keyword to push + create a PR. Built for loop-engineering / unattended runs. Stops only on a hard failure, leaving the branch unmerged.
-
----
-
-### Done implementing?
-
-**`/ops-ship`**: Create a PR for the current feature branch with screenshots if UI changed.
-
-**`/ops-review`**: Read and triage PR review feedback. If you share a PR URL or say "I've added comments to the PR", it reads and classifies the review comments so you know what to fix. Fixing is done via `/plan-apply`.
-
-**`/ops-backlog`**: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
-
-**`/ops-evidence`**: Produce evidence a completed change works and publish it to the originating issue/PR. Uses `playwright-cli` (headless) and `pnpm run dev` to capture screenshots at desktop and mobile viewports, writes `evidence/evidence.json` (passed/skipped/failed/blocked), and upserts an idempotent verified comment. Best-effort; `/plan-goal` runs it automatically. Works inside CI containers.
-
-**`/plan-archive`**: Mark a completed change as archived in OpenSpec. Run this after the PR is merged.
-
----
-
-### Maintaining the project?
-
-**`/make-engineer`**: Add a custom specialist engineer to the team. Interactive persona-driven form: pick a persona, then confirm an inspected-and-recommended set of skills (architecture/patterns like FSD or design patterns, framework, testing, infra) before anything installs. Future `/plan-apply` runs will prefer it when its domain matches.
-
-**`/make-architecture`**: Regenerate `ARCHITECTURE.md` from the current codebase. Safe to rerun any time the architecture evolves.
-
-**`/make-design`**: Regenerate `DESIGN.md` from the design system (Tailwind, CSS vars, tokens, etc.).
-
-**`/make-evidence-scaffold`**: DEPRECATED. Evidence is now built into `/ops-evidence` using `playwright-cli` + `pnpm run dev`. No per-project scaffold needed.
-
-**`/make-guardrails`**: Generate a `pc-guardrails-project` skill from `ARCHITECTURE.md` and project config files. Extracts concrete rules (architecture boundaries, naming, code style, testing, git workflow) that all agents must follow. Updates every `*-engineer.md` to load the skill.
-
-**`/repo-verify`**: Verify the current branch against applicable guardrails and project checks. Runs immutable dependency installs/restores, configured builds, and tests for every discovered project, repairs relevant failures, checks dependency/lockfile consistency, and reports `VERIFIED` only when every required check passes. It runs automatically in `/plan-goal`.
-
-**`/make-user-model <tier> <model>`**: Set the model for a tier (`plan`, `build`, or `fast`). Writes to `.opencode/harness.json` (`models`). Use `user` prefix for a personal override: `/make-user-model user fast opencode/big-pickle`. Use a model id or `current` for the active session model. Restart opencode for the `pc-subagent-tiers` plugin to rebuild tier agents.
-
----
-
-### Typical workflows
-
-**Complex change:**
-```
-/plan-explore   ← optional: think it through first
-/plan-propose   ← create the plan
-/plan-apply     ← implement with the team
-/ops-ship        ← ship
-/plan-archive   ← close out
-```
-
-**Quick change:**
-```
-/plan-quick     ← create a focused task list
-/plan-apply     ← implement
-```
-
-**Unattended / loop-engineering:**
-```
-/plan-goal <description>  ← full pipeline, no interaction
-```
+---
+name: pc-repo-help
+description: The full command reference for this project - every /command with when to use it and the typical workflows. Load when the user asks for help, the command list, or at the end of repo initialization. Invoked by the /repo-help command and the repo-initialize flow.
+license: MIT
+---
+
+# Repo Help
+
+Display the following reference to the user exactly as written. Do not summarize.
+
+## Commands
+
+### Not sure where to start?
+
+**`/init`** (alias: `/repo-initialize`): Initialize the project. Presents a single form with all setup questions (project type, history, architecture, design, evidence), then executes the selected steps.
+
+**`/repo-onboard`**: Guided tour of the project and its agentic infrastructure. Explains agents, commands, skills, OpenSpec workflow, and configuration. Read-only: no files modified.
+
+**`/repo-audit`**: Read-only health audit of every configured source root. Loads the fullstack engineer's abilities, checks guardrails, architecture, tooling, dependencies, lockfiles, tests, and CI, then reports prioritized findings.
+
+**`/plan-explore`**: Your backlog is unclear, you have a half-formed idea, or you need to think through a problem before committing to a plan. This is a thinking partner, not an executor.
+
+**`/plan-story <feature or need>`**: Write a detailed, repo-aware user story from a feature idea. Loads the `@user-story` skill (Mike Cohn format + Gherkin acceptance criteria), analyzes your codebase for concrete context, and produces a development-ready story with specific personas, real outcomes, and testable criteria grounded in your actual file paths, component names, and data models. No files written — just the story.
+
+**`/plan-propose <url or idea>`**: You have a work item URL, or a clear idea and you want to turn it into a structured plan (proposal, specs, tasks). Enriches each task with the best matching agent and model before showing you the plan. Nothing is implemented until you confirm.
+
+---
+
+### Ready to implement?
+
+**`/plan-quick <task>`**: Quick plan for focused changes. Reads the codebase, creates a task checklist in the Todo pane. No files, no OpenSpec. Then you decide: `/plan-apply` to implement, or `/plan-propose` for a full OpenSpec plan.
+
+**`/plan-apply`**: Implement a plan. Detects the source automatically: OpenSpec-annotated tasks (from `/plan-propose`) run as parallel subagent waves; Todo pane tasks (from `/plan-quick`) run sequentially in-session.
+
+**`/plan-goal <feature or URL>`**: Fully autonomous, no confirmations. Branches off `main`, then runs propose → apply → archive on that branch (each phase its own commit). Default: merges to `main` and deletes the branch. Add `push` keyword to push the branch only. Add `pr` keyword to push + create a PR. Built for loop-engineering / unattended runs. Stops only on a hard failure, leaving the branch unmerged.
+
+---
+
+### Done implementing?
+
+**`/ops-ship`**: Create a PR for the current feature branch with screenshots if UI changed.
+
+**`/ops-review`**: Read and triage PR review feedback. If you share a PR URL or say "I've added comments to the PR", it reads and classifies the review comments so you know what to fix. Fixing is done via `/plan-apply`.
+
+**`/ops-backlog`**: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
+
+**`/ops-evidence`**: Produce evidence a completed change works and publish it to the originating issue/PR. Uses `playwright-cli` (headless) and `pnpm run dev` to capture screenshots at desktop and mobile viewports, writes `evidence/evidence.json` (passed/skipped/failed/blocked), and upserts an idempotent verified comment. Best-effort; `/plan-goal` runs it automatically. Works inside CI containers.
+
+**`/plan-archive`**: Mark a completed change as archived in OpenSpec. Run this after the PR is merged.
+
+---
+
+### Maintaining the project?
+
+**`/make-engineer`**: Add a custom specialist engineer to the team. Interactive persona-driven form: pick a persona, then confirm an inspected-and-recommended set of skills (architecture/patterns like FSD or design patterns, framework, testing, infra) before anything installs. Future `/plan-apply` runs will prefer it when its domain matches.
+
+**`/make-architecture`**: Regenerate `ARCHITECTURE.md` from the current codebase. Safe to rerun any time the architecture evolves.
+
+**`/make-design`**: Regenerate `DESIGN.md` from the design system (Tailwind, CSS vars, tokens, etc.).
+
+**`/make-evidence-scaffold`**: DEPRECATED. Evidence is now built into `/ops-evidence` using `playwright-cli` + `pnpm run dev`. No per-project scaffold needed.
+
+**`/make-guardrails`**: Generate a `pc-guardrails-project` skill from `ARCHITECTURE.md` and project config files. Extracts concrete rules (architecture boundaries, naming, code style, testing, git workflow) that all agents must follow. Updates every `*-engineer.md` to load the skill.
+
+**`/repo-verify`**: Verify the current branch against applicable guardrails and project checks. Runs immutable dependency installs/restores, configured builds, and tests for every discovered project, repairs relevant failures, checks dependency/lockfile consistency, and reports `VERIFIED` only when every required check passes. It runs automatically in `/plan-goal`.
+
+**`/make-user-model <tier> <model>`**: Set the model for a tier (`plan`, `build`, or `fast`). Writes to `.opencode/harness.json` (`models`). Use `user` prefix for a personal override: `/make-user-model user fast opencode/big-pickle`. Use a model id or `current` for the active session model. Restart opencode for the `pc-subagent-tiers` plugin to rebuild tier agents.
+
+---
+
+### Typical workflows
+
+**Complex change:**
+```
+/plan-explore   ← optional: think it through first
+/plan-propose   ← create the plan
+/plan-apply     ← implement with the team
+/ops-ship        ← ship
+/plan-archive   ← close out
+```
+
+**Quick change:**
+```
+/plan-quick     ← create a focused task list
+/plan-apply     ← implement
+```
+
+**Unattended / loop-engineering:**
+```
+/plan-goal <description>  ← full pipeline, no interaction
+```