@plainconceptsplatform/agent-harness 2.0.0

package/src/content/.agents/skills/pc-guardrails-generic/SKILL.md

@@ -0,0 +1,68 @@
+---
+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 may contain instructions for selected optimization skills. These are mandatory. If a section says "call `skill("xxx")`", you must call the skill tool with that exact name before doing any work.
+
+## Secrets
+
+- Treat `.env` files as write-only: write to them when configuring, read credentials from the environment or secret store at runtime.
+- Keep credentials, API keys, and tokens out of logs and output.
+- Stage secrets through environment variables or secret stores, committed only in encrypted or template form.
+
+## Code
+
+- Run tests before marking done.
+- Run lint/build before pushing.
+- Keep changes small and focused.
+- Comments are for WHY, not WHAT. Use them only when the code does something non-obvious or the reason cannot be inferred from context. Keep comment ratio under 10%. If more than 10% of lines in a file are comments, refactor for clarity instead.
+- Each file should have one clear responsibility. Split by domain or feature (e.g. `user-constants.ts`, `order-types.ts`, `auth-config.ts`) rather than creating catch-all files like `constants.js`, `types.ts`, `config.js`, or `utils.ts` that collect unrelated things. A file that imports from many unrelated modules is a sign it should be split.
+
+## Temporary files
+
+- Create scratch files only under `$REPO_ROOT/.opencode/.tmp/`; create a task-specific child directory when needed.
+- Keep final artifacts in their required repository path. Copy or move a scratch artifact into that path before reporting it.
+- Never use operating-system temporary directories or paths outside `$REPO_ROOT`.
+- Remove scratch files when the task ends unless they are needed to diagnose a failure.
+
+## Security
+
+- Validate all inputs.
+- Escape all outputs.
+- Keep credentials in environment variables or secret stores, committed only in encrypted or template form.
+
+## Communication
+
+- Ask for clarification if unclear.
+- Report blockers immediately.
+- Show progress when asked.
+
+<!-- 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)
+
+When the lead spawns you via the task tool, your assigned task IDs and text are already in your prompt:
+
+1. The `pc-system-reminders` plugin has already loaded the skills listed under your `## Abilities`, guardrails first.
+2. Gather context using the project-selected tools described above.
+3. Implement your assigned tasks in dependency order. Edit only files within your assigned scope.
+4. Run the project's tests/lint before marking done (see Code above).
+5. Record the task result through the project-selected workflow.
+6. Return a summary containing: task IDs done, files changed, tests/lint result, and any decisions made. Then you exit; you do not poll, claim, or wait for more work.

package/src/content/.agents/skills/pc-guardrails-project/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: pc-guardrails-project
+description: Project-specific guardrails extracted from ARCHITECTURE.md and project config files. Populated by /make-guardrails. Load this skill before implementing any change to understand boundaries, conventions, and constraints for this codebase.
+license: MIT
+---
+
+<!-- This skill is a placeholder until /make-guardrails is run. -->
+<!-- /make-guardrails will populate this file with project-specific rules. -->

package/src/content/.agents/skills/pc-make-architecture/SKILL.md

