pantheon-opencode 1.7.0 → 2.0.0-beta.2

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 (173) hide show
  1. package/AGENTS.global.md +2 -2
  2. package/AGENTS.md +3 -3
  3. package/CHANGELOG.md +85 -59
  4. package/README.md +74 -48
  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 +1 -1
  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 +22 -61
  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 +2870 -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 +5612 -2086
  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/decision-router-state.ts +242 -0
  103. package/src/plugins/tui/src/doctor-state.ts +198 -0
  104. package/src/plugins/tui/src/index.tsx +4222 -2822
  105. package/src/plugins/tui/src/j1-gate-status.ts +85 -0
  106. package/src/plugins/tui/src/pantheon-settings-state.ts +245 -0
  107. package/src/plugins/tui/src/pantheon-settings.tsx +442 -0
  108. package/src/plugins/tui/src/preset-state.ts +143 -0
  109. package/src/plugins/tui/src/server.ts +23 -10
  110. package/src/plugins/tui/src/update-notice.ts +90 -0
  111. package/src/plugins/tui/src/update-status.ts +98 -0
  112. package/src/plugins/tui/tsconfig.typecheck.json +9 -2
  113. package/src/plugins/tui/tsdown.config.ts +3 -5
  114. package/src/plugins/tui/tui.ts +1 -2
  115. package/src/routing.yml +36 -0
  116. package/src/skills/README.md +16 -1
  117. package/src/skills/artifact-management/SKILL.md +10 -67
  118. package/src/skills/artifact-management/references/artifact-templates.md +71 -0
  119. package/src/skills/auto-continue/SKILL.md +10 -0
  120. package/src/skills/code-review-checklist/SKILL.md +11 -44
  121. package/src/skills/code-review-checklist/references/review-checklists.md +54 -0
  122. package/src/skills/instruction-forge/SKILL.md +57 -0
  123. package/src/skills/instruction-forge/references/agents-md-doctrine.md +50 -0
  124. package/src/skills/instruction-forge/references/eval-doctrine.md +37 -0
  125. package/src/skills/instruction-forge/references/skill-doctrine.md +62 -0
  126. package/src/skills/memory-bank/SKILL.md +11 -90
  127. package/src/skills/memory-bank/references/anti-patterns.md +33 -0
  128. package/src/skills/memory-bank/references/product-adoption.md +19 -0
  129. package/src/skills/memory-bank/references/storage-model.md +21 -0
  130. package/src/skills/memory-bank/references/structure-and-frequency.md +44 -0
  131. package/src/skills/reflect/SKILL.md +1 -0
  132. package/src/skills/session-goal/SKILL.md +7 -54
  133. package/src/skills/session-goal/references/goal-format.md +26 -0
  134. package/src/skills/session-goal/references/session-reuse.md +44 -0
  135. package/src/skills/tdd-with-agents/SKILL.md +11 -101
  136. package/src/skills/tdd-with-agents/references/advanced-testing-patterns.md +58 -0
  137. package/src/skills/tdd-with-agents/references/testing-by-layer.md +60 -0
  138. package/src/skills/visual-review-pipeline/SKILL.md +11 -120
  139. package/src/skills/visual-review-pipeline/references/findings-schema.md +49 -0
  140. package/src/skills/visual-review-pipeline/references/workflow-steps.md +111 -0
  141. package/scripts/hooks/log-session-start.sh +0 -48
  142. package/scripts/hooks/validate-post-conditions.sh +0 -21
  143. package/scripts/hooks/validate-talos-scope.sh +0 -50
  144. package/scripts/hooks/validate-tool-safety.sh +0 -49
  145. package/src/pantheon/goal-loop.ts +0 -314
  146. package/src/pantheon/idle-continuation.ts +0 -52
  147. package/src/pantheon/todo-preserve.ts +0 -301
  148. package/src/pantheon/tool-ceiling.ts +0 -159
  149. package/src/pantheon/v2-bridge.ts +0 -153
  150. package/src/plugin-v2.ts +0 -2954
  151. package/src/plugins/pantheon-hooks.ts +0 -1433
  152. package/src/plugins/tui/dist/server-v2.d.ts +0 -30
  153. package/src/plugins/tui/dist/server-v2.d.ts.map +0 -1
  154. package/src/plugins/tui/dist/server-v2.js +0 -33
  155. package/src/plugins/tui/dist/server-v2.js.map +0 -1
  156. package/src/plugins/tui/dist/tui-v2.d.ts +0 -1039
  157. package/src/plugins/tui/dist/tui-v2.d.ts.map +0 -1
  158. package/src/plugins/tui/dist/tui-v2.js +0 -4597
  159. package/src/plugins/tui/dist/tui-v2.js.map +0 -1
  160. package/src/plugins/tui/src/index-v2.tsx +0 -4496
  161. package/src/plugins/tui/src/server-v2.ts +0 -28
  162. package/src/plugins/tui/tui-v2.ts +0 -2
  163. /package/src/pantheon/{v2-decision-budget.ts → decision-budget.ts} +0 -0
  164. /package/src/pantheon/{v2-decision-egress.ts → decision-egress.ts} +0 -0
  165. /package/src/pantheon/{v2-decision-events.ts → decision-events.ts} +0 -0
  166. /package/src/pantheon/{v2-decision-heuristic.ts → decision-heuristic.ts} +0 -0
  167. /package/src/pantheon/{v2-decision-premises.ts → decision-premises.ts} +0 -0
  168. /package/src/pantheon/{v2-decision-rank.ts → decision-rank.ts} +0 -0
  169. /package/src/pantheon/{v2-decision-verify.ts → decision-verify.ts} +0 -0
  170. /package/src/pantheon/{v2-delegation-enforce.ts → delegation-policy.ts} +0 -0
  171. /package/src/pantheon/{v2-model-overrides.ts → model-overrides.ts} +0 -0
  172. /package/src/pantheon/{v2-native-decisions.ts → native-decisions.ts} +0 -0
  173. /package/src/plugins/tui/src/{opencode-v2.d.ts → opencode.d.ts} +0 -0
