pantheon-opencode 1.7.0-beta.1 → 2.0.0-beta.1

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 (168) hide show
  1. package/AGENTS.global.md +2 -2
  2. package/AGENTS.md +3 -3
  3. package/CHANGELOG.md +86 -1
  4. package/README.md +90 -45
  5. package/README.pt-BR.md +19 -19
  6. package/bin/pantheon-init.mjs +11 -48
  7. package/package.json +9 -13
  8. package/plugin.json +2 -2
  9. package/pyproject.toml +1 -1
  10. package/scripts/build-agents-md.mjs +7 -6
  11. package/scripts/{check-plugin-v2-coverage.mjs → check-plugin-coverage.mjs} +7 -7
  12. package/scripts/{decision-router-v2-budget.mjs → decision-router-budget-gates.mjs} +1 -1
  13. package/scripts/{decision-router-v2-egress.mjs → decision-router-egress.mjs} +1 -1
  14. package/scripts/decision-router.mjs +2 -2
  15. package/scripts/docs-media.mjs +1 -1
  16. package/scripts/doctor.mjs +225 -136
  17. package/scripts/install/behavior-overrides.bundle.mjs +123 -0
  18. package/scripts/install/{v2-capabilities.mjs → capabilities.mjs} +7 -7
  19. package/scripts/install/config-migration.mjs +60 -253
  20. package/scripts/install/file-inventory.mjs +6 -4
  21. package/scripts/install/interactive.mjs +9 -2
  22. package/scripts/install/opencode-state.mjs +13 -12
  23. package/scripts/install/opencode-version.mjs +97 -162
  24. package/scripts/install/opencode.mjs +271 -428
  25. package/scripts/install/plan.mjs +1 -9
  26. package/scripts/install/plugin.mjs +19 -35
  27. package/scripts/install/shared.mjs +40 -1
  28. package/scripts/package-evidence.mjs +1 -4
  29. package/scripts/probe-pantheon-cost.mjs +1 -1
  30. package/scripts/reconcile.mjs +5 -7
  31. package/scripts/release-gates.mjs +38 -58
  32. package/scripts/setup-v2-config.mjs +10 -8
  33. package/scripts/setup.mjs +12 -22
  34. package/scripts/sync-tui.mjs +9 -17
  35. package/scripts/{test-opencode-v2-sandbox.sh → test-opencode-sandbox.sh} +9 -9
  36. package/scripts/update-skills-lock.mjs +24 -12
  37. package/scripts/update.mjs +17 -1
  38. package/scripts/validate-routing.mjs +79 -4
  39. package/scripts/validate-sandbox-install.mjs +3 -3
  40. package/skills-lock.json +25 -8
  41. package/src/agents/zeus.md +1 -0
  42. package/src/pantheon/behavior-overrides.ts +191 -0
  43. package/src/pantheon/{v2-bounded-read.ts → bounded-read.ts} +1 -1
  44. package/src/pantheon/cost-command.ts +1 -1
  45. package/src/pantheon/{v2-decision-contracts.ts → decision-contracts.ts} +3 -3
  46. package/src/pantheon/{v2-decision-points → decision-points}/p1-agent.ts +3 -3
  47. package/src/pantheon/{v2-decision-points → decision-points}/p10-claims.ts +2 -2
  48. package/src/pantheon/{v2-decision-points → decision-points}/p11-catalog.ts +2 -2
  49. package/src/pantheon/{v2-decision-points → decision-points}/p2-skill.ts +3 -3
  50. package/src/pantheon/{v2-decision-points → decision-points}/p3-complexity.ts +6 -6
  51. package/src/pantheon/{v2-decision-points → decision-points}/p4-memory.ts +2 -2
  52. package/src/pantheon/{v2-decision-points → decision-points}/p5-themis-verify.ts +2 -2
  53. package/src/pantheon/{v2-decision-points → decision-points}/p6-council.ts +3 -3
  54. package/src/pantheon/{v2-decision-points → decision-points}/p7-loop.ts +5 -5
  55. package/src/pantheon/{v2-decision-points → decision-points}/p8-guardrail.ts +2 -2
  56. package/src/pantheon/{v2-decision-points → decision-points}/p9-memory-compaction.ts +2 -2
  57. package/src/pantheon/{v2-decision-points.ts → decision-points.ts} +5 -5
  58. package/src/pantheon/{v2-decision-policy.ts → decision-policy.ts} +2 -2
  59. package/src/pantheon/{v2-decision-prompt-surface.ts → decision-prompt-surface.ts} +3 -3
  60. package/src/pantheon/{v2-decision-registry.ts → decision-registry.ts} +10 -13
  61. package/src/pantheon/{v2-decision-resource-ids.ts → decision-resource-ids.ts} +1 -1
  62. package/src/pantheon/{v2-decision-shadow.ts → decision-shadow.ts} +1 -1
  63. package/src/pantheon/{v2-decision-telemetry.ts → decision-telemetry.ts} +1 -1
  64. package/src/pantheon/{v2-execute-after.ts → execute-after.ts} +4 -4
  65. package/src/pantheon/goal-store.ts +7 -0
  66. package/src/pantheon/{v2-hook-engine.ts → hook-engine.ts} +3 -3
  67. package/src/pantheon/jev-decision-tool.ts +3 -3
  68. package/src/pantheon/jev-decisions.ts +12 -6
  69. package/src/pantheon/jev-escalation.ts +6 -6
  70. package/src/pantheon/jev-quality-score.ts +2 -2
  71. package/src/pantheon/jev-rank-verify.ts +2 -2
  72. package/src/pantheon/jev-risk-gate.ts +4 -4
  73. package/src/pantheon/local-decision-agents.ts +1 -1
  74. package/src/pantheon/local-decision-router.ts +1 -1
  75. package/src/pantheon/local-decision-tool.ts +2 -2
  76. package/src/pantheon/local-orchestration.ts +1 -1
  77. package/src/pantheon/model-command.ts +1 -1
  78. package/src/pantheon/{v2-vision.ts → native-vision.ts} +12 -15
  79. package/src/pantheon/pantheon-decision-catalog.ts +12 -0
  80. package/src/pantheon/{v2-shell-hooks.ts → shell-hooks.ts} +4 -4
  81. package/src/pantheon/{v2-tools.ts → tools.ts} +4 -4
  82. package/src/pantheon/{v2-unsupported.d.mts → unsupported.d.mts} +3 -3
  83. package/src/pantheon/{v2-unsupported.mjs → unsupported.mjs} +8 -8
  84. package/src/pantheon/update-notifier.ts +101 -0
  85. package/src/pantheon/vision-local.ts +12 -3
  86. package/src/pantheon/vision.ts +120 -2
  87. package/src/{plugin-v2 → plugin}/index.ts +7 -7
  88. package/src/plugin.ts +2875 -500
  89. package/src/plugins/hook-runner.ts +3 -3
  90. package/src/plugins/tui/dist/server.d.ts +23 -9
  91. package/src/plugins/tui/dist/server.d.ts.map +1 -1
  92. package/src/plugins/tui/dist/server.js +25 -12
  93. package/src/plugins/tui/dist/server.js.map +1 -1
  94. package/src/plugins/tui/dist/tui.d.ts +1023 -494
  95. package/src/plugins/tui/dist/tui.d.ts.map +1 -1
  96. package/src/plugins/tui/dist/tui.js +4841 -2066
  97. package/src/plugins/tui/dist/tui.js.map +1 -1
  98. package/src/plugins/tui/{index-v2.ts → index.ts} +1 -1
  99. package/src/plugins/tui/package-lock.json +2 -42
  100. package/src/plugins/tui/package.json +4 -10
  101. package/src/plugins/tui/src/cost-data.ts +1 -1
  102. package/src/plugins/tui/src/index.tsx +4222 -2822
  103. package/src/plugins/tui/src/pantheon-settings-state.ts +111 -0
  104. package/src/plugins/tui/src/pantheon-settings.tsx +236 -0
  105. package/src/plugins/tui/src/server.ts +23 -10
  106. package/src/plugins/tui/src/update-notice.ts +86 -0
  107. package/src/plugins/tui/tsconfig.typecheck.json +1 -1
  108. package/src/plugins/tui/tsdown.config.ts +3 -5
  109. package/src/plugins/tui/tui.ts +1 -2
  110. package/src/routing.yml +36 -0
  111. package/src/skills/README.md +16 -1
  112. package/src/skills/artifact-management/SKILL.md +10 -67
  113. package/src/skills/artifact-management/references/artifact-templates.md +71 -0
  114. package/src/skills/auto-continue/SKILL.md +10 -0
  115. package/src/skills/code-review-checklist/SKILL.md +11 -44
  116. package/src/skills/code-review-checklist/references/review-checklists.md +54 -0
  117. package/src/skills/instruction-forge/SKILL.md +57 -0
  118. package/src/skills/instruction-forge/references/agents-md-doctrine.md +50 -0
  119. package/src/skills/instruction-forge/references/eval-doctrine.md +37 -0
  120. package/src/skills/instruction-forge/references/skill-doctrine.md +62 -0
  121. package/src/skills/memory-bank/SKILL.md +11 -90
  122. package/src/skills/memory-bank/references/anti-patterns.md +33 -0
  123. package/src/skills/memory-bank/references/product-adoption.md +19 -0
  124. package/src/skills/memory-bank/references/storage-model.md +21 -0
  125. package/src/skills/memory-bank/references/structure-and-frequency.md +44 -0
  126. package/src/skills/reflect/SKILL.md +1 -0
  127. package/src/skills/session-goal/SKILL.md +7 -54
  128. package/src/skills/session-goal/references/goal-format.md +26 -0
  129. package/src/skills/session-goal/references/session-reuse.md +44 -0
  130. package/src/skills/tdd-with-agents/SKILL.md +11 -101
  131. package/src/skills/tdd-with-agents/references/advanced-testing-patterns.md +58 -0
  132. package/src/skills/tdd-with-agents/references/testing-by-layer.md +60 -0
  133. package/src/skills/visual-review-pipeline/SKILL.md +11 -120
  134. package/src/skills/visual-review-pipeline/references/findings-schema.md +49 -0
  135. package/src/skills/visual-review-pipeline/references/workflow-steps.md +111 -0
  136. package/scripts/hooks/log-session-start.sh +0 -48
  137. package/scripts/hooks/validate-post-conditions.sh +0 -21
  138. package/scripts/hooks/validate-talos-scope.sh +0 -50
  139. package/scripts/hooks/validate-tool-safety.sh +0 -49
  140. package/src/pantheon/goal-loop.ts +0 -314
  141. package/src/pantheon/idle-continuation.ts +0 -52
  142. package/src/pantheon/todo-preserve.ts +0 -301
  143. package/src/pantheon/tool-ceiling.ts +0 -159
  144. package/src/pantheon/v2-bridge.ts +0 -153
  145. package/src/plugin-v2.ts +0 -2954
  146. package/src/plugins/pantheon-hooks.ts +0 -1433
  147. package/src/plugins/tui/dist/server-v2.d.ts +0 -30
  148. package/src/plugins/tui/dist/server-v2.d.ts.map +0 -1
  149. package/src/plugins/tui/dist/server-v2.js +0 -33
  150. package/src/plugins/tui/dist/server-v2.js.map +0 -1
  151. package/src/plugins/tui/dist/tui-v2.d.ts +0 -1039
  152. package/src/plugins/tui/dist/tui-v2.d.ts.map +0 -1
  153. package/src/plugins/tui/dist/tui-v2.js +0 -4597
  154. package/src/plugins/tui/dist/tui-v2.js.map +0 -1
  155. package/src/plugins/tui/src/index-v2.tsx +0 -4496
  156. package/src/plugins/tui/src/server-v2.ts +0 -28
  157. package/src/plugins/tui/tui-v2.ts +0 -2
  158. /package/src/pantheon/{v2-decision-budget.ts → decision-budget.ts} +0 -0
  159. /package/src/pantheon/{v2-decision-egress.ts → decision-egress.ts} +0 -0
  160. /package/src/pantheon/{v2-decision-events.ts → decision-events.ts} +0 -0
  161. /package/src/pantheon/{v2-decision-heuristic.ts → decision-heuristic.ts} +0 -0
  162. /package/src/pantheon/{v2-decision-premises.ts → decision-premises.ts} +0 -0
  163. /package/src/pantheon/{v2-decision-rank.ts → decision-rank.ts} +0 -0
  164. /package/src/pantheon/{v2-decision-verify.ts → decision-verify.ts} +0 -0
  165. /package/src/pantheon/{v2-delegation-enforce.ts → delegation-policy.ts} +0 -0
  166. /package/src/pantheon/{v2-model-overrides.ts → model-overrides.ts} +0 -0
  167. /package/src/pantheon/{v2-native-decisions.ts → native-decisions.ts} +0 -0
  168. /package/src/plugins/tui/src/{opencode-v2.d.ts → opencode.d.ts} +0 -0
