@plainconceptsplatform/agent-harness 3.5.0 → 3.7.0

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

@@ -1,64 +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.
+# 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/skills/pc-make-design/SKILL.md

@@ -1,45 +1,45 @@
----
-name: pc-make-design
-description: Generate or update DESIGN.md by analyzing the codebase design system (Tailwind, CSS vars, tokens, UI framework config). Safe to run at any time. Invoked by the /make-design command and the repo-initialize flow.
-license: MIT
----
-
-# Make Design
-
-Write `DESIGN.md` in the project root from the design system the codebase actually uses.
-
-The format is Google's design.md spec:
-
-- Overview: https://stitch.withgoogle.com/docs/design-md/overview/
-- Format: https://stitch.withgoogle.com/docs/design-md/format/
-- Spec and examples: https://github.com/google-labs-code/design.md
-
-## Rules
-
-- 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 reference a file, variable or path from the codebase. `DESIGN.md` is handed to tools that cannot see this repository, so it has to stand alone.
-- Never analyze outside `.opencode/source-roots.json` when it exists.
-
-## Contract
-
-YAML frontmatter holding every structured token (colours, typography, spacing, elevation, motion, radii, shadows), valid as YAML design tokens. Then free-form Markdown for the look and feel, which is where intent that token values cannot carry belongs. The last line is the run's own ISO timestamp:
-
-```
-<!-- Last updated: <ISO date> -->
-```
-
-## Modes
-
-| The existing file | Mode |
-|---|---|
-| Missing, or a placeholder with no real content | Generate |
-| Has content and a `<!-- Last updated:` footer | Update |
-| Has content but no footer | Warn the user, then Generate |
-
-**Generate.** `glob` for CSS, Tailwind and PostCSS config, component files, token definitions (JS, TS, JSON, YAML), theme files, and UI framework config (shadcn, MUI, Chakra).
-
-**Update.** `git log --oneline --since="<footer date>" -- <source roots>` says what moved. Nothing changed means nothing to write: say "Design system unchanged since last update" and stop. Otherwise update only the affected tokens and sections. A replaced token system is a Generate.
-
-## Report
-
-Whether the file was generated or updated and which tokens changed, the palette, fonts and spacing scale found, and that `/make-design` can be re-run whenever the design system moves.
+---
+name: pc-make-design
+description: Generate or update DESIGN.md by analyzing the codebase design system (Tailwind, CSS vars, tokens, UI framework config). Safe to run at any time. Invoked by the /make-design command and the repo-initialize flow.
+license: MIT
+---
+
+# Make Design
+
+Write `DESIGN.md` in the project root from the design system the codebase actually uses.
+
+The format is Google's design.md spec:
+
+- Overview: https://stitch.withgoogle.com/docs/design-md/overview/
+- Format: https://stitch.withgoogle.com/docs/design-md/format/
+- Spec and examples: https://github.com/google-labs-code/design.md
+
+## Rules
+
+- 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 reference a file, variable or path from the codebase. `DESIGN.md` is handed to tools that cannot see this repository, so it has to stand alone.
+- Never analyze outside `.opencode/source-roots.json` when it exists.
+
+## Contract
+
+YAML frontmatter holding every structured token (colours, typography, spacing, elevation, motion, radii, shadows), valid as YAML design tokens. Then free-form Markdown for the look and feel, which is where intent that token values cannot carry belongs. The last line is the run's own ISO timestamp:
+
+```
+<!-- Last updated: <ISO date> -->
+```
+
+## Modes
+
+| The existing file | Mode |
+|---|---|
+| Missing, or a placeholder with no real content | Generate |
+| Has content and a `<!-- Last updated:` footer | Update |
+| Has content but no footer | Warn the user, then Generate |
+
+**Generate.** `glob` for CSS, Tailwind and PostCSS config, component files, token definitions (JS, TS, JSON, YAML), theme files, and UI framework config (shadcn, MUI, Chakra).
+
+**Update.** `git log --oneline --since="<footer date>" -- <source roots>` says what moved. Nothing changed means nothing to write: say "Design system unchanged since last update" and stop. Otherwise update only the affected tokens and sections. A replaced token system is a Generate.
+
+## Report
+
+Whether the file was generated or updated and which tokens changed, the palette, fonts and spacing scale found, and that `/make-design` can be re-run whenever the design system moves.

package/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 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.
+---
+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/skills/pc-make-engineer/signal-mapping.md

