arkaos 2.14.0 → 2.16.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 (179) hide show
  1. package/VERSION +1 -1
  2. package/arka/SKILL.md +13 -0
  3. package/arka/skills/comfyui/SKILL.md +82 -0
  4. package/arka/skills/comfyui/references/squads.md +80 -0
  5. package/arka/skills/comfyui/references/workflows.md +435 -0
  6. package/arka/skills/forge/SKILL.md +35 -599
  7. package/arka/skills/forge/references/complexity-engine.md +77 -0
  8. package/arka/skills/forge/references/critic-synthesis.md +154 -0
  9. package/arka/skills/forge/references/workflows.md +408 -0
  10. package/arka/skills/fovory/SKILL.md +91 -0
  11. package/arka/skills/fovory/references/integration.md +186 -0
  12. package/arka/skills/fovory/references/workflows.md +209 -0
  13. package/arka/skills/platform-arka/SKILL.md +121 -0
  14. package/arka/skills/platform-arka/references/workflows.md +202 -0
  15. package/arka/skills/rothbard100/SKILL.md +113 -0
  16. package/arka/skills/rothbard100/references/squad.md +111 -0
  17. package/arka/skills/rothbard100/references/workflows.md +175 -0
  18. package/config/constitution.yaml +8 -0
  19. package/config/hooks/pre-compact.sh +11 -5
  20. package/config/hooks/session-start.sh +4 -5
  21. package/config/hooks/token-hygiene.sh +120 -0
  22. package/config/hooks/user-prompt-submit.sh +28 -10
  23. package/core/agents/__pycache__/schema.cpython-313.pyc +0 -0
  24. package/core/agents/schema.py +20 -1
  25. package/core/synapse/__pycache__/layers.cpython-313.pyc +0 -0
  26. package/core/synapse/layers.py +7 -0
  27. package/core/sync/__init__.py +25 -0
  28. package/core/sync/__pycache__/__init__.cpython-313.pyc +0 -0
  29. package/core/sync/__pycache__/descriptor_syncer.cpython-313.pyc +0 -0
  30. package/core/sync/__pycache__/discovery.cpython-313.pyc +0 -0
  31. package/core/sync/__pycache__/engine.cpython-313.pyc +0 -0
  32. package/core/sync/__pycache__/manifest.cpython-313.pyc +0 -0
  33. package/core/sync/__pycache__/mcp_syncer.cpython-313.pyc +0 -0
  34. package/core/sync/__pycache__/reporter.cpython-313.pyc +0 -0
  35. package/core/sync/__pycache__/schema.cpython-313.pyc +0 -0
  36. package/core/sync/__pycache__/settings_syncer.cpython-313.pyc +0 -0
  37. package/core/sync/descriptor_syncer.py +166 -0
  38. package/core/sync/discovery.py +256 -0
  39. package/core/sync/engine.py +177 -0
  40. package/core/sync/features/forge.yaml +16 -0
  41. package/core/sync/features/quality-gate.yaml +15 -0
  42. package/core/sync/features/spec-gate.yaml +15 -0
  43. package/core/sync/features/workflow-tiers.yaml +19 -0
  44. package/core/sync/manifest.py +87 -0
  45. package/core/sync/mcp_syncer.py +255 -0
  46. package/core/sync/reporter.py +178 -0
  47. package/core/sync/schema.py +94 -0
  48. package/core/sync/settings_syncer.py +121 -0
  49. package/core/workflow/__pycache__/schema.cpython-313.pyc +0 -0
  50. package/core/workflow/schema.py +4 -1
  51. package/departments/brand/SKILL.md +13 -0
  52. package/departments/brand/agents/brand-director.yaml +1 -0
  53. package/departments/brand/agents/brand-strategist.yaml +1 -0
  54. package/departments/brand/agents/ux-designer.yaml +1 -0
  55. package/departments/brand/agents/visual-designer.yaml +1 -0
  56. package/departments/brand/workflows/identity.yaml +1 -0
  57. package/departments/brand/workflows/naming.yaml +1 -0
  58. package/departments/community/SKILL.md +13 -0
  59. package/departments/community/agents/community-manager.yaml +1 -0
  60. package/departments/community/agents/community-strategist.yaml +1 -0
  61. package/departments/community/agents/engagement-designer.yaml +1 -0
  62. package/departments/community/workflows/setup.yaml +1 -0
  63. package/departments/content/SKILL.md +13 -0
  64. package/departments/content/agents/content-strategist.yaml +1 -0
  65. package/departments/content/agents/repurpose-distributor.yaml +1 -0
  66. package/departments/content/agents/scriptwriter.yaml +1 -0
  67. package/departments/content/agents/viral-engineer.yaml +1 -0
  68. package/departments/content/workflows/viral.yaml +1 -0
  69. package/departments/dev/SKILL.md +13 -0
  70. package/departments/dev/agents/architect.yaml +1 -0
  71. package/departments/dev/agents/backend-dev.yaml +1 -0
  72. package/departments/dev/agents/cto.yaml +1 -0
  73. package/departments/dev/agents/dba.yaml +1 -0
  74. package/departments/dev/agents/devops-eng.yaml +1 -0
  75. package/departments/dev/agents/frontend-dev.yaml +1 -0
  76. package/departments/dev/agents/qa-eng.yaml +1 -0
  77. package/departments/dev/agents/research-assistant.yaml +1 -0
  78. package/departments/dev/agents/security-eng.yaml +1 -0
  79. package/departments/dev/agents/tech-lead.yaml +1 -0
  80. package/departments/dev/skills/onboard/SKILL.md +21 -353
  81. package/departments/dev/skills/onboard/references/mcp-config.md +284 -0
  82. package/departments/dev/skills/onboard/references/stack-detection.md +83 -0
  83. package/departments/dev/workflows/debug.yaml +1 -0
  84. package/departments/dev/workflows/feature.yaml +3 -0
  85. package/departments/dev/workflows/refactor.yaml +1 -0
  86. package/departments/ecom/SKILL.md +13 -0
  87. package/departments/ecom/agents/commerce-engineer.yaml +1 -0
  88. package/departments/ecom/agents/cro-specialist.yaml +1 -0
  89. package/departments/ecom/agents/ecom-director.yaml +1 -0
  90. package/departments/ecom/agents/retention-manager.yaml +1 -0
  91. package/departments/ecom/skills/ecommerce/SKILL.md +66 -0
  92. package/departments/ecom/skills/ecommerce/references/audit-flow.md +109 -0
  93. package/departments/ecom/skills/ecommerce/references/playbooks.md +141 -0
  94. package/departments/ecom/workflows/product-page.yaml +1 -0
  95. package/departments/finance/SKILL.md +13 -0
  96. package/departments/finance/agents/cfo.yaml +1 -0
  97. package/departments/finance/agents/financial-analyst.yaml +1 -0
  98. package/departments/finance/agents/investment-strategist.yaml +1 -0
  99. package/departments/finance/workflows/cashflow.yaml +1 -0
  100. package/departments/finance/workflows/model.yaml +1 -0
  101. package/departments/kb/SKILL.md +13 -0
  102. package/departments/kb/agents/data-collector.yaml +1 -0
  103. package/departments/kb/agents/knowledge-curator.yaml +1 -0
  104. package/departments/kb/agents/knowledge-director.yaml +1 -0
  105. package/departments/kb/agents/research-analyst.yaml +1 -0
  106. package/departments/kb/skills/knowledge/SKILL.md +94 -0
  107. package/departments/kb/skills/knowledge/references/async-processing.md +89 -0
  108. package/departments/kb/skills/knowledge/references/ingestion-pipeline.md +308 -0
  109. package/departments/kb/skills/knowledge/scripts/kb-check-capabilities.sh +143 -0
  110. package/departments/kb/skills/knowledge/scripts/kb-cleanup.sh +135 -0
  111. package/departments/kb/skills/knowledge/scripts/kb-queue.sh +156 -0
  112. package/departments/kb/skills/knowledge/scripts/kb-status.sh +195 -0
  113. package/departments/kb/skills/knowledge/scripts/kb-worker.sh +217 -0
  114. package/departments/kb/workflows/learn.yaml +1 -0
  115. package/departments/landing/SKILL.md +13 -0
  116. package/departments/landing/agents/affiliate-manager.yaml +1 -0
  117. package/departments/landing/agents/conversion-strategist.yaml +1 -0
  118. package/departments/landing/agents/cro-specialist.yaml +1 -0
  119. package/departments/landing/agents/sales-copywriter.yaml +1 -0
  120. package/departments/landing/workflows/launch.yaml +1 -0
  121. package/departments/landing/workflows/offer.yaml +3 -0
  122. package/departments/leadership/SKILL.md +13 -0
  123. package/departments/leadership/agents/culture-coach.yaml +1 -0
  124. package/departments/leadership/agents/hr-specialist.yaml +1 -0
  125. package/departments/leadership/agents/leadership-director.yaml +1 -0
  126. package/departments/leadership/workflows/team-build.yaml +1 -0
  127. package/departments/marketing/SKILL.md +13 -0
  128. package/departments/marketing/agents/content-marketer.yaml +1 -0
  129. package/departments/marketing/agents/marketing-director.yaml +1 -0
  130. package/departments/marketing/agents/paid-specialist.yaml +1 -0
  131. package/departments/marketing/agents/seo-specialist.yaml +1 -0
  132. package/departments/marketing/workflows/campaign.yaml +1 -0
  133. package/departments/marketing/workflows/social.yaml +1 -0
  134. package/departments/ops/SKILL.md +13 -0
  135. package/departments/ops/agents/automation-engineer.yaml +1 -0
  136. package/departments/ops/agents/doc-writer.yaml +1 -0
  137. package/departments/ops/agents/ops-lead.yaml +1 -0
  138. package/departments/ops/skills/operations/SKILL.md +83 -0
  139. package/departments/ops/skills/operations/references/calendar-email.md +73 -0
  140. package/departments/ops/skills/operations/references/clickup-ops.md +224 -0
  141. package/departments/ops/skills/update/SKILL.md +43 -0
  142. package/departments/ops/skills/update/references/sync-engine.md +93 -0
  143. package/departments/ops/skills/update/references/workflows.md +84 -0
  144. package/departments/ops/workflows/lean-audit.yaml +1 -0
  145. package/departments/org/SKILL.md +13 -0
  146. package/departments/org/agents/coo.yaml +1 -0
  147. package/departments/org/agents/org-designer.yaml +1 -0
  148. package/departments/org/agents/people-ops.yaml +1 -0
  149. package/departments/org/workflows/design.yaml +2 -0
  150. package/departments/pm/SKILL.md +13 -0
  151. package/departments/pm/agents/pm-director.yaml +1 -0
  152. package/departments/pm/agents/product-owner.yaml +1 -0
  153. package/departments/pm/agents/scrum-master.yaml +1 -0
  154. package/departments/quality/SKILL.md +13 -0
  155. package/departments/quality/agents/copy-director.yaml +1 -0
  156. package/departments/quality/agents/cqo.yaml +1 -0
  157. package/departments/quality/agents/tech-director.yaml +1 -0
  158. package/departments/saas/SKILL.md +13 -0
  159. package/departments/saas/agents/cs-manager.yaml +1 -0
  160. package/departments/saas/agents/growth-engineer.yaml +1 -0
  161. package/departments/saas/agents/metrics-analyst.yaml +1 -0
  162. package/departments/saas/agents/saas-strategist.yaml +1 -0
  163. package/departments/saas/workflows/metrics.yaml +1 -0
  164. package/departments/saas/workflows/validate.yaml +1 -0
  165. package/departments/sales/SKILL.md +13 -0
  166. package/departments/sales/agents/sales-closer.yaml +1 -0
  167. package/departments/sales/agents/sales-director.yaml +1 -0
  168. package/departments/sales/agents/sales-ops.yaml +1 -0
  169. package/departments/sales/workflows/pipeline.yaml +1 -0
  170. package/departments/strategy/SKILL.md +13 -0
  171. package/departments/strategy/agents/business-model-designer.yaml +1 -0
  172. package/departments/strategy/agents/market-analyst.yaml +1 -0
  173. package/departments/strategy/agents/strategy-director.yaml +1 -0
  174. package/departments/strategy/workflows/analysis.yaml +1 -0
  175. package/departments/strategy/workflows/swot.yaml +1 -0
  176. package/installer/index.js +19 -0
  177. package/installer/update.js +14 -0
  178. package/package.json +1 -1
  179. package/pyproject.toml +1 -1
