@plainconceptsplatform/agent-harness 2.4.1 → 2.5.0

package/cli/steps/copy/agents.js

@@ -6,17 +6,17 @@ import { info, success, warn } from '../../utils/exec.js'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const agentsContent = await fse.readJson(path.resolve(__dirname, '../../presets/agents-content.json'))
 
-// Steps are matched by their title text, not by exact heading string:
-// heading level (###/####) and step numbers have drifted before and silently
-// broke removal. Matching `^#{3,4} Step N, <title>` survives both.
+// Steps are matched by their title text, not by exact heading string: heading
+// level (##/###/####), the `Step N,` prefix and any ` (if Yes)` suffix have all
+// drifted before, and every drift silently turned the patch into a no-op that
+// only showed up as a warning nobody read.
 const HISTORY_STEP_TITLE = 'Archive project history'
-const CHAIN_STEP_TITLE = 'Chain make commands'
-
-const CHAIN_CONFIRM_LINE = '- ARCHITECTURE.md generated'
+const ARCHITECTURE_STEP_TITLE = 'Generate ARCHITECTURE.md'
+const DESIGN_STEP_TITLE = 'Generate DESIGN.md'
 
 function stepHeadingPattern(title) {
   const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  return new RegExp(`^#{2,4} Step \\d+, ${escaped}`)
+  return new RegExp(`^#{2,4}\\s+(?:Step\\s+\\d+[a-z]?[,:]\\s+)?${escaped}\\b`, 'i')
 }
 
 // The step heading is kept and its body replaced with an explicit skip note.
