@plainconceptsplatform/agent-harness 2.7.0 → 3.0.1

package/harness/opencode.jsonc

@@ -1,47 +1,36 @@
 {
   "$schema": "https://opencode.ai/config.json",
-  "instructions": [
-    "AGENTS.md"
-  ],
-  "plugin": [
-    "@mohak34/opencode-notifier@0.2.8"
-  ],
   "mcp": {
-    "agent-browser": {
-      "type": "local",
-      "command": ["agent-browser", "mcp", "--tools", "core"],
-      "enabled": true
+    "servers": {
+      "agent-browser": {
+        "type": "local",
+        "command": ["agent-browser", "mcp", "--tools", "core"],
+        "disabled": false
+      }
+    },
+    "timeout": {
+      "catalog": 300000,
+      "execution": 300000
     }
   },
-  "experimental": {
-    "mcp_timeout": 300000
-  },
   "compaction": {
     "auto": true,
-    "prune": true,
-    "reserved": 10000
+    "buffer": 10000
   },
-  "permission": {
-    "question": "allow",
-    "todowrite": "allow",
-    "skill": "allow"
-  },
-  "skills": {
-    "paths": [".agents/skills"]
-  },
-  // build and plan are the only primaries, and plan is the default: a session
-  // starts read-only and you switch to build once you know what to change.
-  // The pc-subagent-tiers plugin
-  // regenerates .opencode/agents/{build,plan}.md from fullstack-engineer.md on
-  // every startup and overrides these two entries with the resolved tier model,
-  // so what is here is only the floor if the plugin cannot run. Every engineer
-  // is mode: subagent and reached through task(), never picked by a human.
+  "permissions": [
+    { "action": "question", "resource": "*", "effect": "allow" },
+    { "action": "skill", "resource": "*", "effect": "allow" }
+  ],
+  "skills": [".agents/skills"],
   "default_agent": "plan",
-  "agent": {
+  "agents": {
     "build": { "mode": "primary" },
     "plan": {
       "mode": "primary",
-      "permission": { "edit": "deny", "task": "deny" }
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "2.7.0",
+  "version": "3.0.1",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",
@@ -29,8 +29,10 @@
   "files": [
     "cli",
     "harness",
+    "skills",
     "!cli/**/*.test.js",
     "!harness/**/*.test.js",
+    "!skills/**/*.test.js",
     "!harness/**/node_modules"
   ],
   "publishConfig": {

package/skills/README.md

@@ -0,0 +1,18 @@
+# skills/
+
+Two kinds of skills live here, both discoverable by `npx skills`:
+
+| Kind | Directories | Purpose |
+| --- | --- | --- |
+| Installable `pc-*` + `browser-automation` | `pc-*`, `browser-automation` | What the CLI copies into a target project under `.agents/skills/` during onboarding. Plain Concepts' own skills. |
+| CLI-self | `agent-harness-cli` | Skills for agents working on THIS CLI repo (driving `npx @plainconceptsplatform/agent-harness`). Never copied into target projects. |
+
+Discoverability: any `SKILL.md` in a subdirectory here is auto-discovered by OpenCode, Claude Code, and `npx skills` (which scans `./skills/` as a recognized project-skill location).
+
+## Using one
+
+Point your agent at the directory, or copy a skill into wherever your tool discovers skills:
+
+```bash
+cp -r skills/agent-harness-cli ~/.claude/skills/
+```

package/skills/agent-harness-cli/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: agent-harness-cli
+description: Drive the agent-harness CLI - install the Plain Concepts Platform Harness into a repository, bring an existing one up to date, set up a teammate's machine, or rerun a single step. Load when asked to install, update, or repair the Platform Harness, when a repo needs AI/agent scaffolding set up, or when a command like `npx @plainconceptsplatform/agent-harness` fails and needs diagnosing.
+license: MIT
+---
+
+# agent-harness CLI
+
+`agent-harness` installs the **Plain Concepts Platform Harness** into a repository and keeps it up to date. The harness is Plain Concepts' own, and it is the set of files agents work from: slash commands, `pc-*` skills (the `pc-` is Plain Concepts), an agent team, OpenCode plugins, an OpenSpec workspace, and generated `ARCHITECTURE.md` and `DESIGN.md`.
+
+Everything runs against the **current working directory**. `cd` into the target repository first; there is no `--path` flag.
+
+## Pick the right verb
+
+Read the repo before running anything. `.opencode/harness.json` is the marker for "harness already installed".
+
+| Situation | Command |
+| --- | --- |
+| No `.opencode/harness.json` | `npx @plainconceptsplatform/agent-harness@latest` (the install wizard) |
+| Harness present, want the latest release's files | `npx @plainconceptsplatform/agent-harness@latest update` |
+| Harness present, new machine or new teammate | `npx @plainconceptsplatform/agent-harness join` |
+| One specific thing needs redoing | a single step command, see below |
+
+Requires Node.js 18+.
+
+## The install wizard is interactive
+
+The wizard asks about source scope, backlog and repository platform, three models, and optional token-optimization tools. **Do not run it in a non-interactive shell.** It will hang or abort. If you cannot present prompts to a human, say so and hand the command to the user rather than trying to drive it.
+
+Everything else (`update`, and the single-step commands other than `platform`, `models`, `optimization`) runs without prompts.
+
+## Single-step commands
+
+Run one step without the full wizard. Each reuses context from `.opencode/harness.json` when it needs to.
+
+```
+clean           Remove pre-existing AI files (AGENTS.md, .cursorrules, CLAUDE.md, ...)
+platform        Choose backlog + repository platform
+copy            Copy agents, skills, commands, docs into the repo
+openspec        Initialize the OpenSpec workspace
+models          Choose plan / build / fast models
+optimization    Configure RTK, quota, Simple English, codegraph, agentmemory, humanizer
+browser         Install agent-browser (npm package + its Chrome for Testing)
+metadata        Rewrite .opencode/harness.json
+```
+
+`metadata` last if you ran several, because it refreshes the config the others read.
+
+## What lands in the repo
+
+```
+.opencode/
+  harness.json            harness config: platform, models, agents.maxConcurrent
+  harness-managed.json    hash per managed file, so update spares your edits
+  harness.user.json       per-developer model override (gitignored)
+  harness-run.json        live subagent wave state (gitignored)
+  commands/               slash commands
+  plugins/                pc-subagent-monitor, pc-subagent-tiers, pc-system-reminders
+  agents/                 fullstack-engineer + user-created *-engineer files
+.agents/skills/           pc-* skills
+AGENTS.md ARCHITECTURE.md DESIGN.md
+```
+
+After a fresh install, the next move is `/repo-initialize` inside OpenCode. That is what generates real `ARCHITECTURE.md` and `DESIGN.md` and activates the agent team. Installing the harness alone does not do it.
+
+## `update` is edit-safe
+
+`update` compares each managed file against the hash recorded in `.opencode/harness-managed.json`. Files you changed by hand are left alone and reported as preserved. Generated skills (`pc-guardrails-project`, `pc-merge-risk-assess`) are never overwritten once populated. So `update` is safe to run repeatedly, and a second consecutive run should report no changes.
+
+## Diagnosing failures
+
+**"This project was set up by opencode-onboard v1".** The repo has v1 state files or `ob-*` skills. v2 renamed both and does not migrate. Re-onboard on a clean branch; do not try to rename the files by hand, because the marker comments inside the installed skills changed too.
+
+**"No config found. Run the wizard first."** `update` or a step needs `.opencode/harness.json` and it is absent. Run the wizard.
+
+**A platform step reports nothing and changes nothing.** Platform content is injected into `<!-- PC-PLATFORM-*-START/END -->` marker pairs. If a marker pair is missing from the target file, injection is skipped silently. Check the markers exist before concluding the step worked.
+
+**Skills missing after install.** Skill installation ends with `npx skills experimental_install --yes`, run once at the end of the optimization step. If it failed, rerun it directly in the repo.
+
+**Platform CLI warnings.** The harness expects `gh` (GitHub), `az` + azure-devops extension (Azure DevOps), `acli` (Jira), `glab` (GitLab), each authenticated. These are warnings, not fatal; the harness installs, but the matching `/ops-*` flows will not work until the CLI is present.
+
+## Rules
+
+- Never edit `.opencode/harness.json` by hand to change models. Use `/make-user-model <tier> <model>` inside OpenCode, or the `models` step.
+- Never commit `harness.user.json` or `harness-run.json`. Both belong in `.opencode/.gitignore`, which `join` verifies.
+- `clean` deletes files. Confirm with the user before running it on a repo that already has AI configuration worth keeping.

package/skills/pc-guardrails-generic/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: pc-guardrails-generic
+description: Generic guardrails, foundational rules that all agents follow. Users add specialized guardrails skills for specific concerns. Covers secrets, code quality, security, tool usage, and engineer workflow.
+license: MIT
+---
+
+## Transitive loads (optimization skills)
+
+The marker sections below name the optimization skills this project selected. Load each before doing any work.
+
+## Secrets
+
+- Treat `.env` files as write-only: write to them when configuring, read credentials at runtime from the environment or secret store.
+- Never put a credential, API key, or token in a log line, output, or commit in anything but encrypted or template form.
+
+## Code
+
+- The default is zero comments. Add one only where the code is genuinely non-obvious. Past 10% comment-to-code ratio, refactor for clarity. Never add comments that restate the code, label variables, TODOs without a linked issue, commented-out code, separator banners, or auto-generated docstrings/JSDoc/XML docs unless explicitly asked.
+- Never add a file that collects unrelated things — `constants.js`, `types.ts`, `utils.ts`. One responsibility per file, split by domain. A file importing from many unrelated modules is already the symptom.
+
+## Temporary files
+
+- Never write outside `$REPO_ROOT` or an OS temp directory: the next agent cannot see it and nobody cleans it up. Scratch goes under `$REPO_ROOT/.opencode/.tmp/` (enforced by pc-system-reminders).
+- Never report a `.tmp/` path as a deliverable. Copy or move the artifact to its repository path first. Never leave scratch files behind unless they are evidence for a failure you are reporting.
+
+## Tests
+
+- Never write more tests than the change requires. A bug fix gets one regression test. A new function gets tests for its public contract, not every internal branch. Never aim for a coverage number.
+- Never test framework or library internals. Test your code's contract, not that EF Core saves a tracked entity.
+- Never generate integration, e2e, or snapshot tests unless explicitly asked. Mock nothing you do not own — use a fake that records state. Never add a test that duplicates a type-check or linter rule.
+
+<!-- PC-GUARDRAILS-RTK-START -->
+<!-- PC-GUARDRAILS-RTK-END -->
+
+<!-- PC-GUARDRAILS-CODEGRAPH-START -->
+<!-- PC-GUARDRAILS-CODEGRAPH-END -->
+
+<!-- PC-GUARDRAILS-MEMORY-START -->
+<!-- PC-GUARDRAILS-MEMORY-END -->
+
+<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->
+<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->
+
+<!-- PC-GUARDRAILS-HUMANIZER-START -->
+<!-- PC-GUARDRAILS-HUMANIZER-END -->
+
+## Engineer workflow (when spawned)
+
+The lead puts your task IDs and their text in your prompt. Two things about that are not up to you:
+
+- Load every skill under your `## Abilities` before you start, guardrails first, one `skill` call per `@skill-name`. Editing, shell and spawning are blocked until you have (pc-system-reminders).
+- Edit only files in your assigned scope, then return: task IDs done, files changed, tests and lint result, decisions made. Then exit. Never poll for more work or claim a task the lead did not give you.

package/{harness/.agents/skills → skills}/pc-make-architecture/SKILL.md

@@ -13,6 +13,7 @@ Write `ARCHITECTURE.md` in the project root from what the codebase actually cont
 - Never regenerate over a file that carries a `<!-- Last updated:` footer. That footer is what makes the next run incremental, and a full rewrite silently drops whatever a human added by hand. Read the file first and pick the mode.
 - Never analyze outside `.opencode/source-roots.json` when it exists, plus this repo's own docs and config.
 - The footer is the file's last line, and it is the run's own ISO timestamp: `<!-- Last updated: <ISO date> -->`.
+- Follow the writing rules and self-check defined in the [structure template](structure-template.md). After generating, re-read each section: if a section only describes what exists without stating what breaks when its constraints are violated, rewrite it as constraint-embedded prose or cut it. The file is not written until the self-check passes.
 
 ## Modes
 

package/skills/pc-make-architecture/structure-template.md

@@ -0,0 +1,64 @@
+# ARCHITECTURE.md structure template
+
+Write (or update) `ARCHITECTURE.md` following this structure. Only include sections relevant to the project; omit sections with no evidence.
+
+- Architecture Overview: what the system is, what problem it solves, major architectural style
+- 1. Project Structure: annotated directory tree with purpose of each major directory
+- 2. High-Level System Diagram: Mermaid diagram of actors, services, data stores, external systems
+- 3. Core Components: each major component: name, responsibility, key files, technologies, inputs/outputs
+  - 3.1 Frontend / User Interface (if present)
+  - 3.2 Backend / Server / API (if present)
+  - 3.3 Shared Libraries / Common Code (if present)
+  - 3.4 CLI / Scripts / Automation (if present)
+- 4. Data Flow: request lifecycle, key user journeys, sequence diagram for main runtime flow
+- 5. Data Stores: all persistent storage: type, purpose, schemas, migration approach
+- 6. External Integrations / APIs: each integration: method, config location, auth, failure behavior
+- 7. Key Technologies: full stack summary with architectural relevance of each
+- 8. Deployment & Infrastructure: build artifacts, env config, containerization, CI/CD, hosting
+- 9. Security Architecture: auth, authz, secrets, input validation, trust boundaries
+- 10. Monitoring & Observability: logging, metrics, tracing, error reporting
+- 11. Performance & Scalability: caching, batching, concurrency, known bottlenecks
+- 12. Development Workflow: local setup, install/dev/test/build/lint commands
+- 13. Testing Strategy: test frameworks, locations, coverage gates, gaps
+- 14. Architectural Decisions & Rationale: key choices with evidence and tradeoffs
+- 15. Constraints, Risks, and Technical Debt: tight coupling, TODOs, operational risks
+- 16. Future Considerations: documented roadmap + reasonable recommendations (labeled as such)
+- 17. Project Identification: name, language, type, runtime, date of review, maintainer
+- 18. Glossary / Acronyms: project-specific terms an agent or new developer needs to know
+
+Append at the very end of the file:
+```
+<!-- Last updated: <current ISO timestamp> -->
+```
+
+Rules:
+- Be specific and concrete: include actual directories, files, modules, commands.
+- Mark anything undiscoverable as "Not evident from the repository".
+- Use Mermaid diagrams where helpful.
+- Write as if this document will be committed and maintained over time.
+
+## Writing rules
+
+These rules govern the voice and shape of every section. The ARCHITECTURE.md is the primary artifact an agent reads to understand the system's invariants — it must teach constraints, not just inventory structure. These are enforced by re-reading each section after generation (see the self-check in the skill).
+
+1. **Every section must answer "what breaks if this is violated," not just "what exists."** A section that only describes structure without stating the constraint it protects and the consequence of crossing it is reference material, not architecture. "The system has four modules" is structure; "Modules must not cross-reference each other in Domain or Application, and flow goes through port interfaces or domain events" is a constraint.
+
+2. **Architectural decisions must carry their rationale and what they superseded.** A decision table row that says "Adopt X" is a fact; "Adopt X because Y, supersedes decision Z which assumed W" is a constraint that teaches an agent why a change would be wrong. If a decision was reached after rejecting an alternative, name the alternative and why it was rejected.
+
+3. **State boundaries as prohibitions with consequences.** "Layering is enforced: Api → Application → Domain" is a constraint. "Api → Application → Domain" alone is a dependency list. "Only the Composition namespace in Api reaches Infrastructure" is a constraint; "Api depends on Infrastructure" is a fact. Prefer the constraint form: name the boundary, state who must not cross it, and what breaks when it is crossed.
+
+4. **Include what was tried and rejected, not just what was chosen.** The most valuable architecture decisions are the ones where an alternative was tested and found wanting. A section that says "dynamic sessions were rejected because they accept no volumes, cost more at scale, and are blocked by policy" teaches an agent more than "the engine runs as a container app."
+
+5. **Narrative over inventory.** Describe how the system behaves, what holds it together, and where the seams are. A reader who understands the constraints can infer the structure; a reader who only sees the structure cannot infer the constraints.
+
+## Self-check (before writing the file)
+
+Re-read every section you are about to write. Then:
+
+1. **Identify inventory-only sections.** If a section describes what exists without stating what breaks when its constraints are violated, rewrite it as constraint-embedded prose or cut it.
+
+2. **Check decision rows.** Every row in the decisions table must carry its rationale. If a decision has no "why," it is a fact, not a decision — cut it or find the rationale.
+
+3. **Scan for bare dependency lists.** "Api depends on Application depends on Domain" is a fact. Rewrite it as: name the boundary, state who must not cross it, and what breaks when it is crossed.
+
+4. **Verify rejected alternatives are present where they matter.** If a significant architectural choice was made, the rejected alternative and the reason for rejection should be in the document. An agent that does not know what was rejected will propose it again.

package/{harness/.agents/skills → skills}/pc-make-engineer/SKILL.md

@@ -1,59 +1,59 @@
----
-name: pc-make-engineer
-description: Create a custom engineer agent via persona-driven interactive design. Invoked by the /make-engineer command.
-license: MIT
----
-
-Create one file, `.opencode/agents/{persona}-engineer.md`, from the [template](template.md). The research behind it is for choosing the right skills, not for filling the file: expertise notes, architecture, conventions, file maps and workflow steps belong in skills.
-
-## Rules
-
-- Never write the agent file before the user has confirmed the skill set and it is installed. An engineer whose abilities do not exist cannot work.
-- Never write `model:` or `color:`. `pc-subagent-tiers` injects both at startup, so a hand-picked colour is overwritten.
-- Never create `*.build.md`, `*.fast.md`, `*.plan.md`, `build.md` or `plan.md`. The plugin regenerates all of them every startup and anything written there is lost.
-- `mode: subagent`. Engineers are reached through `task()`, and a primary would clutter the two-entry list a human picks from.
-- The only `##` heading is `## Abilities`, and the identity paragraph is two or three sentences carrying no project knowledge.
-- Every `@skill` under `## Abilities` exists in `.agents/skills/` and in `skills-lock.json`. A name that is not installed is skipped rather than blocking the worker, so a typo costs the agent that ability in silence.
-- Project-local installs only: `npx skills add -y ...`, never `-g`.
-- At most five form questions, and only where more than one option was detected. A signal with one option is used without asking.
-
-## Contracts
-
-Personas: `frontend`, `layout`, `backend`, `data`, `devops`, `security`, `mobile`, `api`, `qa`. A persona passed as an argument (`/make-engineer frontend`) or typed by the user is taken as given.
-
-Signals to detect: language, framework, data layer, testing, styling, architecture, i18n, CI/CD, cloud and IaC, monitoring, linting, dependency injection.
-
-Discovery needs `find-skills`, and has no fallback without it:
-
-```bash
-npx skills add -y vercel-labs/skills@find-skills
-```
-
-When `.opencode/agents/{persona}-engineer.md` already exists, ask before touching it:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Overwrite engineer",
-      "question": "An engineer named \"{persona}-engineer\" already exists. Overwrite or cancel?",
-      "options": [
-        { "label": "Overwrite", "description": "Rewrite the file from the template." },
-        { "label": "Cancel", "description": "Stop. Do not modify the existing file." }
-      ]
-    }
-  ]
-}
-```
-
-`fullstack-engineer.md` is the body `pc-subagent-tiers` copies into `build.md` and `plan.md`, so every skill listed there reaches both primaries. Merge into it additively: add only skills it does not already list, put them in the category lines that already exist where they fit, and leave its frontmatter, identity paragraph and existing ability lines alone.
-
-## Flow
-
-1. **Persona.** Ask with the `question` tool unless it arrived as an argument. The answer decides what to detect, what to ask, and which skills to look for.
-2. **Signals.** Read `.opencode/source-roots.json` (if it is missing or empty, ask which directories to scan), then `ARCHITECTURE.md`, `DESIGN.md`, and the manifests (`package.json`, `tsconfig.json`, `*.csproj`, `pyproject.toml`, `go.mod`, `Cargo.toml`). Detect what the persona needs and report the inventory.
-3. **Form.** Present the detected options with the `question` tool, pre-selected and marked `(Recommended)`. For `frontend`, `backend`, `layout` and `api`, one question is architecture and patterns, whose options come from the [signal mapping](signal-mapping.md) tables.
-4. **Skills.** A signal already covered by a skill in `.agents/skills/` or `skills-lock.json` needs no search. Map each remaining signal to a query through the [signal mapping](signal-mapping.md), present the candidates as one multi-select `question` grouped by category (name, one line, `owner/repo`, install count), install what the user confirms, and verify each one landed in both `.agents/skills/` and the lockfile.
-5. **Write** the file from the [template](template.md).
-6. **Merge** the new skills into `fullstack-engineer.md`.
-7. **Report** the file created, the skills installed, the signals with no quality skill, whatever failed, and that opencode has to restart before `pc-subagent-tiers` picks the engineer up.
+---
+name: pc-make-engineer
+description: Create a custom engineer agent via persona-driven interactive design. Invoked by the /make-engineer command.
+license: MIT
+---
+
+Create one file, `.opencode/agents/{persona}-engineer.md`, from the [template](template.md). The research behind it is for choosing the right skills, not for filling the file: expertise notes, architecture, conventions, file maps and workflow steps belong in skills.
+
+## Rules
+
+- Never write the agent file before the user has confirmed the skill set and it is installed. An engineer whose abilities do not exist cannot work.
+- Never write `model:` or `color:`. `pc-subagent-tiers` injects both at startup, so a hand-picked colour is overwritten.
+- Never create `*.build.md`, `*.fast.md`, `*.plan.md`, `build.md` or `plan.md`. The plugin regenerates all of them every startup and anything written there is lost.
+- `mode: subagent`. Engineers are reached through the subagent tool, and a primary would clutter the two-entry list a human picks from.
+- The only `##` heading is `## Abilities`, and the identity paragraph is two or three sentences carrying no project knowledge.
+- Every `@skill` under `## Abilities` exists in `.agents/skills/` and in `skills-lock.json`. A name that is not installed is skipped rather than blocking the worker, so a typo costs the agent that ability in silence.
+- Project-local installs only: `npx skills add -y ...`, never `-g`.
+- At most five form questions, and only where more than one option was detected. A signal with one option is used without asking.
+
+## Contracts
+
+Personas: `frontend`, `layout`, `backend`, `data`, `devops`, `security`, `mobile`, `api`, `qa`. A persona passed as an argument (`/make-engineer frontend`) or typed by the user is taken as given.
+
+Signals to detect: language, framework, data layer, testing, styling, architecture, i18n, CI/CD, cloud and IaC, monitoring, linting, dependency injection.
+
+Discovery needs `find-skills`, and has no fallback without it:
+
+```bash
+npx skills add -y vercel-labs/skills@find-skills
+```
+
+When `.opencode/agents/{persona}-engineer.md` already exists, ask before touching it:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Overwrite engineer",
+      "question": "An engineer named \"{persona}-engineer\" already exists. Overwrite or cancel?",
+      "options": [
+        { "label": "Overwrite", "description": "Rewrite the file from the template." },
+        { "label": "Cancel", "description": "Stop. Do not modify the existing file." }
+      ]
+    }
+  ]
+}
+```
+
+`fullstack-engineer.md` is the body `pc-subagent-tiers` copies into `build.md` and `plan.md`, so every skill listed there reaches both primaries. Merge into it additively: add only skills it does not already list, put them in the category lines that already exist where they fit, and leave its frontmatter, identity paragraph and existing ability lines alone.
+
+## Flow
+
+1. **Persona.** Ask with the `question` tool unless it arrived as an argument. The answer decides what to detect, what to ask, and which skills to look for.
+2. **Signals.** Read `.opencode/source-roots.json` (if it is missing or empty, ask which directories to scan), then `ARCHITECTURE.md`, `DESIGN.md`, and the manifests (`package.json`, `tsconfig.json`, `*.csproj`, `pyproject.toml`, `go.mod`, `Cargo.toml`). Detect what the persona needs and report the inventory.
+3. **Form.** Present the detected options with the `question` tool, pre-selected and marked `(Recommended)`. For `frontend`, `backend`, `layout` and `api`, one question is architecture and patterns, whose options come from the [signal mapping](signal-mapping.md) tables.
+4. **Skills.** A signal already covered by a skill in `.agents/skills/` or `skills-lock.json` needs no search. Map each remaining signal to a query through the [signal mapping](signal-mapping.md), present the candidates as one multi-select `question` grouped by category (name, one line, `owner/repo`, install count), install what the user confirms, and verify each one landed in both `.agents/skills/` and the lockfile.
+5. **Write** the file from the [template](template.md).
+6. **Merge** the new skills into `fullstack-engineer.md`.
+7. **Report** the file created, the skills installed, the signals with no quality skill, whatever failed, and that opencode has to restart before `pc-subagent-tiers` picks the engineer up.

package/{harness/.agents/skills → skills}/pc-make-engineer/template.md

@@ -1,42 +1,36 @@
-# Agent file template
-
-The whole file, with nothing else in it:
-
-```markdown
----
-description: <one sentence naming the persona + top 3-5 detected technologies>
-mode: subagent
-permission:
-  edit: allow
-  bash: allow
-  read: allow
-  glob: allow
-  grep: allow
----
-
-<One paragraph: "You are a {persona} engineer specializing in {top technologies}. You own all work in {scope/files}." Keep it to 2-3 sentences max.>
-
-## Abilities
-- Guardrails: @pc-guardrails-generic, @pc-guardrails-project
-- Development: <@installed-skill-1>, <@installed-skill-2>, ...
-- Testing: <@installed-skill-for-testing>, ...
-- Infrastructure: <@installed-skill-for-devops>, ...
-```
-
-Replace every `<...>` placeholder with real values, and drop any category line with no skills in it (Guardrails always stays). Development is language, framework, UI and DI skills; Testing is test, lint and typecheck skills; Infrastructure is DevOps, CI/CD and cloud skills.
-
-## Description quality bar
-
-`description:` is the matching key for `/plan-apply`: the lead compares a task's domain text against it to pick a specialist, so a vague one gets the wrong engineer spawned.
-
-Bad: `"A frontend engineer for React"`
-
-Good: `"Frontend engineer for Ink 7 + React 19 TUI, FSD architecture, Inversify DI, design tokens, and i18n"`
-
-Name the persona, list the three to five technologies actually detected, one sentence, no padding.
-
-## Identity paragraph
-
-Two or three sentences: who the engineer is, and what files or layers it owns. A knowledge dump here is knowledge the lead cannot reuse and the engineer did not ask for.
-
-Good: `"You are a frontend engineer specializing in terminal UI development with Ink 7 + React 19. You own all work in the FSD layers: src/app/, src/widgets/, src/features/, src/entities/, and src/shared/."`
+# Agent file template
+
+The whole file, with nothing else in it:
+
+```markdown
+---
+description: <one sentence naming the persona + top 3-5 detected technologies>
+mode: subagent
+---
+
+<One paragraph: "You are a {persona} engineer specializing in {top technologies}. You own all work in {scope/files}." Keep it to 2-3 sentences max.>
+
+## Abilities
+- Guardrails: @pc-guardrails-generic, @pc-guardrails-project
+- Development: <@installed-skill-1>, <@installed-skill-2>, ...
+- Testing: <@installed-skill-for-testing>, ...
+- Infrastructure: <@installed-skill-for-devops>, ...
+```
+
+Replace every `<...>` placeholder with real values, and drop any category line with no skills in it (Guardrails always stays). Development is language, framework, UI and DI skills; Testing is test, lint and typecheck skills; Infrastructure is DevOps, CI/CD and cloud skills.
+
+## Description quality bar
+
+`description:` is the matching key for `/plan-apply`: the lead compares a task's domain text against it to pick a specialist, so a vague one gets the wrong engineer spawned.
+
+Bad: `"A frontend engineer for React"`
+
+Good: `"Frontend engineer for Ink 7 + React 19 TUI, FSD architecture, Inversify DI, design tokens, and i18n"`
+
+Name the persona, list the three to five technologies actually detected, one sentence, no padding.
+
+## Identity paragraph
+
+Two or three sentences: who the engineer is, and what files or layers it owns. A knowledge dump here is knowledge the lead cannot reuse and the engineer did not ask for.
+
+Good: `"You are a frontend engineer specializing in terminal UI development with Ink 7 + React 19. You own all work in the FSD layers: src/app/, src/widgets/, src/features/, src/entities/, and src/shared/."`

package/{harness/.agents/skills → skills}/pc-make-guardrails/SKILL.md

@@ -14,6 +14,7 @@ Turn this project's own documentation into `.agents/skills/pc-guardrails-project
 - Never invent a rule the project does not state somewhere. A guardrail that came from nowhere is one nobody agreed to, and it will be followed anyway.
 - Never write an empty category. Omit it.
 - Never touch a tier variant (`*-engineer.build.md`, `*-engineer.fast.md`, `*-engineer.plan.md`): they are regenerated from the base templates every startup.