@@ -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
+ ```
@@ -0,0 +1,19 @@
1
+ # Memory Bank — Adopting in a Product
2
+
3
+ Detail companion for `SKILL.md`. Read on demand only when setting up the
4
+ memory bank in a new product repository.
5
+
6
+ ---
7
+
8
+ ## Adopting in a Product
9
+
10
+ ```bash
11
+ mkdir -p .pantheon/memory-bank/_tasks .pantheon/memory-bank/_notes
12
+ touch .pantheon/memory-bank/_tasks/.gitkeep .pantheon/memory-bank/_notes/.gitkeep
13
+ # @mnemosyne Initialize memory bank for this repository
14
+ ```
15
+
16
+ Add to `.github/copilot-instructions.md`:
17
+ ```markdown
18
+ Always read .pantheon/memory-bank/01-active-context.md before answering.
19
+ ```
@@ -0,0 +1,21 @@
1
+ # Memory Bank — Storage Model
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when you need where a memory
4
+ system physically stores data, who owns it, or its lifetime. Golden rules,
5
+ who-writes-what, and maintenance policy stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Actual Storage Model
10
+
11
+ | System | Where | Owner | Lifetime | Purpose |
12
+ |--------|-------|-------|----------|---------|
13
+ | **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 |
14
+ | **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 |
15
+ | **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 |
16
+
17
+ Pantheon does not implement `/memories/repo/` or `/memories/session/` stores.
18
+ Memory Bank files are read explicitly or on demand through
19
+ `pantheon://memory-bank/{path}` from `pantheon-resources`; they are not
20
+ auto-loaded. Memory namespaces are organizational filters, not access-control
21
+ boundaries, and tools are available only when the active agent is granted them.
@@ -0,0 +1,44 @@
1
+ # Memory Bank — Structure and Update Frequency
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when creating or updating
4
+ memory-bank files and you need the layout, file purposes, or the fill/update
5
+ cadence. Golden rules and who-writes-what stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Memory Bank Structure
10
+
11
+ ```
12
+ .pantheon/memory-bank/
13
+ ├── 00-project.md ← What is this project? (fill once)
14
+ ├── 00-architecture.md ← System design and agent hierarchy
15
+ ├── 00-components.md ← Component breakdown and ownership
16
+ ├── 00-tech-stack.md ← Tech stack, setup, environment
17
+ ├── 01-active-context.md ← Current sprint focus, decisions, blockers (MOST IMPORTANT)
18
+ ├── 02-progress-log.md ← What works, what's left, milestones (append-only)
19
+ ├── _tasks/
20
+ │ ├── _index.md ← Task master list
21
+ │ └── TASK0001-name.md ← Individual task records
22
+ └── _notes/
23
+ ├── _index.md ← Notes index
24
+ └── NOTE0001-topic.md ← Architectural decisions, findings
25
+ ```
26
+
27
+ Memory Bank files are not automatically synchronized across clones. In
28
+ particular, `_tasks/` records may be Git-ignored; only files tracked and
29
+ committed under the repository's policy are shared through Git.
30
+
31
+ ---
32
+
33
+ ## File Update Frequency
34
+
35
+ | File | Fill when | Update frequency |
36
+ |------|-----------|-----------------|
37
+ | `00-project.md` | Project start | Rarely |
38
+ | `00-architecture.md` | Project start | On significant changes |
39
+ | `00-components.md` | Project start | When components added/removed |
40
+ | `00-tech-stack.md` | Project start | On stack changes |
41
+ | `01-active-context.md` | Each sprint | Each sprint / major decision |
42
+ | `02-progress-log.md` | First completion | Append-only per milestone |
43
+ | `_tasks/` | Sprint tracking | Per task |
44
+ | `_notes/` | Significant findings | Per finding |
@@ -46,4 +46,5 @@ After completing a task, reflect on what could be improved in the workflow itsel
46
46
  - Be specific: "Searched for auth patterns 4x" not "too much searching"
