pantheon-opencode 1.7.0 → 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 +64 -60
  4. package/README.md +52 -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 +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 +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
@@ -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.
@@ -42,96 +42,6 @@ Use RED → GREEN → REFACTOR for behavior-changing implementation where a mean
42
42
 
43
43
  ---
44
44
 
45
- ## Testing by Layer
46
-
47
- ### Backend (Hermes)
48
- ```python
49
- # Unit: service logic
50
- def test_calculate_discount_applies_percentage():
51
- result = calculate_discount(100, 10)
52
- assert result == 90.0
53
-
54
- # Integration: API endpoint
55
- def test_get_user_returns_404_for_missing():
56
- response = client.get("/users/nonexistent")
57
- assert response.status_code == 404
58
-
59
- # Database: repository
60
- def test_user_repository_saves_and_retrieves():
61
- repo.save(User(id="1", name="Test"))
62
- assert repo.find("1").name == "Test"
63
- ```
64
-
65
- ### Frontend (Aphrodite)
66
- ```typescript
67
- // Test behavior, not implementation
68
- test('shows error message on invalid form', async () => {
69
- render(<LoginForm />)
70
- await userEvent.click(screen.getByText('Submit'))
71
- expect(screen.getByText('Email is required')).toBeInTheDocument()
72
- })
73
- ```
74
-
75
- ### Database (Demeter)
76
- ```python
77
- def test_migration_creates_users_table():
78
- alembic upgrade(head)
79
- assert inspector.has_table('users')
80
-
81
- def test_migration_rollback_drops_table():
82
- alembic upgrade(head)
83
- alembic downgrade(-1)
84
- assert not inspector.has_table('users')
85
- ```
86
-
87
- ---
88
-
89
- ## Advanced Testing Patterns
90
-
91
- ### E2E Testing (Playwright)
92
- ```typescript
93
- test('user can complete full signup flow', async ({ page }) => {
94
- await page.goto('/signup')
95
- await page.fill('[name="email"]', 'test@example.com')
96
- await page.fill('[name="password"]', 'secure123')
97
- await page.click('button[type="submit"]')
98
- await expect(page.locator('.welcome-banner')).toBeVisible()
99
- })
100
- ```
101
-
102
- ### Load Testing (k6/Locust)
103
- ```javascript
104
- // k6 script
105
- export const options = { vus: 50, duration: '30s' }
106
- export default function () {
107
- http.get('http://localhost:8000/api/users')
108
- }
109
- ```
110
-
111
- ### Contract Testing (Pact)
112
- ```python
113
- # Provider verifies consumer contract
114
- @pact.verify_provider
115
- def test_provider_satisfies_consumer_contract():
116
- # Verify all interactions from pact file
117
- pass
118
- ```
119
-
120
- ### Mutation Testing (high-risk/critical logic only)
121
- - Mutate source code (change `>` to `<`, remove conditions)
122
- - Run tests → should fail (mutation killed)
123
- - If tests pass → test is weak; improve it
124
-
125
- ### Visual Regression (visual behavior only)
126
- ```typescript
127
- test('homepage looks the same', async ({ page }) => {
128
- await page.goto('/')
129
- await expect(page).toHaveScreenshot('homepage.png')
130
- })
131
- ```
132
-
133
- ---
134
-
135
45
  ## Coverage Rules
136
46
 
137
47
  - Follow a repository's explicit coverage threshold when the changed code is in its measurement scope; do not manufacture a coverage target for docs, formatting, or a tiny isolated edit.
