@plainconceptsplatform/agent-harness 3.8.2 → 3.9.0

package/skills/pc-plan-goal/branching.md

@@ -1,39 +1,39 @@
-# Branching procedure
-
-Resolve and record the branch names. If the invoking workflow already placed you on a feature branch (`feature/*`, `fix/*`, etc.), it owns the branch: do not stash, switch, pull, or rename. The sandbox hosting the workflow has no git credentials, so those commands would either corrupt the tree or hang, and the workflow has already cut the branch from the default branch. Treat its result as given.
-
-```bash
-BRANCH="$(git branch --show-current)"
-case "$BRANCH" in
-  feature/*|fix/*|chore/*|docs/*|refactor/*)
-    START_BRANCH="$BRANCH"
-    DEFAULT_BRANCH="$BRANCH"
-    GOAL_STASH="none"
-    ;;
-  *)
-    START_BRANCH="$BRANCH"
-    DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
-    [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
-
-    # Stash uncommitted work when needed and record that the goal stash exists.
-    git stash push -u -m "goal-wip"
-    GOAL_STASH="goal-wip"
-
-    # Create the feature branch from the synchronized default branch.
-    git switch "$DEFAULT_BRANCH"
-
-    if git remote get-url origin >/dev/null 2>&1; then
-      git pull origin "$DEFAULT_BRANCH"
-    fi
-
-    git switch -c "feature/{slug}"
-    BRANCH="$(git branch --show-current)"
-    ;;
-esac
-```
-
-Record the branch name and that `feature/{slug}` was applied unconditionally, so downstream phases can restore if they move off it.
-
-Everything through archive happens on `$BRANCH`.
-
-When a later phase renames `$BRANCH` to match the canonical change slug (Phase 3 of `pc-plan-goal`), skip the rename if the workflow already fixed the name. Renaming would call `git branch -m`, which a credentialless sandbox refuses, and the workflow's `create_pull_request` is told to use the branch as named. Detect this by checking that `$BRANCH` already starts with `feature/`; if it does, keep it.
+# Branching procedure
+
+Resolve and record the branch names. If the invoking workflow already placed you on a feature branch (`feature/*`, `fix/*`, etc.), it owns the branch: do not stash, switch, pull, or rename. The sandbox hosting the workflow has no git credentials, so those commands would either corrupt the tree or hang, and the workflow has already cut the branch from the default branch. Treat its result as given.
+
+```bash
+BRANCH="$(git branch --show-current)"
+case "$BRANCH" in
+  feature/*|fix/*|chore/*|docs/*|refactor/*)
+    START_BRANCH="$BRANCH"
+    DEFAULT_BRANCH="$BRANCH"
+    GOAL_STASH="none"
+    ;;
+  *)
+    START_BRANCH="$BRANCH"
+    DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+    [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
+
+    # Stash uncommitted work when needed and record that the goal stash exists.
+    git stash push -u -m "goal-wip"
+    GOAL_STASH="goal-wip"
+
+    # Create the feature branch from the synchronized default branch.
+    git switch "$DEFAULT_BRANCH"
+
+    if git remote get-url origin >/dev/null 2>&1; then
+      git pull origin "$DEFAULT_BRANCH"
+    fi
+
+    git switch -c "feature/{slug}"
+    BRANCH="$(git branch --show-current)"
+    ;;
+esac
+```
+
+Record the branch name and that `feature/{slug}` was applied unconditionally, so downstream phases can restore if they move off it.
+
+Everything through archive happens on `$BRANCH`.
+
+When a later phase renames `$BRANCH` to match the canonical change slug (Phase 3 of `pc-plan-goal`), skip the rename if the workflow already fixed the name. Renaming would call `git branch -m`, which a credentialless sandbox refuses, and the workflow's `create_pull_request` is told to use the branch as named. Detect this by checking that `$BRANCH` already starts with `feature/`; if it does, keep it.

package/skills/pc-plan-goal/failure-policy.md