@@ -9,29 +9,6 @@ Structured artifact trail for planned, multi-phase, or materially risky implemen
9
9
 
10
10
  ---
11
11
 
12
- ## Temp Folder
13
-
14
- All ephemeral artifacts live in `.pantheon/memory-bank/.tmp/` — gitignored and wiped on sprint close.
15
-
16
- ```
17
- .pantheon/memory-bank/
18
- ├── .tmp/ ← GITIGNORED — ephemeral artifacts
19
- │ ├── PLAN-<feature>.md
20
- │ ├── IMPL-phase1-hermes.md
21
- │ ├── IMPL-phase1-aphrodite.md
22
- │ └── REVIEW-<feature>.md
23
- ├── _notes/ ← permanent ADRs; Git tracking follows repository policy
24
- │ └── ADR-<topic>.md
25
- ├── 01-active-context.md
26
- └── 02-progress-log.md
27
- ```
28
-
29
- Memory Bank files are not automatically versioned or shared across clones.
30
- Check the repository's ignore/commit policy before relying on `_tasks/` records
31
- or other files being tracked; `_tasks/` may be Git-ignored.
32
-
33
- ---
34
-
35
12
  ## Artifact Types
36
13
 
37
14
  | Prefix | Location | Ephemeral? | Produced by |