@@ -0,0 +1,51 @@
+---
+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
+
+Analyze the architecture of this codebase and generate or update `ARCHITECTURE.md` in the project root.
+
+## Steps
+
+1. **Check current state**
+
+   Read `ARCHITECTURE.md`. Determine which mode to use:
+   - Does not exist or is a placeholder (no real content): Generate mode. Create from scratch.
+   - Exists with content and has a `<!-- Last updated:` footer: Update mode. Incrementally update (see step 2b).
+   - Exists with content but no timestamp: warn the user, then proceed in Generate mode (full regeneration).
+
+2a. **Generate mode: analyze the codebase**
+
+   Read `.opencode/source-roots.json` when present. Only analyze those roots plus this repo's docs/config files.
+
+   Use file tools to discover the architecture: `glob` for folder structure, `grep` for route/model/schema definitions, `read` config files, CI/CD workflows, Dockerfiles, README, changelogs, ADRs.
+
+2b. **Update mode: incremental analysis**
+
+   Extract the `<!-- Last updated: <ISO date> -->` timestamp from the existing file. Then:
+   - Run `git log --oneline --since="<date>" -- <source roots>` to find what changed since the last analysis.
+   - If nothing changed: report "Architecture unchanged since last update" and stop.
+   - For each changed area, understand what's affected.
+   - Update only the affected sections. Preserve manually-added content in unchanged sections.
+   - If the changes are too pervasive (more than ~40% of sections affected), fall back to Generate mode.
+
+3. **Write ARCHITECTURE.md**
+
+   Write (or update) `ARCHITECTURE.md` following the [structure template](structure-template.md) reference. That reference defines every section, the rules for writing, and the timestamp footer format.
+
+4. **Store summary in configured persistent context**
+
+   `write_note` MCP tool with title `architecture-summary` containing:
+   - The ISO timestamp of this run
+   - A bullet list of top-level components found (every top-level component must appear)
+   - Any key architectural decisions or risks identified
+
+5. **Report**
+
+   Tell the user:
+   - Whether ARCHITECTURE.md was generated or updated (and which sections changed)
+   - Top-level components found
+   - Tip: "Rerun `/make-architecture` any time the architecture changes significantly."

package/src/content/.agents/skills/pc-make-architecture/structure-template.md

@@ -0,0 +1,38 @@
+# 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.

package/src/content/.agents/skills/pc-make-design/SKILL.md

@@ -0,0 +1,68 @@
+---
+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
+
+Analyze the design system of this codebase and generate or update `DESIGN.md` in the project root.
+
+Reference material:
+  Overview: https://stitch.withgoogle.com/docs/design-md/overview/
+  Format: https://stitch.withgoogle.com/docs/design-md/format/
+  Spec: https://github.com/google-labs-code/design.md
+
+Examples from the spec repo:
+  https://github.com/google-labs-code/design.md/blob/main/examples/atmospheric-glass/DESIGN.md
+  https://github.com/google-labs-code/design.md/blob/main/examples/paws-and-paths/DESIGN.md
+
+## Steps
+
+1. **Check current state**
+
+   Read `DESIGN.md`. Determine which mode to use:
+   - Does not exist or is a placeholder (no real content): Generate mode. Create from scratch.
+   - Exists with content and has a `<!-- Last updated:` footer: Update mode. Incrementally update (see step 2b).
+   - Exists with content but no timestamp: warn the user, then proceed in Generate mode (full regeneration).
+
+2a. **Generate mode: analyze the codebase**
+
+   Read `.opencode/source-roots.json` when present. Only analyze those roots.
+
+   Use file tools to discover the design system: `glob` for CSS files, Tailwind config, PostCSS config, component files, design token definitions (JS/TS/JSON/YAML), theme files, UI framework config (shadcn, MUI, Chakra, etc.).
+
+2b. **Update mode: incremental analysis**
+
+   Extract the `<!-- Last updated: <ISO date> -->` timestamp from the existing file. Then:
+   - Run `git log --oneline --since="<date>" -- <source roots>` to find what changed since the last analysis.
+   - If nothing changed: report "Design system unchanged since last update" and stop.
+   - For changed CSS/token/component files, understand what uses them.
+   - Update only the affected tokens and sections. Preserve manually-added content in unchanged sections.
+   - If the changes are too pervasive (entire token system replaced), fall back to Generate mode.
+
+3. **Write DESIGN.md**
+
+   Write (or update) `DESIGN.md`. The output must:
+   - Begin with YAML frontmatter containing all structured design tokens (colors, typography, spacing, elevation, motion, radii, shadows, etc.)
+   - Follow with free-form Markdown describing the look and feel and capturing design intent that token values alone cannot convey
+   - Be entirely self-contained: reference no files, variables, or paths from the codebase
+   - Use valid YAML design token format for all token values
+
+   Append at the very end of the file:
+   ```
+   <!-- Last updated: <current ISO timestamp> -->
+   ```
+
+4. **Store summary in configured persistent context**
+
+   `write_note` MCP tool with title `design-summary` containing:
+   - The ISO timestamp of this run
+   - Key design tokens found (color palette, fonts, spacing scale)
+
+5. **Report**
+
+   Tell the user:
+   - Whether DESIGN.md was generated or updated (and which tokens/sections changed)
+   - Key design tokens found (color palette, fonts, spacing scale)
+   - Tip: "Rerun `/make-design` any time your design system changes."