package/arka/skills/forge/SKILL.md CHANGED
@@ -11,8 +11,8 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
11
11
  # The Forge — ArkaOS Intelligent Planning Engine
12
12
 
13
13
  > **Engine:** `core/forge/` | **Plans stored:** `~/.arkaos/plans/` | **Obsidian:** `ArkaOS/Forge/`
14
- > **Tiers:** Shallow (score ≤30) · Standard (31-65) · Deep (≥66)
15
- > **Explorers:** Pragmatic · Architectural · Contrarian
14
+
15
+ The Forge analyses any prompt across 5 complexity dimensions, routes to 1-3 explorer subagents for independent plans, runs a critic to synthesize the best plan, and persists an approved ForgePlan before execution. Every plan enforces Constitution rules (branch isolation, spec-driven, QA, Quality Gate, Obsidian output).
16
16
 
17
17
  ## Commands
18
18
 
@@ -27,623 +27,59 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
27
27
  | `/forge patterns` | List extracted patterns | See reusable patterns from past plans |
28
28
  | `/forge cancel` | Cancel active forge | Discard current plan without executing |
29
29
 
30
- ---
31
-
32
- ## Main Flow: `/forge <prompt>`
33
-
34
- Execute every step sequentially. Never skip steps. Announce each step before running it.
35
-
36
- ### Step 1 — Context Snapshot
37
-
38
- Collect the current repo context by running these Bash commands:
39
-
40
- ```bash
41
- git rev-parse HEAD # commit hash
42
- git branch --show-current # branch name
43
- git remote get-url origin # repo name
44
- cat VERSION 2>/dev/null || echo "unknown" # ArkaOS version
45
- ```
46
-
47
- Build a context dict:
48
- ```
49
- repo: <origin url or directory name>
50
- branch: <current branch>
51
- commit_at_forge: <HEAD hash>
52
- arkaos_version: <VERSION file content>
53
- prompt: <original user prompt>
54
- ```
55
-
56
- ### Step 2 — Obsidian Knowledge Check
57
-
58
- Search Obsidian for relevant patterns and past plans using the MCP obsidian tool:
59
-
60
- 1. Search `ArkaOS/Forge/Patterns/` for patterns matching keywords from the prompt
61
- 2. Search `ArkaOS/Forge/Plans/` for plans with similar names or tags
62
-
63
- Collect:
64
- - `similar_plans: list[str]` — IDs of plans with overlapping domain/scope
65
- - `reused_patterns: list[str]` — pattern names that match this prompt's domain
66
-
67
- If Obsidian is unavailable, set both to `[]` and continue.
68
-
69
- ### Step 3 — Complexity Analysis
70
-
71
- Call the complexity scorer via Python:
72
-
73
- ```python
74
- import sys
75
- sys.path.insert(0, '<repo_root>')
76
- from core.forge.complexity import analyze_complexity
77
-
78
- result = analyze_complexity(
79
- prompt="<user prompt>",
80
- affected_files=[], # estimate from prompt keywords: auth→auth/, db→core/db/, etc.
81
- departments=[], # estimate from prompt: "deploy"→ops, "feature"→dev, etc.
82
- similar_plans=similar_plans,
83
- reused_patterns=reused_patterns,
84
- )
85
- print(f"score={result.score} tier={result.tier.value}")
86
- print(f"scope={result.dimensions.scope} deps={result.dimensions.dependencies}")
87
- print(f"ambiguity={result.dimensions.ambiguity} risk={result.dimensions.risk} novelty={result.dimensions.novelty}")
88
- ```
89
-
90
- Run this as a Bash command: `cd <repo_root> && python -c "..."`.
91
-
92
- Display the complexity breakdown using the renderer:
93
-
94
- ```python
95
- from core.forge.renderer import render_complexity
96
- print(render_complexity(result))
97
- ```
98
-
99
- ### Step 4 — Tier Confirmation
100
-
101
- Display to user:
102
-
103
- ```
104
- ⚒ FORGE — Complexity Analysis
105
-
106
- Score: <score>/100 (<Tier>)
107
- │ Scope │ <n> │ ██████░░░░
108
- │ Deps │ <n> │ ████░░░░░░
109
- │ Ambig. │ <n> │ ███████░░░
110
- │ Risk │ <n> │ █████░░░░░
111
- │ Novelty │ <n> │ ██░░░░░░░░
112
-
113
- Tier: <Tier> → <N> explorer(s) + <critic>
114
- Similar plans: <list or "none found">
115
- Reusing patterns: <list or "none">
116
-
117
- Proceed with <Tier> tier? [Y/n/override shallow|standard|deep]
118
- ```
119
-
120
- Wait for user input. Accept `Y` or Enter to proceed. Accept `override <tier>` to change tier. Accept `n` to abort.
121
-
122
- ### Step 5 — Launch Explorer Subagents
123
-
124
- Launch explorer subagents **in parallel** based on confirmed tier:
125
-
126
- | Tier | Explorers | Run |
127
- |------|-----------|-----|
128
- | shallow | 1 — Pragmatic only | Sequential (inline) |
129
- | standard | 2 — Pragmatic + Architectural | Parallel via Agent tool |
130
- | deep | 3 — Pragmatic + Architectural + Contrarian | Parallel via Agent tool |
131
-
132
- For **shallow**, run the Pragmatic explorer inline (no subagent needed — just generate the approach directly).
133
-
134
- For **standard** and **deep**, use the Agent tool to dispatch each explorer as a subagent. Pass the full explorer prompt (see Explorer Subagent Instructions below).
135
-
136
- Each explorer must return a structured response:
137
- ```
138
- EXPLORER: <lens>
139
- SUMMARY: <2-3 sentence description of the approach>
140
- KEY_DECISIONS:
141
- - decision: <what>
142
- rationale: <why>
143
- PHASES:
144
- - name: <phase name>
145
- department: <dev|ops|mkt|brand|fin|strat|pm|saas|landing|content|ecom|kb|sales|lead|community|org>
146
- agents: [<agent names>]
147
- deliverables: [<list>]
148
- acceptance_criteria: [<list>]
149
- depends_on: [<phase names that must complete first>]
150
- ```
151
-
152
- ### Step 6 — Launch Critic Subagent
153
-
154
- Assemble all explorer outputs. Strip explorer lens labels (anonymize) before sending to critic.
155
-
156
- Launch a Critic subagent via the Agent tool with the Critic Subagent Instructions below.
157
-
158
- The critic must return:
159
- ```
160
- CONFIDENCE: <0.0-1.0>
161
- SYNTHESIS:
162
- pragmatic: [<adopted elements>]
163
- architectural: [<adopted elements>]
164
- contrarian: [<adopted elements>] # if applicable
165
- REJECTED:
166
- - element: <what was rejected>
167
- reason: <why>
168
- RISKS:
169
- - risk: <description>
170
- severity: high|medium|low
171
- mitigation: <how to address>
172
- FINAL_PHASES:
173
- - name: <phase name>
174
- department: <dept>
175
- agents: [<list>]
176
- deliverables: [<list>]
177
- acceptance_criteria: [<list>]
178
- depends_on: [<list>]
179
- ```
180
-
181
- ### Step 7 — Render Terminal Output
182
-
183
- Build the ForgePlan object and render it:
184
-
185
- ```python
186
- from core.forge.renderer import render_terminal
187
- from core.forge.handoff import select_execution_path
188
-
189
- # Build plan object from collected data
190
- # Call render_terminal(plan) to get the display string
191
- # Call select_execution_path(plan.plan_phases) to determine execution route
192
- ```
193
-
194
- Display:
195
- ```
196
- ⚒ FORGE — <Plan Name>
197
-
198
- ▸ Context Snapshot
199
- Repo: <repo> @ <commit>
200
- ArkaOS: <version> | Branch: <branch>
201
-
202
- ▸ Complexity Analysis
203
- <render_complexity output>
204
-
205
- ▸ Critic Verdict
206
- Confidence: <score>
207
- ✓ <N> elements adopted
208
- ✗ <N> elements rejected
209
- ⚠ <N> risks identified
210
-
211
- ▸ Plan: <N> phases across <N> department(s)
212
- Phase 1: <name> [dept] ░░░░░░░░
213
- Phase 2: <name> [dept] ░░░░░░░░
214
- ...
215
-
216
- Execution: <type> → <target>
217
- Departments: <list>
218
- QG required: yes
219
-
220
- [A]pprove [R]evise [C]ompanion [D]etail phase [Q]uit
221
- ```
222
-
223
- ### Step 8 — User Decision
224
-
225
- Wait for user input and handle each option:
226
-
227
- | Input | Action |
228
- |-------|--------|
229
- | `A` or `approve` | Proceed to Step 9 (handoff) |
230
- | `R <text>` or `revise <text>` | Proceed to Revision Flow |
231
- | `C` or `companion` | Generate HTML companion (Step 6a), then re-show menu |
232
- | `D <n>` or `detail <n>` | Show full detail for phase N (agents, deliverables, criteria), then re-show menu |
233
- | `Q` or `quit` | Save plan as `draft`, clear active, exit |
234
-
235
- ### Step 6a — Visual Companion (on C input)
236
-
237
- Generate HTML via the renderer and serve locally:
238
-
239
- ```python
240
- from core.forge.renderer import render_html, should_suggest_companion
241
-
242
- html_content = render_html(plan)
243
- # Write to /tmp/forge-<plan_id>.html
244
- ```
245
-
246
- ```bash
247
- # Write HTML file
248
- python -c "
249
- import sys
250
- sys.path.insert(0, '<repo_root>')
251
- # ... build plan, call render_html, write to /tmp/forge-<id>.html
252
- "
253
-
254
- # Serve on random available port
255
- python -m http.server 0 --directory /tmp &
256
- # Open in browser
257
- open http://localhost:<port>/forge-<id>.html
258
- ```
259
-
260
- Tell user: "Visual companion available at http://localhost:<port>/forge-<id>.html"
261
-
262
- Note: For `shallow` tier, companion is not generated (`should_suggest_companion()` returns `"none"`).
263
- For `standard`, it is available on request. For `deep`, proactively suggest it.
264
-
265
- ### Step 9 — Handoff (on Approve)
266
-
267
- 1. Check for repo drift since the snapshot:
268
-
269
- ```python
270
- from core.forge.handoff import check_repo_drift
271
- drift = check_repo_drift(plan.context.commit_at_forge)
272
- if drift["changed"]:
273
- # Warn user: "Repo changed since forge: X files modified"
274
- # Ask: "Re-run complexity analysis? [y/N]"
275
- ```
276
-
277
- 2. Determine execution path:
278
-
279
- ```python
280
- from core.forge.handoff import select_execution_path, generate_workflow_yaml
281
- path = select_execution_path(plan.plan_phases)
282
- ```
283
-
284
- 3. If path type is `workflow` or `enterprise_workflow`, generate and save the YAML:
285
-
286
- ```python
287
- workflow_yaml = generate_workflow_yaml(plan)
288
- # Write to .arkaos/workflows/<plan_id>.yaml
289
- ```
290
-
291
- 4. Update plan status to `approved`, set `executed_at` timestamp.
292
-
293
- 5. Save and set as active:
294
-
295
- ```python
296
- from core.forge.persistence import save_plan, set_active_plan
297
- save_plan(plan)
298
- set_active_plan(plan.id)
299
- ```
300
-
301
- 6. Announce:
30
+ ## Complexity Tiers
302
31
 
