@plainconceptsplatform/agent-harness 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +419 -0
  3. package/package.json +68 -0
  4. package/src/commands/join.js +244 -0
  5. package/src/commands/shared.js +27 -0
  6. package/src/commands/single.js +79 -0
  7. package/src/commands/update.js +109 -0
  8. package/src/commands/wizard.js +134 -0
  9. package/src/content/.agents/skills/browser-automation/SKILL.md +66 -0
  10. package/src/content/.agents/skills/pc-guardrails-generic/SKILL.md +68 -0
  11. package/src/content/.agents/skills/pc-guardrails-project/SKILL.md +8 -0
  12. package/src/content/.agents/skills/pc-make-architecture/SKILL.md +51 -0
  13. package/src/content/.agents/skills/pc-make-architecture/structure-template.md +38 -0
  14. package/src/content/.agents/skills/pc-make-design/SKILL.md +68 -0
  15. package/src/content/.agents/skills/pc-make-engineer/SKILL.md +219 -0
  16. package/src/content/.agents/skills/pc-make-engineer/signal-mapping.md +68 -0
  17. package/src/content/.agents/skills/pc-make-engineer/template.md +81 -0
  18. package/src/content/.agents/skills/pc-make-evidence-scaffold/SKILL.md +18 -0
  19. package/src/content/.agents/skills/pc-make-evidence-scaffold/evidence-contract.md +29 -0
  20. package/src/content/.agents/skills/pc-make-guardrails/SKILL.md +74 -0
  21. package/src/content/.agents/skills/pc-make-guardrails/category-reference.md +68 -0
  22. package/src/content/.agents/skills/pc-make-merge-risk-assess/SKILL.md +70 -0
  23. package/src/content/.agents/skills/pc-make-merge-risk-assess/category-reference.md +98 -0
  24. package/src/content/.agents/skills/pc-make-user-model/SKILL.md +66 -0
  25. package/src/content/.agents/skills/pc-ops-evidence/SKILL.md +127 -0
  26. package/src/content/.agents/skills/pc-ops-ship/SKILL.md +18 -0
  27. package/src/content/.agents/skills/pc-plan-apply/SKILL.md +83 -0
  28. package/src/content/.agents/skills/pc-plan-apply/simple-mode.md +21 -0
  29. package/src/content/.agents/skills/pc-plan-archive/SKILL.md +63 -0
  30. package/src/content/.agents/skills/pc-plan-explore/SKILL.md +9 -0
  31. package/src/content/.agents/skills/pc-plan-goal/SKILL.md +94 -0
  32. package/src/content/.agents/skills/pc-plan-goal/branching.md +30 -0
  33. package/src/content/.agents/skills/pc-plan-goal/failure-policy.md +30 -0
  34. package/src/content/.agents/skills/pc-plan-goal/output-mode.md +9 -0
  35. package/src/content/.agents/skills/pc-plan-goal/output.md +68 -0
  36. package/src/content/.agents/skills/pc-plan-propose/SKILL.md +125 -0
  37. package/src/content/.agents/skills/pc-plan-propose/task-annotation.md +39 -0
  38. package/src/content/.agents/skills/pc-plan-quick/SKILL.md +62 -0
  39. package/src/content/.agents/skills/pc-plan-story/SKILL.md +146 -0
  40. package/src/content/.agents/skills/pc-repo-audit/SKILL.md +44 -0
  41. package/src/content/.agents/skills/pc-repo-help/SKILL.md +91 -0
  42. package/src/content/.agents/skills/pc-repo-initialize/SKILL.md +130 -0
  43. package/src/content/.agents/skills/pc-repo-onboard/SKILL.md +87 -0
  44. package/src/content/.agents/skills/pc-repo-verify/SKILL.md +34 -0
  45. package/src/content/.agents/skills/pc-userstory-az/SKILL.md +157 -0
  46. package/src/content/.agents/skills/pc-userstory-browser/SKILL.md +132 -0
  47. package/src/content/.agents/skills/pc-userstory-gh/SKILL.md +120 -0
  48. package/src/content/.agents/skills/pc-userstory-jira/SKILL.md +131 -0
  49. package/src/content/.opencode/_gitignore +7 -0
  50. package/src/content/.opencode/commands/init.md +5 -0
  51. package/src/content/.opencode/commands/make-architecture.md +5 -0
  52. package/src/content/.opencode/commands/make-design.md +5 -0
  53. package/src/content/.opencode/commands/make-engineer.md +5 -0
  54. package/src/content/.opencode/commands/make-evidence-scaffold.md +5 -0
  55. package/src/content/.opencode/commands/make-guardrails.md +5 -0
  56. package/src/content/.opencode/commands/make-user-model.md +5 -0
  57. package/src/content/.opencode/commands/ops-backlog.md +10 -0
  58. package/src/content/.opencode/commands/ops-evidence.md +9 -0
  59. package/src/content/.opencode/commands/ops-review.md +8 -0
  60. package/src/content/.opencode/commands/ops-ship.md +9 -0
  61. package/src/content/.opencode/commands/plan-apply.md +9 -0
  62. package/src/content/.opencode/commands/plan-archive.md +5 -0
  63. package/src/content/.opencode/commands/plan-explore.md +9 -0
  64. package/src/content/.opencode/commands/plan-goal.md +5 -0
  65. package/src/content/.opencode/commands/plan-propose.md +9 -0
  66. package/src/content/.opencode/commands/plan-quick.md +5 -0
  67. package/src/content/.opencode/commands/plan-story.md +9 -0
  68. package/src/content/.opencode/commands/repo-audit.md +5 -0
  69. package/src/content/.opencode/commands/repo-help.md +5 -0
  70. package/src/content/.opencode/commands/repo-initialize.md +5 -0
  71. package/src/content/.opencode/commands/repo-onboard.md +5 -0
  72. package/src/content/.opencode/commands/repo-verify.md +5 -0
  73. package/src/content/.opencode/package.json +10 -0
  74. package/src/content/.opencode/plugins/pc-subagent-monitor.js +139 -0
  75. package/src/content/.opencode/plugins/pc-subagent-tiers.js +179 -0
  76. package/src/content/.opencode/plugins/pc-system-reminders.js +96 -0
  77. package/src/content/.opencode/plugins/pc-system-reminders.test.js +35 -0
  78. package/src/content/.opencode/tui/pc-subagents.tsx +98 -0
  79. package/src/content/.opencode/tui.json +6 -0
  80. package/src/content/AGENTS.md +71 -0
  81. package/src/content/ARCHITECTURE.md +16 -0
  82. package/src/content/DESIGN.md +16 -0
  83. package/src/content/opencode.jsonc +31 -0
  84. package/src/content/openspec/changes/archive/.gitkeep +0 -0
  85. package/src/content/openspec/config.yaml +20 -0
  86. package/src/content/openspec/specs/.gitkeep +0 -0
  87. package/src/content/skills-lock.json +17 -0
  88. package/src/fragments/archive/az.md +95 -0
  89. package/src/fragments/archive/gh.md +94 -0
  90. package/src/fragments/archive/gl.md +94 -0
  91. package/src/fragments/archive/none.md +73 -0
  92. package/src/fragments/guardrails/codegraph.md +7 -0
  93. package/src/fragments/guardrails/humanizer.md +4 -0
  94. package/src/fragments/guardrails/memory.md +4 -0
  95. package/src/fragments/guardrails/rtk.md +3 -0
  96. package/src/fragments/guardrails/simple-english.md +4 -0
  97. package/src/fragments/ops-backlog/az.md +29 -0
  98. package/src/fragments/ops-backlog/gh.md +30 -0
  99. package/src/fragments/ops-backlog/jira.md +29 -0
  100. package/src/fragments/ops-evidence/az.md +41 -0
  101. package/src/fragments/ops-evidence/gh.md +53 -0
  102. package/src/fragments/ops-evidence/jira.md +38 -0
  103. package/src/fragments/ops-review/az.md +63 -0
  104. package/src/fragments/ops-review/gh.md +53 -0
  105. package/src/fragments/ops-review/gl.md +57 -0
  106. package/src/fragments/ops-ship/az.md +81 -0
  107. package/src/fragments/ops-ship/gh.md +69 -0
  108. package/src/fragments/ops-ship/gl.md +86 -0
  109. package/src/index.js +107 -0
  110. package/src/presets/agents-content.json +53 -0
  111. package/src/presets/browser.json +22 -0
  112. package/src/presets/clean.json +21 -0
  113. package/src/presets/models.json +68 -0
  114. package/src/presets/openspec.json +1 -0
  115. package/src/presets/optimization.json +37 -0
  116. package/src/presets/platforms.json +76 -0
  117. package/src/presets/quota.json +16 -0
  118. package/src/presets/source.json +23 -0
  119. package/src/steps/browser/index.js +91 -0
  120. package/src/steps/clean/index.js +120 -0
  121. package/src/steps/copy/agents.js +118 -0
  122. package/src/steps/copy/commands.js +91 -0
  123. package/src/steps/copy/fullstack-engineer.js +83 -0
  124. package/src/steps/copy/index.js +88 -0
  125. package/src/steps/copy/opencode-json.js +129 -0
  126. package/src/steps/copy/skills.js +196 -0
  127. package/src/steps/metadata/index.js +108 -0
  128. package/src/steps/models/format.js +88 -0
  129. package/src/steps/models/index.js +64 -0
  130. package/src/steps/models/write.js +34 -0
  131. package/src/steps/openspec/index.js +136 -0
  132. package/src/steps/optimization/codegraph.js +127 -0
  133. package/src/steps/optimization/humanizer.js +17 -0
  134. package/src/steps/optimization/index.js +163 -0
  135. package/src/steps/optimization/memory.js +88 -0
  136. package/src/steps/optimization/patch-guardrails.js +108 -0
  137. package/src/steps/optimization/quota.js +119 -0
  138. package/src/steps/optimization/simple-english.js +17 -0
  139. package/src/steps/optimization/skills-lock.js +30 -0
  140. package/src/steps/platform/index.js +109 -0
  141. package/src/steps/source/index.js +123 -0
  142. package/src/utils/copy.js +108 -0
  143. package/src/utils/exec-spinner.js +47 -0
  144. package/src/utils/exec.js +134 -0
  145. package/src/utils/legacy-check.js +30 -0
  146. package/src/utils/models-cache.js +58 -0
  147. package/src/utils/models-pricing.js +42 -0
  148. package/src/utils/paths.js +64 -0
  149. package/src/utils/process.js +3 -0
  150. package/src/utils/terminal.js +6 -0
  151. package/src/utils/update-manifest.js +49 -0