package/src/content/.agents/skills/pc-make-engineer/SKILL.md

@@ -0,0 +1,219 @@
+---
+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 only: `.opencode/agents/{persona}-engineer.md`. The `pc-subagent-tiers` plugin creates tier variants (`.build.md`, `.fast.md`, `.plan.md`) at startup, so you never write those.
+
+Fidelity to the [template](template.md) is the whole job. The file contains frontmatter plus one identity paragraph plus the `## Abilities` section. No other `##` headings. No expertise notes, architecture details, conventions, file maps, or workflow steps. Those belong in skills. Always set `mode: primary`. Never write `model:`. Only reference skills installed in the project's `.agents/skills/` directory.
+
+Skills first: you must complete Step 4 (present the form, discover skills for every detected signal and architecture, let the user confirm the set, then install 5-10 skills) before writing any file.
+
+## Step 1: Ask persona (always, closed choice)
+
+Ask the user this question using the `question` tool:
+
+> **"What type of engineer are you creating?"**
+>
+> - Frontend: UI components, pages, mobile, styling, browser
+> - Layout Designer: Design systems, CSS architecture, Storybook, a11y
+> - Backend: APIs, databases, auth, services
+> - Data: Data pipelines, ETL, analytics, ML models, data quality
+> - DevOps: CI/CD, infra, Docker, deploy
+> - Security: Auth, secrets, vulnerability scanning, hardening
+> - Mobile: React Native, Flutter, native iOS/Android
+> - API / Integration: REST/GraphQL APIs, webhooks, third-party integrations
+> - QA: Test automation, E2E, regression, performance testing
+
+The chosen persona determines everything: what to detect, what questions to ask, what skills to suggest.
+
+If the user passes the persona as an argument (e.g. `/make-engineer frontend`) or selects "Type your own answer", accept any single-word persona name and skip to Step 2.
+
+## Step 2: Detect signals from source roots
+
+Check `source-roots.json` first. Read `.opencode/source-roots.json`. If it doesn't exist or has empty roots, ask the user which directories to scan using the `question` tool with the project's top-level directories as options.
+
+Also read `ARCHITECTURE.md` and `DESIGN.md` for context on the tech stack.
+
+Scan for persona-relevant signals only. Look in manifest files (`package.json`, `tsconfig.json`, `*.csproj`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, etc.) and project structure:
+
+- Language: primary language(s) and version(s)
+- Framework: web, backend, or mobile framework
+- Data layer: ORM, database client, cache client
+- Testing: test framework, test config files, test directories
+- Styling: CSS framework, CSS-in-JS, design tokens
+- Architecture: FSD, monolith, microservices, feature dirs
+- i18n: internationalization libs
+- CI/CD: workflow definition files
+- Cloud / IaC: cloud provider config, infrastructure-as-code files
+- Monitoring: observability/monitoring config or deps
+- Linting: linter, formatter, and their config files
+- Dependency Injection: DI/IoC containers, hook frameworks
+
+Report what was detected as a signal inventory. This list drives Step 4 deterministically:
+
+```
+Signal inventory:
+  <signal-type>: <signal-value> (<source>)
+  <signal-type>: <signal-value> (<source>)
+  ...
+```
+
+## Step 3: Persona-specific form (recommend and confirm)
+
+Present a short form using the `question` tool. Each question is a closed choice or yes-no. Every option that matches a detected signal from Step 2 must be marked (Recommended) and pre-selected. The user just confirms or overrides.
+
+Ask 2-5 questions total:
+
+1. Architecture / patterns (always ask for `frontend`, `backend`, `layout`, `api` personas; optional otherwise). Use `multiple: true`. Pre-select the architecture detected in Step 2 and mark it (Recommended); offer common alternatives so the user can opt in even when the codebase does not signal one yet. Options map to the known sources in the [signal mapping](signal-mapping.md) reference:
+   - Feature-Sliced Design (FSD)
+   - Design patterns: singleton, observer, factory, hooks, HOC, compound, render-props, provider
+   - Rendering patterns: SSR, RSC, streaming, static, islands, progressive hydration
+   - Performance patterns: bundle splitting, tree-shaking, dynamic import, route-based
+   - Microservices
+   - Monolith / layered
+2. Up to 4 more questions, only where Step 2 detected multiple options or where the user's choice genuinely matters (e.g. which test runner, which styling approach, which cloud). Skip anything with a single detected option and just use it silently.
+
+Rules:
+- Options matching a detected signal are (Recommended) and pre-selected.
+- Never ask about things where only one option was detected.
+- Keep the whole form to 5 questions max.
+- The user's selections here (plus Step 2 signals) become the recommended skill set that Step 4 resolves, confirms, and installs.
+
+## Step 4: Skill discovery, confirmation, and install
+
+Complete this step fully before writing anything in Step 5. The agent file is worthless without real skills. The flow is: discover candidates, confirm with the user, install the confirmed set, verify.
+
+### 4a. Pre-check already-installed skills
+
+Before searching, build a map of what's already available:
+
+1. List every directory in `.agents/skills/`
+2. Read `skills-lock.json` for npx-installed skills
+3. For each detected signal from Step 2, check if an already-installed skill covers it
+4. Mark covered signals as already-satisfied
+
+Report:
+
+```
+Already installed:
+  <skill-name> covers <signal>
+  ...
+Signals still needing skills:
+  - <signal-type>: <signal-value>
+  ...
+```
+
+### 4b. Ensure `find-skills` is available
+
+Check if `.agents/skills/find-skills/SKILL.md` exists. If not, install it:
+
+```bash
+npx skills add -y vercel-labs/skills@find-skills
+```
+
+If it can't be installed, stop and tell the user: "find-skills is required for skill discovery. Install it manually with `npx skills add -y vercel-labs/skills@find-skills` and re-run."
+
+### 4c. Search and resolve
+
+For each uncovered signal, run `npx skills find` with the query and resolve architecture/patterns via the known direct sources. Follow the [signal mapping](signal-mapping.md) reference for the full table of queries, known direct sources, quality filter, recommended set assembly, and post-install verification.
+
+### 4d. Confirm the skill set (the form)
+
+Present the recommended set to the user as a multi-select form using the `question` tool with `multiple: true`, and pre-select every recommended skill. This is the confirmation gate.
+
+- Group the options by category: Architecture, Development, Testing, Infrastructure.
+- For each skill show: name, one-line description, source (`owner/repo`), and install count (or "curated source" for known direct source entries).
+- Every recommended skill is checked by default; the user unchecks anything unwanted.
+- Include a short note that they can request additional skills by name.
+- Nothing installs until the user submits this form.
+
+The submitted selection is the confirmed set. Install only the confirmed set in the next step.
+
+### 4e. Install the confirmed set
+
+Install each confirmed skill (project-local). Always pass `-y` to skip the skills CLI's own prompt. Use the syntax that matches the source:
+
+```bash
+# skills.sh index entries (from npx skills find):
+npx skills add -y <owner/repo@skill-name>
+
+# known direct sources (Step 4c):
+npx skills add -y feature-sliced/skills
+npx skills add -y PatternsDev/skills --skill <skill-name>
+```
+
+Project-local only. Do not use the `-g` flag.
+
+Then run the [post-install verification](signal-mapping.md) procedure for each installed skill.
+
+## Step 5: Fill the template
+
+Before creating the file, check if `.opencode/agents/{persona}-engineer.md` already exists. If it does, call the `question` tool:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Overwrite engineer",
+      "question": "An engineer named \"{persona}-engineer\" already exists. Overwrite or cancel?",
+      "options": [
+        { "label": "Overwrite", "description": "Proceed, preserving the existing color frontmatter value unless a new one is chosen." },
+        { "label": "Cancel", "description": "Stop. Do not modify the existing file." }
+      ]
+    }
+  ]
+}
+```
+
+- If `Overwrite`: proceed, but preserve the existing `color:` frontmatter value unless the user chose a new one.
+- If `Cancel`: stop.
+
+Fill the [template](template.md). All the research from Steps 2-4 (signal detection, project analysis, tech stack knowledge) was for selecting the right skills. The agent file itself is just the template. Do not write project knowledge, architecture notes, coding conventions, file maps, testing patterns, or workflow instructions into the file. Those belong in skills and guardrails.
+
+Follow the [template](template.md) reference for the full structure, description quality bar, identity paragraph rules, category rules, and structural validation checklist.
+
+## Step 6: Validate the file
+
+After writing the agent file, run both checks from the [template](template.md) reference:
+
+1. Structural validation: verify frontmatter, no `model:` field, `## Abilities` is the only `##` heading, one identity paragraph, abilities categorized, one file only.
+2. Skill reference validation: verify every `@skill-name` in `## Abilities` exists in `.agents/skills/` and in `skills-lock.json`.
+
+If either check fails, fix the file and re-validate.
+
+## Step 7: Update fullstack-engineer.md abilities
+
+The `fullstack-engineer.md` is `mode: primary`, the planning session agent, not a spawned worker. Having all skills here is fine since it does planning, not parallel implementation.
+
+After creating the persona engineer and validating its references, additively merge new skills into fullstack:
+
+1. Read `.agents/skills/` directory to list all installed skills.
+2. Read `skills-lock.json` for npx-installed skills.
+3. Read the current `fullstack-engineer.md`.
+4. Parse its existing `## Abilities` section to find which skills are already listed.
+5. Append-only: add only skills that are not already in the file (dedup by skill name).
+6. Preserve the frontmatter (mode, color, permissions, model if stamped), the identity paragraph, and all existing ability lines.
+7. Remove any old startup directive line. The `pc-system-reminders` plugin loads abilities for every session.
+8. Write the file back.
+
+Merge new skills into existing categories. If a new skill belongs to "Development" and that line already exists, append to it. If a new category is needed, add it. Do not overwrite the Abilities section.
+
+## Step 8: Update AGENTS.md
+
+Add the new agent to the agents table in AGENTS.md (if a table exists) or note it:
+```
+| `{persona}-engineer` | .opencode/agents/{persona}-engineer.md | <short role description> |
+```
+
+## Step 9: Show summary
+
+Report:
+- Engineer file created at `.opencode/agents/{persona}-engineer.md`
+- Skills installed from skills.sh (list each with source and install count)
+- Signals with no quality skill found on skills.sh (list each)
+- Skills that failed validation or install (list each with reason)
+- `fullstack-engineer.md` updated (additive, list new skills added)
+- How to use: "This agent will be spawned by the lead during `/plan-apply` for tasks matching its specialty."
+- "Restart opencode for the `pc-subagent-tiers` plugin to pick up the new engineer."

