@plainconceptsplatform/agent-harness 2.0.0 → 2.0.1

package/src/content/.agents/skills/browser-automation/SKILL.md

@@ -1,66 +1,66 @@
----
-name: browser-automation
-description: Reliable, composable browser automation using OpenCode Browser primitives. 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 opencode-browser extension installed and running.
-metadata:
-  author: copilots
-  version: "1.0"
----
-
-This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and queries 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. Inspect tabs with `browser_get_tabs`
-2. Open new tabs with `browser_open_tab` when needed
-3. Navigate with `browser_navigate` if needed
-4. Wait for UI using `browser_query` with `timeoutMs`
-5. Discover candidates using `browser_query` with `mode=list`
-6. Click, type, or select using `index`
-7. Confirm using `browser_query` or `browser_snapshot`
-
-## CLI-first debugging
-
-- List all available tools: `npx @different-ai/opencode-browser@4.6.1 tools`
-- Run one tool directly: `npx @different-ai/opencode-browser@4.6.1 tool browser_status`
-- Pass JSON args: `npx @different-ai/opencode-browser@4.6.1 tool browser_query --args '{"mode":"page_text"}'`
-- Run smoke test: `npx @different-ai/opencode-browser@4.6.1 self-test`
-- After `update`, reload the unpacked extension in `chrome://extensions`
-
-## Selecting options
-
-- Use `browser_select` for native `<select>` elements
-- Prefer `value` or `label`; use `optionIndex` when needed
-- Example: `browser_select({ selector: "select", value: "plugin" })`
-
-## Query modes
-
-- `text`: read visible text from a matched element
-- `value`: read input values
-- `list`: list many matches with text/metadata
-- `exists`: check presence and count
-- `page_text`: extract visible page text
-
-## Opening tabs
-
-- Use `browser_open_tab` to create a new tab, optionally with `url` and `active`
-- Example: `browser_open_tab({ url: "https://example.com", active: false })`
-
-## Troubleshooting
-
-- If a selector fails, run `browser_query` with `mode=page_text` to confirm the content exists
-- Use `mode=list` on broad selectors (`button`, `a`, `*[role="button"]`, `*[role="listitem"]`) and choose by index
-- For inbox/chat panes, try text selectors first (`text:Subject line`) then verify selection with `browser_query`
-- For scrollable containers, pass both `selector` and `x`/`y` to `browser_scroll` and then verify `scrollTop`
-
-## Scope
-
-- Screenshots of locally running app on `localhost` URLs: in scope
-- Click, type, scroll, query 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 OpenCode Browser primitives. 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 opencode-browser extension installed and running.
+metadata:
+  author: copilots
+  version: "1.0"
+---
+
+This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and queries 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. Inspect tabs with `browser_get_tabs`
+2. Open new tabs with `browser_open_tab` when needed
+3. Navigate with `browser_navigate` if needed
+4. Wait for UI using `browser_query` with `timeoutMs`
+5. Discover candidates using `browser_query` with `mode=list`
+6. Click, type, or select using `index`
+7. Confirm using `browser_query` or `browser_snapshot`
+
+## CLI-first debugging
+
+- List all available tools: `npx @different-ai/opencode-browser@4.6.1 tools`
+- Run one tool directly: `npx @different-ai/opencode-browser@4.6.1 tool browser_status`
+- Pass JSON args: `npx @different-ai/opencode-browser@4.6.1 tool browser_query --args '{"mode":"page_text"}'`
+- Run smoke test: `npx @different-ai/opencode-browser@4.6.1 self-test`
+- After `update`, reload the unpacked extension in `chrome://extensions`
+
+## Selecting options
+
+- Use `browser_select` for native `<select>` elements
+- Prefer `value` or `label`; use `optionIndex` when needed
+- Example: `browser_select({ selector: "select", value: "plugin" })`
+
+## Query modes
+
+- `text`: read visible text from a matched element
+- `value`: read input values
+- `list`: list many matches with text/metadata
+- `exists`: check presence and count
+- `page_text`: extract visible page text
+
+## Opening tabs
+
+- Use `browser_open_tab` to create a new tab, optionally with `url` and `active`
+- Example: `browser_open_tab({ url: "https://example.com", active: false })`
+
+## Troubleshooting
+
+- If a selector fails, run `browser_query` with `mode=page_text` to confirm the content exists
+- Use `mode=list` on broad selectors (`button`, `a`, `*[role="button"]`, `*[role="listitem"]`) and choose by index
+- For inbox/chat panes, try text selectors first (`text:Subject line`) then verify selection with `browser_query`
+- For scrollable containers, pass both `selector` and `x`/`y` to `browser_scroll` and then verify `scrollTop`
+
+## Scope
+
+- Screenshots of locally running app on `localhost` URLs: in scope
+- Click, type, scroll, query 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/src/content/.agents/skills/pc-guardrails-generic/SKILL.md

@@ -1,68 +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.
+---
+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

@@ -1,8 +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. -->
+---
+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

@@ -1,51 +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."
+---
+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

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

@@ -1,68 +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."
+---
+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."