303
- ```
304
- ⚒ FORGE — Approved
305
-
306
- Plan ID: <id>
307
- Execution: <type> → <target>
308
- Branch: <suggested branch name>
309
-
310
- Ready. Proceeding with execution.
311
- ```
312
-
313
- 7. Hand off to the appropriate executor:
314
- - `skill` → invoke the named ArkaOS skill with plan context
315
- - `workflow` or `enterprise_workflow` → invoke `/dev feature` or equivalent department command, passing forge context as preamble
316
-
317
- ### Step 10 — Persist to YAML + Obsidian
318
-
319
- After approval (or on quit/cancel):
320
-
321
- ```python
322
- from core.forge.persistence import save_plan, export_to_obsidian
323
-
324
- path = save_plan(plan)
325
- obsidian_path = export_to_obsidian(plan)
326
- ```
327
-
328
- For approved + completed plans, also extract patterns:
329
-
330
- ```python
331
- from core.forge.persistence import extract_patterns
332
- patterns = extract_patterns(plan)
333
- if patterns:
334
- print(f" Patterns extracted: {len(patterns)}")
335
- ```
336
-
337
- ---
338
-
339
- ## Explorer Subagent Instructions
340
-
341
- Each explorer subagent receives this preamble, then its specific lens instruction.
342
-
343
- **Preamble (send to all explorers):**
344
-
345
- ```
346
- You are an expert planning agent within ArkaOS. Your task is to produce a
347
- structured execution plan for the following prompt.
348
-
349
- PROMPT: <original user prompt>
350
-
351
- REPO CONTEXT:
352
- Repo: <repo>
353
- Branch: <branch>
354
- Commit: <commit>
355
- ArkaOS: <version>
356
-
357
- OBSIDIAN KNOWLEDGE:
358
- Similar plans found: <list or "none">
359
- Reusable patterns: <list or "none">
360
-
361
- CONSTITUTION RULES (non-negotiable):
362
- - branch-isolation: all work on feature branches, never main
363
- - spec-driven: spec must exist before implementation
364
- - solid-clean-code: SOLID + Clean Code on all code
365
- - mandatory-qa: tests must pass, coverage >= 80%
366
- - quality-gate: Marta + Eduardo + Francisca must APPROVE before done
367
- - conventional-commits: all commits follow conventional commit format
368
-
369
- AVAILABLE DEPARTMENTS: dev, ops, mkt, brand, fin, strat, pm, saas,
370
- landing, content, ecom, kb, sales, lead, community, org
371
-
372
- AVAILABLE AGENTS (examples):
373
- dev: Paulo (lead), Gabriel (architect), Andre (backend), Diana (frontend),
374
- Bruno (security), Carlos (devops), Rita (qa), Vasco (dba)
375
- ops: Daniel (lead), Lucas (automation)
376
- mkt: Luna (lead), Sofia (growth), Pedro (analytics), Carla (email)
377
- brand: Valentina (lead), Miguel (visual), Ana (copy), Joao (ux)
378
- quality (cross-cutting): Marta (CQO), Eduardo (copy), Francisca (tech)
379
-
380
- Your output MUST follow this exact format:
381
- EXPLORER: <your lens name>
382
- SUMMARY: <2-3 sentences>
383
- KEY_DECISIONS:
384
- - decision: <what>
385
- rationale: <why>
386
- PHASES:
387
- - name: <phase name>
388
- department: <dept>
389
- agents: [<names>]
390
- deliverables: [<items>]
391
- acceptance_criteria: [<items>]
392
- depends_on: [<phase names>]
393
- ```
394
-
395
- **Pragmatic Explorer lens instruction:**
396
-
397
- ```
398
- Your lens: PRAGMATIC
399
- Question to answer: "What is the simplest thing that works?"
400
- Principles:
401
- - Minimum viable approach — reuse existing patterns, avoid over-engineering
402
- - Maximum reuse of existing ArkaOS skills and workflows
403
- - Fewer phases is better — collapse where safe to do so
404
- - Prefer known, proven solutions over novel ones
405
- - Identify what can be skipped without meaningful quality loss
406
- Be direct. Challenge gold-plating. Propose the leanest plan that still
407
- satisfies all Constitution rules.
408
- ```
409
-
410
- **Architectural Explorer lens instruction:**
411
-
412
- ```
413
- Your lens: ARCHITECTURAL
414
- Question to answer: "What is the right way to build this for the long term?"
415
- Principles:
416
- - Long-term extensibility and maintainability over short-term speed
417
- - Proper separation of concerns, clean boundaries
418
- - Identify technical debt that would be created by a simpler approach
419
- - Ensure observability, testability, and deployability are first-class
420
- - Reference DDD, SOLID, Clean Architecture where applicable
421
- Be thorough. Do not cut corners that will create future problems.
422
- ```
423
-
424
- **Contrarian Explorer lens instruction:**
425
-
426
- ```
427
- Your lens: CONTRARIAN
428
- Question to answer: "What is everyone missing or assuming wrongly?"
429
- Principles:
430
- - Challenge the premise of the prompt — is this the right problem to solve?
431
- - Surface hidden dependencies, risks, and blockers others would miss
432
- - Question every assumed constraint — are they real?
433
- - Propose an alternative framing if the original prompt is misguided
434
- - Identify the single biggest risk in the other approaches
435
- Be adversarial but constructive. Your job is to stress-test assumptions,
436
- not to be contrarian for its own sake. You must still produce a valid plan.
437
- ```
438
-
439
- ---
440
-
441
- ## Critic Subagent Instructions
442
-
443
- The critic receives anonymized approaches (lens labels stripped). Send this prompt:
444
-
445
- ```
446
- You are the Plan Critic within ArkaOS. You have received <N> independent
447
- planning approaches for the same prompt. Your job is to synthesize the best
448
- plan by combining the strongest elements from each approach.
449
-
450
- PROMPT: <original user prompt>
32
+ | Tier | Score | Explorers | Critic | Companion | Model |
33
+ |------|-------|-----------|--------|-----------|-------|
34
+ | Simple (Shallow) | ≤ 30 | 1 (Pragmatic, inline) | Light | None | haiku |
35
+ | Standard | 31-65 | 2 (Pragmatic + Architectural, parallel) | Full | On request | sonnet |
36
+ | Complex (Deep) | 66-85 | 3 (+ Contrarian, parallel) | Full | Proactive | opus |
37
+ | Super | ≥ 86 | 3 + full synthesis | Full (highest judgment) | Proactive | opus |
451
38
 
452
- APPROACHES:
453
- <approach_1_phases_and_decisions — label stripped>
454
- ---
455
- <approach_2_phases_and_decisions — label stripped>
456
- ---
457
- <approach_3_phases_and_decisions — label stripped, if deep tier>
39
+ Five dimensions score 0-100 each: **scope**, **dependencies**, **ambiguity**, **risk**, **novelty**. See `references/complexity-engine.md` for scoring details and tier confirmation prompt.
458
40
 
459
- RULES:
460
- - You MUST adopt the best elements from multiple approaches (do not just pick one)
461
- - You MUST reject at least 1 element with a clear reason
462
- - You MUST identify at least 1 risk in the final plan
463
- - Confidence score must reflect genuine uncertainty (do not always output 0.9)
464
- - The final phase list MUST include a Quality Gate phase as the penultimate step
465
- - The final phase list MUST include an Obsidian persistence phase as the last step
466
- - All Constitution rules apply to the final plan
41
+ ## Subagent Dispatch — Model Routing
467
42
 
468
- Your output MUST follow this exact format:
469
- CONFIDENCE: <0.0-1.0>
470
- SYNTHESIS:
471
- approach_1: [<adopted elements from approach 1>]
472
- approach_2: [<adopted elements from approach 2>]
473
- approach_3: [<adopted elements from approach 3, if applicable>]
474
- REJECTED:
475
- - element: <what>
476
- reason: <why>
477
- RISKS:
478
- - risk: <description>
479
- severity: high|medium|low
480
- mitigation: <how to address>
481
- FINAL_PHASES:
482
- - name: <phase name>
483
- department: <dept>
484
- agents: [<names>]
485
- deliverables: [<items>]
486
- acceptance_criteria: [<items>]
487
- depends_on: [<phase names>]
488
- ```
43
+ When dispatching explorer subagents via the Task tool, include `model: <tier_model>` parameter. The tier-to-model mapping is:
489
44
 