47
47
  - One action item per friction point
48
48
  - Escalate to @mnemosyne for memory-bank updates
49
+ - "Create skill" and "Add instruction" action items are executed through `instruction-forge` (it owns where the rule lives and how it is tested); "Update agent" routes to `agent-forge`
49
50
  - At end: "Reflection complete. Action items created."
@@ -33,26 +33,9 @@ All work in this session must serve this goal.
33
33
  3. **Focuses verification** — Themis checks that implementations serve the goal
34
34
  4. **Surfaces drift** — if a task drifts from the goal, flag it before proceeding
35
35
 
36
- ---
37
-
38
36
  ## Goal Format
39
37
 
40
- A good session goal has 4 components:
41
-
42
- ```
43
- GOAL: <What to build>
44
- SCOPE: <Which layers/modules are in scope>
45
- SUCCESS CRITERIA: <How we know it's done>
46
- OUT OF SCOPE: <What to explicitly exclude>
47
- ```
48
-
49
- **Example:**
50
- ```
51
- GOAL: Add email verification to the registration flow
52
- SCOPE: Backend (POST /auth/verify, token model), Frontend (VerifyEmail page), DB (verification_tokens table)
53
- SUCCESS CRITERIA: User can register, receive a verification email link, click it, and have their account marked as verified. All layers tested >80% coverage.
54
- OUT OF SCOPE: Password reset, 2FA, email template design
55
- ```
38
+ Pin four components — `GOAL`, `SCOPE`, `SUCCESS CRITERIA`, `OUT OF SCOPE`. Full template and worked example: [references/goal-format.md](references/goal-format.md).
56
39
 
57
40
  ---
58
41
 
@@ -94,41 +77,11 @@ Never silently drift from the goal — always confirm with the user before chang
94
77
 
95
78
  ---
96
79
 
97
- ## Session Reuse (Cross-Task Continuity)
98
-
99
- Reuse agent sessions between related delegations to avoid re-reading files and re-building context.
100
-
101
- ### When to Reuse
102
-
103
- Prefer reusing an existing session when:
104
- - Follow-up task touches the **same files** or **same feature thread** as a previous delegation
105
- - The specialist already loaded relevant file context in the prior session
106
- - Debugging continues on the same stack trace or module
107
-
108
- ### When to Start Fresh
109
-
110
- Force a new session when:
111
- - Unrelated feature or different part of the codebase
112
- - Previous session has too much noise from an abandoned investigation
113
- - The specialist's accumulated context would mislead the new task
114
-
115
- ### How to Signal Reuse
116
-
117
- When dispatching a follow-up task, include the session reuse context explicitly:
118
-
119
- ```
120
- @hermes — continuing the auth endpoint work from the previous session.
121
- Files already explored: backend/routers/auth.py, backend/services/auth_service.py.
122
- New task: add refresh token rotation.
123
- ```
124
-
125
- ### Session Tracking
126
-
127
- Zeus tracks active sessions with a `task_id` per delegation:
80
+ ## Routing
128
81
 