@@ -0,0 +1,71 @@
1
+ # AGENTS.md
2
+
3
+ <!-- PC-NOT-INITIALIZED -->
4
+
5
+ # Agent operating guide
6
+
7
+ This guide defines the common operating contract for AI agents in this repository.
8
+ It is agent-agnostic and works with OpenCode, Claude Code, Codex, Gemini, and other agents.
9
+
10
+ ## Purpose and scope
11
+
12
+ Use this file for repository-wide workflow rules. Keep product architecture, security constraints, and design rules in their source documents rather than duplicating them here.
13
+
14
+ ## Session context
15
+
16
+ Before a non-trivial change, read these documents in order:
17
+
18
+ 1. `AGENTS.md` for workflow and repository rules.
19
+ 2. `ARCHITECTURE.md` for boundaries, dependencies, and component interactions.
20
+ 3. `DESIGN.md` for UI and design-system work.
21
+ 4. The active OpenSpec change or the relevant specification for the area being changed.
22
+
23
+ Read each document once per session unless it changes or the task moves into a different area.
24
+
25
+ Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
26
+
27
+ ## Workflow ownership
28
+
29
+ <!-- PC-PLATFORM-WORKFLOW-START -->
30
+ <!-- PC-PLATFORM-WORKFLOW-END -->
31
+
32
+ ## Planning and execution
33
+
34
+ - Plan before delegating work. Use OpenSpec when the change needs explicit scope, decisions, or sequenced tasks.
35
+ - Keep changes focused. Do not combine unrelated refactors with requested work.
36
+ - Do not guess when requirements, architecture, or security constraints are unclear. Ask before proceeding.
37
+ - Prefer the project's established patterns and source documents over introducing new conventions.
38
+
39
+ ## Engineer selection
40
+
41
+ Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `fullstack-engineer` is `mode: primary`, the planning agent, and is not a spawned worker. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
42
+
43
+ The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. Read `agents.maxConcurrent` from `.opencode/harness.json` before spawning workers.
44
+
45
+ ## Tool and repository safety
46
+
47
+ - Never expose or commit secrets, credentials, tokens, or production data.
48
+ - Read before editing. Respect repository ownership, generated files, and existing local changes.
49
+ - Run only commands appropriate to the task. Do not bypass checks, weaken tests, or silence lint rules to get a green result.
50
+ - Commit, push, create pull requests, alter dependencies, or change deployment configuration only with the user's explicit approval and the repository's stated process.
51
+
52
+ ## Verification and completion
53
+
54
+ - Run the applicable tests, lint, typecheck, and build before reporting completion.
55
+ - A bug fix needs a test that would have caught the defect when practical.
56
+ - Update specifications, architecture, or design documentation when the change makes their current statements inaccurate.
57
+ - Report changed files, checks run, and any remaining risk or follow-up work.
58
+
59
+ ## Communication
60
+
61
+ - Keep updates concise and factual.
62
+ - State blockers early and explain the decision needed.
63
+ - Use the repository's language and writing conventions for source, documentation, issues, commits, and pull requests.
64
+ - Comments explain non-obvious reasons, constraints, or invariants. Do not add comments that restate code.
65
+
66
+ ## Skills
67
+
68
+ Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`. The always-installed `pc-system-reminders` plugin loads each agent's `## Abilities` before work, guardrails first. Skills can require mandatory transitive loads. Keep `## Abilities` complete and do not treat entries as passive references.
69
+
70
+ <!-- PC-PLATFORM-SKILLS-GUIDE-START -->
71
+ <!-- PC-PLATFORM-SKILLS-GUIDE-END -->
@@ -0,0 +1,16 @@
1
+ > NOT GENERATED YET
2
+ >
3
+ > This file has not been populated yet. It is intentionally empty.
4
+ >
5
+ > **If this is a greenfield project** (no codebase exists yet): skip this for now.
6
+ > Come back and run `/make-architecture` once you have meaningful code, structure, or infrastructure in place.
7
+ >
8
+ > **If this is a brownfield project** (existing codebase): run this command now to generate the architecture documentation:
9
+ >
10
+ > ```
11
+ > /make-architecture
12
+ > ```
13
+ >
14
+ > This command analyzes your folder structure, config files, routes, data models, integrations, and build setup,
15
+ > then writes a complete ARCHITECTURE.md covering components, data flow, tech stack, deployment, and more.
16
+ > It is safe to rerun any time the architecture changes significantly.
@@ -0,0 +1,16 @@
1
+ > NOT GENERATED YET
2
+ >
3
+ > This file has not been populated yet. It is intentionally empty.
4
+ >
5
+ > **If this is a greenfield project** (no UI exists yet): skip this for now.
6
+ > Come back and run `/make-design` once you have a design system, UI components, or styles in place.
7
+ >
8
+ > **If this is a brownfield project** (existing UI/styles): run this command now to generate the design documentation:
9
+ >
10
+ > ```
11
+ > /make-design
12
+ > ```
13
+ >
14
+ > This command analyzes your CSS, Tailwind config, component files, and design tokens,
15
+ > then writes a complete DESIGN.md with structured YAML tokens and written design intent.
16
+ > It is safe to rerun any time your design system changes.
@@ -0,0 +1,31 @@
1
+ {
2
+ "$schema": "https://opencode.ai/config.json",
3
+ "instructions": [
4
+ "AGENTS.md"
5
+ ],
6
+ "plugin": [
7
+ "@different-ai/opencode-browser@4.6.1",
8
+ "@mohak34/opencode-notifier@0.2.8"
9
+ ],
10
+ "experimental": {
11
+ "mcp_timeout": 300000
12
+ },
13
+ "compaction": {
14
+ "auto": true,
15
+ "prune": true,
16
+ "reserved": 10000
17
+ },
18
+ "permission": {
19
+ "question": "allow",
20
+ "todowrite": "allow",
21
+ "skill": "allow"
22
+ },
23
+ "skills": {
24
+ "paths": [".agents/skills"]
25
+ },
26
+ "default_agent": "fullstack-engineer",
27
+ "agent": {
28
+ "build": { "disable": true },
29
+ "plan": { "disable": true }
30
+ }
31
+ }
File without changes
@@ -0,0 +1,20 @@
1
+ schema: spec-driven
2
+
3
+ # Project context (optional)
4
+ # This is shown to AI when creating artifacts.
5
+ # Add your tech stack, conventions, style guides, domain knowledge, etc.
6
+ # Example:
7
+ # context: |
8
+ # Tech stack: TypeScript, React, Node.js
9
+ # We use conventional commits
10
+ # Domain: e-commerce platform
11
+
12
+ # Per-artifact rules (optional)
13
+ # Add custom rules for specific artifacts.
14
+ # Example:
15
+ # rules:
16
+ # proposal:
17
+ # - Keep proposals under 500 words
18
+ # - Always include a "Non-goals" section
19
+ # tasks:
20
+ # - Break tasks into chunks of max 2 hours
File without changes
@@ -0,0 +1,17 @@
1
+ {
2
+ "version": 1,
3
+ "skills": {
4
+ "find-skills": {
5
+ "source": "vercel-labs/skills",
6
+ "sourceType": "github",
7
+ "skillPath": "skills/find-skills/SKILL.md",
8
+ "computedHash": "781bd6d3f9b19f8c9af6b53d8d0e4876d0183841b565db34ca7092ffa412d111"
9
+ },
10
+ "user-story": {
11
+ "source": "deanpeters/product-manager-skills",
12
+ "sourceType": "github",
13
+ "skillPath": "skills/user-story/SKILL.md",
14
+ "computedHash": "user-story-placeholder"
15
+ }
16
+ }
17
+ }
@@ -0,0 +1,95 @@
1
+ 2. **Find the oldest change with a completed PR**
2
+
3
+ List unarchived changes (top-level only, excludes `archive/`):
4
+
5
+ ```bash
6
+ find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
7
+ ```
8
+
9
+ If empty, report a blocker and stop.
10
+
11
+ List completed PRs:
12
+
13
+ ```bash
14
+ az repos pr list --repository {repo} --status completed --query "sort_by(@, &closedDate)[].{name:title,sourceRefName:sourceRefName,closedDate:closedDate,pullRequestId:pullRequestId}"
15
+ ```
16
+
17
+ Match each change to a completed PR using its ID and slug as search hints:
18
+ - No match → skip (record as blocked: `no merged PR found`).
19
+ - One match → eligible.
20
+ - Multiple matches → ask the user which PR belongs to that change.
21
+
22
+ If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** PR `closedDate` as the candidate.
23
+
24
+ 3. **Confirm the candidate**
25
+
26
+ Show the candidate (ID, title, PR ID, merged date) and any blocked changes, then ask:
27
+
28
+ ```text
29
+ Oldest unarchived merged change found:
30
+ ID: {change-id}
31
+ Title: {title from resolved PR}
32
+ PR ID: {pullRequestId}
33
+ Merged: {closedDate}
34
+
35
+ Proceed with archiving? [yes/no]
36
+ ```
37
+
38
+ Stop if the user does not confirm.
39
+
40
+ 4. **Archive the change**
41
+
42
+ ```bash
43
+ git checkout -b archive/{change-id}
44
+ ```
45
+
46
+ Load `@openspec-archive-change` skill and follow it to archive the change.
47
+
48
+ 5. **Update docs**
49
+
50
+ Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
51
+
52
+ 6. **Create the archive PR**
53
+
54
+ ```bash
55
+ git add -A
56
+ git commit -m "archive: {title} ({change-id})"
57
+ git push origin archive/{change-id}
58
+
59
+ az repos pr create \
60
+ --repository {repo} \
61
+ --source-branch refs/heads/archive/{change-id} \
62
+ --target-branch "refs/heads/$DEFAULT_BRANCH" \
63
+ --title "archive: {title} ({change-id})" \
64
+ --description "Archive SDD artifacts for {change-id} after merge of {sourceRefName}." \
65
+ --auto-complete
66
+ ```
67
+
68
+ If work was stashed in step 1, restore it after the PR is created unless the user opts out.
69
+
70
+ 7. **Report**
71
+
72
+ Display:
73
+
74
+ ```text
75
+ Archive complete
76
+
77
+ Change ID: {change-id}
78
+ Title: {title}
79
+ Original PR: {original-pr-link}
80
+ Archive PR: {archive-pr-link}
81
+
82
+ Documentation updates:
83
+ - ARCHITECTURE.md: {count} changes applied
84
+ - DESIGN.md: {count} changes applied
85
+ ```
86
+
87
+ ## Rules
88
+
89
+ - All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
90
+ - Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
91
+ - Use change ID and slug only as search hints; do not assume the source branch name.
92
+ - 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).
93
+ - Never proceed if the selected PR is not completed.
94
+ - Never use browser tools or direct web requests for Azure DevOps. Use `az` CLI only.
95
+ - Never invent or guess PR, branch, or merge metadata.
@@ -0,0 +1,94 @@
1
+ 2. **Find the oldest change with a completed PR**
2
+
3
+ List unarchived changes (top-level only, excludes `archive/`):
4
+
5
+ ```bash
6
+ find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
7
+ ```
8
+
9
+ If empty, report a blocker and stop.
10
+
11
+ List completed PRs:
12
+
13
+ ```bash
14
+ 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}'
15
+ ```
16
+
17
+ Match each change to a completed PR using its ID and slug as search hints:
18
+ - No match → skip (record as blocked: `no merged PR found`).
19
+ - One match → eligible.
20
+ - Multiple matches → ask the user which PR belongs to that change.
21
+
22
+ If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** PR `mergedAt` as the candidate.
23
+
24
+ 3. **Confirm the candidate**
25
+
26
+ Show the candidate (ID, title, PR ID, merged date) and any blocked changes, then ask:
27
+
28
+ ```text
29
+ Oldest unarchived merged change found:
30
+ ID: {change-id}
31
+ Title: {title from resolved PR}
32
+ PR ID: {pullRequestId}
33
+ Merged: {mergedAt}
34
+
35
+ Proceed with archiving? [yes/no]
36
+ ```
37
+
38
+ Stop if the user does not confirm.
39
+
40
+ 4. **Archive the change**
41
+
42
+ ```bash
43
+ git checkout -b archive/{change-id}
44
+ ```
45
+
46
+ Load `@openspec-archive-change` skill and follow it to archive the change.
47
+
48
+ 5. **Update docs**
49
+
50
+ Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
51
+
52
+ 6. **Create the archive PR**
53
+
54
+ ```bash
55
+ git add -A
56
+ git commit -m "archive: {title} ({change-id})"
57
+ git push origin archive/{change-id}
58
+
59
+ gh pr create \
60
+ --repo {owner}/{repo} \
61
+ --base "$DEFAULT_BRANCH" \
62
+ --head archive/{change-id} \
63
+ --title "archive: {title} ({change-id})" \
64
+ --body "Archive SDD artifacts for {change-id} after merge."
65
+ ```
66
+
67
+ If work was stashed in step 1, restore it after the PR is created unless the user opts out.
68
+
69
+ 7. **Report**
70
+
71
+ Display:
72
+
73
+ ```text
74
+ Archive complete
75
+
76
+ Change ID: {change-id}
77
+ Title: {title}
78
+ Original PR: {original-pr-link}
79
+ Archive PR: {archive-pr-link}
80
+
81
+ Documentation updates:
82
+ - ARCHITECTURE.md: {count} changes applied
83
+ - DESIGN.md: {count} changes applied
84
+ ```
85
+
86
+ ## Rules
87
+
88
+ - All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
89
+ - Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
90
+ - Use change ID and slug only as search hints; do not assume the source branch name.
91
+ - 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).
92
+ - Never proceed if the selected PR is not completed.
93
+ - Never use browser tools or direct web requests for GitHub. Use `gh` CLI only.
94
+ - Never invent or guess PR, branch, or merge metadata.
@@ -0,0 +1,94 @@
1
+ 2. **Find the oldest change with a completed MR**
2
+
3
+ List unarchived changes (top-level only, excludes `archive/`):
4
+
5
+ ```bash
6
+ find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
7
+ ```
8
+
9
+ If empty, report a blocker and stop.
10
+
11
+ List completed merge requests:
12
+
13
+ ```bash
14
+ glab mr list --repo {owner}/{repo} --merged --output json --jq 'sort_by(.merged_at) | .[] | {name: .title, sourceRefName: .source_branch, mergedAt: .merged_at, mergeRequestId: .iid}'
15
+ ```
16
+
17
+ Match each change to a completed MR using its ID and slug as search hints:
18
+ - No match → skip (record as blocked: `no merged MR found`).
19
+ - One match → eligible.
20
+ - Multiple matches → ask the user which MR belongs to that change.
21
+
22
+ If nothing is eligible, report a blocker and stop. Otherwise select the eligible change with the **oldest** MR `merged_at` as the candidate.
23
+
24
+ 3. **Confirm the candidate**
25
+
26
+ Show the candidate (ID, title, MR ID, merged date) and any blocked changes, then ask:
27
+
28
+ ```text
29
+ Oldest unarchived merged change found:
30
+ ID: {change-id}
31
+ Title: {title from resolved MR}
32
+ MR ID: {iid}
33
+ Merged: {merged_at}
34
+
35
+ Proceed with archiving? [yes/no]
36
+ ```
37
+
38
+ Stop if the user does not confirm.
39
+
40
+ 4. **Archive the change**
41
+
42
+ ```bash
43
+ git checkout -b archive/{change-id}
44
+ ```
45
+
46
+ Load `@openspec-archive-change` skill and follow it to archive the change.
47
+
48
+ 5. **Update docs**
49
+
50
+ Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
51
+
52
+ 6. **Create the archive MR**
53
+
54
+ ```bash
55
+ git add -A
56
+ git commit -m "archive: {title} ({change-id})"
57
+ git push origin archive/{change-id}
58
+
59
+ glab mr create \
60
+ --repo {owner}/{repo} \
61
+ --source-branch "archive/{change-id}" \
62
+ --target-branch "$DEFAULT_BRANCH" \
63
+ --title "archive: {title} ({change-id})" \
64
+ --description "Archive SDD artifacts for {change-id} after merge."
65
+ ```
66
+
67
+ If work was stashed in step 1, restore it after the MR is created unless the user opts out.
68
+
69
+ 7. **Report**
70
+
71
+ Display:
72
+
73
+ ```text
74
+ Archive complete
75
+
76
+ Change ID: {change-id}
77
+ Title: {title}
78
+ Original MR: {original-mr-link}
79
+ Archive MR: {archive-mr-link}
80
+
81
+ Documentation updates:
82
+ - ARCHITECTURE.md: {count} changes applied
83
+ - DESIGN.md: {count} changes applied
84
+ ```
85
+
86
+ ## Rules
87
+
88
+ - All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
89
+ - Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
90
+ - Use change ID and slug only as search hints; do not assume the source branch name.
91
+ - The oldest eligible merged change is the only candidate: never ask the user which change to archive (but do ask which MR if multiple match one change).
92
+ - Never proceed if the selected MR is not completed.
93
+ - Never use browser tools or direct web requests for GitLab. Use `glab` CLI only.
94
+ - Never invent or guess MR, branch, or merge metadata.
@@ -0,0 +1,73 @@
1
+ 2. **Find the oldest unarchived change**
2
+
3
+ List unarchived changes (top-level only, excludes `archive/`):
4
+
5
+ ```bash
6
+ find "$REPO_ROOT/openspec/changes" -mindepth 1 -maxdepth 1 -type d -not -name 'archive' | sort
7
+ ```
8
+
9
+ If empty, report a blocker and stop. Otherwise select the **oldest** change (by directory creation/sort order) as the candidate.
10
+
11
+ This mode has no platform PR integration, so completion is judged from local state only. Do not look up remote PRs or work items.
12
+
13
+ 3. **Confirm the candidate**
14
+
15
+ Show the candidate (ID, title) and any other unarchived changes, then ask:
16
+
17
+ ```text
18
+ Oldest unarchived change found:
19
+ ID: {change-id}
20
+ Title: {title from proposal.md}
21
+
22
+ Proceed with archiving? [yes/no]
23
+ ```
24
+
25
+ Stop if the user does not confirm.
26
+
27
+ 4. **Archive the change**
28
+
29
+ ```bash
30
+ git checkout -b archive/{change-id}
31
+ ```
32
+
33
+ Load `@openspec-archive-change` skill and follow it to archive the change.
34
+
35
+ 5. **Update docs**
36
+
37
+ Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`. If updates are needed, show them and get user approval before applying.
38
+
39
+ 6. **Commit the archive**
40
+
41
+ ```bash
42
+ git add -A
43
+ git commit -m "archive: {title} ({change-id})"
44
+ ```
45
+
46
+ No PR is created in this mode. Leave the `archive/{change-id}` branch for the user to merge or push manually if they choose.
47
+
48
+ If work was stashed in step 1, restore it after the commit unless the user opts out.
49
+
50
+ 7. **Report**
51
+
52
+ Display:
53
+
54
+ ```text
55
+ Archive complete
56
+
57
+ Change ID: {change-id}
58
+ Title: {title}
59
+ Archive branch: archive/{change-id}
60
+
61
+ Documentation updates:
62
+ - ARCHITECTURE.md: {count} changes applied
63
+ - DESIGN.md: {count} changes applied
64
+ ```
65
+
66
+ ## Rules
67
+
68
+ - All OpenSpec paths resolve from `git rev-parse --show-toplevel`. Never use `/openspec/...`.
69
+ - Only process top-level directories in `$REPO_ROOT/openspec/changes/`; exclude `archive/`.
70
+ - Use change ID and slug only as search hints; do not assume the source branch name.
71
+ - The oldest unarchived change is the only candidate: never ask the user which change to archive.
72
+ - This mode has no GitHub or Azure DevOps integration. Never call `gh` or `az`, and never use browser tools or direct web requests for PR/work-item lookups.
73
+ - Never invent or guess PR, branch, or merge metadata.
@@ -0,0 +1,7 @@
1
+ ## CodeGraph
2
+
3
+ - **Use `codegraph_explore` INSTEAD OF grep, glob, or read.** It is always available. Do not assume it might be missing.
4
+ - One call returns the relevant symbols' verbatim, line-numbered source plus the call paths between them, use it as a full replacement for Read, Grep, and file-reading sub-tasks when working with indexed code.
5
+ - If you instinctively reach for grep or read to find or understand code, STOP: call `codegraph_explore` instead with the symbol name, file path, or a natural-language question. It covers the same ground in one call instead of a dozen.
6
+ - **Fall back to grep/glob/read ONLY when `codegraph_explore` returns no results** or the query is for something codegraph does not index (config files, plain-text docs, `.env` patterns, raw string searches). When you do fall back, you MUST state that codegraph returned nothing.
7
+ - Do NOT run `codegraph` in bash: it is an MCP server, not a CLI tool.
@@ -0,0 +1,4 @@
1
+ ## Humanizer (optimization skill — MANDATORY LOAD)
2
+
3
+ - **You MUST call `skill("humanizer")` via the skill tool before writing any prose** (commit messages, PR descriptions, docs, proposals) to remove AI writing patterns and sound more natural.
4
+ - Do NOT apply humanizer to code, config files, or terminal output: only to prose.
@@ -0,0 +1,4 @@
1
+ ## Agentmemory
2
+
3
+ - Use agentmemory MCP tools (`memory_smart_search`, `memory_save`, `memory_sessions`, `memory_governance_delete`) for cross-session context: `memory_smart_search` for prior decisions before implementing unfamiliar areas, `memory_save` for architecture decisions and cross-agent context.
4
+ - Do NOT run `agentmemory` in bash: it is an MCP server. Start the server with `agentmemory` in a separate terminal, then use MCP tools.
@@ -0,0 +1,3 @@
1
+ ## RTK
2
+
3
+ - Prefix ALL CLI commands with `rtk` (e.g. `rtk git diff`, `rtk pnpm test`). Read-only commands like `cat`, `ls`, `Get-Content` are exempt.
@@ -0,0 +1,4 @@
1
+ ## Simple English (optimization skill - MANDATORY LOAD)
2
+
3
+ - **You MUST call `skill("simple-english")` via the skill tool before responding.** This is not optional. Apply Simplified Technical English to all prose responses.
4
+ - Keep code blocks, identifiers, CLI commands, file paths, quoted errors, and product names exact.
@@ -0,0 +1,29 @@
1
+ **Browser MCP tools are FORBIDDEN for all Azure DevOps operations.**
2
+
3
+ ---
4
+
5
+ ### Step 1: Parse input
6
+
7
+ `$ARGUMENTS` is the work item title/description. If it contains a title and body separated by a newline or `---`, split them. Otherwise use the full text as the title with an empty body.
8
+
9
+ ### Step 2: Create work item
10
+
11
+ ```bash
12
+ az boards work-item create \
13
+ --title "{title}" \
14
+ --description "{body}" \
15
+ --type "User Story"
16
+ ```
17
+
18
+ ### Step 3: Report
19
+
20
+ ```text
21
+ Work item created
22
+ ID: {id}
23
+ Title: {title}
24
+ URL: {work-item-url}
25
+ ```
26
+
27
+ Tell the user: "Use `/plan-propose {work-item-url}` to turn this into a plan."
28
+
29
+ ---
@@ -0,0 +1,30 @@
1
+ **ALL GitHub data MUST come from `gh` CLI. NEVER use webfetch, HTTP requests, or browser MCP tools for GitHub operations, even if gh CLI fails. If `gh` is unavailable, report as a blocker.**
2
+ Always pass `--repo {owner}/{repo}` explicitly, never rely on git context to resolve the repo.
3
+
4
+ ---
5
+
6
+ ### Step 1: Parse input
7
+
8
+ `$ARGUMENTS` is the issue title/description. If it contains a title and body separated by a newline or `---`, split them. Otherwise use the full text as the title with an empty body.
9
+
10
+ ### Step 2: Create issue
11
+
12
+ ```bash
13
+ gh issue create \
14
+ --repo {owner}/{repo} \
15
+ --title "{title}" \
16
+ --body "{body}"
17
+ ```
18
+
19
+ ### Step 3: Report
20
+
21
+ ```text
22
+ Issue created
23
+ URL: {issue-url}
24
+ Number: #{number}
25
+ Title: {title}
26
+ ```
27
+
28
+ Tell the user: "Use `/plan-propose {issue-url}` to turn this into a plan."
29
+
30
+ ---
@@ -0,0 +1,29 @@
1
+ **NEVER use browser tools to navigate to atlassian.net: use `acli` CLI only.**
2
+
3
+ ---
4
+
5
+ ### Step 1: Parse input
6
+
7
+ `$ARGUMENTS` is the issue title/description. If it contains a title and body separated by a newline or `---`, split them. Otherwise use the full text as the title with an empty body.
8
+
9
+ ### Step 2: Create issue
10
+
11
+ ```bash
12
+ acli jira issue create \
13
+ --summary "{title}" \
14
+ --description "{body}" \
15
+ --type "Story"
16
+ ```
17
+
18
+ ### Step 3: Report
19
+
20
+ ```text
21
+ Issue created
22
+ Key: {key}
23
+ Title: {title}
24
+ URL: {issue-url}
25
+ ```
26
+
27
+ Tell the user: "Use `/plan-propose {issue-url}` to turn this into a plan."
28
+
29
+ ---