@plainconceptsplatform/agent-harness 2.0.0 → 2.1.0

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

@@ -1,130 +1,130 @@
----
-name: pc-repo-initialize
-description: Initialize the project. Presents a single form with all setup questions, then executes selected steps. Invoked by the /init command (alias: /repo-initialize).
-license: MIT
----
-Check if `AGENTS.md` contains the `<!-- PC-NOT-INITIALIZED -->` marker.
-
-- If no: tell the user the project is already initialized. Suggest running `/make-architecture` or `/make-design` if they want to refresh those docs.
-- If yes: run the sequence below.
-
-## Step 1: Ask everything at once
-
-Call the `question` tool with all five questions in a single batch (do not ask them one at a time). Use exactly these fields:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Type",
-      "question": "What type of project is this?",
-      "options": [
-        { "label": "brownfield", "description": "Existing codebase. Generate docs from your code." },
-        { "label": "greenfield", "description": "Starting from scratch, little or no existing code." }
-      ]
-    },
-    {
-      "header": "History",
-      "question": "Archive project history into OpenSpec?",
-      "options": [
-        { "label": "Yes", "description": "Scan codebase for existing docs, changelogs, decisions and archive them." },
-        { "label": "No", "description": "Skip history archival." }
-      ]
-    },
-    {
-      "header": "Architecture",
-      "question": "Generate ARCHITECTURE.md from the codebase?",
-      "options": [
-        { "label": "Yes", "description": "Analyze project structure and generate architecture documentation." },
-        { "label": "No", "description": "Skip, leave as placeholder." }
-      ]
-    },
-    {
-      "header": "Design",
-      "question": "Generate DESIGN.md from the design system?",
-      "options": [
-        { "label": "Yes", "description": "Analyze Tailwind, CSS vars, tokens and generate design documentation." },
-        { "label": "No", "description": "Skip, leave as placeholder." }
-      ]
-    },
-    {
-      "header": "Evidence",
-      "question": "Enable visual evidence capture for this project? (playwright-cli + pnpm run dev; no per-project scaffold needed)",
-      "options": [
-        { "label": "Yes", "description": "Evidence will be captured automatically by /plan-goal using playwright-cli + pnpm run dev." },
-        { "label": "No", "description": "Skip evidence capture." }
-      ]
-    }
-  ]
-}
-```
-
-## Step 2: Execute selected steps
-
-Based on the user's answers, run the selected steps in order:
-
-### Sync skills (always)
-
-Ensure all skills listed in `skills-lock.json` are installed. Run `npx skills experimental_install --yes` in the project root. This installs the core and selected optional skills queued by onboarding. If the command fails or is unavailable, warn the user but continue because optional skills can be installed manually later.
-
-### Archive project history (if Yes)
-
-Scan the codebase for existing documentation, changelogs, ADRs, README files, or notable history. Create an OpenSpec archive entry that captures this history.
-
-Before scanning, load source roots from `.opencode/source-roots.json` when present. Only scan those roots plus this repo's docs/config files.
-
-```bash
-openspec new change "project-history"
-```
-
-Write a `proposal.md` inside that change summarizing:
-- What this project is
-- Key decisions already made (inferred from code and docs)
-- Known tech debt or constraints visible in the codebase
-- Current state of the project
-
-Then archive it immediately (`-y` skips the confirmation prompt so this never blocks):
-
-```bash
-openspec archive "project-history" -y
-```
-
-### Generate ARCHITECTURE.md (if Yes)
-
-Load the `pc-make-architecture` skill now. Follow every step defined in it.
-
-### Generate DESIGN.md (if Yes)
-
-Load the `pc-make-design` skill now. Follow every step defined in it.
-
-### Generate guardrails (always)
-
-Load the `pc-make-guardrails` skill now. Follow every step defined in it.
-
-### Visual evidence (if Yes)
-
-Evidence is built into the `pc-ops-evidence` skill using `playwright-cli` + `pnpm run dev`. No scaffold is needed — it works out of the box as long as the project has a root `pnpm run dev` script that starts the full app stack with mock auth. Ensure `playwright-cli` is installed (handled by `opencode-ci.md` in CI).
-
-## Step 3: Show help
-
-Load the `pc-repo-help` skill and display the full command reference exactly as written.
-
-## Step 4: Confirm
-
-Tell the user:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Initialization complete.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Restart OpenCode now.
-Nothing will work correctly until you do.
-After restarting you are ready to work.
-```
-
-If the user answered Yes to Question 5 (Evidence), no post-init step is needed. Evidence works automatically via `pc-ops-evidence` using `playwright-cli` + `pnpm run dev`.
-
-## Init scope
-
-During init, write only to: ARCHITECTURE.md, DESIGN.md, AGENTS.md, openspec/, .agents/skills/. Read source files for analysis. Feature implementation, branches, PRs, and project source file modification are outside init's scope.
+---
+name: pc-repo-initialize
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps. Invoked by the /init command (alias: /repo-initialize).
+license: MIT
+---
+Check if `AGENTS.md` contains the `<!-- PC-NOT-INITIALIZED -->` marker.
+
+- If no: tell the user the project is already initialized. Suggest running `/make-architecture` or `/make-design` if they want to refresh those docs.
+- If yes: run the sequence below.
+
+## Step 1: Ask everything at once
+
+Call the `question` tool with all five questions in a single batch (do not ask them one at a time). Use exactly these fields:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Type",
+      "question": "What type of project is this?",
+      "options": [
+        { "label": "brownfield", "description": "Existing codebase. Generate docs from your code." },
+        { "label": "greenfield", "description": "Starting from scratch, little or no existing code." }
+      ]
+    },
+    {
+      "header": "History",
+      "question": "Archive project history into OpenSpec?",
+      "options": [
+        { "label": "Yes", "description": "Scan codebase for existing docs, changelogs, decisions and archive them." },
+        { "label": "No", "description": "Skip history archival." }
+      ]
+    },
+    {
+      "header": "Architecture",
+      "question": "Generate ARCHITECTURE.md from the codebase?",
+      "options": [
+        { "label": "Yes", "description": "Analyze project structure and generate architecture documentation." },
+        { "label": "No", "description": "Skip, leave as placeholder." }
+      ]
+    },
+    {
+      "header": "Design",
+      "question": "Generate DESIGN.md from the design system?",
+      "options": [
+        { "label": "Yes", "description": "Analyze Tailwind, CSS vars, tokens and generate design documentation." },
+        { "label": "No", "description": "Skip, leave as placeholder." }
+      ]
+    },
+    {
+      "header": "Evidence",
+      "question": "Enable visual evidence capture for this project? (playwright-cli + pnpm run dev; no per-project scaffold needed)",
+      "options": [
+        { "label": "Yes", "description": "Evidence will be captured automatically by /plan-goal using playwright-cli + pnpm run dev." },
+        { "label": "No", "description": "Skip evidence capture." }
+      ]
+    }
+  ]
+}
+```
+
+## Step 2: Execute selected steps
+
+Based on the user's answers, run the selected steps in order:
+
+### Sync skills (always)
+
+Ensure all skills listed in `skills-lock.json` are installed. Run `npx skills experimental_install --yes` in the project root. This installs the core and selected optional skills queued by onboarding. If the command fails or is unavailable, warn the user but continue because optional skills can be installed manually later.
+
+### Archive project history (if Yes)
+
+Scan the codebase for existing documentation, changelogs, ADRs, README files, or notable history. Create an OpenSpec archive entry that captures this history.
+
+Before scanning, load source roots from `.opencode/source-roots.json` when present. Only scan those roots plus this repo's docs/config files.
+
+```bash
+openspec new change "project-history"
+```
+
+Write a `proposal.md` inside that change summarizing:
+- What this project is
+- Key decisions already made (inferred from code and docs)
+- Known tech debt or constraints visible in the codebase
+- Current state of the project
+
+Then archive it immediately (`-y` skips the confirmation prompt so this never blocks):
+
+```bash
+openspec archive "project-history" -y
+```
+
+### Generate ARCHITECTURE.md (if Yes)
+
+Load the `pc-make-architecture` skill now. Follow every step defined in it.
+
+### Generate DESIGN.md (if Yes)
+
+Load the `pc-make-design` skill now. Follow every step defined in it.
+
+### Generate guardrails (always)
+
+Load the `pc-make-guardrails` skill now. Follow every step defined in it.
+
+### Visual evidence (if Yes)
+
+Evidence is built into the `pc-ops-evidence` skill using `playwright-cli` + `pnpm run dev`. No scaffold is needed — it works out of the box as long as the project has a root `pnpm run dev` script that starts the full app stack with mock auth. Ensure `playwright-cli` is installed (handled by `opencode-ci.md` in CI).
+
+## Step 3: Show help
+
+Load the `pc-repo-help` skill and display the full command reference exactly as written.
+
+## Step 4: Confirm
+
+Tell the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Initialization complete.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Restart OpenCode now.
+Nothing will work correctly until you do.
+After restarting you are ready to work.
+```
+
+If the user answered Yes to Question 5 (Evidence), no post-init step is needed. Evidence works automatically via `pc-ops-evidence` using `playwright-cli` + `pnpm run dev`.
+
+## Init scope
+
+During init, write only to: ARCHITECTURE.md, DESIGN.md, AGENTS.md, openspec/, .agents/skills/. Read source files for analysis. Feature implementation, branches, PRs, and project source file modification are outside init's scope.

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