+- Before writing the file, run the self-check defined in the [category reference](category-reference.md): count rules, cut positive phrasing and reference facts, strip anything already enforced by tooling or by `pc-guardrails-generic`, and re-count. The file is not written until the self-check passes.
 
 ## Sources
 

package/{harness/.agents/skills → skills}/pc-make-guardrails/category-reference.md

@@ -20,12 +20,26 @@ Each rule must be:
 - **Concrete**: "Use `pnpm` not `npm`" not "Use the right package manager".
 - **Evidence-based**: derived from the files and code graph you analyzed. Never invent a rule the project does not state or demonstrate somewhere.
 - **Not enforced elsewhere.** Skip anything the formatter, linter, type checker, test suite, CI gate or a harness plugin already fails the build on. A rule restating `biome.json` is read on every load and changes nothing: the build was going to catch it. Write the rules that nothing but a careful reader would catch.
-- **Not already in `pc-guardrails-generic`.** That skill loads alongside this one, every request. Secrets, comment discipline, scratch-file location and one-responsibility-per-file are its rules, not this file's.
+- **Not already in `pc-guardrails-generic`.** That skill loads alongside this one, every request. Secrets, zero-comment default, scratch-file location, one-responsibility-per-file, minimal-test discipline, and the engineer workflow are its rules, not this file's.
 
 **At most 40 rules, across all categories.** Rank by what a violation costs and cut from the bottom; a category with nothing consequential in it gets no rules at all. This cap is the point of the exercise, not tidiness: compliance falls away as a rule file grows, so the 41st rule does not just cost its own tokens, it dilutes the 40 that matter. If more than 40 survive every bar above, the excess is a sign the project's constraints belong in a linter rule or a CI check instead.
 
