@plainconceptsplatform/agent-harness 3.2.0 → 3.3.0

package/cli/commands/wizard.js

@@ -1,134 +1,134 @@
-import { select as wizardSelect } from '@inquirer/prompts'
-import chalk from 'chalk'
-import { ensureGitLongpaths } from './shared.js'
-import { chooseSourceScope } from '../steps/source/index.js'
-import { cleanAiFiles } from '../steps/clean/index.js'
-import { choosePlatform } from '../steps/platform/index.js'
-import { copyContentStep } from '../steps/copy/index.js'
-import { initOpenspec } from '../steps/openspec/index.js'
-import { chooseModels } from '../steps/models/index.js'
-import { tokenOptimizationStep } from '../steps/optimization/index.js'
-import { installBrowser } from '../steps/browser/index.js'
-import { writeHarnessConfig } from '../steps/metadata/index.js'
-
-export async function runWizard(version) {
-  const logo = chalk.hex('#fe3d57')
-  const bannerLines = [
-    logo('                             '),
-    logo('        ▒▒▒▒▒▒▒▒▒▒▒▒▒        '),
-    logo('        ▒▒▓       ▓▒▓        '),
-    logo('   ▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒   '),
-    logo('  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓  '),
-    logo(' ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓ '),
-    logo(' ▓▒▒▒▒░░░▒▒▒▒▒▒▒▒▒▒▒░░░▒▒▒▓▓ '),
-    logo('  ▓▓▓▓▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▓▓▓▓  '),
-    logo('  ▓▓▒▒▒▒▒▒░▒▒▒▒▒▒▒░▒▒▒▒▒▒▓▓  '),
-    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
-    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
-    logo('   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    '),
-    '',
-    chalk.bold('        🧰 agent-harness') + chalk.dim(` v${version}`),
-    chalk.dim('        Prepare your codebase for AI agents'),
-  ]
-
-  for (const line of bannerLines) console.log(line)
-  console.log()
-  console.log('  This tool will set up your project with a team of AI agents,')
-  console.log('  install skills, select models, and configure OpenCode.')
-  console.log()
-
-  // Only wait for Enter in a real interactive TTY
-  if (process.stdin.isTTY) {
-    console.log(chalk.bold('  Press Enter to begin...'))
-    console.log()
-    await new Promise(resolve => {
-      process.stdin.resume()
-      process.stdin.once('data', () => {
-        process.stdin.pause()
-        resolve()
-      })
-    })
-  }
-
-  const longpathsConfigured = await ensureGitLongpaths()
-  if (longpathsConfigured) console.log(chalk.dim('  Git long paths enabled for this repository.'))
-
-  const scope = await chooseSourceScope()
-
-  const maxConcurrentAgents = await wizardSelect({
-    message: 'Max concurrent agents:',
-    default: 3,
-    choices: [
-      { name: '1', value: 1, description: 'Serial: one agent at a time' },
-      { name: '2', value: 2, description: 'Conservative: lower resource usage' },
-      { name: '3 (default)', value: 3, description: 'Recommended: balances speed vs MCP load' },
-      { name: '4', value: 4, description: 'Higher parallelism' },
-      { name: '5', value: 5, description: 'Maximum: needs more resources' },
-    ],
-  })
-
-  const installScope = await wizardSelect({
-    message: 'Install dependencies:',
-    default: 'local',
-    choices: [
-      { name: 'Locally (default)', value: 'local', description: 'Install tools project-locally where possible' },
-      { name: 'Globally', value: 'global', description: 'Install tools globally (affects all projects on this machine)' },
-    ],
-  })
-
-  const preserve = await cleanAiFiles({ removeLegacyConfig: true })
-  const ctx = { ...preserve, ...scope, maxConcurrentAgents, installScope }
-
-  const { backlogPlatform, repoPlatform } = await choosePlatform()
-
-  await copyContentStep({ backlogPlatform, repoPlatform }, ctx)
-
-  const openspec = await initOpenspec()
-
-  const selectedModels = await chooseModels()
-
-  const tokenOpt = await tokenOptimizationStep({ ctx })
-  const { rtk, quota, simpleEnglish, codegraph, memory, humanizer } = tokenOpt
-
-  await installBrowser()
-
-  await writeHarnessConfig({
-    ...ctx,
-    backlogPlatform,
-    repoPlatform,
-    openspec,
-    maxConcurrentAgents,
-    installScope,
-    additionalSkillsProvider: 'npx-skills',
-    ...selectedModels,
-    optionalTools: { rtk, quota, simpleEnglish, codegraph, memory, humanizer },
-  })
-
-  const toGenerate = [
-    !ctx.hasDesign && 'DESIGN.md',
-    !ctx.hasArchitecture && 'ARCHITECTURE.md',
-  ].filter(Boolean)
-
-  console.log()
-  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
-  console.log(chalk.bold.green('  Onboarding complete!'))
-  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
-  console.log()
-  console.log('  Open this project in OpenCode and type:')
-  console.log(chalk.bold('  "/init"'))
-  console.log('  Or run the following command in your terminal:')
-  console.log(chalk.bold('  opencode --prompt "/init" --model "opencode/big-pickle"  '))
-  console.log()
-  console.log(chalk.dim('  Note: the first time you open OpenCode in this project,'))
-  console.log(chalk.dim('  it will install plugin dependencies. You may see a black'))
-  console.log(chalk.dim('  screen for a moment: this is normal. Wait for it to load.'))
-  console.log()
-  if (toGenerate.length > 0) {
-    console.log(`  OpenCode will generate ${toGenerate.join(' and ')}`)
-    console.log('  from your actual codebase, then activate the agent team.')
-  } else {
-    console.log('  OpenCode will activate the agent team.')
-  }
-  console.log(`  Source scope: ${ctx.sourceMode === 'parent-selected' ? ctx.sourceRoots.map(p => `../${p.split(/[/\\]/).pop()}`).join(', ') : 'current folder'}`)
-  console.log()
-}
+import { select as wizardSelect } from '@inquirer/prompts'
+import chalk from 'chalk'
+import { ensureGitLongpaths } from './shared.js'
+import { chooseSourceScope } from '../steps/source/index.js'
+import { cleanAiFiles } from '../steps/clean/index.js'
+import { choosePlatform } from '../steps/platform/index.js'
+import { copyContentStep } from '../steps/copy/index.js'
+import { initOpenspec } from '../steps/openspec/index.js'
+import { chooseModels } from '../steps/models/index.js'
+import { tokenOptimizationStep } from '../steps/optimization/index.js'
+import { installBrowser } from '../steps/browser/index.js'
+import { writeHarnessConfig } from '../steps/metadata/index.js'
+
+export async function runWizard(version) {
+  const logo = chalk.hex('#fe3d57')
+  const bannerLines = [
+    logo('                             '),
+    logo('        ▒▒▒▒▒▒▒▒▒▒▒▒▒        '),
+    logo('        ▒▒▓       ▓▒▓        '),
+    logo('   ▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒   '),
+    logo('  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓  '),
+    logo(' ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓ '),
+    logo(' ▓▒▒▒▒░░░▒▒▒▒▒▒▒▒▒▒▒░░░▒▒▒▓▓ '),
+    logo('  ▓▓▓▓▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▓▓▓▓  '),
+    logo('  ▓▓▒▒▒▒▒▒░▒▒▒▒▒▒▒░▒▒▒▒▒▒▓▓  '),
+    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
+    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
+    logo('   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    '),
+    '',
+    chalk.bold('        🧰 agent-harness') + chalk.dim(` v${version}`),
+    chalk.dim('        Prepare your codebase for AI agents'),
+  ]
+
+  for (const line of bannerLines) console.log(line)
+  console.log()
+  console.log('  This tool will set up your project with a team of AI agents,')
+  console.log('  install skills, select models, and configure OpenCode.')
+  console.log()
+
+  // Only wait for Enter in a real interactive TTY
+  if (process.stdin.isTTY) {
+    console.log(chalk.bold('  Press Enter to begin...'))
+    console.log()
+    await new Promise(resolve => {
+      process.stdin.resume()
+      process.stdin.once('data', () => {
+        process.stdin.pause()
+        resolve()
+      })
+    })
+  }
+
+  const longpathsConfigured = await ensureGitLongpaths()
+  if (longpathsConfigured) console.log(chalk.dim('  Git long paths enabled for this repository.'))
+
+  const scope = await chooseSourceScope()
+
+  const maxConcurrentAgents = await wizardSelect({
+    message: 'Max concurrent agents:',
+    default: 3,
+    choices: [
+      { name: '1', value: 1, description: 'Serial: one agent at a time' },
+      { name: '2', value: 2, description: 'Conservative: lower resource usage' },
+      { name: '3 (default)', value: 3, description: 'Recommended: balances speed vs MCP load' },
+      { name: '4', value: 4, description: 'Higher parallelism' },
+      { name: '5', value: 5, description: 'Maximum: needs more resources' },
+    ],
+  })
+
+  const installScope = await wizardSelect({
+    message: 'Install dependencies:',
+    default: 'local',
+    choices: [
+      { name: 'Locally (default)', value: 'local', description: 'Install tools project-locally where possible' },
+      { name: 'Globally', value: 'global', description: 'Install tools globally (affects all projects on this machine)' },
+    ],
+  })
+
+  const preserve = await cleanAiFiles({ removeLegacyConfig: true })
+  const ctx = { ...preserve, ...scope, maxConcurrentAgents, installScope }
+
+  const { backlogPlatform, repoPlatform } = await choosePlatform()
+
+  await copyContentStep({ backlogPlatform, repoPlatform }, ctx)
+
+  const openspec = await initOpenspec()
+
+  const selectedModels = await chooseModels()
+
+  const tokenOpt = await tokenOptimizationStep({ ctx })
+  const { rtk, quota, simpleEnglish, codegraph, memory, humanizer } = tokenOpt
+
+  await installBrowser()
+
+  await writeHarnessConfig({
+    ...ctx,
+    backlogPlatform,
+    repoPlatform,
+    openspec,
+    maxConcurrentAgents,
+    installScope,
+    additionalSkillsProvider: 'npx-skills',
+    ...selectedModels,
+    optionalTools: { rtk, quota, simpleEnglish, codegraph, memory, humanizer },
+  })
+
+  const toGenerate = [
+    !ctx.hasDesign && 'DESIGN.md',
+    !ctx.hasArchitecture && 'ARCHITECTURE.md',
+  ].filter(Boolean)
+
+  console.log()
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log(chalk.bold.green('  Onboarding complete!'))
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log()
+  console.log('  Open this project in OpenCode and type:')
+  console.log(chalk.bold('  "/init"'))
+  console.log('  Or run the following command in your terminal:')
+  console.log(chalk.bold('  opencode --prompt "/init" --model "opencode/big-pickle"  '))
+  console.log()
+  console.log(chalk.dim('  Note: the first time you open OpenCode in this project,'))
+  console.log(chalk.dim('  it will install plugin dependencies. You may see a black'))
+  console.log(chalk.dim('  screen for a moment: this is normal. Wait for it to load.'))
+  console.log()
+  if (toGenerate.length > 0) {
+    console.log(`  OpenCode will generate ${toGenerate.join(' and ')}`)
+    console.log('  from your actual codebase, then activate the agent team.')
+  } else {
+    console.log('  OpenCode will activate the agent team.')
+  }
+  console.log(`  Source scope: ${ctx.sourceMode === 'parent-selected' ? ctx.sourceRoots.map(p => `../${p.split(/[/\\]/).pop()}`).join(', ') : 'current folder'}`)
+  console.log()
+}