@@ -141,17 +51,6 @@ test('homepage looks the same', async ({ page }) => {
141
51
 
142
52
  ---
143
53
 
144
- ## Agent Responsibilities
145
-
146
- | Agent | Tests |
147
- |-------|-------|
148
- | **Hermes** | Unit + integration for FastAPI endpoints, services, middleware |
149
- | **Aphrodite** | Component behavior tests with React Testing Library |
150
- | **Demeter** | Migration upgrade/downgrade, query correctness |
151
- | **Themis** | Reviews the changed surface, relevant edge/error cases, and applicable repository coverage requirements; always review sensitive/material changes |
152
-
153
- ---
154
-
155
54
  ## Workflow
156
55
 
157
56
  ```
@@ -173,3 +72,14 @@ test('homepage looks the same', async ({ page }) => {
173
72
  - ❌ Mocking everything (test real behavior where possible)
174
73
  - ❌ Skipping RED step (test must fail first)
175
74
  - ❌ Ignoring flaky tests (fix or delete)
75
+
76
+ ---
77
+
78
+ ## Routing
79
+
80
+ | Action / trigger | Reference |
81
+ |---|---|
82
+ | Writing tests for a specific layer (Hermes/Aphrodite/Demeter) or assigning per-agent test duties | [references/testing-by-layer.md](references/testing-by-layer.md) |
83
+ | When risk or surface warrants E2E, load, contract, mutation, or visual-regression testing | [references/advanced-testing-patterns.md](references/advanced-testing-patterns.md) |
84
+
85
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.
@@ -0,0 +1,58 @@
1
+ # TDD with Agents — Advanced Testing Patterns
2
+
3
+ Detail companion for `SKILL.md`. Advanced patterns are reserved for changes
4
+ that warrant them — read on demand only when the change's risk or surface
5
+ calls for that pattern. The TDD cycle, proportional rules, coverage rules,
6
+ and anti-patterns stay in `SKILL.md`.
7
+
8
+ ---
9
+
10
+ ## E2E Testing (Playwright)
11
+ ```typescript
12
+ test('user can complete full signup flow', async ({ page }) => {
13
+ await page.goto('/signup')
14
+ await page.fill('[name="email"]', 'test@example.com')
15
+ await page.fill('[name="password"]', 'secure123')
16
+ await page.click('button[type="submit"]')
17
+ await expect(page.locator('.welcome-banner')).toBeVisible()
18
+ })
19
+ ```
20
+
21
+ ---
22
+
23
+ ## Load Testing (k6/Locust)
24
+ ```javascript
25
+ // k6 script
26
+ export const options = { vus: 50, duration: '30s' }
27
+ export default function () {
28
+ http.get('http://localhost:8000/api/users')
29
+ }
30
+ ```
31
+
32
+ ---
33
+
34
+ ## Contract Testing (Pact)
35
+ ```python
36
+ # Provider verifies consumer contract
37
+ @pact.verify_provider
38
+ def test_provider_satisfies_consumer_contract():
39
+ # Verify all interactions from pact file
40
+ pass
41
+ ```
42
+
43
+ ---
44
+
45
+ ## Mutation Testing (high-risk/critical logic only)
46
+ - Mutate source code (change `>` to `<`, remove conditions)
47
+ - Run tests → should fail (mutation killed)
48
+ - If tests pass → test is weak; improve it
49
+
50
+ ---
51
+
52
+ ## Visual Regression (visual behavior only)
53
+ ```typescript
54
+ test('homepage looks the same', async ({ page }) => {
55
+ await page.goto('/')
56
+ await expect(page).toHaveScreenshot('homepage.png')
57
+ })
58
+ ```
@@ -0,0 +1,60 @@
1
+ # TDD with Agents — Testing by Layer
2
+
3
+ Detail companion for `SKILL.md`. Read on demand when writing tests for a
4
+ specific layer or assigning test duties in a delegation. The TDD cycle,
5
+ proportional rules, coverage rules, and workflow stay in `SKILL.md`.
6
+
7
+ ---
8
+
9
+ ## Testing by Layer
10
+
11
+ ### Backend (Hermes)
12
+ ```python
13
+ # Unit: service logic
14
+ def test_calculate_discount_applies_percentage():
15
+ result = calculate_discount(100, 10)
16
+ assert result == 90.0
17
+
18
+ # Integration: API endpoint
19
+ def test_get_user_returns_404_for_missing():
20
+ response = client.get("/users/nonexistent")
21
+ assert response.status_code == 404
22
+
23
+ # Database: repository
24
+ def test_user_repository_saves_and_retrieves():
25
+ repo.save(User(id="1", name="Test"))
26
+ assert repo.find("1").name == "Test"
27
+ ```
28
+
29
+ ### Frontend (Aphrodite)
30
+ ```typescript
31
+ // Test behavior, not implementation
32
+ test('shows error message on invalid form', async () => {
33
+ render(<LoginForm />)
34
+ await userEvent.click(screen.getByText('Submit'))
35
+ expect(screen.getByText('Email is required')).toBeInTheDocument()
36
+ })
37
+ ```
38
+
39
+ ### Database (Demeter)
40
+ ```python
41
+ def test_migration_creates_users_table():
42
+ alembic upgrade(head)
43
+ assert inspector.has_table('users')
44
+
45
+ def test_migration_rollback_drops_table():
46
+ alembic upgrade(head)
47
+ alembic downgrade(-1)
48
+ assert not inspector.has_table('users')
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Agent Responsibilities
54
+
55
+ | Agent | Tests |
56
+ |-------|-------|
57
+ | **Hermes** | Unit + integration for FastAPI endpoints, services, middleware |
58
+ | **Aphrodite** | Component behavior tests with React Testing Library |
59
+ | **Demeter** | Migration upgrade/downgrade, query correctness |
60
+ | **Themis** | Reviews the changed surface, relevant edge/error cases, and applicable repository coverage requirements; always review sensitive/material changes |
@@ -7,11 +7,11 @@ description: "Automated visual review pipeline — Playwright screenshots, self-
7
7
 
8
8
  Automated visual review: Aphrodite captures screenshots via Playwright MCP → Self-analyzes for visual issues → Addresses findings in a loop.
9
9
 
10
- ## Overview
10
+ This pipeline enforces structured JSON output, iteration limits, and escalation criteria to prevent infinite fix loops.
11
11
 
12
- This pipeline establishes a formal workflow for detecting and resolving visual regressions and design issues. It enforces structured JSON output, iteration limits, and escalation criteria to prevent infinite fix loops.
12
+ ---
13
13
 
14
- ### Pipeline Flow
14
+ ## Loop Contract
15
15
 
16
16
  ```
17
17
  Aphrodite implements UI
@@ -25,43 +25,7 @@ Aphrodite self-analyzes (layout, contrast, responsive, accessibility)
25
25
  └─ verdict: fail + iteration = 3 → Zeus escalation
26
26
  ```
27
27
 
28
- ## Workflow Steps
29
-
30
- ### Step 1: Capture
31
- Aphrodite uses Playwright MCP to capture screenshots.
32
- - Navigate to target URL or render component
33
- - Capture full-page screenshot via `browser/screenshotPage`
34
- - Capture viewport-specific screenshots for responsive checks
35
- - Name files descriptively: `screenshot-iteration-N-component.png`
36
-
37
- ### Step 2: Analyze
38
- Aphrodite self-analyzes screenshots visually.
39
- - Examine screenshot(s) for visual issues
40
- - Identify problems in layout, contrast, responsive behavior, and accessibility
41
- - Return findings in the structured JSON schema (below)
42
- - Include iteration number in findings
43
- - Mark issues with `pass_if_fixed` IDs
44
-
45
- ### Step 3: Fix
46
- Aphrodite addresses each finding from self-analysis.
47
- - Triage findings by severity (critical → high → medium → low)
48
- - Fix each issue in component code
49
- - Commit changes with descriptive message
50
- - Re-capture screenshot for next iteration
51
-
52
- ### Step 4: Loop
53
- Repeat Steps 1-3 for up to **3 iterations**.
54
- - Each iteration must fix at least one `pass_if_fixed` issue
55
- - Track iteration count in findings object
56
- - If no progress detected (zero fixes applied), escalate immediately
57
- - Compare before/after screenshots to verify fixes
58
-
59
- ### Step 5: Escalate
60
- Zeus intervenes if issues persist after 3 iterations.
61
- - **Trigger:** 3 iterations exhausted or zero-progress detected
62
- - **Action:** Zeus coordinates manual review or architectural decision
63
-
64
- ## JSON Schema
28
+ ## Findings Contract (format safety — keep in core)
65
29
 
66
30
  Aphrodite must return findings in this exact structure:
67
31
 
@@ -85,44 +49,6 @@ Aphrodite must return findings in this exact structure:
85
49
  }
86
50
  ```
87
51
 
88
- ### Field Definitions
89
-
90
- | Field | Type | Description |
91
- |-------|------|-------------|
92
- | `verdict` | enum | `pass` = no issues, `fail` = blocking, `warn` = non-blocking |
93
- | `iteration` | int | Current iteration number (1-3) |
94
- | `max_iterations` | int | Always 3 |
95
- | `issues` | array | List of visual issues found |
96
- | `issues[].id` | string | Unique ID in format `VIS-NNN` |
97
- | `issues[].category` | enum | Issue category (see Categories) |
98
- | `issues[].severity` | enum | Severity level (see Severity) |
99
- | `issues[].description` | string | Clear description of the issue |
100
- | `issues[].screenshot_region` | string | Bounding box or region reference |
101
- | `issues[].recommendation` | string | Suggested fix |
102
- | `summary` | string | One-line overall assessment |
103
- | `pass_if_fixed` | string[] | Issue IDs that must be resolved to pass |
104
-
105
- ## Categories
106
-
107
- | Category | Description | Examples |
108
- |----------|-------------|---------|
109
- | `layout` | Positioning, alignment, overflow | Element misplaced, container overflow, z-index issues |
110
- | `contrast` | Color contrast, visibility | Text hard to read, low contrast ratio |
111
- | `responsive` | Mobile/tablet behavior | Elements break at specific breakpoints |
112
- | `missing_element` | Expected element not rendered | Button not visible, icon missing |
113
- | `typography` | Font, size, weight, spacing | Wrong font family, text truncation |
114
- | `spacing` | Margins, padding, gaps | Uneven spacing, cramped elements |
115
- | `accessibility` | ARIA, focus states, keyboard nav | Missing alt text, no focus ring |
116
-
117
- ## Severity Levels
118
-
119
- | Level | Description | Action Required |
120
- |-------|-------------|-----------------|
121
- | `critical` | Blocks user interaction or content | Must fix before merge |
122
- | `high` | Significant visual regression | Must fix before merge |
123
- | `medium` | Noticeable but not blocking | Fix in current sprint |
124
- | `low` | Minor polish item | Backlog, fix when convenient |
125
-
126
52
  ## Iteration Rules
127
53
 
128
54
  1. **Minimum progress:** Each iteration fixes at least one `pass_if_fixed` issue
@@ -131,14 +57,6 @@ Aphrodite must return findings in this exact structure:
131
57
  4. **Early exit:** If `verdict` is `pass`, stop iterating
132
58
  5. **Immediate escalation:** If zero issues fixed in an iteration, escalate to Zeus
133
59
 
134
- ### Progress Detection
135
- ```
136
- Iteration N:
137
- - Compare pass_if_fixed list to previous iteration
138
- - If any ID removed from pass_if_fixed → progress detected
139
- - If pass_if_fixed unchanged → zero progress → escalate
140
- ```
141
-
142
60
  ## Escalation Criteria
143
61
 
144
62
  Zeus must be invoked when:
@@ -148,13 +66,6 @@ Zeus must be invoked when:
148
66
  4. **Zero progress** — no `pass_if_fixed` issues resolved in an iteration
149
67
  5. **Conflicting fixes** — resolving one issue introduces another
150
68
 
151
- **Escalation format:**
152
- ```
153
- @zeus Visual review escalation: [component] failed after [N] iterations.
154
- Remaining issues: [list of unresolved pass_if_fixed IDs]
155
- Root cause: [backend | architectural | conflicting]
156
- ```
157
-
158
69
  ## MCP Requirements
159
70
 
160
71
  ### Playwright MCP (Required)
@@ -167,33 +78,13 @@ Root cause: [backend | architectural | conflicting]
167
78
  ```
168
79
  For UI implementation review, Aphrodite self-reviews.
169
80
 
170
- ## Integration Points
81
+ ---
171
82
 
172
- - **Code Review (Themis):** Visual review runs as part of frontend code review; findings feed into Themis's verdict.
173
- - **Artifact Protocol:** Visual review findings can attach to `IMPL-` artifacts. Escalation decisions documented in `_notes/`.
174
- - **Memory Bank:** Recurring visual issues documented in `01-active-context.md`. Architectural visual decisions recorded as `_notes/NOTE000X-*.md`.
83
+ ## Routing
175
84
 
176
- ## Example Workflow
85
+ | Action / trigger | Reference |
86
+ |---|---|
87
+ | Running the capture → analyze → fix loop, writing the escalation message, or wiring integrations | [references/workflow-steps.md](references/workflow-steps.md) |
88
+ | Classifying findings fields, issue categories, or severity levels | [references/findings-schema.md](references/findings-schema.md) |
177
89
 
178
- ```
179
- 1. Aphrodite captures screenshot of LoginButton
180
- → screenshot-iteration-1-login-button.png
181
-
182
- 2. Self-analysis returns:
183
- {
184
- "verdict": "fail", "iteration": 1,
185
- "issues": [{
186
- "id": "VIS-001", "category": "contrast", "severity": "high",
187
- "description": "White text on light blue bg, contrast ratio 2.1:1",
188
- "recommendation": "Darken background to #1a56db"
189
- }],
190
- "pass_if_fixed": ["VIS-001"]
191
- }
192
-
193
- 3. Fix contrast, re-capture → screenshot-iteration-2-login-button.png
194
-
195
- 4. Re-analysis: { "verdict": "pass", "iteration": 2, "issues": [],
196
- "summary": "All visual issues resolved", "pass_if_fixed": [] }
197
-
198
- 5. Pipeline complete — 2 iterations, all issues fixed.
199
- ```
90
+ A missing reference interrupts the action — read nothing in its place, never improvise from memory.