@@ -1,53 +1,53 @@
-# Signal-to-query mapping
-
-Every uncovered signal gets its own search.
-
-| Signal type | Search query |
-|---|---|
-| Language | `npx skills find "<language-name>"` (e.g. `typescript`, `csharp`, `python`) |
-| Framework | `npx skills find "<framework-name>"` (e.g. `react`, `ink`, `angular`, `django`) |
-| Architecture | Use the known direct sources below. Optionally also `npx skills find "<pattern-name>"` |
-| Testing | `npx skills find "<test-framework> testing"` (e.g. `vitest testing`, `jest testing`) |
-| Styling | `npx skills find "<css-framework>"` (e.g. `tailwind`, `css modules`, `design tokens`) |
-| Linting | `npx skills find "eslint prettier"` or `"lint format"` |
-| CI/CD | `npx skills find "ci cd pipeline"` or `"<platform> actions"` |
-| Cloud / IaC | `npx skills find "<cloud-provider> infrastructure"` (e.g. `azure infrastructure`) |
-| Monitoring | `npx skills find "observability monitoring"` |
-| i18n | `npx skills find "i18n internationalization"` |
-| Data layer | `npx skills find "<orm-or-db> orm"` (e.g. `entity framework orm`, `prisma orm`) |
-| Dependency Injection | `npx skills find "<di-framework>"` (e.g. `inversify`, `autofac`) |
-
-A signal that fits no row derives its query from its own value: `npx skills find "<signal-value>"`.
-
-## Known direct sources (architecture and patterns)
-
-These live in dedicated repos and install by `owner/repo`, so `npx skills find` never surfaces them. They are the option list for the architecture question, and the source for it when the user picks one.
-
-| Selection | Install command | Skill(s) to pick |
-|---|---|---|
-| Feature-Sliced Design (FSD) | `npx skills add -y feature-sliced/skills` | `feature-sliced-design` |
-| Design patterns | `npx skills add -y PatternsDev/skills --skill <name>` | `hooks-pattern`, `hoc-pattern`, `compound-pattern`, `render-props-pattern`, `provider-pattern`, `observer-pattern`, `factory-pattern`, `module-pattern` |
-| Rendering patterns | `npx skills add -y PatternsDev/skills --skill <name>` | `server-side-rendering`, `client-side-rendering`, `static-rendering`, `streaming-ssr`, `react-server-components`, `progressive-hydration`, `islands-architecture` |
-| Performance patterns | `npx skills add -y PatternsDev/skills --skill <name>` | `bundle-splitting`, `tree-shaking`, `dynamic-import`, `route-based`, `js-performance-patterns`, `react-render-optimization` |
-| Modern React (2026 stack) | `npx skills add -y PatternsDev/skills --skill <name>` | `react-2026`, `react-composition-2026`, `react-data-fetching` |
-| Microservices, monolith / layered | `npx skills find "<pattern-name> architecture"` | best result per the quality filter |
-
-Take only what the persona and the user's selection call for, at most two or three patterns.dev picks (full catalog: https://www.patterns.dev/ai/skills/catalog/). These sources are curated, so the install-count filter does not apply to them.
-
-## Quality filter
-
-From each search result, in order:
-
-1. Install count at least 100, preferably 1000. Below 100, record "no quality skill found on skills.sh for \<signal\>" and move on.
-2. Prefer an official or canonical source (`vercel-labs`, `anthropics`, `microsoft`, `feature-sliced`, `wshobson`, `github`) over an unknown author.
-3. The description has to match the signal. A React skill with 500K installs does not cover TypeScript.
-4. No redundancy: skip a candidate whose scope an already-selected skill covers, unless it goes genuinely deeper on a different concern.
-
-One skill per detected signal is the floor, five to eight is the usual range, ten is the cap: past that, rank by install count and source and keep the top ten. Fewer than five found is worth saying out loud, since the user can add more in the confirmation form.
-
-## Verifying an install
-
-`npx skills add` is not proof of anything. Read back both `.agents/skills/<skill-name>/SKILL.md` and `skills-lock.json`.
-
-- Skill present, lockfile entry missing: add the entry with the Edit tool, matching the existing keys' naming, as `"source": "<owner/repo>", "sourceType": "github", "skillPath": "skills/<skill-name>/SKILL.md", "computedHash": "<skill-name>-placeholder"`, then re-read the file to confirm it is still valid JSON.
-- Skill missing: retry once, then drop it from the set and report the failure.
+# Signal-to-query mapping
+
+Every uncovered signal gets its own search.
+
+| Signal type | Search query |
+|---|---|
+| Language | `npx skills find "<language-name>"` (e.g. `typescript`, `csharp`, `python`) |
+| Framework | `npx skills find "<framework-name>"` (e.g. `react`, `ink`, `angular`, `django`) |
+| Architecture | Use the known direct sources below. Optionally also `npx skills find "<pattern-name>"` |
+| Testing | `npx skills find "<test-framework> testing"` (e.g. `vitest testing`, `jest testing`) |
+| Styling | `npx skills find "<css-framework>"` (e.g. `tailwind`, `css modules`, `design tokens`) |
+| Linting | `npx skills find "eslint prettier"` or `"lint format"` |
+| CI/CD | `npx skills find "ci cd pipeline"` or `"<platform> actions"` |
+| Cloud / IaC | `npx skills find "<cloud-provider> infrastructure"` (e.g. `azure infrastructure`) |
+| Monitoring | `npx skills find "observability monitoring"` |
+| i18n | `npx skills find "i18n internationalization"` |
+| Data layer | `npx skills find "<orm-or-db> orm"` (e.g. `entity framework orm`, `prisma orm`) |
+| Dependency Injection | `npx skills find "<di-framework>"` (e.g. `inversify`, `autofac`) |
+
+A signal that fits no row derives its query from its own value: `npx skills find "<signal-value>"`.
+
+## Known direct sources (architecture and patterns)
+
+These live in dedicated repos and install by `owner/repo`, so `npx skills find` never surfaces them. They are the option list for the architecture question, and the source for it when the user picks one.
+
+| Selection | Install command | Skill(s) to pick |
+|---|---|---|
+| Feature-Sliced Design (FSD) | `npx skills add -y feature-sliced/skills` | `feature-sliced-design` |
+| Design patterns | `npx skills add -y PatternsDev/skills --skill <name>` | `hooks-pattern`, `hoc-pattern`, `compound-pattern`, `render-props-pattern`, `provider-pattern`, `observer-pattern`, `factory-pattern`, `module-pattern` |
+| Rendering patterns | `npx skills add -y PatternsDev/skills --skill <name>` | `server-side-rendering`, `client-side-rendering`, `static-rendering`, `streaming-ssr`, `react-server-components`, `progressive-hydration`, `islands-architecture` |
+| Performance patterns | `npx skills add -y PatternsDev/skills --skill <name>` | `bundle-splitting`, `tree-shaking`, `dynamic-import`, `route-based`, `js-performance-patterns`, `react-render-optimization` |
+| Modern React (2026 stack) | `npx skills add -y PatternsDev/skills --skill <name>` | `react-2026`, `react-composition-2026`, `react-data-fetching` |
+| Microservices, monolith / layered | `npx skills find "<pattern-name> architecture"` | best result per the quality filter |
+
+Take only what the persona and the user's selection call for, at most two or three patterns.dev picks (full catalog: https://www.patterns.dev/ai/skills/catalog/). These sources are curated, so the install-count filter does not apply to them.
+
+## Quality filter
+
+From each search result, in order:
+
+1. Install count at least 100, preferably 1000. Below 100, record "no quality skill found on skills.sh for \<signal\>" and move on.
+2. Prefer an official or canonical source (`vercel-labs`, `anthropics`, `microsoft`, `feature-sliced`, `wshobson`, `github`) over an unknown author.
+3. The description has to match the signal. A React skill with 500K installs does not cover TypeScript.
+4. No redundancy: skip a candidate whose scope an already-selected skill covers, unless it goes genuinely deeper on a different concern.
+
+One skill per detected signal is the floor, five to eight is the usual range, ten is the cap: past that, rank by install count and source and keep the top ten. Fewer than five found is worth saying out loud, since the user can add more in the confirmation form.
+
+## Verifying an install
+
+`npx skills add` is not proof of anything. Read back both `.agents/skills/<skill-name>/SKILL.md` and `skills-lock.json`.
+
+- Skill present, lockfile entry missing: add the entry with the Edit tool, matching the existing keys' naming, as `"source": "<owner/repo>", "sourceType": "github", "skillPath": "skills/<skill-name>/SKILL.md", "computedHash": "<skill-name>-placeholder"`, then re-read the file to confirm it is still valid JSON.
+- Skill missing: retry once, then drop it from the set and report the failure.