package/cli/fragments/archive/az.md

@@ -1,97 +1,97 @@
-2. **Find the oldest change with a completed PR**
-
-   List unarchived changes (top-level only, excludes `archive/`):
-
-   ```bash
-   find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
-   ```
-
-   If empty, report a blocker and stop.
-
-   List completed PRs:
-
-   ```bash
-   az repos pr list --repository {repo} --status completed --query "sort_by(@, &closedDate)[].{name:title,sourceRefName:sourceRefName,closedDate:closedDate,pullRequestId:pullRequestId}"
-   ```
-
-   Match each change to a completed PR using its ID and slug as search hints:
-   - No match → skip (record as blocked: `no merged PR found`).
-   - One match → eligible.
-   - Multiple matches → ask the user which PR belongs to that change.
-
-   If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** PR `closedDate` as the candidate.
-
-3. **Confirm the candidate**
-
-   Show the candidate (ID, title, PR ID, merged date) and any blocked changes, then ask:
-
-   ```text
-   Oldest unarchived merged change found:
-     ID: {change-id}
-     Title: {title from resolved PR}
-     PR ID: {pullRequestId}
-     Merged: {closedDate}
-
-   Proceed with archiving? [yes/no]
-   ```
-
-   Stop if the user does not confirm.
-
-4. **Archive the change**
-
-   ```bash
-   git checkout -b archive/{change-id}
-   ```
-
-   Load `@openspec-archive-change` skill and follow it to archive the change.
-
-5. **Update docs**
-
-   Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
-
-6. **Create the archive PR**
-
-   ```bash
-   # Stage specific paths only: a shared tree may hold another agent's or a
-   # person's edits, and -A commits them under this message.
-   git add openspec/changes/   # plus ARCHITECTURE.md / DESIGN.md if step 5 updated them
-   git commit -m "archive: {title} ({change-id})"
-   git push origin archive/{change-id}
-
-   az repos pr create \
-     --repository {repo} \
-     --source-branch refs/heads/archive/{change-id} \
-     --target-branch "refs/heads/$DEFAULT_BRANCH" \
-     --title "archive: {title} ({change-id})" \
-     --description "Archive SDD artifacts for {change-id} after merge of {sourceRefName}." \
-     --auto-complete
-   ```
-
-   If work was stashed in step 1, restore it after the PR is created unless the user opts out.
-
-7. **Report**
-
-   Display:
-
-   ```text
-   Archive complete
-
-     Change ID: {change-id}
-     Title: {title}
-     Original PR: {original-pr-link}
-     Archive PR: {archive-pr-link}
-
-     Documentation updates:
-     - ARCHITECTURE.md: {count} changes applied
-     - DESIGN.md: {count} changes applied
-   ```
-
-## Rules
-
-- All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
-- Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
-- Use change ID and slug only as search hints; do not assume the source branch name.
-- The oldest eligible merged change is the only candidate: never ask the user which change to archive (but do ask which PR if multiple match one change).
-- Never proceed if the selected PR is not completed.
-- Never use browser tools or direct web requests for Azure DevOps. Use `az` CLI only.
-- Never invent or guess PR, branch, or merge metadata.
+2. **Find the oldest change with a completed PR**
+
+   List unarchived changes (top-level only, excludes `archive/`):
+
+   ```bash
+   find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
+   ```
+
+   If empty, report a blocker and stop.
+
+   List completed PRs:
+
+   ```bash
+   az repos pr list --repository {repo} --status completed --query "sort_by(@, &closedDate)[].{name:title,sourceRefName:sourceRefName,closedDate:closedDate,pullRequestId:pullRequestId}"
+   ```
+
+   Match each change to a completed PR using its ID and slug as search hints:
+   - No match → skip (record as blocked: `no merged PR found`).
+   - One match → eligible.
+   - Multiple matches → ask the user which PR belongs to that change.
+
+   If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** PR `closedDate` as the candidate.
+
+3. **Confirm the candidate**
+
+   Show the candidate (ID, title, PR ID, merged date) and any blocked changes, then ask:
+
+   ```text
+   Oldest unarchived merged change found:
+     ID: {change-id}
+     Title: {title from resolved PR}
+     PR ID: {pullRequestId}
+     Merged: {closedDate}
+
+   Proceed with archiving? [yes/no]
+   ```
+
+   Stop if the user does not confirm.
+
+4. **Archive the change**
+
+   ```bash
+   git checkout -b archive/{change-id}
+   ```
+
+   Load `@openspec-archive-change` skill and follow it to archive the change.
+
+5. **Update docs**
+
+   Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
+
+6. **Create the archive PR**
+
+   ```bash
+   # Stage specific paths only: a shared tree may hold another agent's or a
+   # person's edits, and -A commits them under this message.
+   git add openspec/changes/   # plus ARCHITECTURE.md / DESIGN.md if step 5 updated them
+   git commit -m "archive: {title} ({change-id})"
+   git push origin archive/{change-id}
+
+   az repos pr create \
+     --repository {repo} \
+     --source-branch refs/heads/archive/{change-id} \
+     --target-branch "refs/heads/$DEFAULT_BRANCH" \
+     --title "archive: {title} ({change-id})" \
+     --description "Archive SDD artifacts for {change-id} after merge of {sourceRefName}." \
+     --auto-complete
+   ```
+
+   If work was stashed in step 1, restore it after the PR is created unless the user opts out.
+
+7. **Report**
+
+   Display:
+
+   ```text
+   Archive complete
+
+     Change ID: {change-id}
+     Title: {title}
+     Original PR: {original-pr-link}
+     Archive PR: {archive-pr-link}
+
+     Documentation updates:
+     - ARCHITECTURE.md: {count} changes applied
+     - DESIGN.md: {count} changes applied
+   ```
+
+## Rules
+
+- All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
+- Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
+- Use change ID and slug only as search hints; do not assume the source branch name.
+- The oldest eligible merged change is the only candidate: never ask the user which change to archive (but do ask which PR if multiple match one change).
+- Never proceed if the selected PR is not completed.
+- Never use browser tools or direct web requests for Azure DevOps. Use `az` CLI only.
+- Never invent or guess PR, branch, or merge metadata.