490
- ---
45
+ - simple → `model: haiku` (fast routing, single explorer)
46
+ - standard → `model: sonnet` (default, 1-2 explorers)
47
+ - complex → `model: opus` (3 explorers + critic synthesis)
48
+ - super → `model: opus` (highest judgment, full synthesis)
491
49
 
492
- ## Revision Flow
50
+ Example: for complex tier, use `model: opus` on every explorer Task call and on the critic synthesis dispatch.
493
51
 
494
- Triggered when user inputs `R <revision text>` at the decision menu.
495
-
496
- 1. Do NOT re-run explorers. The critic re-evaluates incrementally.
497
- 2. Increment `plan.revision_count` by 1.
498
- 3. Send the critic subagent the current plan + user revision text:
499
-
500
- ```
501
- REVISION REQUEST: <user revision text>
502
- CURRENT PLAN VERSION: <revision_count>
52
+ ## Explorer Lenses
503
53
 
504
- Current phases:
505
- <current final phases>
54
+ | Lens | Question | Role |
55
+ |------|----------|------|
56
+ | Pragmatic | "What is the simplest thing that works?" | Minimum viable, reuse-first, collapse phases |
57
+ | Architectural | "What is the right way to build this long-term?" | SOLID/DDD/Clean Arch, testability, no tech debt |
58
+ | Contrarian | "What is everyone missing or assuming wrongly?" | Stress-test assumptions, surface hidden risk |
506
59
 
507
- Current risks:
508
- <current risks>
509
-
510
- Update the plan to incorporate the revision. Apply the same output format.
511
- Only change what the revision explicitly requests. Preserve everything else.
512
- ```
513
-
514
- 4. Update plan with new critic output.
515
- 5. Re-render terminal output (Step 7) with updated plan.
516
- 6. Re-show the `[A]pprove [R]evise [C]ompanion [D]etail [Q]uit` menu.
517
-
518
- Maximum 5 revisions. After 5, warn user and offer approve-as-is or quit.
519
-
520
- ---
60
+ Full lens prompts and the Critic synthesis prompt live in `references/critic-synthesis.md`.
521
61
 