129
- | Agent | Active Session | Files in Context | Max Age |
130
- |-------|---------------|-----------------|---------|
131
- | hermes | ses_abc123 | 4 files | 15 min |
132
- | aphrodite | ses_def456 | 3 files | 15 min |
82
+ | Action / trigger | Reference |
83
+ |---|---|
84
+ | Pinning a goal and needing the full template or a worked example | [references/goal-format.md](references/goal-format.md) |
85
+ | Deciding whether a follow-up delegation reuses an agent session or starts fresh (reuse criteria, signaling, `task_id` tracking) | [references/session-reuse.md](references/session-reuse.md) |
133
86
 
134
- When `session_max: 2` is set in routing.yml, Zeus keeps the last 2 sessions for that agent and discards older ones. This prevents stale context from accumulating.
87
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,26 @@
1
+ # Session Goal — Format Template and Example
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when pinning a goal and you
4
+ need the full template or a worked example. The alignment check and the
5
+ persistence guardrails stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Goal Format
10
+
11
+ A good session goal has 4 components:
12
+
13
+ ```
14
+ GOAL: <What to build>
15
+ SCOPE: <Which layers/modules are in scope>
16
+ SUCCESS CRITERIA: <How we know it's done>
17
+ OUT OF SCOPE: <What to explicitly exclude>
18
+ ```
19
+
20
+ **Example:**
21
+ ```
22
+ GOAL: Add email verification to the registration flow
23
+ SCOPE: Backend (POST /auth/verify, token model), Frontend (VerifyEmail page), DB (verification_tokens table)
24
+ SUCCESS CRITERIA: User can register, receive a verification email link, click it, and have their account marked as verified. All layers tested >80% coverage.
25
+ OUT OF SCOPE: Password reset, 2FA, email template design
26
+ ```
@@ -0,0 +1,44 @@
1
+ # Session Goal — Session Reuse (Cross-Task Continuity)
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when deciding whether a
4
+ follow-up delegation reuses an agent session or starts fresh. Goal pinning,
5
+ alignment checks, and persistence guardrails stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ Reuse agent sessions between related delegations to avoid re-reading files and re-building context.
10
+
11
+ ### When to Reuse
12
+
13
+ Prefer reusing an existing session when:
14
+ - Follow-up task touches the **same files** or **same feature thread** as a previous delegation
15
+ - The specialist already loaded relevant file context in the prior session
16
+ - Debugging continues on the same stack trace or module
17
+
18
+ ### When to Start Fresh
19
+
20
+ Force a new session when:
21
+ - Unrelated feature or different part of the codebase
22
+ - Previous session has too much noise from an abandoned investigation
23
+ - The specialist's accumulated context would mislead the new task
24
+
25
+ ### How to Signal Reuse
26
+
27
+ When dispatching a follow-up task, include the session reuse context explicitly:
28
+
29
+ ```
30
+ @hermes — continuing the auth endpoint work from the previous session.
31
+ Files already explored: backend/routers/auth.py, backend/services/auth_service.py.
32
+ New task: add refresh token rotation.
33
+ ```
34
+
35
+ ### Session Tracking
36
+
37
+ Zeus tracks active sessions with a `task_id` per delegation:
38
+
39
+ | Agent | Active Session | Files in Context | Max Age |
40
+ |-------|---------------|-----------------|---------|
41
+ | hermes | ses_abc123 | 4 files | 15 min |
42
+ | aphrodite | ses_def456 | 3 files | 15 min |
43
+
44
+ When `session_max: 2` is set in routing.yml, Zeus keeps the last 2 sessions for that agent and discards older ones. This prevents stale context from accumulating.