pgserve 2.1.3 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/CHANGELOG.md +86 -0
  2. package/README.md +105 -1
  3. package/bin/autopg-wrapper.cjs +16 -0
  4. package/bin/pgserve-wrapper.cjs +31 -6
  5. package/bin/postgres-server.js +56 -0
  6. package/console/README.md +131 -0
  7. package/console/api.js +173 -0
  8. package/console/app.jsx +483 -0
  9. package/console/colors_and_type.css +227 -0
  10. package/console/components.jsx +167 -0
  11. package/console/console.css +1666 -0
  12. package/console/data.jsx +350 -0
  13. package/console/index.html +31 -0
  14. package/console/screens/databases.jsx +5 -0
  15. package/console/screens/health.jsx +5 -0
  16. package/console/screens/ingress.jsx +5 -0
  17. package/console/screens/optimizer.jsx +5 -0
  18. package/console/screens/rlm-sim.jsx +5 -0
  19. package/console/screens/rlm-trace.jsx +5 -0
  20. package/console/screens/security.jsx +5 -0
  21. package/console/screens/settings.jsx +611 -0
  22. package/console/screens/sql.jsx +5 -0
  23. package/console/screens/sync.jsx +5 -0
  24. package/console/screens/tables.jsx +5 -0
  25. package/console/tweaks-panel.jsx +425 -0
  26. package/package.json +11 -1
  27. package/src/cli-config.cjs +310 -0
  28. package/src/cli-install.cjs +98 -11
  29. package/src/cli-restart.cjs +228 -0
  30. package/src/cli-ui.cjs +580 -0
  31. package/src/cluster.js +43 -38
  32. package/src/postgres.js +141 -19
  33. package/src/settings-loader.cjs +235 -0
  34. package/src/settings-migrate.cjs +212 -0
  35. package/src/settings-pg-args.cjs +146 -0
  36. package/src/settings-schema.cjs +422 -0
  37. package/src/settings-validator.cjs +416 -0
  38. package/src/settings-writer.cjs +288 -0
  39. package/.claude/context/windows-debug.md +0 -119
  40. package/.genie/AGENTS.md +0 -15
  41. package/.genie/agents/README.md +0 -110
  42. package/.genie/agents/analyze.md +0 -176
  43. package/.genie/agents/forge.md +0 -290
  44. package/.genie/agents/garbage-cleaner.md +0 -324
  45. package/.genie/agents/garbage-collector.md +0 -596
  46. package/.genie/agents/github-issue-gc.md +0 -618
  47. package/.genie/agents/review.md +0 -380
  48. package/.genie/agents/semantic-analyzer/find-duplicates.md +0 -90
  49. package/.genie/agents/semantic-analyzer/find-orphans.md +0 -99
  50. package/.genie/agents/semantic-analyzer.md +0 -101
  51. package/.genie/agents/update.md +0 -182
  52. package/.genie/agents/wish.md +0 -357
  53. package/.genie/brainstorms/pgserve-v2/DESIGN.md +0 -174
  54. package/.genie/code/AGENTS.md +0 -694
  55. package/.genie/code/agents/audit/risk.md +0 -173
  56. package/.genie/code/agents/audit/security.md +0 -189
  57. package/.genie/code/agents/audit.md +0 -145
  58. package/.genie/code/agents/challenge.md +0 -230
  59. package/.genie/code/agents/change-reviewer.md +0 -295
  60. package/.genie/code/agents/code-garbage-collector.md +0 -425
  61. package/.genie/code/agents/code-quality.md +0 -410
  62. package/.genie/code/agents/commit-suggester.md +0 -255
  63. package/.genie/code/agents/commit.md +0 -124
  64. package/.genie/code/agents/consensus.md +0 -204
  65. package/.genie/code/agents/daily-standup.md +0 -722
  66. package/.genie/code/agents/docgen.md +0 -48
  67. package/.genie/code/agents/explore.md +0 -79
  68. package/.genie/code/agents/fix.md +0 -100
  69. package/.genie/code/agents/git/commit-advisory.md +0 -219
  70. package/.genie/code/agents/git/workflows/issue.md +0 -244
  71. package/.genie/code/agents/git/workflows/pr.md +0 -179
  72. package/.genie/code/agents/git/workflows/release.md +0 -460
  73. package/.genie/code/agents/git/workflows/report.md +0 -342
  74. package/.genie/code/agents/git.md +0 -432
  75. package/.genie/code/agents/implementor.md +0 -161
  76. package/.genie/code/agents/install.md +0 -515
  77. package/.genie/code/agents/issue-creator.md +0 -344
  78. package/.genie/code/agents/polish.md +0 -116
  79. package/.genie/code/agents/qa.md +0 -653
  80. package/.genie/code/agents/refactor.md +0 -294
  81. package/.genie/code/agents/release.md +0 -1129
  82. package/.genie/code/agents/roadmap.md +0 -885
  83. package/.genie/code/agents/tests.md +0 -557
  84. package/.genie/code/agents/tracer.md +0 -50
  85. package/.genie/code/agents/update/upstream-update.md +0 -85
  86. package/.genie/code/agents/update/versions/generic-update.md +0 -305
  87. package/.genie/code/agents/vibe.md +0 -1317
  88. package/.genie/code/spells/agent-configuration.md +0 -58
  89. package/.genie/code/spells/automated-rc-publishing.md +0 -106
  90. package/.genie/code/spells/branch-tracker-guidance.md +0 -28
  91. package/.genie/code/spells/debug.md +0 -320
  92. package/.genie/code/spells/emoji-naming-convention.md +0 -303
  93. package/.genie/code/spells/evidence-storage.md +0 -26
  94. package/.genie/code/spells/file-naming-rules.md +0 -35
  95. package/.genie/code/spells/forge-code-blueprints.md +0 -195
  96. package/.genie/code/spells/genie-integration.md +0 -153
  97. package/.genie/code/spells/publishing-protocol.md +0 -61
  98. package/.genie/code/spells/team-consultation-protocol.md +0 -284
  99. package/.genie/code/spells/tool-requirements.md +0 -20
  100. package/.genie/code/spells/triad-maintenance-protocol.md +0 -154
  101. package/.genie/code/teams/tech-council/council.md +0 -328
  102. package/.genie/code/teams/tech-council/jt.md +0 -352
  103. package/.genie/code/teams/tech-council/nayr.md +0 -305
  104. package/.genie/code/teams/tech-council/oettam.md +0 -375
  105. package/.genie/neurons/README.md +0 -193
  106. package/.genie/neurons/forge.md +0 -106
  107. package/.genie/neurons/genie.md +0 -63
  108. package/.genie/neurons/review.md +0 -106
  109. package/.genie/neurons/wish.md +0 -104
  110. package/.genie/product/README.md +0 -20
  111. package/.genie/product/cli-automation.md +0 -359
  112. package/.genie/product/environment.md +0 -60
  113. package/.genie/product/mission.md +0 -60
  114. package/.genie/product/roadmap.md +0 -44
  115. package/.genie/product/tech-stack.md +0 -34
  116. package/.genie/product/templates/context-template.md +0 -218
  117. package/.genie/product/templates/qa-done-report-template.md +0 -68
  118. package/.genie/product/templates/review-report-template.md +0 -89
  119. package/.genie/product/templates/wish-template.md +0 -120
  120. package/.genie/scripts/helpers/analyze-commit.js +0 -195
  121. package/.genie/scripts/helpers/bullet-counter.js +0 -194
  122. package/.genie/scripts/helpers/bullet-find.js +0 -289
  123. package/.genie/scripts/helpers/bullet-id.js +0 -244
  124. package/.genie/scripts/helpers/check-secrets.js +0 -237
  125. package/.genie/scripts/helpers/count-tokens.js +0 -200
  126. package/.genie/scripts/helpers/create-frontmatter.js +0 -456
  127. package/.genie/scripts/helpers/detect-markers.js +0 -293
  128. package/.genie/scripts/helpers/detect-todos.js +0 -267
  129. package/.genie/scripts/helpers/detect-unlabeled-blocks.js +0 -135
  130. package/.genie/scripts/helpers/embeddings.js +0 -344
  131. package/.genie/scripts/helpers/find-empty-sections.js +0 -158
  132. package/.genie/scripts/helpers/index.js +0 -319
  133. package/.genie/scripts/helpers/validate-frontmatter.js +0 -578
  134. package/.genie/scripts/helpers/validate-links.js +0 -207
  135. package/.genie/scripts/helpers/validate-paths.js +0 -373
  136. package/.genie/spells/README.md +0 -9
  137. package/.genie/spells/ace-protocol.md +0 -118
  138. package/.genie/spells/ask-one-at-a-time.md +0 -175
  139. package/.genie/spells/backup-analyzer.md +0 -542
  140. package/.genie/spells/blocker.md +0 -12
  141. package/.genie/spells/break-things-move-fast.md +0 -56
  142. package/.genie/spells/context-candidates.md +0 -72
  143. package/.genie/spells/context-critic.md +0 -51
  144. package/.genie/spells/defer-to-expertise.md +0 -278
  145. package/.genie/spells/delegate-dont-do.md +0 -292
  146. package/.genie/spells/error-investigation-protocol.md +0 -328
  147. package/.genie/spells/evidence-based-completion.md +0 -273
  148. package/.genie/spells/experiment.md +0 -65
  149. package/.genie/spells/file-creation-protocol.md +0 -229
  150. package/.genie/spells/forge-integration.md +0 -281
  151. package/.genie/spells/forge-orchestration.md +0 -514
  152. package/.genie/spells/gather-context.md +0 -18
  153. package/.genie/spells/global-health-check.md +0 -34
  154. package/.genie/spells/global-noop-roundtrip.md +0 -25
  155. package/.genie/spells/install-genie.md +0 -1232
  156. package/.genie/spells/install.md +0 -82
  157. package/.genie/spells/investigate-before-commit.md +0 -112
  158. package/.genie/spells/know-yourself.md +0 -288
  159. package/.genie/spells/learn.md +0 -828
  160. package/.genie/spells/mcp-diagnostic-protocol.md +0 -246
  161. package/.genie/spells/mcp-first.md +0 -124
  162. package/.genie/spells/multi-step-execution.md +0 -67
  163. package/.genie/spells/orchestration-boundary-protocol.md +0 -256
  164. package/.genie/spells/orchestrator-not-implementor.md +0 -189
  165. package/.genie/spells/prompt.md +0 -746
  166. package/.genie/spells/reflect.md +0 -404
  167. package/.genie/spells/routing-decision-matrix.md +0 -368
  168. package/.genie/spells/run-in-parallel.md +0 -12
  169. package/.genie/spells/session-state-updater-example.md +0 -196
  170. package/.genie/spells/session-state-updater.md +0 -220
  171. package/.genie/spells/track-long-running-tasks.md +0 -133
  172. package/.genie/spells/troubleshoot-infrastructure.md +0 -176
  173. package/.genie/spells/upgrade-genie.md +0 -415
  174. package/.genie/spells/url-presentation-protocol.md +0 -301
  175. package/.genie/spells/wish-initiation.md +0 -158
  176. package/.genie/spells/wish-issue-linkage.md +0 -410
  177. package/.genie/spells/wish-lifecycle.md +0 -100
  178. package/.genie/state/provider-status.json +0 -3
  179. package/.genie/state/version.json +0 -16
  180. package/.genie/wishes/canonical-pgserve-pm2-supervision/WISH.md +0 -290
  181. package/.genie/wishes/pgserve-v2/BRIEF-from-genie-pgserve.md +0 -99
  182. package/.genie/wishes/pgserve-v2/WISH.md +0 -442
  183. package/.genie/wishes/release-system-genie-pattern/WISH.md +0 -268
  184. package/.genie/wishes/release-system-genie-pattern/validation.md +0 -205
  185. package/.gitguardian.yaml +0 -29
  186. package/.gitguardianignore +0 -16
  187. package/.github/workflows/ci.yml +0 -122
  188. package/.github/workflows/release.yml +0 -289
  189. package/.github/workflows/version.yml +0 -228
  190. package/.husky/pre-commit +0 -2
  191. package/AGENTS.md +0 -433
  192. package/CLAUDE.md +0 -1
  193. package/Makefile +0 -285
  194. package/assets/icon.ico +0 -0
  195. package/bun.lock +0 -435
  196. package/bunfig.toml +0 -28
  197. package/ecosystem.config.cjs +0 -23
  198. package/eslint.config.js +0 -63
  199. package/examples/multi-tenant-demo.js +0 -104
  200. package/install.sh +0 -123
  201. package/knip.json +0 -9
  202. package/scripts/test-bun-self-heal.sh +0 -163
  203. package/scripts/test-npx.sh +0 -60
  204. package/tests/audit.test.js +0 -189
  205. package/tests/backpressure.test.js +0 -167
  206. package/tests/benchmarks/runner.js +0 -1197
  207. package/tests/benchmarks/vector-generator.js +0 -368
  208. package/tests/cli-install.test.js +0 -322
  209. package/tests/control-db.test.js +0 -285
  210. package/tests/daemon-args.test.js +0 -86
  211. package/tests/daemon-control.test.js +0 -171
  212. package/tests/daemon-fingerprint-integration.test.js +0 -111
  213. package/tests/daemon-pr24-regression.test.js +0 -198
  214. package/tests/fingerprint.test.js +0 -263
  215. package/tests/fixtures/240-orphan-seed.sql +0 -30
  216. package/tests/multi-tenant.test.js +0 -374
  217. package/tests/orphan-cleanup.test.js +0 -390
  218. package/tests/pg-version-regex.test.js +0 -129
  219. package/tests/quick-bench.js +0 -135
  220. package/tests/router-handshake-retry.test.js +0 -119
  221. package/tests/router-handshake-watchdog.test.js +0 -110
  222. package/tests/sdk.test.js +0 -71
  223. package/tests/stale-postmaster-pid.test.js +0 -85
  224. package/tests/stress-test.js +0 -439
  225. package/tests/sync-perf-test.js +0 -150
  226. package/tests/tcp-listen.test.js +0 -368
  227. package/tests/tenancy.test.js +0 -403
  228. package/tests/wrapper-supervision.test.js +0 -107