@@ -1,30 +1,30 @@
-# Failure policy
-
-`/plan-goal` never asks for input, but must halt instead of shipping broken or incoherent work.
-
-Use the failure policy when:
-
-- exploration cannot produce a safe and coherent functional interpretation after its one retry,
-- exploration determines the goal is infeasible or outside the repository's feasible responsibility,
-- the proposal produces no actionable tasks,
-- the proposal materially contradicts the exploration brief,
-- a task wave stalls because tasks remain but none are eligible,
-- a task exhausts its single retry,
-- tests, lint, build, type checks, or required verification fail and cannot be cleared by re-waving,
-- any verification command (lint, typecheck, test) exits non-zero after the apply phase and re-waving does not clear it,
-- archive verification still prints `ARCHIVE_FAILED` after one retry,
-- required repository state is missing or inconsistent before output,
-- or a merge conflict cannot be resolved cleanly and automatically.
-
-On failure:
-
-1. Stop the pipeline.
-2. Do not merge.
-3. Do not push the default branch.
-4. Leave `$BRANCH` intact whenever it exists.
-5. Abort any incomplete merge.
-6. Restore the Phase 1 goal stash on `$START_BRANCH`.
-7. If stash restoration conflicts, preserve the stash and report its reference.
-8. Report: the failed phase, the exact failed postcondition, commands or verification that failed, retry attempts, current branch, repository state, completed commits, archive state, and the safest manual next step.
-
-For loop-engineering, a clean failure with the feature branch preserved is the correct outcome. Never merge or ship unverified work.
+# Failure policy
+
+`/plan-goal` never asks for input, but must halt instead of shipping broken or incoherent work.
+
+Use the failure policy when:
+
+- exploration cannot produce a safe and coherent functional interpretation after its one retry,
+- exploration determines the goal is infeasible or outside the repository's feasible responsibility,
+- the proposal produces no actionable tasks,
+- the proposal materially contradicts the exploration brief,
+- a task wave stalls because tasks remain but none are eligible,
+- a task exhausts its single retry,
+- tests, lint, build, type checks, or required verification fail and cannot be cleared by re-waving,
+- any verification command (lint, typecheck, test) exits non-zero after the apply phase and re-waving does not clear it,
+- archive verification still prints `ARCHIVE_FAILED` after one retry,
+- required repository state is missing or inconsistent before output,
+- or a merge conflict cannot be resolved cleanly and automatically.
+
+On failure:
+
+1. Stop the pipeline.
+2. Do not merge.
+3. Do not push the default branch.
+4. Leave `$BRANCH` intact whenever it exists.
+5. Abort any incomplete merge.
+6. Restore the Phase 1 goal stash on `$START_BRANCH`.
+7. If stash restoration conflicts, preserve the stash and report its reference.
+8. Report: the failed phase, the exact failed postcondition, commands or verification that failed, retry attempts, current branch, repository state, completed commits, archive state, and the safest manual next step.
+
+For loop-engineering, a clean failure with the feature branch preserved is the correct outcome. Never merge or ship unverified work.

package/skills/pc-plan-goal/output-mode.md

@@ -1,10 +1,10 @@
-# Output mode
-
-Determine the mode only from the first whitespace-delimited token of `$ARGUMENTS`.
-
-- `pr`: remove the token, push the feature branch, and create a PR.
-- `push`: remove the token and push the feature branch.
-- `branch`: remove the token, keep the feature branch, merge nothing and push nothing.
-- Any other first token: keep the full input and merge locally into the default branch.
-
-Words such as "push notifications" or "PR template" inside the feature description are feature data. They do not change output mode.
+# Output mode
+
+Determine the mode only from the first whitespace-delimited token of `$ARGUMENTS`.
+
+- `pr`: remove the token, push the feature branch, and create a PR.
+- `push`: remove the token and push the feature branch.
+- `branch`: remove the token, keep the feature branch, merge nothing and push nothing.
+- Any other first token: keep the full input and merge locally into the default branch.
+
+Words such as "push notifications" or "PR template" inside the feature description are feature data. They do not change output mode.

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

@@ -1,71 +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.
-
-## 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.
+# 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/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>]`.
-
-## 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.