@@ -29,19 +29,19 @@ export function skipStepBlock(content, title, note) {
   const start = lines.findIndex(l => pattern.test(l.trim()))
   if (start === -1) return { content, matched: false }
 
+  // The block ends at the next heading or rule, NOT at end of file. Scanning
+  // only for `---` meant a document without one lost everything below the
+  // matched step.
   let end = lines.length
   for (let i = start + 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') { end = i; break }
+    const line = lines[i].trim()
+    if (line === '---' || /^#{1,4}\s/.test(line)) { end = i; break }
   }
 
   lines.splice(start + 1, end - start - 1, '', `> ${note}`, '')
   return { content: lines.join('\n'), matched: true }
 }
 
-function removeConfirmLine(content, line) {
-  return content.split('\n').filter(l => l.trim() !== line.trim()).join('\n')
-}
-
 const PLATFORM_WORKFLOW_START = '<!-- PC-PLATFORM-WORKFLOW-START -->'
 const PLATFORM_WORKFLOW_END = '<!-- PC-PLATFORM-WORKFLOW-END -->'
 const PLATFORM_SKILLS_GUIDE_START = '<!-- PC-PLATFORM-SKILLS-GUIDE-START -->'
@@ -78,13 +78,15 @@ export async function patchAgentsMd(ctx) {
   const patches = []
 
   const skips = [
-    [ctx.hasOpenspec, HISTORY_STEP_TITLE, null,
+    [ctx.hasOpenspec, HISTORY_STEP_TITLE,
       'Skipped during onboarding: this project already had an openspec/ history. Do not archive again; continue with the next step.'],
-    [ctx.hasDesign || ctx.hasArchitecture, CHAIN_STEP_TITLE, CHAIN_CONFIRM_LINE,
-      'Skipped during onboarding: project files already exist. Run /make-architecture or /make-design individually to regenerate.'],
+    [ctx.hasArchitecture, ARCHITECTURE_STEP_TITLE,
+      'Skipped during onboarding: ARCHITECTURE.md already exists. Run /make-architecture to regenerate it, which keeps its update mode.'],
+    [ctx.hasDesign, DESIGN_STEP_TITLE,
+      'Skipped during onboarding: DESIGN.md already exists. Run /make-design to regenerate it, which keeps its update mode.'],
   ]
 
-  for (const [enabled, title, confirmLine, note] of skips) {
+  for (const [enabled, title, note] of skips) {
     if (!enabled) continue
     const result = skipStepBlock(content, title, note)
     if (!result.matched) {
@@ -92,7 +94,6 @@ export async function patchAgentsMd(ctx) {
       continue
     }
     content = result.content
-    if (confirmLine) content = removeConfirmLine(content, confirmLine)
     patches.push(`Step "${title}" marked as skipped, file already exists`)
   }
 

package/cli/steps/copy/opencode-json.js

@@ -54,7 +54,8 @@ export async function patchOpencodeJson(cwd = process.cwd()) {
   const needsAgentOverride = hasStaleDisable || !(
     parsed?.agent?.build?.mode === 'primary' &&
     parsed?.agent?.plan?.mode === 'primary' &&
-    parsed?.agent?.plan?.permission?.edit === 'deny'
+    parsed?.agent?.plan?.permission?.edit === 'deny' &&
+    parsed?.agent?.plan?.permission?.task === 'deny'
   )
 
   // default_agent pointing at fullstack-engineer is now invalid: it became a
@@ -97,6 +98,9 @@ export async function patchOpencodeJson(cwd = process.cwd()) {
     text = applyModify(text, ['agent', 'build', 'mode'], 'primary')
     text = applyModify(text, ['agent', 'plan', 'mode'], 'primary')
     text = applyModify(text, ['agent', 'plan', 'permission', 'edit'], 'deny')
+    // Read-only has to include spawning: a plan session that can call task()
+    // can have a build worker make the change for it.
+    text = applyModify(text, ['agent', 'plan', 'permission', 'task'], 'deny')
   }
   if (needsDefaultAgent) {
     text = applyModify(text, ['default_agent'], 'plan')

package/cli/steps/copy/skills.js

@@ -51,6 +51,75 @@ const MARKER_SKILLS = new Set([
   'pc-repo-initialize',
 ])
 
+// Marker skills whose prose must track the shipped version on update.
+//
+// These are shipped content, not project content: the project-specific part is
+// injected into their marker pairs, and the platform patchers plus
+// patchGuardrails re-inject it immediately after this copy. Treating them as
+// project-owned froze their prose at whatever version a consumer first
+// installed, so a skill rewrite never reached an existing repo. That is also
+// how browser-automation sat on v1.0 in five repos while the harness shipped
+// v2.0.
+//
+// pc-repo-initialize is deliberately absent. patchAgentsMd stamps "skipped
+// during onboarding" notes into it that only run on a fresh install
+// (copy/index.js runs it under `!ctx.updateMode`), so refreshing it would
+// discard decisions made at onboarding.
+const REFRESHABLE_MARKER_SKILLS = new Set([
+  'pc-guardrails-generic',
+  'pc-plan-archive',
+  'pc-ops-ship',
+  'pc-ops-evidence',
+])
+
+// A project-owned slot inside a shipped skill: the content between the markers
+// survives a refresh, everything around it takes the new shipped version. This
+// is the supported way to adapt one example to a project without forking the
+// file, which consumers have otherwise done by editing shipped prose in place.
+const PROJECT_SLOT_RE = /<!-- (PC-PROJECT-[A-Z0-9-]+)-START -->([\s\S]*?)<!-- \1-END -->/g
+// Separate, non-global: `.test()` on a /g/ regex advances lastIndex, so reusing
+// PROJECT_SLOT_RE for the check would answer false on every other call.
+const HAS_PROJECT_SLOT = /<!-- PC-PROJECT-[A-Z0-9-]+-START -->/
+
+function readProjectSlots(text) {
+  const slots = new Map()
+  for (const match of text.matchAll(PROJECT_SLOT_RE)) slots.set(match[1], match[2])
+  return slots
+}
+
+function writeProjectSlots(text, slots) {
+  if (slots.size === 0) return text
+  // Replacer function, not a replacement string: carried content can contain
+  // shell quoting like $'...', and a string replacement expands $' as
+  // "everything after the match" and truncates the file.
+  return text.replace(PROJECT_SLOT_RE, (whole, name) => {
+    const kept = slots.get(name)
+    if (kept === undefined || kept.trim() === '') return whole
+    return `<!-- ${name}-START -->${kept}<!-- ${name}-END -->`
+  })
+}
+
+async function refreshMarkerSkill(src, dest, relativeRoot) {
+  for (const entry of await fse.readdir(src, { withFileTypes: true })) {
+    const sourcePath = path.join(src, entry.name)
+    const destinationPath = path.join(dest, entry.name)
+    const relativePath = path.join(relativeRoot, entry.name)
+    if (entry.isDirectory()) {
+      await refreshMarkerSkill(sourcePath, destinationPath, relativePath)
+      continue
+    }
+    const shipped = await fse.readFile(sourcePath, 'utf-8')
+    const existing = await fse.pathExists(destinationPath)
+      ? await fse.readFile(destinationPath, 'utf-8')
+      : ''
+    const merged = writeProjectSlots(shipped, readProjectSlots(existing))
+    if (merged === existing) continue
+    await fse.ensureDir(path.dirname(destinationPath))
+    await fse.writeFile(destinationPath, merged, 'utf-8')
+    success(`Refreshed skill: ${relativePath}`)
+  }
+}
+
 async function isGeneratedSkill(dest) {
   const skillMd = path.join(dest, 'SKILL.md')
   if (!await fse.pathExists(skillMd)) return false
@@ -72,9 +141,26 @@ async function syncSkillFiles(src, dest, relativeRoot, cwd, manifest) {
       await fse.copyFile(sourcePath, destinationPath)
       await recordManagedFile(manifest, relativePath, sourcePath)
       success(`Updated skill: ${relativePath}`)
-    } else {
-      info(`Preserving modified skill file: ${relativePath}`)
+      continue
     }
+
+    // A shipped file that declares a PC-PROJECT-* slot states in its own prose
+    // that the slot is the project's and everything else is the harness's, so a
+    // hand-edited copy still takes the update: merge rather than preserve.
+    // Without this the file is frozen at whatever version the project edited,
+    // which is how five repos ended up with stale skills.
+    const shipped = await fse.readFile(sourcePath, 'utf-8')
+    if (HAS_PROJECT_SLOT.test(shipped)) {
+      const existing = await fse.readFile(destinationPath, 'utf-8')
+      const merged = writeProjectSlots(shipped, readProjectSlots(existing))
+      if (merged !== existing) {
+        await fse.writeFile(destinationPath, merged, 'utf-8')
+        success(`Refreshed skill, project slot kept: ${relativePath}`)
+      }
+      continue
+    }
+
+    info(`Preserving modified skill file: ${relativePath}`)
   }
 }
 
@@ -145,12 +231,19 @@ async function installObSkills(backlogPlatform = 'github', repoPlatform, { force
       continue
     }
     if (updateMode) {
+      const relativeRoot = path.join('.agents', 'skills', destName)
       if (!await fse.pathExists(dest)) {
-        await syncSkillFiles(src, dest, path.join('.agents', 'skills', destName), process.cwd(), manifest)
-      } else if (MARKER_SKILLS.has(destName) || GENERATABLE_SKILLS.has(destName)) {
+        await syncSkillFiles(src, dest, relativeRoot, process.cwd(), manifest)
+      } else if (GENERATABLE_SKILLS.has(destName)) {
+        info(`Preserving generated skill: ${destName}`)
+      } else if (REFRESHABLE_MARKER_SKILLS.has(destName)) {
+        // Shipped prose refreshes; the patchers re-inject the marker pairs and
+        // any PC-PROJECT-* slot is carried over.
+        await refreshMarkerSkill(src, dest, relativeRoot)
+      } else if (MARKER_SKILLS.has(destName)) {
         info(`Preserving project-owned skill: ${destName}`)
       } else {
-        await syncSkillFiles(src, dest, path.join('.agents', 'skills', destName), process.cwd(), manifest)
+        await syncSkillFiles(src, dest, relativeRoot, process.cwd(), manifest)
       }
       continue
     }

package/cli/steps/optimization/patch-guardrails.js

@@ -77,10 +77,12 @@ export async function patchGuardrails(selections = {}, { cwd = process.cwd() } =
     ).replace(
       '<!-- PC-GUARDRAILS-CAVEMAN-START -->\n\n<!-- PC-GUARDRAILS-CAVEMAN-END -->',
       '<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->\n<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->',
-    ).replace(
-      '1. Load ALL skills listed under your own `## Abilities` now (Guardrails first, then the rest), by calling the `skill` tool once per `@skill-name`.',
-      '1. The `pc-system-reminders` plugin has already loaded the skills listed under your `## Abilities`, guardrails first.',
     )
+    // A third replace used to rewrite the engineer workflow's step 1 into "the
+    // plugin has already loaded the skills". That was never true: the plugin
+    // appends a reminder and never calls the skill tool. The shipped skill now
+    // carries the honest wording, and update refreshes this file, so the
+    // migration is gone rather than perpetuated.
     for (const [key, markerSuffix] of Object.entries(MARKER_SECTIONS)) {
       let sectionContent = ''
       if (selections[key]) {

package/cli/utils/copy.js

@@ -1,6 +1,6 @@
 import fse from 'fs-extra'
 import path from 'path'
-import { canUpdateManagedFile, hashFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from './update-manifest.js'
+import { canUpdateManagedFile, hashComparableFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from './update-manifest.js'
 
 // Folders never copied (skills handled separately by installSkills, .bootstrap is internal tooling)
 const ALWAYS_EXCLUDE = ['.bootstrap', 'skills', 'node_modules']
@@ -82,8 +82,13 @@ export async function recordManagedContent(contentDir, destDir, { updateMode = f
 
       const destinationPath = path.join(destDir, relativePath)
       if (!await fse.pathExists(destinationPath)) continue
-      const sourceHash = await hashFile(sourcePath)
-      const destinationHash = await hashFile(destinationPath)
+      // Comparable, not raw: this runs after the patchers, so a managed file's
+      // destination never equals its source byte for byte once anything has
+      // been injected into a marker pair. Comparing raw hashes here meant no
+      // entry was ever recorded for those files, which left them permanently
+      // indistinguishable from files a project had edited by hand.
+      const sourceHash = await hashComparableFile(sourcePath)
+      const destinationHash = await hashComparableFile(destinationPath)
       const manifestPath = relativePath.split(path.sep).join('/')
       const previousHash = manifest.files?.[manifestPath]
       if (!updateMode || destinationHash === sourceHash || destinationHash === previousHash) {

package/cli/utils/update-manifest.js

@@ -17,6 +17,28 @@ export async function hashFile(filePath) {
   return hashContent(await fse.readFile(filePath))
 }
 
+// A file counts as untouched when it differs from what we shipped only in ways
+// the harness itself caused. Two of those, and both made the raw-bytes
+// comparison call an untouched file modified — permanently, because the flag is
+// re-derived on every update:
+//
+//   1. Marker pairs. The patchers rewrite them after the copy, so a file with
+//      any PC-* marker never matches its own source again.
+//   2. Line endings. A file that reaches a consumer's tree through git arrives
+//      CRLF on Windows while the shipped source is LF.
+//
+// This is the general form of the bug that left five repos on a stale
+// browser-automation skill through repeated updates.
+const MARKER_PAIR = /(<!-- PC-[A-Z0-9-]+-START -->)[\s\S]*?(<!-- PC-[A-Z0-9-]+-END -->)/g
+
+function comparableContent(buffer) {
+  return buffer.toString('utf-8').replace(/\r\n/g, '\n').replace(MARKER_PAIR, '$1$2')
+}
+
+export async function hashComparableFile(filePath) {
+  return hashContent(comparableContent(await fse.readFile(filePath)))
+}
+
 export async function readUpdateManifest(cwd = process.cwd()) {
   const manifestPath = path.join(cwd, MANIFEST_RELATIVE_PATH)
   const manifest = await fse.readJson(manifestPath).catch(() => ({ version: 1, files: {} }))
@@ -36,12 +58,16 @@ export async function canUpdateManagedFile(relativePath, cwd, manifest) {
   if (!await fse.pathExists(destinationPath)) return true
   const previousHash = manifest.files?.[normalizedPath]
   if (!previousHash) return false
-  return previousHash === await hashFile(destinationPath)
+  // Raw is accepted too: manifests written before this comparison existed hold
+  // raw source hashes, and re-recording them all would need an update to run
+  // first, which is the thing being unblocked.
+  return previousHash === await hashComparableFile(destinationPath)
+    || previousHash === await hashFile(destinationPath)
 }
 
 export async function recordManagedFile(manifest, relativePath, sourcePath) {
   const files = manifest.files
-  files[normalizeRelativePath(relativePath)] = await hashFile(sourcePath)
+  files[normalizeRelativePath(relativePath)] = await hashComparableFile(sourcePath)
 }
 
 export function manifestPath() {

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

@@ -1,68 +1,47 @@
----
-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 name the optimization skills this project selected. Load each one before doing any work.
+
+## Secrets
+
+- Treat `.env` files as write-only: write to them when configuring, and read credentials at runtime from the environment or the secret store.
+- Never put a credential, API key or token in a log line, an output, or a commit in anything but encrypted or template form. Anything printed is in a CI log that outlives the run.
+
+## Code
+
+- Comments are for WHY, not WHAT. Use them only where the code does something non-obvious or the reason cannot be inferred from context. Past a 10% comment ratio in a file, refactor for clarity instead.
+- Never add a file that collects unrelated things — `constants.js`, `types.ts`, `config.js`, `utils.ts`. One responsibility per file, split by domain or feature (`user-constants.ts`, `order-types.ts`, `auth-config.ts`). A file importing from many unrelated modules is already the symptom.
+
+## Temporary files
+
+- Never write outside `$REPO_ROOT`, and never to an operating-system temporary directory: the next step and the next agent cannot see it, and nobody cleans it up. Scratch goes under `$REPO_ROOT/.opencode/.tmp/`, in a task-specific child directory when needed (enforced by pc-system-reminders).
+- Never report a path under `.tmp/` as a deliverable. Copy or move the artifact to its required repository path first.
+- Never leave scratch files behind at the end of a task, unless they are the evidence for a failure you are reporting.
+
+<!-- PC-GUARDRAILS-RTK-START -->
+<!-- PC-GUARDRAILS-RTK-END -->
+
+<!-- PC-GUARDRAILS-CODEGRAPH-START -->
+<!-- PC-GUARDRAILS-CODEGRAPH-END -->
+
+<!-- PC-GUARDRAILS-MEMORY-START -->
+<!-- PC-GUARDRAILS-MEMORY-END -->
+
+<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->
+<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->
+
+<!-- PC-GUARDRAILS-HUMANIZER-START -->
+<!-- PC-GUARDRAILS-HUMANIZER-END -->
+
+## Engineer workflow (when spawned)
+
+The lead put your task IDs and their text in your prompt. Two things about that are not up to you:
+
+- Load every skill under your `## Abilities` before you start, guardrails first, one `skill` call per `@skill-name`. Editing, shell and spawning are blocked until you have (pc-system-reminders).
+- Edit only files in your assigned scope, then return a summary: task IDs done, files changed, tests and lint result, decisions made. Then you exit. Never poll for more work, and never claim a task the lead did not give you: the lead spawns with the work in hand, so a worker that waits is a worker that hangs the wave.

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

@@ -1,51 +1,31 @@
----
-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
+
+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> -->`.
+
+## 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/harness/.agents/skills/pc-make-design/SKILL.md

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