@@ -1,87 +1,87 @@
----
-name: pc-repo-onboard
-description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system. Invoked by the /repo-onboard command.
-license: MIT
----
-
-This command is a guided tour. Read and explain only.
-
-## Step 1: Project overview
-
-Read `AGENTS.md`, `ARCHITECTURE.md`, and `DESIGN.md`. Summarize:
-
-- What this project is (name, purpose, domain)
-- Tech stack (languages, frameworks, build system)
-- Project structure (key directories and what they contain)
-
-Keep it to 3 to 5 bullet points. Focus on what a new contributor needs to know.
-
-## Step 2: Agent infrastructure
-
-Inspect `.opencode/agents/` and list every agent file. For each agent, read its frontmatter and summarize:
-
-- Agent name and role (primary, subagent, or specialist)
-- Model tier it uses (plan, build, or fast)
-- Key abilities: what it can do
-
-Present as a table:
-
-| Agent | Role | Tier | Purpose |
-|---|---|---|---|
-| ... | ... | ... | ... |
-
-Then explain the agent selection model:
-- Primary agents appear in Tab and handle direct user interaction
-- Subagent engineers are spawned by the lead for parallel implementation waves
-- Specialist engineers are preferred when their domain matches the task; `fullstack-engineer` is the user's planning agent (`mode: primary`), not a spawned worker. If no specialist matches, create one with `/make-engineer`.
-
-## Step 3: Command reference
-
-Read every `.md` file in `.opencode/commands/`. List each command with its name and description:
-
-| Command | What it does |
-|---|---|
-| ... | ... |
-
-Group them by workflow phase if possible:
-- Planning: plan-explore, plan-story, plan-propose, plan-quick, plan-goal
-- Implementation: plan-apply, plan-archive
-- Maintenance: make-architecture, make-design, make-engineer, make-guardrails, make-evidence-scaffold
-- Shipping: ops-ship, ops-review, ops-backlog, ops-evidence
-- Quality: repo-audit, repo-verify
-- Setup: init, make-user-model, repo-help
-
-## Step 4: Skills
-
-Inspect `.agents/skills/` (if present). List installed skills with a one-line description each. Note which are platform-specific (userstory, pullrequest) vs general-purpose, and identify `pc-repo-audit` as read-only and `pc-repo-verify` as the current-branch verification gate.
-
-## Step 5: OpenSpec workflow
-
-Explain the OpenSpec change lifecycle:
-
-1. Explore (`/plan-explore`): investigate and discuss, no files created
-2. Propose (`/plan-propose`): structured plan, saved to `openspec/changes/`
-3. Apply (`/plan-apply`): implement tasks via parallel subagent waves
-4. Archive (`/plan-archive`): finalize and clean up
-
-Explain `openspec/config.yaml`: what it contains and why it matters.
-
-## Step 6: Configuration
-
-Explain `harness.json`:
-- What each field controls (platform, models, agents, tools, source)
-- How to change the model for a tier (`/make-user-model`)
-- What `agents.maxConcurrent` does
-
-## Step 7: Quick tips
-
-End with 3 to 5 practical tips:
-
-- How to start working: "Run `/plan-goal` with a description of what you want to build"
-- How to add a specialist: "Run `/make-engineer`"
-- How to regenerate docs: "Run `/make-architecture` or `/make-design`"
-- How to audit the whole repository: "Run `/repo-audit`"
-- How to verify an active branch: "Run `/repo-verify`"
-- How to set up visual evidence: "Run `/make-evidence-scaffold` (UI projects) so `/plan-goal` can prove changes with screenshots"
-- How to see all commands: "Run `/repo-help`"
-- How to refresh config after changes: "Re-run `npx @plainconceptsplatform/agent-harness` in the terminal"
+---
+name: pc-repo-onboard
+description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system. Invoked by the /repo-onboard command.
+license: MIT
+---
+
+This command is a guided tour. Read and explain only.
+
+## Step 1: Project overview
+
+Read `AGENTS.md`, `ARCHITECTURE.md`, and `DESIGN.md`. Summarize:
+
+- What this project is (name, purpose, domain)
+- Tech stack (languages, frameworks, build system)
+- Project structure (key directories and what they contain)
+
+Keep it to 3 to 5 bullet points. Focus on what a new contributor needs to know.
+
+## Step 2: Agent infrastructure
+
+Inspect `.opencode/agents/` and list every agent file. For each agent, read its frontmatter and summarize:
+
+- Agent name and role (primary, subagent, or specialist)
+- Model tier it uses (plan, build, or fast)
+- Key abilities: what it can do
+
+Present as a table:
+
+| Agent | Role | Tier | Purpose |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
+Then explain the agent selection model:
+- Primary agents appear in Tab and handle direct user interaction
+- Subagent engineers are spawned by the lead for parallel implementation waves
+- Specialist engineers are preferred when their domain matches the task. `build` and `plan` are the only agents the user selects, and both run the `fullstack-engineer` body; `plan` cannot edit files. Everything else is `mode: subagent` and spawned. If no specialist matches, create one with `/make-engineer`.
+
+## Step 3: Command reference
+
+Read every `.md` file in `.opencode/commands/`. List each command with its name and description:
+
+| Command | What it does |
+|---|---|
+| ... | ... |
+
+Group them by workflow phase if possible:
+- Planning: plan-explore, plan-story, plan-propose, plan-quick, plan-goal
+- Implementation: plan-apply, plan-archive
+- Maintenance: make-architecture, make-design, make-engineer, make-guardrails, make-evidence-scaffold
+- Shipping: ops-ship, ops-review, ops-backlog, ops-evidence
+- Quality: repo-audit, repo-verify
+- Setup: init, make-user-model, repo-help
+
+## Step 4: Skills
+
+Inspect `.agents/skills/` (if present). List installed skills with a one-line description each. Note which are platform-specific (userstory, pullrequest) vs general-purpose, and identify `pc-repo-audit` as read-only and `pc-repo-verify` as the current-branch verification gate.
+
+## Step 5: OpenSpec workflow
+
+Explain the OpenSpec change lifecycle:
+
+1. Explore (`/plan-explore`): investigate and discuss, no files created
+2. Propose (`/plan-propose`): structured plan, saved to `openspec/changes/`
+3. Apply (`/plan-apply`): implement tasks via parallel subagent waves
+4. Archive (`/plan-archive`): finalize and clean up
+
+Explain `openspec/config.yaml`: what it contains and why it matters.
+
+## Step 6: Configuration
+
+Explain `harness.json`:
+- What each field controls (platform, models, agents, tools, source)
+- How to change the model for a tier (`/make-user-model`)
+- What `agents.maxConcurrent` does
+
+## Step 7: Quick tips
+
+End with 3 to 5 practical tips:
+
+- How to start working: "Run `/plan-goal` with a description of what you want to build"
+- How to add a specialist: "Run `/make-engineer`"
+- How to regenerate docs: "Run `/make-architecture` or `/make-design`"
+- How to audit the whole repository: "Run `/repo-audit`"
+- How to verify an active branch: "Run `/repo-verify`"
+- How to set up visual evidence: "Run `/make-evidence-scaffold` (UI projects) so `/plan-goal` can prove changes with screenshots"
+- How to see all commands: "Run `/repo-help`"
+- How to refresh config after changes: "Re-run `npx @plainconceptsplatform/agent-harness` in the terminal"

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