package/src/content/.agents/skills/pc-make-engineer/signal-mapping.md

@@ -0,0 +1,68 @@
+# Signal-to-query mapping
+
+For each uncovered signal, run a mandatory `npx skills find` with a specific query. Every uncovered signal gets its own search. No signal is skipped. Capture the output of each 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`) |
+
+If a signal doesn't fit any table row, derive a query from the signal value itself: `npx skills find "<signal-value>"`.
+
+## Known direct sources (architecture and patterns)
+
+Some high-value skills live in dedicated repos and install by direct `owner/repo` reference, so `npx skills find` never surfaces them. When the persona is `frontend` / `backend` / `layout` / `api`, or the user selected an architecture/pattern in Step 3, pull from this table:
+
+| Selection (Step 3) | 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` |
+
+Rules for this table:
+- Pick only skills relevant to the persona and the user's Step 3 selections.
+- Cap patterns.dev picks at 2-3 of the most relevant. Full catalog: https://www.patterns.dev/ai/skills/catalog/
+- These sources are curated and canonical, so they are exempt from the install-count filter below.
+- Add the resolved skills to the recommended set. They are installed only after the user confirms.
+
+## Quality filter
+
+From each search result, select the best candidate using these rules in order:
+
+1. Install count at least 100. Skip anything below. Prefer at least 1000.
+2. Official or canonical source. Prefer `vercel-labs`, `anthropics`, `microsoft`, `feature-sliced`, `wshobson`, `github` over unknown authors.
+3. Topical match. The skill description must clearly match the signal. A React skill with 500K installs doesn't cover TypeScript if its description is only about React components.
+4. If the top result is below 100 installs, record "no quality skill found on skills.sh for \<signal\>" and move on.
+
+## Assembling the recommended set
+
+Combine the winners from the `npx skills find` searches and the known direct sources into a single recommended set:
+
+- Minimum = number of detected persona-relevant signals (if 6 signals detected, aim for at least 6 skills, one per signal minimum)
+- Ideal range: 5-8 for most engineers
+- Hard cap: 10. If more candidates found, rank by install count and source reputation and keep the top 10.
+- No redundant skills. If an already-selected skill covers the same scope as a new candidate (e.g. `vercel-react-best-practices` already covers TypeScript basics), skip the new candidate unless it provides genuinely deeper coverage for a different concern.
+- If fewer than 5 skills are found after all searches, note it. The user can still add more in the confirmation form.
+
+## Post-install verification
+
+After each `npx skills add`, verify the skill actually landed and tracked itself in the lockfile:
+
+1. Check `.agents/skills/<skill-name>/SKILL.md` exists
+2. Check `skills-lock.json` now contains the skill entry (read it back, do not assume the entry was written)
+
+If `.agents/skills/<skill-name>/SKILL.md` exists but `skills-lock.json` does not contain the entry: manually patch the lockfile using the Edit tool. Open `skills-lock.json`, add a new entry inside the `"skills"` object using the `owner/repo` from the install command and the structure `"source": "<owner/repo>", "sourceType": "github", "skillPath": "skills/<skill-name>/SKILL.md", "computedHash": "<skill-name>-placeholder"`. Match the existing entries' key naming. Re-read `skills-lock.json` to confirm the entry is valid JSON.
+
+If `.agents/skills/<skill-name>/SKILL.md` is missing (network glitch, wrong repo name, auth issue): retry the install once. If still failing, drop the skill from the selection and note it in the summary as "install failed".

