@plainconceptsplatform/agent-harness 3.1.1 → 3.2.0

package/skills/README.md

@@ -1,18 +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/
-```
+# 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/browser-automation/SKILL.md

@@ -1,72 +1,72 @@
----
-name: browser-automation
-description: Reliable, composable browser automation using agent-browser. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
-license: MIT
-compatibility: Requires agent-browser CLI installed (Rust binary) and running.
-metadata:
-  author: copilots
-  version: "2.0"
----
-
-This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and reads on locally running apps are in scope. External services (github.com, dev.azure.com, npmjs.com, etc.) are out of scope for browser tools.
-
-The only exception: when the user selects "Others (Browser)" as their backlog platform during onboarding, the `pc-userstory` skill may navigate to work item URLs the user explicitly provides. That is the sole case where external navigation is permitted, and only to URLs the user explicitly gives you.
-
-## Best-practice workflow
-
-1. Open the page: `agent-browser open <url>` (launches its own Chrome; reuses the running daemon)
-2. Take a snapshot: `agent-browser snapshot` to get the accessibility tree with `@ref` handles
-3. Interact by ref: `agent-browser click @e2`, `agent-browser fill @e3 "text"`
-4. Wait when needed: `agent-browser wait --load networkidle` or `agent-browser wait <selector>`
-5. Confirm the result with a fresh `snapshot`, `get text`, or `screenshot`
-
-Refs like `@e2` come from the last snapshot and go stale after page changes: retake the snapshot after navigation or dynamic updates before reusing them. When a click fails because another element covers the target (consent banner, modal), dismiss or interact with the covering element, then take a fresh snapshot before retrying.
-
-## Tool access
-
-- MCP tools (inside OpenCode): `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, `agent_browser_fill`, `agent_browser_type`, `agent_browser_wait_for_selector`, `agent_browser_screenshot`, `agent_browser_eval`, `agent_browser_close` — configured in `opencode.jsonc` with `--tools core`
-- CLI (any agent, any host): every command below works identically via bash
-- Diagnose the install: `agent-browser doctor`
-
-## Selecting elements
-
-- Prefer refs from `snapshot` (`@e1`, `@e2`, ...) over CSS selectors
-- CSS selectors also work: `agent-browser click "#submit"`, `agent-browser fill "#email" "text"`
-- Semantic locators: `agent-browser find role button click --name "Submit"`, `find text "Sign In" click`, `find label "Email" fill "value"`, `find testid <id> click`
-- Native selects: `agent-browser select <sel> <value>`
-
-## Reading state
-
-- `agent-browser get text <sel>` — text content of an element
-- `agent-browser get value <sel>` — input value
-- `agent-browser snapshot` — structured accessibility tree (preferred for parsing)
-- `agent-browser screenshot [path]` — `--full` for full page, `--annotate` for numbered labels
-- `agent-browser read` — agent-readable markdown of the active tab (no Chrome launch for URL reads)
-
-## Tabs and sessions
-
-- `agent-browser tab` lists tabs with stable `t1`, `t2` ids; `tab new --label <name>` and `tab <label>` switch
-- `agent-browser close` closes the browser; `close --all` closes every session
-
-## CLI-first debugging
-
-- `agent-browser doctor` — diagnose install, Chrome, and daemon state
-- `agent-browser console` — view console messages; `agent-browser errors` — uncaught exceptions
-- `agent-browser eval "<js>"` — run JavaScript in the page
-- `agent-browser network requests --filter api` — inspect tracked requests
-
-## Troubleshooting
-
-- Stale ref: take a fresh `snapshot` after any navigation or DOM change
-- Covered click: the error names the covering element; dismiss it, re-snapshot, retry
-- Selector fails: confirm the content exists with `agent-browser get text` or a snapshot before retrying
-- Daemon or Chrome issues: run `agent-browser doctor`
-
-## Scope
-
-- Screenshots of locally running app on `localhost` URLs: in scope
-- Click, type, scroll, read on `localhost` pages: in scope
-- Navigate to work item URLs the user explicitly provides (when backlog platform is "Others (Browser)"): in scope
-- Navigate to external services for non-work-item purposes: out of scope
-- DevOps or GitHub CLI operations via browser tools: out of scope
-- Reading or modifying production systems via browser tools: out of scope
+---
+name: browser-automation
+description: Reliable, composable browser automation using agent-browser. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
+license: MIT
+compatibility: Requires agent-browser CLI installed (Rust binary) and running.
+metadata:
+  author: copilots
+  version: "2.0"
+---
+
+This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and reads on locally running apps are in scope. External services (github.com, dev.azure.com, npmjs.com, etc.) are out of scope for browser tools.
+
+The only exception: when the user selects "Others (Browser)" as their backlog platform during onboarding, the `pc-userstory` skill may navigate to work item URLs the user explicitly provides. That is the sole case where external navigation is permitted, and only to URLs the user explicitly gives you.
+
+## Best-practice workflow
+
+1. Open the page: `agent-browser open <url>` (launches its own Chrome; reuses the running daemon)
+2. Take a snapshot: `agent-browser snapshot` to get the accessibility tree with `@ref` handles
+3. Interact by ref: `agent-browser click @e2`, `agent-browser fill @e3 "text"`
+4. Wait when needed: `agent-browser wait --load networkidle` or `agent-browser wait <selector>`
+5. Confirm the result with a fresh `snapshot`, `get text`, or `screenshot`
+
+Refs like `@e2` come from the last snapshot and go stale after page changes: retake the snapshot after navigation or dynamic updates before reusing them. When a click fails because another element covers the target (consent banner, modal), dismiss or interact with the covering element, then take a fresh snapshot before retrying.
+
+## Tool access
+
+- MCP tools (inside OpenCode): `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, `agent_browser_fill`, `agent_browser_type`, `agent_browser_wait_for_selector`, `agent_browser_screenshot`, `agent_browser_eval`, `agent_browser_close` — configured in `opencode.jsonc` with `--tools core`
+- CLI (any agent, any host): every command below works identically via bash
+- Diagnose the install: `agent-browser doctor`
+
+## Selecting elements
+
+- Prefer refs from `snapshot` (`@e1`, `@e2`, ...) over CSS selectors
+- CSS selectors also work: `agent-browser click "#submit"`, `agent-browser fill "#email" "text"`
+- Semantic locators: `agent-browser find role button click --name "Submit"`, `find text "Sign In" click`, `find label "Email" fill "value"`, `find testid <id> click`
+- Native selects: `agent-browser select <sel> <value>`
+
+## Reading state
+
+- `agent-browser get text <sel>` — text content of an element
+- `agent-browser get value <sel>` — input value
+- `agent-browser snapshot` — structured accessibility tree (preferred for parsing)
+- `agent-browser screenshot [path]` — `--full` for full page, `--annotate` for numbered labels
+- `agent-browser read` — agent-readable markdown of the active tab (no Chrome launch for URL reads)
+
+## Tabs and sessions
+
+- `agent-browser tab` lists tabs with stable `t1`, `t2` ids; `tab new --label <name>` and `tab <label>` switch
+- `agent-browser close` closes the browser; `close --all` closes every session
+
+## CLI-first debugging
+
+- `agent-browser doctor` — diagnose install, Chrome, and daemon state
+- `agent-browser console` — view console messages; `agent-browser errors` — uncaught exceptions
+- `agent-browser eval "<js>"` — run JavaScript in the page
+- `agent-browser network requests --filter api` — inspect tracked requests
+
+## Troubleshooting
+
+- Stale ref: take a fresh `snapshot` after any navigation or DOM change
+- Covered click: the error names the covering element; dismiss it, re-snapshot, retry
+- Selector fails: confirm the content exists with `agent-browser get text` or a snapshot before retrying
+- Daemon or Chrome issues: run `agent-browser doctor`
+
+## Scope
+
+- Screenshots of locally running app on `localhost` URLs: in scope
+- Click, type, scroll, read on `localhost` pages: in scope
+- Navigate to work item URLs the user explicitly provides (when backlog platform is "Others (Browser)"): in scope
+- Navigate to external services for non-work-item purposes: out of scope
+- DevOps or GitHub CLI operations via browser tools: out of scope
+- Reading or modifying production systems via browser tools: out of scope

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

@@ -15,7 +15,7 @@ The marker sections below name the optimization skills this project selected. Lo
 
 ## 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.
+- Zero comments by default. Write one only for what the code cannot show and we do not control: a vendor bug, an external contract, a legal rule. Leave every file you touch with no comment slop, old or new.
 - 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
@@ -28,6 +28,7 @@ The marker sections below name the optimization skills this project selected. Lo
 - 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.
+- `node .opencode/scripts/check-diff.mjs` enforces the comment and test rules on the diff and must exit 0.
 
 <!-- PC-GUARDRAILS-RTK-START -->
 <!-- PC-GUARDRAILS-RTK-END -->

package/skills/pc-make-architecture/SKILL.md

@@ -1,32 +1,32 @@
----
-name: pc-make-architecture
-description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time. Invoked by the /make-architecture command and the repo-initialize flow.
-license: MIT
----
-
-# Make Architecture
-
-Write `ARCHITECTURE.md` in the project root from what the codebase actually contains, following the [structure template](structure-template.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 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
-
-| 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.** Discover the architecture with the file tools: `glob` for structure, `grep` for routes, models and schemas, `read` for config, CI workflows, Dockerfiles, README, changelogs and ADRs.
-
-**Update.** `git log --oneline --since="<footer date>" -- <source roots>` says what moved. Nothing changed means nothing to write: say "Architecture unchanged since last update" and stop. Otherwise rewrite only the affected sections and leave the rest, including anything hand-written, as it stands. Past roughly 40% of sections affected, fall back to Generate.
-
-## Report
-
-Whether the file was generated or updated and which sections changed, the top-level components found, and that `/make-architecture` can be re-run whenever the architecture moves.
+---
+name: pc-make-architecture
+description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time. Invoked by the /make-architecture command and the repo-initialize flow.
+license: MIT
+---
+
+# Make Architecture
+
+Write `ARCHITECTURE.md` in the project root from what the codebase actually contains, following the [structure template](structure-template.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 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
+
+| 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.** Discover the architecture with the file tools: `glob` for structure, `grep` for routes, models and schemas, `read` for config, CI workflows, Dockerfiles, README, changelogs and ADRs.
+
+**Update.** `git log --oneline --since="<footer date>" -- <source roots>` says what moved. Nothing changed means nothing to write: say "Architecture unchanged since last update" and stop. Otherwise rewrite only the affected sections and leave the rest, including anything hand-written, as it stands. Past roughly 40% of sections affected, fall back to Generate.
+
+## Report
+
+Whether the file was generated or updated and which sections changed, the top-level components found, and that `/make-architecture` can be re-run whenever the architecture moves.

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/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-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.