@@ -1,34 +1,34 @@
----
-name: pc-repo-verify
-description: Verify and repair current-branch changes using applicable fullstack engineer abilities, project checks, and dependency rules. Invoked by /repo-verify and the plan-goal pipeline.
-license: MIT
----
-
-# Repo Verify
-
-Verify the current branch before it is archived, shipped, or handed to an external automation gate. Work only on the current branch: do not switch branches, push, create pull requests or backlog items, or contact external platforms.
-
-## Step 1: Load verification rules
-
-1. Read `.opencode/agents/fullstack-engineer.md`.
-2. Parse every `@skill-name` in its `## Abilities` section.
-3. Load every listed skill, guardrails first. A missing referenced skill is a verification failure; report it and do not claim `VERIFIED`.
-
-## Step 2: Determine changed scope
-
-1. Read `.opencode/source-roots.json` when it exists. Use its non-empty `roots` array; otherwise use the repository root.
-2. Inspect `git diff` against the branch base and the working tree. Map every changed path to a configured root and discovered project.
-3. Discover every project in every configured source root. Read each project's manifest, scripts, test configuration, CI configuration, and applicable guardrail instructions.
-4. Build a check matrix. Include every discovered project's repository-defined immutable dependency install or restore command, build command, and test command, even when that project is untouched. Add changed-scope lint, typecheck, migration, generated-artifact, documentation, evidence, and required repository-wide checks from loaded guardrails.
-
-## Step 3: Verify and repair
-
-Run every discovered project's repository-defined immutable dependency install or restore command, build command, and test command. Run the changed-scope lint, typecheck, migration, generated-artifact, documentation, and evidence checks. A project without one of those commands is the only allowed skip, and the report must name the missing command.
-
-When a dependency manifest changes, require its ecosystem lockfile to change when the package manager uses one. The dependency install or restore command must validate that lockfile without mutating it.
-
-When a check fails, repair only the current branch's relevant files and rerun the failed check. Continue until every applicable check passes or a hard blocker prevents progress. Never hide a failure by deleting tests, weakening checks, or reverting requested work.
-
-## Step 4: Result
-
-Report a check matrix with command, affected project, result, and skip reason where applicable. Report `VERIFIED` only when every applicable check passed, every dependency change has consistent lockfiles, and no required ability is missing. Otherwise report `NOT VERIFIED`, the blockers, and the exact next command.
+---
+name: pc-repo-verify
+description: Verify and repair current-branch changes using applicable fullstack engineer abilities, project checks, and dependency rules. Invoked by /repo-verify and the plan-goal pipeline.
+license: MIT
+---
+
+# Repo Verify
+
+Verify the current branch before it is archived, shipped, or handed to an external automation gate. Work only on the current branch: do not switch branches, push, create pull requests or backlog items, or contact external platforms.
+
+## Step 1: Load verification rules
+
+1. Read `.opencode/agents/fullstack-engineer.md`.
+2. Parse every `@skill-name` in its `## Abilities` section.
+3. Load every listed skill, guardrails first. A missing referenced skill is a verification failure; report it and do not claim `VERIFIED`.
+
+## Step 2: Determine changed scope
+
+1. Read `.opencode/source-roots.json` when it exists. Use its non-empty `roots` array; otherwise use the repository root.
+2. Inspect `git diff` against the branch base and the working tree. Map every changed path to a configured root and discovered project.
+3. Discover every project in every configured source root. Read each project's manifest, scripts, test configuration, CI configuration, and applicable guardrail instructions.
+4. Build a check matrix. Include every discovered project's repository-defined immutable dependency install or restore command, build command, and test command, even when that project is untouched. Add changed-scope lint, typecheck, migration, generated-artifact, documentation, evidence, and required repository-wide checks from loaded guardrails.
+
+## Step 3: Verify and repair
+
+Run every discovered project's repository-defined immutable dependency install or restore command, build command, and test command. Run the changed-scope lint, typecheck, migration, generated-artifact, documentation, and evidence checks. A project without one of those commands is the only allowed skip, and the report must name the missing command.
+
+When a dependency manifest changes, require its ecosystem lockfile to change when the package manager uses one. The dependency install or restore command must validate that lockfile without mutating it.
+
+When a check fails, repair only the current branch's relevant files and rerun the failed check. Continue until every applicable check passes or a hard blocker prevents progress. Never hide a failure by deleting tests, weakening checks, or reverting requested work.
+
+## Step 4: Result
+
+Report a check matrix with command, affected project, result, and skip reason where applicable. Report `VERIFIED` only when every applicable check passed, every dependency change has consistent lockfiles, and no required ability is missing. Otherwise report `NOT VERIFIED`, the blockers, and the exact next command.