package/src/content/.agents/skills/pc-make-engineer/template.md

@@ -0,0 +1,81 @@
+# Agent file template
+
+The agent file is exactly this structure: frontmatter plus one identity paragraph plus the `## Abilities` section. No other sections. No other content.
+
+```markdown
+---
+description: <one sentence naming the persona + top 3-5 detected technologies>
+mode: primary
+color: <pick: primary|secondary|accent|error|info: avoid colors used by existing agents; warning is reserved for the lead engineer>
+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>, ...
+```
+
+That is the entire file: frontmatter, one identity paragraph, and the `## Abilities` section. The always-installed `pc-system-reminders` plugin loads the listed skills for every session. Replace every `<...>` placeholder with real values from your research. Remove any ability category line that has no skills assigned (besides Guardrails which is always present).
+
+## Description quality bar
+
+The `description:` field is the matching key for `/plan-apply`. The lead compares task domain text against agent descriptions to pick the right specialist. A weak description means the wrong engineer gets spawned.
+
+Bad: `"A frontend engineer for React"`
+Good: `"Frontend engineer for Ink 7 + React 19 TUI, FSD architecture, Inversify DI, design tokens, and i18n"`
+
+Rules:
+- Name the persona explicitly
+- List the top 3-5 detected technologies from Step 2
+- One sentence, no padding
+
+## Identity paragraph
+
+The identity paragraph sits between frontmatter and `## Abilities`. It tells the engineer who it is and what it owns in 2-3 sentences max. Not a spec, not a knowledge dump, a quick scoping statement.
+
+Bad: 5 paragraphs of architecture details, FSD rules, design tokens, file maps, testing patterns.
+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/."`
+
+Rules:
+- State the persona and specialization in one sentence
+- State what files or layers the engineer owns in one sentence
+- Never exceed 3 sentences
+
+## Category rules
+
+- Development = language/framework/UI/DI skills. Testing = test/lint/typecheck skills. Infrastructure = DevOps/CI/CD/cloud skills.
+- Only include ability categories that have at least one real skill (besides Guardrails which is always present).
+- Name follows `{persona}-engineer` pattern (e.g. `frontend-engineer`, `backend-engineer`).
+- Read existing agents' `color:` frontmatter first: pick a color not already used.
+- `warning` is reserved for the lead (fullstack) engineer, the planning agent. Never assign it to a spawned specialist.
+
+## Structural validation checklist
+
+After writing the agent file, verify:
+
+1. Frontmatter exists: starts with `---`, has `description`, `mode: primary`, `color`, `permission` block.
+2. No `model:` field in the frontmatter. The `pc-subagent-tiers` plugin injects it.
+3. `## Abilities` is the only `##` heading. No other `##` sections exist in the file.
+4. One identity paragraph before `## Abilities`: 2-3 sentences max, not multiple paragraphs.
+5. Abilities are categorized: each line starts with `- Guardrails:`, `- Development:`, `- Testing:`, or `- Infrastructure:`. No bare `@skill-name` lines.
+6. One file only: no `.build.md`, `.fast.md`, or `.plan.md` variant was created.
+
+If any check fails, rewrite the file to match the template exactly.
+
+## Skill reference validation
+
+1. Parse every `@skill-name` from the `## Abilities` section (excluding `@pc-guardrails-generic` and `@pc-guardrails-project` which are installed at init).
+2. For each: check `.agents/skills/<skill-name>/SKILL.md` exists.
+3. For each: check `skills-lock.json` contains the skill.
+4. If `.agents/skills/<skill-name>/SKILL.md` exists but `skills-lock.json` is missing the entry: manually patch `skills-lock.json` using the Edit tool (same procedure as in the signal mapping reference). Re-read `skills-lock.json` to confirm it is valid JSON.
+5. If `.agents/skills/<skill-name>/SKILL.md` is missing: try to install it: `npx skills add -y <owner/repo@skill-name>` (search `skills-lock.json` or `npx skills find` for the owner/repo). If install fails or the skill can't be found on skills.sh, remove the reference from the file, warn the user, and note it in the summary.
+6. Re-read the file to confirm all remaining `@skill-name` references are valid.

package/src/content/.agents/skills/pc-make-evidence-scaffold/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pc-make-evidence-scaffold
+description: DEPRECATED. Visual evidence is now built into pc-ops-evidence using playwright-cli + pnpm run dev. No per-project scaffold is needed. This skill is kept for backward compatibility but should not be used.
+license: MIT
+---
+
+# DEPRECATED
+
+This skill is no longer needed. Visual evidence uses a two-phase architecture:
+
+1. **Agent phase:** `pc-ops-evidence` writes a `capturePlan` in `evidence.json` (the agent sandbox cannot run Docker or headless Chromium)
+2. **CI phase:** A separate "Visual evidence" CI workflow reads the capturePlan and captures screenshots on a runner with full Docker and Chrome access
+
+No per-project scaffold, fixture apps, or scenario registries are required. The `pc-ops-evidence` skill handles everything generically.
+
+If you previously ran `/make-evidence-scaffold` and have a `src/visual-evidence/` directory or `visual-evidence` scripts in `package.json`, you can delete them — the new system does not use them.
+
+To capture evidence for a change, just run `/ops-evidence` or let `/plan-goal` handle it automatically.