@@ -65,50 +42,6 @@ or other files being tracked; `_tasks/` may be Git-ignored.
65
42
 
66
43
  ---
67
44
 
68
- ## Templates
69
-
70
- ### PLAN
71
- ```markdown
72
- # PLAN-<feature>
73
- **Date:** YYYY-MM-DD **Status:** Awaiting Approval
74
-
75
- ## Goal
76
- [One sentence]
77
-
78
- ## Phases
79
- 1. Phase 1 — @hermes
80
- 2. Phase 2 — @aphrodite
81
-
82
- ## Risks
83
- - [Risk]
84
- ```
85
-
86
- ### IMPL
87
- ```markdown
88
- # IMPL-<phase>-<agent>
89
- **Date:** YYYY-MM-DD **Status:** Awaiting Themis Review
90
-
91
- ## What Was Implemented
92
- - [file] — [what changed]
93
-
94
- ## Tests
95
- - ✅ X tests / Coverage: Y%
96
- ```
97
-
98
- ### REVIEW
99
- ```markdown
100
- # REVIEW-<feature>
101
- **Status:** APPROVED | NEEDS_REVISION | FAILED
102
-
103
- ## Verdict
104
- [APPROVED | NEEDS_REVISION | FAILED]
105
-
106
- ## Issues
107
- - CRITICAL: X / HIGH: Y / MEDIUM: Z
108
- ```
109
-
110
- ---
111
-
112
45
  ## Human Pause Points
113
46
 
114
47
  1. **After a required PLAN** → pause only when a material scope/risk decision needs approval.
@@ -124,3 +57,13 @@ or other files being tracked; `_tasks/` may be Git-ignored.
124
57
  @mnemosyne Clean tmp # Wipes .tmp/ without closing sprint
125
58
  @mnemosyne List artifacts # Check what's in .tmp/