+## Contrastive example
+
+**Bad** (reference fact — cut):
+> - The SQL Server database name is `myapp`, lowercase.
+
+The agent reads the connection string in config. It costs tokens on every load and the agent cannot "break" it.
+
+**Good** (negative constraint with consequence — keep):
+> - Never add a cached column for a value that is derived from another entity; a later edit to the source leaves the cache stale, and nothing in the build catches it.
+
+The agent could break this without noticing, nothing mechanically enforces it, and the consequence is stated.
+
 ## Skill template
 
+Each section holds constraints an agent could break without noticing, not reference facts. "Naming Conventions" does not mean "list how files are named" — it means "name the conventions whose violation is silent and costly." "Build & Deployment" does not mean "list the build commands" — it means "name the build rules a developer could violate without CI catching it." If a section has only reference facts, omit it entirely.
+
 Write (or update) `.agents/skills/pc-guardrails-project/SKILL.md`:
 
 ```markdown
@@ -71,3 +85,28 @@ license: MIT
 ```
 
 Only include sections that have real rules. Omit empty sections.
+
+## Self-check (before writing the file)
+
+Re-read the output you are about to write. Then:
+
+1. **Count the rules** (every bullet under every section). If there are more than 40, cut from the bottom — rank by what a violation costs and remove the cheapest until you are at or under 40. A rule file past 40 dilutes the ones that matter.
+
+2. **Scan for positive phrasing and reference facts.** Cut or rewrite any rule that:
+   - States what something is named, rather than what must not be named that way and why.
+   - Lists a port number, a database name, a package version, a SDK version, or a connection string. The agent discovers these by reading config.
+   - Describes how something works (e.g. "auth uses a smart scheme that forwards to JWT or Cookies"), rather than what must not be done with it.
+   - Restates a project's tech stack as a list ("Frontend: React 19, Next.js 15, TypeScript…"). That is reference material, not a constraint.
+
+3. **Strip anything already enforced by tooling.** Remove a rule if any of these already fails the build on its violation:
+   - Biome / ESLint / Prettier / Steiger / lint:fsd
+   - NetArchTest / architecture test projects
+   - Semgrep / Trivy / TruffleHog / SBOM checks
+   - Coverage gates (`scripts/check-coverage.mjs`)
+   - `.editorconfig`, `Directory.Build.props`, NuGet audit gates
+   - CI workflow steps (`app-ci.yml`, `ci.yml`)
+   - GitHub branch protection / required checks. If the build catches it, the rule costs tokens and adds nothing. The only exception is a rule whose enforcement is partial or non-obvious (e.g. architecture tests enforce layering but a developer could still import a namespace through reflection or a transitive dependency — that nuance is worth a rule).
+
+4. **Strip anything already in `pc-guardrails-generic`.** That skill loads on every request alongside this one. Its rules are: secrets discipline, zero-comment default (WHY not WHAT, 10% ceiling, no auto-generated docstrings), scratch-file location, one-responsibility-per-file, minimal-test discipline (one regression test per bug, no framework/library tests, no integration/e2e/snapshot unless asked, no mock-assertion of third-party calls), and the engineer workflow. Do not restate any of them here.
+
+5. **Re-count after cutting.** If you are still over 40, you are writing reference material, not constraints. Cut harder.