522
- ## Secondary Commands
523
-
524
- ### `/forge resume`
525
-
526
- 1. Call `get_active_plan()` from `core.forge.persistence`
527
- 2. If no active plan: "No active forge plan. Run `/forge <prompt>` to start."
528
- 3. If plan found:
529
- - Call `check_repo_drift(plan.context.commit_at_forge)`
530
- - If drift detected: warn user, offer to re-run complexity analysis
531
- - Re-render terminal output (Step 7)
532
- - Re-show decision menu (Step 8)
533
-
534
- ### `/forge status`
535
-
536
- 1. Call `get_active_plan()` from `core.forge.persistence`
537
- 2. If none: "No active forge plan."
538
- 3. Display:
539
- ```
540
- ⚒ FORGE — Active Plan
541
-
542
- ID: <id>
543
- Name: <name>
544
- Status: <status>
545
- Tier: <tier> | Score: <score>/100
546
- Confidence: <critic confidence>
547
- Phases: <N> across <depts>
548
- Created: <timestamp>
549
- Revisions: <count>
550
- ```
551
-
552
- ### `/forge history`
553
-
554
- 1. Call `list_plans()` from `core.forge.persistence`
555
- 2. If empty: "No forge plans found in ~/.arkaos/plans/"
556
- 3. Display table:
557
- ```
558
- ⚒ FORGE — History
559
-
560
- ID Name Status Tier Conf. Created
561
- forge-20260411-abc1 Add auth module approved deep 0.87 2026-04-11
562
- forge-20260410-def2 Refactor billing flow completed standard 0.74 2026-04-10
563
- ...
564
- ```
62
+ ## Orchestration Overview
565
63
 