126
59
  ```
60
+
61
+ ---
62
+
63
+ ## Routing
64
+
65
+ | Action / trigger | Reference |
66
+ |---|---|
67
+ | Creating an artifact: the `.tmp/` layout or the PLAN/IMPL/REVIEW templates | [references/artifact-templates.md](references/artifact-templates.md) |
68
+
69
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,71 @@
1
+ # Artifact Management — Templates
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when creating an artifact and
4
+ you need the `.tmp/` layout or a PLAN/IMPL/REVIEW template. Artifact types,
5
+ who-generates-what, proportional-use rules, pause points, and cleanup stay in
6
+ `SKILL.md`.
7
+
8
+ ---
9
+
10
+ ## Temp Folder
11
+
12
+ All ephemeral artifacts live in `.pantheon/memory-bank/.tmp/` — gitignored and wiped on sprint close.
13
+
14
+ ```
15
+ .pantheon/memory-bank/
16
+ ├── .tmp/ ← GITIGNORED — ephemeral artifacts
17
+ │ ├── PLAN-<feature>.md
18
+ │ ├── IMPL-phase1-hermes.md
19
+ │ ├── IMPL-phase1-aphrodite.md
20
+ │ └── REVIEW-<feature>.md
21
+ ├── _notes/ ← permanent ADRs; Git tracking follows repository policy
22
+ │ └── ADR-<topic>.md
23
+ ├── 01-active-context.md
24
+ └── 02-progress-log.md
25
+ ```
26
+
27
+ Memory Bank files are not automatically versioned or shared across clones.
28
+ Check the repository's ignore/commit policy before relying on `_tasks/` records
29
+ or other files being tracked; `_tasks/` may be Git-ignored.
30
+
31
+ ---
32
+
33
+ ### PLAN
34
+ ```markdown
35
+ # PLAN-<feature>
36
+ **Date:** YYYY-MM-DD **Status:** Awaiting Approval
37
+
38
+ ## Goal
39
+ [One sentence]
40
+
41
+ ## Phases
42
+ 1. Phase 1 — @hermes
43
+ 2. Phase 2 — @aphrodite
44
+
45
+ ## Risks
46
+ - [Risk]
47
+ ```
48
+
49
+ ### IMPL
50
+ ```markdown
51
+ # IMPL-<phase>-<agent>
52
+ **Date:** YYYY-MM-DD **Status:** Awaiting Themis Review
53
+
54
+ ## What Was Implemented
55
+ - [file] — [what changed]
56
+
57
+ ## Tests
58
+ - ✅ X tests / Coverage: Y%
59
+ ```
60
+
61
+ ### REVIEW
62
+ ```markdown
63
+ # REVIEW-<feature>
64
+ **Status:** APPROVED | NEEDS_REVISION | FAILED
65
+
66
+ ## Verdict
67
+ [APPROVED | NEEDS_REVISION | FAILED]
68
+
69
+ ## Issues
70
+ - CRITICAL: X / HIGH: Y / MEDIUM: Z
71
+ ```
@@ -84,6 +84,16 @@ placeholder.
84
84
 
85
85
  ---
86
86
 
87
+ ## Routing
88
+
89
+ | Action / trigger | Reference |
90
+ |---|---|
91
+ | A delegation times out, you need a cooldown template or the tracking-table format, or you are about to checkpoint | [references/auto-continue-details.md](references/auto-continue-details.md) |
92
+
93
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
94
+
95
+ ---
96
+
87
97
  ## Details under demand
88
98
 
89
99
  The cooldown templates, timeout/retry enforcement (the single authority is
@@ -35,40 +35,7 @@ biome check --write --unsafe <files>
35
35
 
36
36
  ## Review Checklist
37
37
 
38
- ### Correctness
39
- - [ ] Logic is correct and complete
40
- - [ ] Edge cases handled
41
- - [ ] Error handling appropriate
42
- - [ ] Performance acceptable
43
-
44
- ### Code Quality
45
- - [ ] No duplication (DRY principle)
46
- - [ ] Single responsibility functions
47
- - [ ] Clear and descriptive naming
48
- - [ ] Reasonable complexity (no god functions)
49
- - [ ] Proper file sizes (<300 lines)
50
-
51
- ### Testing
52
- - [ ] Tests cover the changed behavior where meaningful; documentation/format-only changes do not need invented tests
53
- - [ ] Apply an explicit repository coverage threshold only when measurable and relevant to the changed code
54
- - [ ] Integration tests where the change crosses workflow boundaries
55
- - [ ] Relevant edge cases tested for the changed behavior/risk
56
- - [ ] Relevant error conditions tested
57
-
58
- ### Security (OWASP Top 10)
59
- - [ ] Input validation present
60
- - [ ] No hardcoded secrets/credentials
61
- - [ ] No XXE, CSRF, XSS vulnerabilities
62
- - [ ] Authentication/authorization proper
63
- - [ ] Sensitive data encrypted
64
- - [ ] Rate limiting on sensitive endpoints
65
- - [ ] Audit logging for security events
66
-
67
- ### Documentation
68
- - [ ] Public functions documented
69
- - [ ] Comments explain WHY not WHAT
70
- - [ ] README/guides accurate
71
- - [ ] API documentation complete
38
+ Run the itemized pass (Correctness, Code Quality, Testing, Security/OWASP, Documentation) and the SOLID check from [references/review-checklists.md](references/review-checklists.md) before issuing a verdict.
72
39
 
73
40
  ---
74
41
 
@@ -117,16 +84,6 @@ For comprehensive reviews, run 5 checks simultaneously:
117
84
 
118
85
  ---
119
86
 
120
- ## SOLID Principles Check
121
-
122
- - **S**ingle Responsibility: Each class/function does one thing
123
- - **O**pen/Closed: Extensible without modification
124
- - **L**iskov Substitution: Subtypes behave like base types
125
- - **I**nterface Segregation: Small, focused interfaces
126
- - **D**ependency Inversion: Depend on abstractions, not concretions
127
-
128
- ---
129
-
130
87
  ## Anti-Patterns
131
88
 
132
89
  - ❌ Reviewing entire file instead of diff
@@ -134,3 +91,13 @@ For comprehensive reviews, run 5 checks simultaneously:
134
91
  - ❌ Ignoring security implications
135
92
  - ❌ Vague feedback ("looks good", "needs work")
136
93
  - ❌ Nitpicking style over substance
94
+
95
+ ---
96
+
97
+ ## Routing
98
+
99
+ | Action / trigger | Reference |
100
+ |---|---|
101
+ | Executing the itemized review pass (Correctness, Quality, Testing, Security, Documentation) or the SOLID check | [references/review-checklists.md](references/review-checklists.md) |
102
+
103
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,54 @@
1
+ # Code Review — Itemized Checklists and SOLID
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when executing the itemized
4
+ review pass. The review scope, automated-check-first rule, feedback format,
5
+ severity definitions, and anti-patterns stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Review Checklist
10
+
11
+ ### Correctness
12
+ - [ ] Logic is correct and complete
13
+ - [ ] Edge cases handled
14
+ - [ ] Error handling appropriate
15
+ - [ ] Performance acceptable
16
+
17
+ ### Code Quality
18
+ - [ ] No duplication (DRY principle)
19
+ - [ ] Single responsibility functions
20
+ - [ ] Clear and descriptive naming
21
+ - [ ] Reasonable complexity (no god functions)
22
+ - [ ] Proper file sizes (<300 lines)
23
+
24
+ ### Testing
25
+ - [ ] Tests cover the changed behavior where meaningful; documentation/format-only changes do not need invented tests
26
+ - [ ] Apply an explicit repository coverage threshold only when measurable and relevant to the changed code
27
+ - [ ] Integration tests where the change crosses workflow boundaries
28
+ - [ ] Relevant edge cases tested for the changed behavior/risk
29
+ - [ ] Relevant error conditions tested
30
+
31
+ ### Security (OWASP Top 10)
32
+ - [ ] Input validation present
33
+ - [ ] No hardcoded secrets/credentials
34
+ - [ ] No XXE, CSRF, XSS vulnerabilities
35
+ - [ ] Authentication/authorization proper
36
+ - [ ] Sensitive data encrypted
37
+ - [ ] Rate limiting on sensitive endpoints
38
+ - [ ] Audit logging for security events
39
+
40
+ ### Documentation
41
+ - [ ] Public functions documented
42
+ - [ ] Comments explain WHY not WHAT
43
+ - [ ] README/guides accurate
44
+ - [ ] API documentation complete
45
+
46
+ ---
47
+
48
+ ## SOLID Principles Check
49
+
50
+ - **S**ingle Responsibility: Each class/function does one thing
51
+ - **O**pen/Closed: Extensible without modification
52
+ - **L**iskov Substitution: Subtypes behave like base types
53
+ - **I**nterface Segregation: Small, focused interfaces
54
+ - **D**ependency Inversion: Depend on abstractions, not concretions
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: instruction-forge
3
+ description: "Write and maintain AI instructions — AGENTS.md, agent prompts, and skill packages. Use when creating or editing any directive artifact, deciding where a rule lives, or testing that a rule fires."
4
+ ---
5
+
6
+ # Instruction Forge
7
+
8
+ > **The smallest context that fully specifies the required behavior. Every rule has exactly one home, and every rule is tested for where it fires — and where it must not.**
9
+
10
+ ---
11
+
12
+ ## When this fires
13
+
14
+ - Writing or editing any directive artifact: AGENTS.md (either artifact), an agent prompt, an instruction file, a SKILL.md.
15
+ - A rule keeps being repeated in prompts or conversation — it needs a single home.
16
+ - A directive changed and you must prove nothing the old text required was lost.
17
+ - Deciding WHERE a new rule lives at all — or concluding it should not be written down.
18
+
19
+ Do NOT fire for one-shot task instructions given in conversation; those stay in conversation. Only durable, reusable behavior gets an artifact.
20
+
21
+ ## Where a rule lives — one home per fact
22
+
23
+ | Rule kind | Home | Loaded when |
24
+ |---|---|---|
25
+ | Repo setup (commands, layout, gates of THIS repo) | `AGENTS.md` managed region | Every session in the repo |
26
+ | Repo-agnostic behavior every session must pay for | `AGENTS.global.md` / shared instruction (`agents: ["*"]`) | Every session |
27
+ | Behavior scoped to one agent | `src/instructions/*.instructions.md` with `agents:` selector | That agent's prompt, at build |
28
+ | A recurring workflow a specialist executes | A skill (`SKILL.md`, ≤120-line core + `references/`) | On demand via grant |
29
+ | A runtime gate the plugin owns | `behaviors:` registry in `routing.yml` (then env/override), never prose | Plugin setup |
30
+ | Generated region content | `scripts/build-agents-md.mjs` (source of truth) — NEVER hand-edited | Regenerated |
31
+
32
+ Two artifacts, zero overlap: the project `AGENTS.md` carries repo setup; `AGENTS.global.md` carries repo-agnostic rules. A session pays for global + project exactly once — a rule in both is a defect (`tests/eval/instruction-golden.test.mjs` pins this).
33
+
34
+ ## The contract (before any edit)
35
+
36
+ 1. **Home first** — place the rule with the table above; if no home fits, the rule is not durable enough to write down.
37
+ 2. **Nothing lost** — diff the old text's REQUIREMENTS against the new: every imperative, threshold, and exception either survives or has a named successor.
38
+ 3. **Test the edges** — write the trigger case, the no-trigger case, and the exception. Structural cases go in `tests/eval/`; semantic cases are documented in the artifact.
39
+ 4. **Budget** — the main artifact pays context every session; depth moves to `references/` behind a Routing table. Passing every check still does not GUARANTEE an agent obeys — say so, and keep enforcement deterministic (hooks, gates) where it matters.
40
+
41
+ ## Routing
42
+
43
+ | Action / trigger | Reference |
44
+ |---|---|
45
+ | Writing or editing AGENTS.md or a shared instruction | [references/agents-md-doctrine.md](references/agents-md-doctrine.md) |
46
+ | Writing or editing a SKILL.md or skill package | [references/skill-doctrine.md](references/skill-doctrine.md) |
47
+ | Deciding how a rule is tested (trigger / no-trigger / exception) | [references/eval-doctrine.md](references/eval-doctrine.md) |
48
+
49
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
50
+
51
+ ## Rules
52
+
53
+ - Generated regions (`pantheon:generated`) are machine-written: change the generator, never the output.
54
+ - Existing conventions of the codebase outrank personal preference — a rule that fights the grain gets rejected, not encoded.
55
+ - Frontmatter contracts are enforced by tests (`tests/agent-skills-contract.test.mjs`); never add unlisted keys.
56
+ - An instruction that says "always" but has a known exception must state the exception or it is a defect, not a style choice.
57
+ - Route friction capture through `reflect` (it decides an artifact is warranted); this skill executes the writing.
@@ -0,0 +1,50 @@
1
+ # Agents.md Doctrine
2
+
3
+ The two artifacts are generated, disjunct, and budgeted. Every session pays
4
+ for global + project exactly once; overlap is a defect pinned by
5
+ `tests/eval/instruction-golden.test.mjs`.
6
+
7
+ ## The managed region
8
+
9
+ - Sentinels: `<!-- pantheon:generated:begin -->` … `<!-- pantheon:generated:end -->`.
10
+ - Content between them is machine-written by `scripts/build-agents-md.mjs`
11
+ (source of truth: project sections in that script + `src/instructions/`).
12
+ - To change generated content: edit the generator or the instruction files,
13
+ then run `node scripts/build-agents-md.mjs`. The `--check` flag fails on a
14
+ stale artifact — CI and doctor both run it.
15
+ - User content outside the region is preserved verbatim across regeneration
16
+ (`writeAgentsMdManaged` carves by sentinel). The installer deliberately
17
+ excludes AGENTS.md from the file inventory: a file carrying user content is
18
+ never safe to claim or remove.
19
+
20
+ ## Global vs project
21
+
22
+ - **Global artifact** (`AGENTS.global.md`, installed to the config dir as the
23
+ user's AGENTS.md): agent table + shared instruction bodies
24
+ (`agents: ["*"]`). Repo-agnostic — the same on every project.
25
+ - **Project artifact** (`AGENTS.md`): THIS repo's setup only — commands,
26
+ layout, lint/test gates, conventions. It must not contain a rule a session
27
+ could need on any other repo.
28
+ - A shared instruction is a file in `src/instructions/*.instructions.md` with
29
+ `agents: ["*"]`. An agent-scoped one declares `agents: [<id>]` and rides
30
+ that agent's prompt at build (`generateAgentPrompt`); it never rides
31
+ another agent's.
32
+
33
+ ## Writing rules that survive
34
+
35
+ - One imperative per line where possible; a threshold is a number, not "fast".
36
+ - State the trigger ("when X"), the action ("do Y"), and the exception
37
+ ("unless Z") — an "always" with a known unstated exception is a defect.
38
+ - No narrative, no rationale paragraphs: the artifact pays per session, the
39
+ rationale lives in docs/ or the commit that introduced the rule.
40
+ - Budget awareness: `logicalLineCount` and the carve tests bound the
41
+ artifacts; if growth is needed, carve a new shared instruction instead of
42
+ inflating a static section.
43
+ - Never restate what a hook or gate already enforces deterministically —
44
+ point at it once. Enforcement lives in code; prose only explains.
45
+
46
+ ## Testing
47
+
48
+ Structural golden cases run in `tests/eval/instruction-golden.test.mjs`
49
+ (carve, zero-overlap, scoped routing). When you change a shared instruction
50
+ or the generator, add the negative case you just protected against there.
@@ -0,0 +1,37 @@
1
+ # Eval Doctrine — how a rule is tested
2
+
3
+ Instructions are code written in prose: they get trigger tests, no-trigger
4
+ tests, and exception tests. What they do NOT get is a guarantee — passing
5
+ every check proves the artifact says the right thing, never that an agent
6
+ will obey. Say so when reporting; keep real enforcement deterministic.
7
+
8
+ ## The three cases (write all three)
9
+
10
+ 1. **Trigger** — an input where the rule MUST change the behavior. Assert the
11
+ visible effect (block emitted, section present, route chosen).
12
+ 2. **No-trigger** — a near-miss where the rule MUST stay silent. This is the
13
+ case authors forget; most instruction bugs are over-firing.
14
+ 3. **Exception** — the stated "unless" of the rule, exercised end to end.
15
+ An exception you cannot exercise is a rule you cannot enforce.
16
+
17
+ ## Where the tests live
18
+
19
+ - **Structural (CI, deterministic)** — `tests/eval/*.test.mjs` over the real
20
+ generators and artifacts: carve semantics, zero-overlap, scoped routing,
21
+ budgets, lock integrity, reference graphs. Import the generator, call it,
22
+ assert the output; a golden case is a diff you refuse, not a snapshot you
23
+ bless.
24
+ - **Semantic (documented, not automated)** — for rules whose trigger is
25
+ judgment ("proportional effort"), write the three cases as examples IN the
26
+ artifact (wrong/right pairs beat paragraphs) and note the limits.
27
+ - **Model-in-the-loop (gated)** — routing/complexity scoring against held-out
28
+ cases follows `docs/reference/offline-evaluation.md`: frozen rubric, slot
29
+ labels, pre-registered acceptance. Never run it ad hoc.
30
+
31
+ ## The honest disclaimer
32
+
33
+ A green eval suite means: the artifacts say what they must, the seams hold,
34
+ and the deterministic gates fire where designed. It does not measure
35
+ compliance. When a rule matters enough that non-compliance is expensive,
36
+ move it out of prose — hook, gate, permission, or the behaviors registry —
37
+ and test THAT.
@@ -0,0 +1,62 @@
1
+ # Skill Doctrine
2
+
3
+ A skill is a workflow a specialist executes on demand. The core pays its
4
+ context cost every invocation; depth must be earned by the trigger, not
5
+ carried by default.
6
+
7
+ ## Anatomy (the enforced contract)
8
+
9
+ - `src/skills/<id>/SKILL.md` — the ONLY required file. Frontmatter allows
10
+ exactly `name`, `description`, `license`, `compatibility`, `metadata`
11
+ (`tests/agent-skills-contract.test.mjs` rejects anything else); `name` must
12
+ equal the directory id; `description` must be non-empty and work as a
13
+ router.
14
+ - Optional `references/*.md` — depth, loaded on demand by the agent's own
15
+ `read`. Every shipped reference MUST be cited in the core's `## Routing`
16
+ table; an uncited reference is dead weight (validate-routing warns).
17
+ - Optional `scripts/` — deterministic helpers, never prose in disguise.
18
+
19
+ ## The description is the router
20
+
21
+ Selection reads the description, not the body. It must name the trigger
22
+ surfaced to the model ("Use when…") and the domain keywords for routing.
23
+ Write it as the ONE line a busy router sees among 22.
24
+
25
+ ## Core budget: 120 lines
26
+
27
+ `tests/agent-skills-contract.test.mjs` pins the budget. The core keeps:
28
+
29
+ - frontmatter, one-line thesis, When-this-fires (triggers AND non-triggers),
30
+ - the operational contract (the rules that change behavior — format contracts
31
+ stay in core: the agent cannot pause to load a file mid-output),
32
+ - the `## Routing` table + the interruption rule.
33
+
34
+ Everything else — worked examples, long checklists, edge cases, fixtures —
35
+ moves to `references/`. The split precedent is `auto-continue`: 2,656 →
36
+ 1,003 tokens core, details under demand.
37
+
38
+ ## The Routing section (mandatory when references/ exists)
39
+
40
+ ```markdown
41
+ ## Routing
42
+
43
+ | Action / trigger | Reference |
44
+ |---|---|
45
+ | <what the agent is about to do> | [references/x.md](references/x.md) |
46
+
47
+ A missing reference interrupts the action — read nothing in its place, never
48
+ improvise from memory.
49
+ ```
50
+
51
+ The table is the source of truth; validate-routing fails the build when a
52
+ cited path is missing on disk and warns when a shipped reference is never
53
+ cited.
54
+
55
+ ## Lifecycle
56
+
57
+ - New skill → add the catalog entry (`src/pantheon/pantheon-decision-catalog.ts`),
58
+ the index (`src/skills/README.md`), then run `node scripts/update-skills-lock.mjs`.
59
+ - Grants: an agent runs a skill only if its frontmatter `skills:` grants it;
60
+ permissions derive fail-closed (`permission.skill: { '*': 'deny' }`).
61
+ - Capture the friction through `reflect` first; if the artifact is an agent
62
+ (not a skill), route to `agent-forge` instead.
@@ -5,60 +5,13 @@ description: "Memory bank rules, structure, and optimization — complete guide
5
5
 
6
6
  # Memory Bank
7
7
 
8
- Complete guide to Pantheon memory bank — structure, rules, optimization, and maintenance.
8
+ Pantheon memory bank — rules, structure, and maintenance. The rules below change behavior; tables of detail live in `references/`.
9
9
 
10
10
  ---
11
11
 
12
- ## Actual Storage Model
12
+ ## Storage Guardrail
13
13
 
14
- | System | Where | Owner | Lifetime | Purpose |
15
- |--------|-------|-------|----------|---------|
16
- | **Durable Memory** | `pantheon-memory` MCP (SQLite `memory.db`) | Agents with the relevant tool grant | No entry TTL; retained until explicitly forgotten | Reusable facts and decisions |
17
- | **Persistence** | `pantheon-persistence` MCP | Agents with the relevant tool grant | Optional, separate checkpoint/KV store; checkpoint TTLs apply | Explicit session/workflow checkpoints and temporary state |
18
- | **Memory Bank** | `.pantheon/memory-bank/` | Team | Files persist in the working tree; Git tracking depends on repository ignore/commit policy | Project context: architecture, patterns, progress, ADRs |
19
-
20
- Pantheon does not implement `/memories/repo/` or `/memories/session/` stores.
21
- Memory Bank files are read explicitly or on demand through
22
- `pantheon://memory-bank/{path}` from `pantheon-resources`; they are not
23
- auto-loaded. Memory namespaces are organizational filters, not access-control
24
- boundaries, and tools are available only when the active agent is granted them.
25
-
26
- ---
27
-
28
- ## Memory Bank Structure
29
-
30
- ```
31
- .pantheon/memory-bank/
32
- ├── 00-project.md ← What is this project? (fill once)
33
- ├── 00-architecture.md ← System design and agent hierarchy
34
- ├── 00-components.md ← Component breakdown and ownership
35
- ├── 00-tech-stack.md ← Tech stack, setup, environment
36
- ├── 01-active-context.md ← Current sprint focus, decisions, blockers (MOST IMPORTANT)
37
- ├── 02-progress-log.md ← What works, what's left, milestones (append-only)
38
- ├── _tasks/
39
- │ ├── _index.md ← Task master list
40
- │ └── TASK0001-name.md ← Individual task records
41
- └── _notes/
42
- ├── _index.md ← Notes index
43
- └── NOTE0001-topic.md ← Architectural decisions, findings
44
- ```
45
-
46
- Memory Bank files are not automatically synchronized across clones. In
47
- particular, `_tasks/` records may be Git-ignored; only files tracked and
48
- committed under the repository's policy are shared through Git.
49
-
50
- ### File Update Frequency
51
-
52
- | File | Fill when | Update frequency |
53
- |------|-----------|-----------------|
54
- | `00-project.md` | Project start | Rarely |
55
- | `00-architecture.md` | Project start | On significant changes |
56
- | `00-components.md` | Project start | When components added/removed |
57
- | `00-tech-stack.md` | Project start | On stack changes |
58
- | `01-active-context.md` | Each sprint | Each sprint / major decision |
59
- | `02-progress-log.md` | First completion | Append-only per milestone |
60
- | `_tasks/` | Sprint tracking | Per task |
61
- | `_notes/` | Significant findings | Per finding |
14
+ Pantheon has no `/memories/repo/` or `/memories/session/` stores. Memory Bank files under `.pantheon/memory-bank/` are read explicitly or on demand via `pantheon://memory-bank/{path}` — never auto-loaded — and are not automatically synchronized across clones; Git tracking follows the repository's ignore/commit policy.
62
15
 
63
16
  ---
64
17
 
@@ -107,45 +60,13 @@ targets, rewrite the archive automatically, or create one artifact per phase.
107
60
 
108
61
  ---
109
62
 
110
- ## Anti-Patterns
63
+ ## Routing
111
64
 
112
- ### ❌ Session output as files
113
- ```
114
- # Wrong
115
- Create IMPLEMENTATION_SUMMARY.md
116
- Create STATUS.md
65
+ | Action / trigger | Reference |
66
+ |---|---|
67
+ | Needing where each memory system stores data, ownership, or lifetime | [references/storage-model.md](references/storage-model.md) |
68
+ | Creating/updating files and needing the layout or fill/update cadence | [references/structure-and-frequency.md](references/structure-and-frequency.md) |
69
+ | Unsure whether a write pattern (session files, phase handoffs, duplication) is allowed | [references/anti-patterns.md](references/anti-patterns.md) |
70
+ | Setting up the memory bank in a product repository | [references/product-adoption.md](references/product-adoption.md) |
117
71
 
118
- # Right
119
- @mnemosyne Append to 02-progress-log.md: [summary]
120
- ```
121
-
122
- ### ❌ Mandatory handoff after every phase
123
- ```
124
- # Wrong: After every phase → handoff to @mnemosyne
125
-
126
- # Right: Agent appends to 01-active-context.md directly
127
- At sprint close → explicit @mnemosyne invocation
128
- ```
129
-
130
- ### ❌ Duplicating information
131
- ```
132
- # Wrong: duplicate the same fact in both durable Memory and a project document
133
-
134
- # Right: Durable reusable fact → pantheon-memory (when warranted and granted)
135
- Narrative context → 00-project.md (read on demand)
136
- ```
137
-
138
- ---
139
-
140
- ## Adopting in a Product
141
-
142
- ```bash
143
- mkdir -p .pantheon/memory-bank/_tasks .pantheon/memory-bank/_notes
144
- touch .pantheon/memory-bank/_tasks/.gitkeep .pantheon/memory-bank/_notes/.gitkeep
145
- # @mnemosyne Initialize memory bank for this repository
146
- ```
147
-
148
- Add to `.github/copilot-instructions.md`:
149
- ```markdown
150
- Always read .pantheon/memory-bank/01-active-context.md before answering.
151
- ```
72
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,33 @@
1
+ # Memory Bank — Anti-Patterns
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when unsure whether a write
4
+ pattern violates the memory-bank rules. The golden rules themselves stay in
5
+ `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ### ❌ Session output as files
10
+ ```
11
+ # Wrong
12
+ Create IMPLEMENTATION_SUMMARY.md
13
+ Create STATUS.md
14
+
15
+ # Right
16
+ @mnemosyne Append to 02-progress-log.md: [summary]
17
+ ```
18
+
19
+ ### ❌ Mandatory handoff after every phase
20
+ ```
21
+ # Wrong: After every phase → handoff to @mnemosyne
22
+
23
+ # Right: Agent appends to 01-active-context.md directly
24
+ At sprint close → explicit @mnemosyne invocation
25
+ ```
26
+
27
+ ### ❌ Duplicating information
28
+ ```
29
+ # Wrong: duplicate the same fact in both durable Memory and a project document
30
+
31
+ # Right: Durable reusable fact → pantheon-memory (when warranted and granted)
32
+ Narrative context → 00-project.md (read on demand)
33
+ ```