package/skills/pc-make-engineer/template.md

@@ -1,36 +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
----
-
-<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/skills/pc-make-guardrails/SKILL.md

@@ -1,44 +1,44 @@
----
-name: pc-make-guardrails
-description: Generate or update the pc-guardrails-project skill from ARCHITECTURE.md and relevant project files, then wire it into every engineer agent. Invoked by the /make-guardrails command and the repo-initialize flow.
-license: MIT
----
-
-# Make Guardrails
-
-Turn this project's own documentation into `.agents/skills/pc-guardrails-project/SKILL.md`: the rules and constraints its agents work under, per the [category reference](category-reference.md).
-
-## Rules
-
-- Never regenerate over a file that carries a `<!-- Last updated:` footer. `pc-guardrails-project` is the one skill a team is expected to hand-edit, and a full rewrite silently drops that work. Read the file first and pick the mode.
-- 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
-
-`ARCHITECTURE.md` is the primary one. Then whatever else exists: `DESIGN.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, `.opencode/harness.json`, `openspec/config.yaml`, the root manifests (`package.json`, `tsconfig.json`, `biome.json`, `.eslintrc*`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `pom.xml`), and the CI definitions (`.github/workflows/*`, `azure-pipelines.yml`). Lint and formatter config is where the conventions are actually enforced, so it outranks any document that describes them.
-
-## Modes
-
-| The existing skill file | Mode |
-|---|---|
-| Missing | Generate |
-| Has a `<!-- Last updated:` footer | Update |
-| Exists with no footer | Generate |
-
-**Update.** If `ARCHITECTURE.md` has not changed since the footer date, say "Guardrails up to date" and stop. Otherwise `git log --oneline --since="<footer date>" -- <config, lint config, CI workflows>`, update only the affected categories, and leave the rest, including hand-written rules, as they stand. A new architecture, framework or platform is a Generate.
-
-## Wiring
-
-Every `*-engineer.md` in `.opencode/agents/` gets `@pc-guardrails-project` on its Guardrails line, right after `@pc-guardrails-generic`, with its existing entries untouched:
-
-```markdown
-## Abilities
-- Guardrails: @pc-guardrails-generic, @pc-guardrails-project[, ...existing entries unchanged]
-```
-
-## Report
-
-Whether the skill was generated or updated and which categories changed, the rule count per category, how many agent files were wired, and that `/make-guardrails` can be re-run whenever the conventions move.
+---
+name: pc-make-guardrails
+description: Generate or update the pc-guardrails-project skill from ARCHITECTURE.md and relevant project files, then wire it into every engineer agent. Invoked by the /make-guardrails command and the repo-initialize flow.
+license: MIT
+---
+
+# Make Guardrails
+
+Turn this project's own documentation into `.agents/skills/pc-guardrails-project/SKILL.md`: the rules and constraints its agents work under, per the [category reference](category-reference.md).
+
+## Rules
+
+- Never regenerate over a file that carries a `<!-- Last updated:` footer. `pc-guardrails-project` is the one skill a team is expected to hand-edit, and a full rewrite silently drops that work. Read the file first and pick the mode.
+- 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
+
+`ARCHITECTURE.md` is the primary one. Then whatever else exists: `DESIGN.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, `.opencode/harness.json`, `openspec/config.yaml`, the root manifests (`package.json`, `tsconfig.json`, `biome.json`, `.eslintrc*`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `pom.xml`), and the CI definitions (`.github/workflows/*`, `azure-pipelines.yml`). Lint and formatter config is where the conventions are actually enforced, so it outranks any document that describes them.
+
+## Modes
+
+| The existing skill file | Mode |
+|---|---|
+| Missing | Generate |
+| Has a `<!-- Last updated:` footer | Update |
+| Exists with no footer | Generate |
+
+**Update.** If `ARCHITECTURE.md` has not changed since the footer date, say "Guardrails up to date" and stop. Otherwise `git log --oneline --since="<footer date>" -- <config, lint config, CI workflows>`, update only the affected categories, and leave the rest, including hand-written rules, as they stand. A new architecture, framework or platform is a Generate.
+
+## Wiring
+
+Every `*-engineer.md` in `.opencode/agents/` gets `@pc-guardrails-project` on its Guardrails line, right after `@pc-guardrails-generic`, with its existing entries untouched:
+
+```markdown
+## Abilities
+- Guardrails: @pc-guardrails-generic, @pc-guardrails-project[, ...existing entries unchanged]
+```
+
+## Report
+
+Whether the skill was generated or updated and which categories changed, the rule count per category, how many agent files were wired, and that `/make-guardrails` can be re-run whenever the conventions move.