566
- ### `/forge show <id>`
64
+ Every `/forge <prompt>` executes a 10-step flow: (1) context snapshot, (2) Obsidian knowledge check, (3) complexity analysis, (4) tier confirmation gate, (5) launch explorers in parallel, (6) critic synthesis on anonymized outputs, (7) render terminal plan, (8) user decision (Approve / Revise / Companion / Detail / Quit), (9) handoff with repo-drift check, (10) persist to YAML + Obsidian and extract patterns.
567
65
 
568
- 1. Call `load_plan(id)` from `core.forge.persistence`
569
- 2. If not found: "Plan <id> not found."
570
- 3. Display full terminal render via `render_terminal(plan)`
571
- 4. Then show all approaches (explorer summaries) and full critic verdict.
66
+ Revisions re-run the critic only (not explorers), capped at 5. Secondary commands (`resume`, `status`, `history`, `show`, `compare`, `patterns`, `cancel`) operate on persisted plans in `~/.arkaos/plans/`.
572
67
 
573
- ### `/forge compare <id1> <id2>`
574
-
575
- 1. Load both plans via `load_plan()`
576
- 2. Display side-by-side:
577
- ```
578
- ⚒ FORGE — Comparing Plans
579
-
580
- Left: <id1> (<name1>) | Right: <id2> (<name2>)
581
- Score: <s1>/100 (<tier1>) | Score: <s2>/100 (<tier2>)
582
- Confidence: <c1> | Confidence: <c2>
583
- Phases: <n1> | Phases: <n2>
584
-
585
- PHASES LEFT PHASES RIGHT
586
- ─────────────────────────────── ───────────────────────────────
587
- Phase 1: <name> [dept] Phase 1: <name> [dept]
588
- Phase 2: <name> [dept] Phase 2: <name> [dept]
589
- ...
590
-
591
- RISK DELTA:
592
- Left risks not in right: <list>
593
- Right risks not in left: <list>
594
- ```
595
-
596
- ### `/forge patterns`
597
-
598
- 1. Call `load_patterns()` from `core.forge.persistence`
599
- 2. If empty: "No patterns found in ArkaOS/Forge/Patterns/"
600
- 3. Display:
601
- ```
602
- ⚒ FORGE — Reusable Patterns
603
-
604
- Name Tier Depts Phases Used
605
- repo-dev-ops-pattern deep dev, ops 6 3
606
- repo-dev-pattern standard dev 4 7
607
- ...
608
- ```
609
-
610
- ### `/forge cancel`
611
-
612
- 1. Load active plan via `get_active_plan()`
613
- 2. If none: "No active plan to cancel."
614
- 3. Confirm: "Cancel plan '<name>'? This cannot be undone. [y/N]"
615
- 4. On confirm: set `plan.status = ForgeStatus.CANCELLED`, call `save_plan()`, call `clear_active_plan()`
616
- 5. "Forge plan cancelled. No changes were made to the codebase."
617
-
618
- ---
619
-
620
- ## Constitution Compliance
621
-
622
- The Forge enforces these Constitution rules at the plan level:
623
-
624
- | Rule | Enforcement |
625
- |------|-------------|
626
- | `branch-isolation` | Every plan must include a "Create feature branch" step in Phase 1 |
627
- | `spec-driven` | Plans touching code must have a Specification phase before Implementation |
628
- | `mandatory-qa` | All plans must include a QA phase (Rita) before Quality Gate |
629
- | `quality-gate` | All plans must end with a Quality Gate phase (Marta + Eduardo + Francisca) |
630
- | `obsidian-output` | All plans must end with an Obsidian persistence step |
631
- | `conventional-commits` | Remind in handoff message |
632
-
633
- If a critic output violates any of these, inject the missing phases automatically before showing the plan to the user. Announce: "Constitution enforcement: added missing <phase name> phase."
634
-
635
- ---
68
+ **See `references/workflows.md` for the full step-by-step flows, revision flow, secondary commands, and Constitution enforcement rules.**
636
69
 
637
70
  ## Plan ID Format
638
71
 
639
- Plan IDs follow the format: `forge-YYYYMMDD-<4-char hex>`
72
+ Plan IDs follow the format: `forge-YYYYMMDD-<4-char hex>` (example: `forge-20260411-a3f2`).
640
73
 
641
- Example: `forge-20260411-a3f2`
642
-
643
- Generate with:
644
74
  ```python
645
75
  import hashlib, datetime
646
76
  date = datetime.date.today().strftime("%Y%m%d")
647
77
  suffix = hashlib.md5(prompt.encode()).hexdigest()[:4]
648
78
  plan_id = f"forge-{date}-{suffix}"
649
79
  ```
80
+
81
+ ## References
82
+
83
+ - `references/workflows.md` — Full 10-step main flow, revision flow, secondary commands, Constitution compliance
84
+ - `references/complexity-engine.md` — Complexity scoring, dimensions, tier thresholds, tier confirmation prompt
85
+ - `references/critic-synthesis.md` — Explorer preamble and 3 lens instructions, Critic subagent synthesis prompt