@@ -1,514 +0,0 @@
1
- ---
2
- name: Forge Orchestration
3
- description: Complete Forge orchestration - delegation workflow, patterns, MCP task descriptions
4
- ---
5
-
6
- # Forge Orchestration - Complete Guide
7
-
8
- **Purpose:** Proper delegation patterns for Forge operations and execution coordination
9
-
10
- ---
11
-
12
- ## Part 1: Orchestration Workflow 🔴 CRITICAL
13
-
14
- **Core Principle:** Genie (base orchestrator) does NOT create Forge tasks directly.
15
-
16
- Genie orchestrates via **wish → forge → review** workflow delegation.
17
-
18
- ### The Mistake Pattern (NEVER DO)
19
-
20
- **What happened:**
21
- ```
22
- User: "Learn about proper Forge workflow"
23
-
24
- Genie: Creates Forge task directly via mcp__automagik_forge__create_task
25
-
26
- ❌ WRONG: Genie executed implementation instead of orchestrating
27
- ```
28
-
29
- **Why this is wrong:**
30
- 1. Genie's role is **orchestration**, not execution
31
- 2. Skips wish planning step (no context gathering)
32
- 3. Skips forge breakdown step (no execution groups)
33
- 4. Skips review validation step (no quality gate)
34
- 5. Direct MCP usage = implementation work (not orchestration)
35
-
36
- ### The Correct Pattern (ALWAYS DO)
37
-
38
- **Proper workflow:**
39
- ```
40
- User: "Learn about proper Forge workflow"
41
-
42
- Genie: Delegates to wish.md agent
43
-
44
- wish.md: Creates wish document with context
45
-
46
- Genie: Delegates to forge.md agent
47
-
48
- forge.md: Breaks wish into execution groups, creates Forge tasks
49
-
50
- Genie: Delegates to review.md agent
51
-
52
- review.md: Validates implementation against wish acceptance criteria
53
-
54
- ✅ CORRECT: Complete orchestration chain with proper delegation
55
- ```
56
-
57
- ---
58
-
59
- ## Part 2: Three-Step Workflow Breakdown
60
-
61
- ### Step 1: wish.md Agent (Planning)
62
-
63
- **Purpose:** Gather context and create wish document
64
-
65
- **Genie delegates:**
66
- ```
67
- mcp__genie__run with agent="wish" and prompt="[User's request with full context]"
68
- ```
69
-
70
- **wish.md creates:**
71
- - [forge-orch-001] helpful=0 harmful=0: `.genie/wishes/YYYY-MM-DD-topic/YYYY-MM-DD-topic-wish.md`
72
- - [forge-orch-002] helpful=0 harmful=0: Context gathered from conversation
73
- - [forge-orch-003] helpful=0 harmful=0: Problem statement
74
- - [forge-orch-004] helpful=0 harmful=0: Proposed solution
75
- - [forge-orch-005] helpful=0 harmful=0: Acceptance criteria
76
- - [forge-orch-006] helpful=0 harmful=0: References to relevant code/docs
77
-
78
- **Output:** Wish document path for next step
79
-
80
- ### Step 2: forge.md Agent (Execution Breakdown)
81
-
82
- **Purpose:** Break wish into execution groups and create Forge tasks
83
-
84
- **Genie delegates:**
85
- ```
86
- mcp__genie__run with agent="forge" and prompt="Create forge plan for @.genie/wishes/<slug>/<slug>-wish.md"
87
- ```
88
-
89
- **forge.md creates:**
90
- - [forge-orch-007] helpful=0 harmful=0: Forge plan document: `.genie/wishes/<slug>/reports/forge-plan-<slug>-<timestamp>.md`
91
- - [forge-orch-008] helpful=0 harmful=0: Task files: `.genie/wishes/<slug>/task-*.md` (one per execution group)
92
- - [forge-orch-009] helpful=0 harmful=0: **Forge MCP tasks** via `mcp__automagik_forge__create_task` (forge.md owns MCP operations)
93
- - [forge-orch-010] helpful=0 harmful=0: Validation hooks and evidence paths
94
-
95
- **forge.md responsibilities:**
96
- - [forge-orch-011] helpful=0 harmful=0: Parse wish document `<spec_contract>`
97
- - [forge-orch-012] helpful=0 harmful=0: Define execution groups (A, B, C...)
98
- - [forge-orch-013] helpful=0 harmful=0: Assign personas (implementor, tests, polish)
99
- - [forge-orch-014] helpful=0 harmful=0: Create Forge task cards with proper context
100
- - [forge-orch-015] helpful=0 harmful=0: Document branch strategy
101
- - [forge-orch-016] helpful=0 harmful=0: Set up evidence collection paths
102
-
103
- **Output:** Forge plan + task IDs for monitoring
104
-
105
- ### Step 3: review.md Agent (Validation)
106
-
107
- **Purpose:** Validate implementation against wish acceptance criteria
108
-
109
- **Genie delegates:**
110
- ```
111
- mcp__genie__run with agent="review" and prompt="Review implementation for @.genie/wishes/<slug>/<slug>-wish.md"
112
- ```
113
-
114
- **review.md validates:**
115
- - [forge-orch-017] helpful=0 harmful=0: All acceptance criteria met
116
- - [forge-orch-018] helpful=0 harmful=0: Tests passing
117
- - [forge-orch-019] helpful=0 harmful=0: Documentation updated
118
- - [forge-orch-020] helpful=0 harmful=0: Code quality standards met
119
- - [forge-orch-021] helpful=0 harmful=0: Evidence collected in wish qa/ folders
120
-
121
- **Output:** Approval or change requests
122
-
123
- ---
124
-
125
- ## Part 3: Role Clarity - Who Does What
126
-
127
- ### Genie (Base Orchestrator)
128
-
129
- **Responsibilities:**
130
- - [forge-orch-022] helpful=0 harmful=0: ✅ Human interface (receive requests, provide updates)
131
- - [forge-orch-023] helpful=0 harmful=0: ✅ Workflow coordination (delegate to wish → forge → review)
132
- - [forge-orch-024] helpful=0 harmful=0: ✅ Session tracking (via SESSION-STATE.md)
133
- - [forge-orch-025] helpful=0 harmful=0: ✅ Context aggregation (synthesize agent outputs)
134
- - [forge-orch-026] helpful=0 harmful=0: ✅ Final reporting (summarize outcomes to user)
135
-
136
- **Forbidden:**
137
- - [forge-orch-027] helpful=0 harmful=0: ❌ NEVER create Forge tasks directly (that's forge.md's job)
138
- - [forge-orch-028] helpful=0 harmful=0: ❌ NEVER create wish documents directly (that's wish.md's job)
139
- - [forge-orch-029] helpful=0 harmful=0: ❌ NEVER run validation directly (that's review.md's job)
140
- - [forge-orch-030] helpful=0 harmful=0: ❌ NEVER execute implementation (that's specialist agents' job)
141
-
142
- ### wish.md Agent (Planner)
143
-
144
- **Responsibilities:**
145
- - [forge-orch-031] helpful=0 harmful=0: ✅ Gather context from conversation
146
- - [forge-orch-032] helpful=0 harmful=0: ✅ Create wish document structure
147
- - [forge-orch-033] helpful=0 harmful=0: ✅ Document problem + solution + criteria
148
- - [forge-orch-034] helpful=0 harmful=0: ✅ Collect references to code/docs
149
-
150
- **Forbidden:**
151
- - [forge-orch-035] helpful=0 harmful=0: ❌ NEVER create Forge tasks
152
- - [forge-orch-036] helpful=0 harmful=0: ❌ NEVER execute implementation
153
- - [forge-orch-037] helpful=0 harmful=0: ❌ NEVER perform validation
154
-
155
- **Output:** Wish document for forge.md consumption
156
-
157
- ### forge.md Agent (Executor Orchestrator)
158
-
159
- **Responsibilities:**
160
- - [forge-orch-038] helpful=0 harmful=0: ✅ Parse wish document `<spec_contract>`
161
- - [forge-orch-039] helpful=0 harmful=0: ✅ Break wish into execution groups
162
- - [forge-orch-040] helpful=0 harmful=0: ✅ Create task files in wish folder
163
- - [forge-orch-041] helpful=0 harmful=0: ✅ **Create Forge MCP tasks** via `mcp__automagik_forge__create_task`
164
- - [forge-orch-042] helpful=0 harmful=0: ✅ Assign personas to groups
165
- - [forge-orch-043] helpful=0 harmful=0: ✅ Document validation hooks
166
- - [forge-orch-044] helpful=0 harmful=0: ✅ Set up evidence paths
167
-
168
- **Forbidden:**
169
- - [forge-orch-045] helpful=0 harmful=0: ❌ NEVER modify original wish document
170
- - [forge-orch-046] helpful=0 harmful=0: ❌ NEVER execute implementation directly
171
- - [forge-orch-047] helpful=0 harmful=0: ❌ NEVER skip task file creation
172
- - [forge-orch-048] helpful=0 harmful=0: ❌ NEVER delegate to other orchestrators
173
-
174
- **Output:** Forge plan + Forge task IDs + task files
175
-
176
- **MCP Operations Authority:**
177
- - [forge-orch-049] helpful=0 harmful=0: forge.md **OWNS** all Forge MCP tool usage:
178
- - `mcp__automagik_forge__create_task`
179
- - `mcp__automagik_forge__update_task`
180
- - `mcp__automagik_forge__list_tasks`
181
- - `mcp__automagik_forge__get_task`
182
-
183
- **Why forge.md owns MCP:**
184
- - [forge-orch-050] helpful=0 harmful=0: Forge operations ARE execution breakdown (forge.md's specialty)
185
- - [forge-orch-051] helpful=0 harmful=0: Genie orchestrates workflows, not tools
186
- - [forge-orch-052] helpful=0 harmful=0: Separation: orchestration (Genie) vs execution coordination (forge.md)
187
-
188
- ### review.md Agent (Validator)
189
-
190
- **Responsibilities:**
191
- - [forge-orch-053] helpful=0 harmful=0: ✅ Validate against wish acceptance criteria
192
- - [forge-orch-054] helpful=0 harmful=0: ✅ Check test coverage
193
- - [forge-orch-055] helpful=0 harmful=0: ✅ Verify documentation
194
- - [forge-orch-056] helpful=0 harmful=0: ✅ Approve or request changes
195
-
196
- **Forbidden:**
197
- - [forge-orch-057] helpful=0 harmful=0: ❌ NEVER create tasks
198
- - [forge-orch-058] helpful=0 harmful=0: ❌ NEVER execute implementation
199
- - [forge-orch-059] helpful=0 harmful=0: ❌ NEVER modify wish
200
-
201
- **Output:** Approval decision + feedback
202
-
203
- ---
204
-
205
- ## Part 4: Orchestration Patterns 🔴 CRITICAL
206
-
207
- ### Isolated Worktrees - No Cross-Task Waiting
208
-
209
- - [forge-orch-060] helpful=0 harmful=0: Each Forge task runs in isolated git worktree/sandbox
210
- - [forge-orch-061] helpful=0 harmful=0: Tasks CANNOT wait for each other - they don't share filesystem
211
- - [forge-orch-062] helpful=0 harmful=0: Task B cannot see Task A's changes until Task A is MERGED to base branch
212
-
213
- ### Humans Are The Merge Gate
214
-
215
- - [forge-orch-063] helpful=0 harmful=0: Only humans can review and merge Forge task PRs
216
- - [forge-orch-064] helpful=0 harmful=0: Agents NEVER merge - always human decision
217
- - [forge-orch-065] helpful=0 harmful=0: This is by design for quality control
218
-
219
- ### Sequential Dependency Pattern
220
-
221
- If Task B depends on Task A's changes:
222
- 1. Launch Task A
223
- 2. Wait for Task A to complete
224
- 3. **STOP and ask human:** "Please review and merge Task A"
225
- 4. Human reviews/merges Task A to base branch
226
- 5. THEN launch Task B (now has Task A's changes in base)
227
-
228
- ### Parallel Tasks
229
-
230
- - [forge-orch-066] helpful=0 harmful=0: Tasks CAN run in parallel if independent
231
- - [forge-orch-067] helpful=0 harmful=0: Example: Fix test + Populate PR can run together
232
- - [forge-orch-068] helpful=0 harmful=0: But final validation MUST wait for test fix to be merged
233
-
234
- ### Common Mistake Pattern
235
-
236
- - [forge-orch-069] helpful=0 harmful=0: **Mistake:** Launch Task 3 (validation) telling it to 'wait' for Task 1 (test fix)
237
- - [forge-orch-070] helpful=0 harmful=0: **Why impossible:** Task 3's worktree doesn't have Task 1's changes
238
- - [forge-orch-071] helpful=0 harmful=0: **Result:** Task 3 would fail because test fix not in its base branch
239
-
240
- ### Correct Pattern
241
-
242
- 1. Launch Task 1 & 2 (parallel, independent)
243
- 2. Wait for completion
244
- 3. Ask human to merge Task 1
245
- 4. After merge, launch Task 3 (now has test fix)
246
-
247
- ---
248
-
249
- ## Part 5: MCP Task Description Patterns (Claude Executor Only)
250
-
251
- When creating Forge MCP tasks via `mcp__forge__create_task` with Claude as executor, explicitly instruct Claude to use the subagent and load context from files only.
252
-
253
- ### Pattern
254
-
255
- ```
256
- Use the <persona> subagent to [action verb] this task.
257
-
258
- `@.genie/code/agents/<persona>.md`
259
- `@.genie/wishes/<slug>/task-<group>.md`
260
- `@.genie/wishes/<slug>/<slug>-wish.md`
261
-
262
- Load all context from the referenced files above. Do not duplicate content here.
263
- ```
264
-
265
- ### Example
266
-
267
- ```
268
- Use the implementor subagent to implement this task.
269
-
270
- `@.genie/code/agents/implementor.md`
271
- `@.genie/wishes/claude-executor/task-a.md`
272
- `@.genie/wishes/claude-executor-wish.md`
273
-
274
- Load all context from the referenced files above. Do not duplicate content here.
275
- ```
276
-
277
- ### Why This Pattern
278
-
279
- - [forge-orch-072] helpful=0 harmful=0: Explicit instruction tells Claude to spawn the subagent
280
- - [forge-orch-073] helpful=0 harmful=0: Agent reference points to actual agent prompt file
281
- - [forge-orch-074] helpful=0 harmful=0: File references provide context paths
282
- - [forge-orch-075] helpful=0 harmful=0: Avoids token waste from duplicating task file contents
283
-
284
- ### Agent Reference Pattern
285
-
286
- - [forge-orch-076] helpful=0 harmful=0: Code agents: `@.genie/code/agents/<agent>.md`
287
- - [forge-orch-077] helpful=0 harmful=0: Universal agents: `@.genie/code/agents/<agent>.md`
288
- - [forge-orch-078] helpful=0 harmful=0: Workflows: `@.genie/code/workflows/<workflow>.md`
289
-
290
- **Note:** This pattern is ONLY for Forge MCP task descriptions when using Claude executor. Task file creation (task-*.md) remains unchanged with full context.
291
-
292
- ---
293
-
294
- ## Part 6: Monitoring Pattern - Sleep, Don't Stop
295
-
296
- **Critical Learning:** When instructed to "monitor" tasks, Genie does NOT stop/idle.
297
-
298
- **Incorrect behavior:**
299
- ```
300
- Felipe: "Monitor these Forge tasks"
301
-
302
- Genie: Reports status once, then waits passively
303
-
304
- ❌ WRONG: Monitoring means periodic checking, not one-shot
305
- ```
306
-
307
- **Correct behavior:**
308
- ```
309
- Felipe: "Monitor these Forge tasks"
310
-
311
- Genie: Reports status, then continues checking periodically
312
-
313
- ✅ RIGHT: Monitoring = sleep/wait loop, check again, report updates
314
- ```
315
-
316
- **Implementation:**
317
- - [forge-orch-079] helpful=0 harmful=0: Use `mcp__automagik_forge__get_task` periodically (every 30-60s)
318
- - [forge-orch-080] helpful=0 harmful=0: Check for status changes (in-progress → in-review → done)
319
- - [forge-orch-081] helpful=0 harmful=0: Report meaningful updates to user
320
- - [forge-orch-082] helpful=0 harmful=0: Continue until task complete or user interrupts
321
- - [forge-orch-083] helpful=0 harmful=0: "Monitor" = active vigilance, not passive waiting
322
-
323
- **Why this matters:**
324
- - [forge-orch-084] helpful=0 harmful=0: Forge tasks run in background (separate processes)
325
- - [forge-orch-085] helpful=0 harmful=0: User expects real-time updates on progress
326
- - [forge-orch-086] helpful=0 harmful=0: Genie's role is orchestration = keeping user informed
327
- - [forge-orch-087] helpful=0 harmful=0: Sleeping/polling is appropriate for async operations
328
-
329
- ---
330
-
331
- ## Part 7: File Structure Created by Workflow
332
-
333
- ```
334
- .genie/wishes/
335
- └── YYYY-MM-DD-topic/
336
- ├── YYYY-MM-DD-topic-wish.md # Created by wish.md
337
- ├── task-a.md # Created by forge.md
338
- ├── task-b.md # Created by forge.md
339
- ├── qa/ # Evidence collection
340
- │ ├── group-a/
341
- │ └── group-b/
342
- └── reports/
343
- ├── forge-plan-<slug>-<timestamp>.md # Created by forge.md
344
- └── review-<slug>-<timestamp>.md # Created by review.md
345
- ```
346
-
347
- ---
348
-
349
- ## Part 8: Integration with Forge-as-Entry-Point Pattern
350
-
351
- **Context:** Forge is PRIMARY entry point for ALL work
352
-
353
- **Workflow alignment:**
354
- ```
355
- GitHub issue → wish.md (plan) → forge.md (creates Forge task) → Forge executor → review.md
356
-
357
- Forge task = PR = worktree
358
-
359
- All work converges on main
360
- ```
361
-
362
- **Key points:**
363
- 1. **wish.md** captures GitHub issue context in wish document
364
- 2. **forge.md** creates Forge task card (1 task = 1 PR)
365
- 3. **Forge executor** performs implementation in worktree
366
- 4. **review.md** validates before merge to main
367
- 5. **Genie** orchestrates entire chain (does not execute)
368
-
369
- ---
370
-
371
- ## Part 9: When to Use Each Agent
372
-
373
- ### Use wish.md when:
374
- - [forge-orch-088] helpful=0 harmful=0: ✅ Request needs formal context capture
375
- - [forge-orch-089] helpful=0 harmful=0: ✅ Scope spans multiple components
376
- - [forge-orch-090] helpful=0 harmful=0: ✅ Ambiguity or risk is high
377
- - [forge-orch-091] helpful=0 harmful=0: ✅ Compliance/approval gates required
378
-
379
- ### Use forge.md when:
380
- - [forge-orch-092] helpful=0 harmful=0: ✅ Wish is APPROVED
381
- - [forge-orch-093] helpful=0 harmful=0: ✅ Need to break wish into execution groups
382
- - [forge-orch-094] helpful=0 harmful=0: ✅ Need to create Forge task cards
383
- - [forge-orch-095] helpful=0 harmful=0: ✅ Need to assign work to specialists
384
-
385
- ### Use review.md when:
386
- - [forge-orch-096] helpful=0 harmful=0: ✅ Implementation complete
387
- - [forge-orch-097] helpful=0 harmful=0: ✅ Need acceptance criteria validation
388
- - [forge-orch-098] helpful=0 harmful=0: ✅ Quality gate before merge
389
-
390
- ### Skip workflow when:
391
- - [forge-orch-099] helpful=0 harmful=0: Simple bug fix or trivial change
392
- - [forge-orch-100] helpful=0 harmful=0: Route directly to implementor/debug
393
- - [forge-orch-101] helpful=0 harmful=0: Escalate to wish.md if complexity grows
394
-
395
- ---
396
-
397
- ## Part 10: Common Anti-Patterns to Avoid
398
-
399
- ### ❌ Anti-Pattern 1: Genie Creates Forge Tasks
400
-
401
- ```
402
- # WRONG
403
- mcp__automagik_forge__create_task(...) # Called by Genie
404
- ```
405
-
406
- **Why wrong:** Genie orchestrates, doesn't execute. MCP operations belong to forge.md.
407
-
408
- **Correct:**
409
- ```
410
- # RIGHT
411
- mcp__genie__run(agent="forge", prompt="...") # Genie delegates to forge.md
412
-
413
- forge.md calls mcp__automagik_forge__create_task(...) # forge.md executes
414
- ```
415
-
416
- ### ❌ Anti-Pattern 2: Skipping wish.md
417
-
418
- ```
419
- # WRONG
420
- User request → Genie → forge.md directly
421
- ```
422
-
423
- **Why wrong:** No context gathering, no wish document for reference.
424
-
425
- **Correct:**
426
- ```
427
- # RIGHT
428
- User request → Genie → wish.md → forge.md → review.md
429
- ```
430
-
431
- ### ❌ Anti-Pattern 3: forge.md Modifies Wish
432
-
433
- ```
434
- # WRONG
435
- forge.md edits .genie/wishes/<slug>/<slug>-wish.md
436
- ```
437
-
438
- **Why wrong:** Wish is source of truth, forge.md only reads it.
439
-
440
- **Correct:**
441
- ```
442
- # RIGHT
443
- forge.md reads wish, creates companion files (forge plan, task files)
444
- ```
445
-
446
- ---
447
-
448
- ## Part 11: Validation Checklist
449
-
450
- **Before creating Forge tasks, verify:**
451
- - [forge-orch-102] helpful=0 harmful=0: [ ] Wish document exists and is APPROVED
452
- - [forge-orch-103] helpful=0 harmful=0: [ ] Genie delegated to wish.md (not created wish directly)
453
- - [forge-orch-104] helpful=0 harmful=0: [ ] Genie delegated to forge.md (not created Forge tasks directly)
454
- - [forge-orch-105] helpful=0 harmful=0: [ ] forge.md parsed wish `<spec_contract>`
455
- - [forge-orch-106] helpful=0 harmful=0: [ ] forge.md created task files in wish folder
456
- - [forge-orch-107] helpful=0 harmful=0: [ ] forge.md created Forge MCP tasks (not Genie)
457
- - [forge-orch-108] helpful=0 harmful=0: [ ] Evidence paths documented
458
- - [forge-orch-109] helpful=0 harmful=0: [ ] Validation hooks specified
459
-
460
- **During implementation, verify:**
461
- - [forge-orch-110] helpful=0 harmful=0: [ ] Work happens in Forge task worktree
462
- - [forge-orch-111] helpful=0 harmful=0: [ ] Evidence collected in wish qa/ folders
463
- - [forge-orch-112] helpful=0 harmful=0: [ ] Progress tracked via Forge task updates
464
-
465
- **After implementation, verify:**
466
- - [forge-orch-113] helpful=0 harmful=0: [ ] Genie delegated to review.md (not validated directly)
467
- - [forge-orch-114] helpful=0 harmful=0: [ ] Review validates against wish acceptance criteria
468
- - [forge-orch-115] helpful=0 harmful=0: [ ] All tests passing
469
- - [forge-orch-116] helpful=0 harmful=0: [ ] Documentation updated
470
-
471
- ---
472
-
473
- ## Key Takeaways
474
-
475
- 1. **Genie orchestrates, doesn't execute**
476
- - Delegates to wish.md, forge.md, review.md
477
- - Synthesizes outputs, reports to user
478
- - Never touches MCP Forge tools directly
479
- - **Monitors actively** when tasks are running
480
-
481
- 2. **forge.md owns MCP operations**
482
- - Creates/updates Forge tasks
483
- - Owns all `mcp__automagik_forge__*` tool usage
484
- - Coordinates execution groups
485
-
486
- 3. **Complete chain = quality**
487
- - wish.md (context) → forge.md (breakdown) → review.md (validation)
488
- - Skipping steps = incomplete orchestration
489
- - Each step adds value and safety
490
-
491
- 4. **Isolated worktrees = sequential dependencies**
492
- - Tasks cannot wait for each other
493
- - Humans are the merge gate
494
- - Sequential dependencies require human approval between tasks
495
-
496
- 5. **Monitoring = active vigilance**
497
- - Sleep/poll/check/report loop
498
- - Not one-shot status check
499
- - Keep user informed of progress
500
- - Continue until completion or interruption
501
-
502
- ---
503
-
504
- ## References
505
-
506
- - [forge-orch-117] helpful=0 harmful=0: `@.genie/code/workflows/wish.md` - Wish workflow documentation
507
- - [forge-orch-118] helpful=0 harmful=0: `@.genie/code/workflows/forge.md` - Forge workflow documentation
508
- - [forge-orch-119] helpful=0 harmful=0: `@.genie/code/workflows/review.md` - Review workflow documentation (when exists)
509
- - [forge-orch-120] helpful=0 harmful=0: `@.genie/spells/forge-integration.md` - Forge-as-entry-point pattern
510
- - [forge-orch-121] helpful=0 harmful=0: `@.genie/spells/orchestrator-not-implementor.md` - Agent role boundaries
511
-
512
- ---
513
-
514
- **Evidence:** Merged from 3 spell files (forge-orchestration-workflow, forge-orchestration-patterns, forge-mcp-task-patterns) on 2025-10-23 during duplicate cleanup initiative.
@@ -1,18 +0,0 @@
1
- ---
2
- name: Genie Missing Context Protocol
3
- description: Provide Files Needed block when critical context is missing
4
- ---
5
-
6
- # Genie Missing Context Protocol
7
-
8
- When critical technical context is missing (files, specs), provide a Files Needed block instead of speculative output.
9
-
10
- ## Files Needed (use when necessary)
11
-
12
- ```
13
- status: files_required_to_continue
14
- mandatory_instructions: <what is needed and why>
15
- files_needed: [ path/or/folder, ... ]
16
- ```
17
-
18
- Use only for technical implementation gaps, not for business/strategy questions.
@@ -1,34 +0,0 @@
1
- ---
2
- name: forge-global-health-check
3
- description: Sanity check Forge orchestration and MCP access (domain-agnostic)
4
-
5
- ---
6
-
7
- # Forge Global Health Check
8
-
9
- ## Goals
10
- - Verify Genie MCP tools are available
11
- - Verify core agents (forge, wish, review) are resolvable
12
- - Optional: verify a no-op wish→review roundtrip without domain specifics
13
-
14
- ## Steps
15
- 1) List agents
16
- ```
17
- mcp__genie__list_agents
18
- ```
19
- Expect `forge`, `wish`, `review` to be present.
20
-
21
- 2) Start noop wish (optional)
22
- ```
23
- mcp__genie__run agent="wish" prompt="Create a placeholder wish (no code), context: @.genie/product/mission.md"
24
- ```
25
- Record wish path if created.
26
-
27
- 3) Dry review (optional)
28
- ```
29
- mcp__genie__run agent="review" prompt="Review placeholder wish (no code)"
30
- ```
31
-
32
- ## Evidence
33
- - Save outputs to `.genie/qa/evidence/forge-health-<timestamp>.txt`
34
-
@@ -1,25 +0,0 @@
1
- ---
2
- name: forge-global-noop-roundtrip
3
- description: No-op Wish → Review roundtrip without domain specifics
4
-
5
- ---
6
-
7
- # Forge Global No-Op Roundtrip
8
-
9
- ## Steps
10
- 1) Create placeholder wish
11
- ```
12
- mcp__genie__run agent="wish" prompt="Create placeholder wish with no code changes"
13
- ```
14
- 2) Review placeholder wish
15
- ```
16
- mcp__genie__run agent="review" prompt="Review placeholder wish"
17
- ```
18
-
19
- ## Success Criteria
20
- - Wish document written under `.genie/wishes/<slug>/`
21
- - Review runs without code-specific dependencies
22
-
23
- ## Evidence
24
- - Save outputs to `.genie/qa/evidence/forge-noop-<timestamp>.txt`
25
-