package/cli/fragments/archive/gh.md

@@ -1,96 +1,96 @@
-2. **Find the oldest change with a completed PR**
-
-   List unarchived changes (top-level only, excludes `archive/`):
-
-   ```bash
-   find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
-   ```
-
-   If empty, report a blocker and stop.
-
-   List completed PRs:
-
-   ```bash
-   gh pr list --repo {owner}/{repo} --state merged --json title,headRefName,mergedAt,number --jq 'sort_by(.mergedAt) | .[] | {name: .title, sourceRefName: .headRefName, mergedAt: .mergedAt, pullRequestId: .number}'
-   ```
-
-   Match each change to a completed PR using its ID and slug as search hints:
-   - No match → skip (record as blocked: `no merged PR found`).
-   - One match → eligible.
-   - Multiple matches → ask the user which PR belongs to that change.
-
-   If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** PR `mergedAt` as the candidate.
-
-3. **Confirm the candidate**
-
-   Show the candidate (ID, title, PR ID, merged date) and any blocked changes, then ask:
-
-   ```text
-   Oldest unarchived merged change found:
-     ID: {change-id}
-     Title: {title from resolved PR}
-     PR ID: {pullRequestId}
-     Merged: {mergedAt}
-
-   Proceed with archiving? [yes/no]
-   ```
-
-   Stop if the user does not confirm.
-
-4. **Archive the change**
-
-   ```bash
-   git checkout -b archive/{change-id}
-   ```
-
-   Load `@openspec-archive-change` skill and follow it to archive the change.
-
-5. **Update docs**
-
-   Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
-
-6. **Create the archive PR**
-
-   ```bash
-   # Stage specific paths only: a shared tree may hold another agent's or a
-   # person's edits, and -A commits them under this message.
-   git add openspec/changes/   # plus ARCHITECTURE.md / DESIGN.md if step 5 updated them
-   git commit -m "archive: {title} ({change-id})"
-   git push origin archive/{change-id}
-
-   gh pr create \
-      --repo {owner}/{repo} \
-      --base "$DEFAULT_BRANCH" \
-      --head archive/{change-id} \
-      --title "archive: {title} ({change-id})" \
-      --body "Archive SDD artifacts for {change-id} after merge."
-   ```
-
-   If work was stashed in step 1, restore it after the PR is created unless the user opts out.
-
-7. **Report**
-
-   Display:
-
-   ```text
-   Archive complete
-
-     Change ID: {change-id}
-     Title: {title}
-     Original PR: {original-pr-link}
-     Archive PR: {archive-pr-link}
-
-     Documentation updates:
-     - ARCHITECTURE.md: {count} changes applied
-     - DESIGN.md: {count} changes applied
-   ```
-
-## Rules
-
-- All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
-- Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
-- Use change ID and slug only as search hints; do not assume the source branch name.
-- The oldest eligible merged change is the only candidate: never ask the user which change to archive (but do ask which PR if multiple match one change).
-- Never proceed if the selected PR is not completed.
-- Never use browser tools or direct web requests for GitHub. Use `gh` CLI only.
-- Never invent or guess PR, branch, or merge metadata.
+2. **Find the oldest change with a completed PR**
+
+   List unarchived changes (top-level only, excludes `archive/`):
+
+   ```bash
+   find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
+   ```
+
+   If empty, report a blocker and stop.
+
+   List completed PRs:
+
+   ```bash
+   gh pr list --repo {owner}/{repo} --state merged --json title,headRefName,mergedAt,number --jq 'sort_by(.mergedAt) | .[] | {name: .title, sourceRefName: .headRefName, mergedAt: .mergedAt, pullRequestId: .number}'
+   ```
+
+   Match each change to a completed PR using its ID and slug as search hints:
+   - No match → skip (record as blocked: `no merged PR found`).
+   - One match → eligible.
+   - Multiple matches → ask the user which PR belongs to that change.
+
+   If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** PR `mergedAt` as the candidate.
+
+3. **Confirm the candidate**
+
+   Show the candidate (ID, title, PR ID, merged date) and any blocked changes, then ask:
+
+   ```text
+   Oldest unarchived merged change found:
+     ID: {change-id}
+     Title: {title from resolved PR}
+     PR ID: {pullRequestId}
+     Merged: {mergedAt}
+
+   Proceed with archiving? [yes/no]
+   ```
+
+   Stop if the user does not confirm.
+
+4. **Archive the change**
+
+   ```bash
+   git checkout -b archive/{change-id}
+   ```
+
+   Load `@openspec-archive-change` skill and follow it to archive the change.
+
+5. **Update docs**
+
+   Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
+
+6. **Create the archive PR**
+
+   ```bash
+   # Stage specific paths only: a shared tree may hold another agent's or a
+   # person's edits, and -A commits them under this message.
+   git add openspec/changes/   # plus ARCHITECTURE.md / DESIGN.md if step 5 updated them
+   git commit -m "archive: {title} ({change-id})"
+   git push origin archive/{change-id}
+
+   gh pr create \
+      --repo {owner}/{repo} \
+      --base "$DEFAULT_BRANCH" \
+      --head archive/{change-id} \
+      --title "archive: {title} ({change-id})" \
+      --body "Archive SDD artifacts for {change-id} after merge."
+   ```
+
+   If work was stashed in step 1, restore it after the PR is created unless the user opts out.
+
+7. **Report**
+
+   Display:
+
+   ```text
+   Archive complete
+
+     Change ID: {change-id}
+     Title: {title}
+     Original PR: {original-pr-link}
+     Archive PR: {archive-pr-link}
+
+     Documentation updates:
+     - ARCHITECTURE.md: {count} changes applied
+     - DESIGN.md: {count} changes applied
+   ```
+
+## Rules
+
+- All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
+- Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
+- Use change ID and slug only as search hints; do not assume the source branch name.
+- The oldest eligible merged change is the only candidate: never ask the user which change to archive (but do ask which PR if multiple match one change).
+- Never proceed if the selected PR is not completed.
+- Never use browser tools or direct web requests for GitHub. Use `gh` CLI only.
+- Never invent or guess PR, branch, or merge metadata.