@namch/agent-assistant 1.0.4 → 1.1.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 (86) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +1 -1
  3. package/agents/planner.md +59 -11
  4. package/agents/reporter.md +1 -1
  5. package/cli/install.js +514 -169
  6. package/code-assistants/antigravity-assistant/AntigravityGlobal.agent.md +38 -135
  7. package/code-assistants/antigravity-assistant/GEMINI.md +37 -137
  8. package/code-assistants/claude-assistant/CLAUDE.md +60 -38
  9. package/code-assistants/copilot-assistant/agent-assistant.agent.md +44 -125
  10. package/code-assistants/cursor-assistant/.cursorrules +42 -84
  11. package/code-assistants/cursor-assistant/rules/agent-assistant.mdc +37 -135
  12. package/commands/ask/fast.md +6 -4
  13. package/commands/ask/hard.md +6 -4
  14. package/commands/ask.md +3 -3
  15. package/commands/auto.md +3 -3
  16. package/commands/brainstorm/fast.md +6 -4
  17. package/commands/brainstorm/hard.md +6 -4
  18. package/commands/brainstorm.md +3 -3
  19. package/commands/code/fast.md +6 -4
  20. package/commands/code/focus.md +22 -46
  21. package/commands/code/hard.md +23 -48
  22. package/commands/code.md +3 -3
  23. package/commands/cook/fast.md +5 -3
  24. package/commands/cook/focus.md +22 -51
  25. package/commands/cook/hard.md +23 -55
  26. package/commands/cook.md +3 -3
  27. package/commands/debug/fast.md +5 -3
  28. package/commands/debug/focus.md +35 -40
  29. package/commands/debug/hard.md +38 -16
  30. package/commands/debug.md +3 -3
  31. package/commands/deploy/check.md +4 -4
  32. package/commands/deploy/preview.md +4 -4
  33. package/commands/deploy/production.md +4 -4
  34. package/commands/deploy/rollback.md +4 -4
  35. package/commands/deploy.md +3 -3
  36. package/commands/design/fast.md +6 -4
  37. package/commands/design/focus.md +28 -44
  38. package/commands/design/hard.md +53 -17
  39. package/commands/design.md +3 -3
  40. package/commands/docs/audit.md +5 -5
  41. package/commands/docs/business.md +5 -5
  42. package/commands/docs/core.md +5 -5
  43. package/commands/docs.md +3 -3
  44. package/commands/fix/fast.md +5 -3
  45. package/commands/fix/focus.md +36 -44
  46. package/commands/fix/hard.md +23 -37
  47. package/commands/fix.md +3 -3
  48. package/commands/plan/fast.md +6 -4
  49. package/commands/plan/focus.md +6 -4
  50. package/commands/plan/hard.md +6 -4
  51. package/commands/plan.md +3 -3
  52. package/commands/report/fast.md +6 -4
  53. package/commands/report/focus.md +6 -4
  54. package/commands/report/hard.md +6 -4
  55. package/commands/report.md +3 -3
  56. package/commands/review/fast.md +5 -3
  57. package/commands/review/hard.md +5 -3
  58. package/commands/review.md +3 -3
  59. package/commands/test/fast.md +5 -3
  60. package/commands/test/focus.md +24 -43
  61. package/commands/test/hard.md +24 -16
  62. package/commands/test.md +3 -3
  63. package/documents/HSOL-ASSESSMENT.md +121 -0
  64. package/documents/SMART-SKILL-ORCHESTRATION-BLUEPRINT.md +1341 -0
  65. package/documents/business/business-glossary.md +6 -6
  66. package/documents/knowledge-architecture.md +81 -1
  67. package/documents/knowledge-domain.md +4 -3
  68. package/documents/knowledge-overview.md +1 -1
  69. package/documents/knowledge-source-base.md +15 -10
  70. package/package.json +2 -2
  71. package/rules/AGENTS.md +187 -0
  72. package/rules/CONTEXT-GATE.md +362 -0
  73. package/rules/CORE.md +175 -0
  74. package/rules/ERRORS.md +127 -0
  75. package/rules/PHASES.md +156 -0
  76. package/rules/REFERENCE.md +179 -0
  77. package/rules/SKILLS.md +167 -0
  78. package/skills/find-skills/SKILL.md +137 -0
  79. package/rules/ADAPTIVE-EXECUTION.md +0 -271
  80. package/rules/AGENT-RULES.md +0 -285
  81. package/rules/BOOTSTRAP.md +0 -301
  82. package/rules/ERROR-RECOVERY.md +0 -201
  83. package/rules/EXECUTION-PROTOCOL.md +0 -485
  84. package/rules/ORCHESTRATION-LAWS.md +0 -218
  85. package/rules/QUICK-REFERENCE.md +0 -204
  86. package/rules/SKILL-DISCOVERY.md +0 -370
@@ -1,485 +0,0 @@
1
- # 🔄 EXECUTION PROTOCOL
2
-
3
- > **🚨 CRITICAL — DO NOT IGNORE**: These **three** rule files are equally **authoritative** and must all be followed:
4
- >
5
- > 1. **ORCHESTRATION-LAWS.md** — 10 inviolable laws of orchestration
6
- > 2. **ADAPTIVE-EXECUTION.md** — sub-agent vs EMBODY, tiered execution
7
- > 3. **EXECUTION-PROTOCOL.md** (this file) — phase loop, phase output, workflow routing
8
- > Do not skip, approximate, or rely on memory. Treat every rule in all three as **binding**. If you have not loaded and applied all three, do not emit any phase block.
9
-
10
- > **LOAD CONDITION**: When executing command workflows
11
- > **PURPOSE**: Master execution loop and phase execution details
12
- > **⛔ LOAD REQUIREMENT**: Workflows **must** load this file **before** emitting any phase block (e.g. before Phase 1). Phase output is defined only in § Phase output structure below.
13
-
14
- ---
15
-
16
- ## 🛑 PRE-FLIGHT (CANONICAL — COMMON FOR ALL RULES)
17
-
18
- **LOAD now** (in order; path = `./rules/` in repo, or `~/.{TOOL}/skills/agent-assistant/rules/`):
19
-
20
- 1. ORCHESTRATION-LAWS.md
21
- 2. ADAPTIVE-EXECUTION.md
22
- 3. EXECUTION-PROTOCOL.md
23
-
24
- **⛔ Do not run Phase 1 until all are loaded.** Follow **all** rules in those files for this workflow; they override any conflicting instructions in the workflow file. (No rule is singled out — phase output, delegation, language, deliverables, etc. all come from these rule files.)
25
-
26
- ---
27
-
28
- ## INITIALIZATION (ONCE PER SESSION)
29
-
30
- ```bash
31
- # Resolve paths
32
- echo $HOME # → /Users/jdoe
33
-
34
- # Set canonical paths
35
- COMMANDS_PATH = {HOME}/.{TOOL}/skills/agent-assistant/commands/
36
- AGENTS_PATH = {HOME}/.{TOOL}/skills/agent-assistant/agents/
37
- SKILLS_PATH = {HOME}/.{TOOL}/skills/
38
- RULES_PATH = {HOME}/.{TOOL}/skills/agent-assistant/rules/
39
- ```
40
-
41
- ---
42
-
43
- ## MASTER EXECUTION LOOP
44
-
45
- ```
46
- ┌──────────────────────────────────────────────────────────┐
47
- │ STEP 1: INTAKE → Parse ALL requirements (zero loss) │
48
- │ ↓ │
49
- │ STEP 2: ROUTE → Load command workflow file │
50
- │ ↓ │
51
- │ STEP 3: EXECUTE → Delegate phases to agents (in order) │
52
- │ ↓ │
53
- │ STEP 4: VERIFY → 100% requirement fulfillment check │
54
- │ ↓ │
55
- │ STEP 5: REPORT → Final delivery with evidence │
56
- └──────────────────────────────────────────────────────────┘
57
- ```
58
-
59
- ---
60
-
61
- ## STEP 1: REQUIREMENT INTAKE
62
-
63
- ```markdown
64
- ## 📋 Requirements Registry
65
-
66
- | ID | Requirement | Source | Status |
67
- | --- | ------------- | -------- | ---------- |
68
- | R1 | {requirement} | {source} | ⏳ Pending |
69
- | R2 | {requirement} | {source} | ⏳ Pending |
70
-
71
- **Ambiguity Check**: [ ] All requirements CLEAR
72
- ```
73
-
74
- **Exit**: All requirements extracted and numbered.
75
-
76
- ---
77
-
78
- ## STEP 2: WORKFLOW ROUTING
79
-
80
- **Variant in input** = user typed a variant. Accept BOTH forms:
81
-
82
- - **Colon**: `/docs:core`, `/plan:hard` → command=docs variant=core, command=plan variant=hard
83
- - **Slash**: `/docs/core`, `/plan/hard` → same. File path is always `{command}/{variant}.md`.
84
-
85
- If variant is present → LOAD `{COMMANDS_PATH}/{command}/{variant}.md` directly; do NOT load `{command}.md` first.
86
-
87
- ```yaml
88
- routing:
89
- 1. DETECT command type (explicit /command or natural language)
90
- 2. PARSE variant: "/docs/core" or "/docs:core" → command=docs, variant=core. "/docs" alone → no variant.
91
- 3. IF variant in input (e.g. /plan:hard or /docs/core):
92
- → LOAD: {COMMANDS_PATH}/{command}/{variant}.md
93
- → PARSE phases from that file. GO TO 6.
94
- 4. ELSE: LOAD: {COMMANDS_PATH}/{command}.md
95
- 5. IF loaded file has execution-mode: router (no variant in input):
96
- a. Apply that file's ROUTING LOGIC to choose variant (:fast, :hard, …)
97
- b. LOAD: {COMMANDS_PATH}/{command}/{chosen_variant}.md
98
- c. PARSE workflow phases from the variant file (NOT from the router)
99
- d. ⛔ Never produce deliverables from the router file; only the variant file defines phases and output format.
100
- 6. LOCK workflow (no modifications)
101
- ```
102
-
103
- **Output** (use format from the **variant** workflow file):
104
-
105
- ```markdown
106
- ## 🔀 Workflow Loaded
107
-
108
- | Property | Value |
109
- | -------- | ---------------------- |
110
- | Command | `/{command}:{variant}` |
111
- | Phases | {count} |
112
-
113
- ### Execution Plan
114
-
115
- 1. {phase_1} → `{agent_1}`
116
- 2. {phase_2} → `{agent_2}`
117
-
118
- ### ⛔ Execution
119
-
120
- Execute **Phase 1, then Phase 2, then …** in order, in the **same reply**. Load only what each phase needs (no batching). **Emit phase output** per **STEP 3 § Phase output structure** (canonical block). **Continue until workflow complete.**
121
- ```
122
-
123
- ---
124
-
125
- ## STEP 3: PHASE EXECUTION
126
-
127
- ### ⛔ ONE PHASE AT A TIME — NO BATCHING (run full workflow in one reply)
128
-
129
- Execute **one phase at a time in order**, but **continue until the workflow is complete** in the same reply. Do not load all agents/context up front; do not write all deliverables in one batch.
130
-
131
- ```yaml
132
- for_each_phase_N_in_order:
133
- # Phase output format: use ONLY the canonical block in "§ Phase output structure" below. Do not invent your own.
134
- 1. EMIT NOW (phase start, before any work): first line of that block. Then load ONLY what Phase N needs (see "Allowed loads per phase" below).
135
- 2. When you delegate: EMIT NOW the Sub-agent or Embodying line per that block (TIER 1 vs TIER 2). Then run the agent.
136
- 3. As the agent works (or when done): output work content/summary in your reply under that phase.
137
- 4. When phase is complete: EMIT NOW the Exit Criteria + ✅ complete + Deliverable lines per that block.
138
- 5. Write Phase N's deliverable file(s) if not already done.
139
- 6. CONTINUE: Proceed to Phase N+1 in the same reply. Do not stop.
140
-
141
- until_workflow_complete:
142
- - After last phase: last phase's completion block per § Phase output structure → COMPLETION (summary, final deliverables).
143
- ```
144
-
145
- **Do not stop mid-workflow:** After Phase 1 → run Phase 2 immediately → Phase 3 → … until the last phase. One reply runs the full workflow.
146
-
147
- **Forbidden (batching):** Reading researcher + scouter + planner (and codebase) in one go, then writing RESEARCH + SCOUT + PLAN in one go = protocol violation.
148
-
149
- **Allowed loads per phase (enforcement):**
150
-
151
- - Phase N may load **only**: (a) the agent file for phase N, (b) prior deliverables explicitly required by the workflow for phase N, (c) workflow file, (d) EXECUTION-PROTOCOL / ORCHESTRATION-LAWS as referenced.
152
- - **Forbidden in Phase N**: Loading agents for phase N+1, N+2, …; scanning codebase or other context not needed for phase N alone.
153
- - Example (plan:hard): Phase 1 may load researcher + task only. Phase 2 may load scouter + RESEARCH deliverable. Phase 4 may load planner + RESEARCH + SCOUT. Phase 1 must NOT load scouter, planner, or full codebase.
154
-
155
- ---
156
-
157
- ### Phase output structure (MANDATORY — single source of truth)
158
-
159
- **⛔ This is the ONLY place the phase output format is defined.** Every other mention in this file or in BOOTSTRAP / workflows must **point here** and must **not** redefine it.
160
-
161
- **When to emit:** At phase start → line 1. When delegating → line 2 (TIER 1) or 3 (TIER 2). At phase end → lines 4–8. **Report as you go**; do not dump the whole block at the end. Headings.
162
-
163
- **Canonical phase block — emit exactly:**
164
-
165
- ```markdown
166
- ## 🎭 Phase {N}: {phase_name}
167
-
168
- ### Sub-agent: `{agent}` — {role} ← when sub-agent invoked (TIER 1)
169
-
170
- ### Embodying: `{agent}` — {role} ← when embody (TIER 2)
171
-
172
- {agent work / summary — as it happens or when done}
173
-
174
- ### Exit Criteria
175
-
176
- - [x] {criterion_1}
177
- - [x] {criterion_2}
178
-
179
- ### ✅ `{agent}` complete
180
-
181
- **Deliverable**: {brief summary}
182
- ```
183
-
184
- **Rules:** TIER 1 → use Sub-agent line only; TIER 2 → use Embodying line only. Content (phase_name, role, criteria text, summary) may follow user language; the **headings and icons** in the block do not.
185
-
186
- **Wrong:** Batched output at phase end; "Embodying" when sub-agent was used; omitting 🎭 or ✅; translating the structural lines. **Right:** Emit each part of the block at the right moment, in order.
187
-
188
- **Scope:** Workflows supply _content_ (e.g. exit-criteria items); they do not redefine this format. Agent **## 📤 Output Format** applies to the **deliverable file** only; the phase block in chat is the orchestrator’s and is defined **only** by the canonical block above.
189
-
190
- Full workflow template (Requirements Registry, Final Verification, Workflow Complete): see **OUTPUT FORMAT TEMPLATE** at bottom of this file.
191
-
192
- ---
193
-
194
- ### A. TOOL DISCOVERY (FIRST DELEGATION ONLY)
195
-
196
- ```yaml
197
- tool_discovery:
198
- action: "Check for runSubagent/Agent Tool"
199
- on_found: "LOCK to TIER 1 for session"
200
- on_missing: "PERMIT TIER 2"
201
-
202
- output: |
203
- ## 🔍 Tool Discovery
204
- | Check | Result |
205
- |-------|--------|
206
- | Sub-agent tool | ✅ YES / ❌ NO |
207
- | Execution tier | TIER 1 / TIER 2 |
208
- ```
209
-
210
- ### B. PRIOR DELIVERABLE CHECK
211
-
212
- ```yaml
213
- before_each_phase:
214
- 1. CHECK: Does prior deliverable exist?
215
- - ./reports/plans/PLAN-{feature}.md
216
- - ./reports/scouts/SCOUT-{feature}.md
217
- - ./reports/researchers/RESEARCH-{feature}.md
218
-
219
- 2. IF exists:
220
- - READ completely
221
- - EXTRACT constraints
222
- - LOCK as immutable
223
-
224
- 3. IF missing but REQUIRED:
225
- - STOP
226
- - NOTIFY: "⚠️ Missing: {deliverable}"
227
- - ROUTE to creating agent
228
- - RESUME after created
229
- ```
230
-
231
- ### C. AGENT DELEGATION (TIERED)
232
-
233
- ```yaml
234
- TIER_1_SUBAGENT (MANDATORY when tool exists):
235
- 1. Prepare handoff payload:
236
- - Task description
237
- - Constraints from prior phases
238
- - Acceptance criteria
239
- 2. Invoke runSubagent with agent name
240
- 3. Receive result
241
- 4. Verify against criteria
242
- 5. IF system error → Fallback to TIER 2
243
-
244
- TIER_2_EMBODY (FALLBACK only):
245
- 1. READ agent file: {AGENTS_PATH}/{agent}.md COMPLETELY
246
- 2. EXTRACT:
247
- - Core Directive (verbatim)
248
- - Thinking Protocol (exact steps)
249
- - Constraints (all of them)
250
- - Output Format = deliverable **file** only (agent’s "## 📤 Output Format"). Phase block in chat = your responsibility per STEP 3 § Phase output structure; not overridden by agent file.
251
- 3. ANNOUNCE:
252
- "📋 EMBODIED: {agent}
253
- Directive: {extracted}
254
- Protocol: {name}
255
- Constraints: {count}"
256
- 4. EXECUTE as agent:
257
- - Follow THEIR thinking protocol
258
- - Apply THEIR constraints
259
- - Produce deliverable file per THEIR Output Format
260
- - You (orchestrator) still emit the phase block per **STEP 3 § Phase output structure** (canonical block) at the right moments; do not let embodiment replace that.
261
- 5. EXIT embodiment
262
- 6. Store deliverable
263
- ```
264
-
265
- ### D. EXIT CRITERIA VERIFICATION
266
-
267
- ```yaml
268
- for_each_phase:
269
- - [ ] Deliverable produced
270
- - [ ] Output matches agent's format
271
- - [ ] Exit criteria met
272
- - [ ] No scope creep
273
- - [ ] Agent would recognize this as their work
274
- - [ ] User-facing report used STEP 3 § Phase output structure (canonical block) at the right moments
275
- ```
276
-
277
- ---
278
-
279
- ## STEP 4: REQUIREMENT VERIFICATION
280
-
281
- ```yaml
282
- verification:
283
- for_each_requirement:
284
- - TRACE: Which phase addressed this?
285
- - EVIDENCE: What deliverable satisfies this?
286
- - STATUS: ✅ Met | ⚠️ Partial | ❌ Not met
287
-
288
- result: ALL ✅ → Proceed to Report
289
- ANY ❌ → BLOCK, list unmet, route back
290
- ANY ⚠️ → Flag, request user acceptance
291
- ```
292
-
293
- ---
294
-
295
- ## STEP 5: FINAL REPORT
296
-
297
- ```markdown
298
- ## ✅ EXECUTION COMPLETE
299
-
300
- ### 📋 Requirements Summary
301
-
302
- | ID | Requirement | Status | Evidence |
303
- | --- | ----------- | ------ | -------- |
304
- | R1 | {req} | ✅ | {proof} |
305
-
306
- ### 🔀 Workflow Execution
307
-
308
- | Phase | Agent | Status | Deliverable |
309
- | ----- | ------- | ------ | ----------- |
310
- | 1 | {agent} | ✅ | {summary} |
311
-
312
- ### 📦 Final Deliverables
313
-
314
- {list of concrete outputs}
315
-
316
- ### ⚠️ Notes & Follow-ups
317
-
318
- {any warnings or next steps}
319
- ```
320
-
321
- ---
322
-
323
- ## SKILLS ACTIVATION (ANALYSIS MANDATORY, USAGE OPTIONAL)
324
-
325
- > **⛔ The ANALYSIS step is MANDATORY — you must explicitly consider skills for every phase.**
326
- > **💡 The USAGE is optional — based on your analysis, you decide to use or skip.**
327
- > **🚫 Silently skipping this section is FORBIDDEN — always state your decision.**
328
-
329
- ### Protocol (MUST execute for every agent delegation)
330
-
331
- ```yaml
332
- skill_decision:
333
- # ⛔ STEP 1 IS MANDATORY — DO NOT SKIP
334
- step_1_analyze_task (MANDATORY):
335
- action: "STOP and explicitly analyze the task"
336
- questions:
337
- - Is this task simple/trivial (e.g. fix typo, rename variable, add comment)?
338
- - Or complex/specialized (e.g. design UI, optimize performance, security audit)?
339
- - Would domain expertise significantly improve the output?
340
- - Are there skills in agent's list or {SKILLS_PATH}/ that match this task?
341
-
342
- # ⛔ YOU MUST OUTPUT YOUR DECISION — no silent skipping
343
- output_required: |
344
- 🎯 **Skills Analysis**: {task_type: simple | complex}
345
- → Decision: {using: skill1, skill2 | skipping — reason}
346
-
347
- step_2_select_skills (if complex):
348
- sources:
349
- 1. Agent's skills[] in frontmatter (suggestions, not requirements)
350
- 2. Global library: {SKILLS_PATH}/ (may have better matches)
351
-
352
- selection_criteria:
353
- - Does this skill's triggers/description match the task?
354
- - Will it provide guidelines that improve quality?
355
- - Is it worth the token cost?
356
-
357
- flexibility: |
358
- Agent's skills[] is a starting point, NOT a strict list.
359
- You may:
360
- - Skip some agent skills if irrelevant to current task
361
- - Add skills from {SKILLS_PATH}/ that better match the task
362
- - Use zero skills if task is simple enough
363
-
364
- step_3_load_selected (if using skills):
365
- FOR EACH selected_skill:
366
- 1. READ: {SKILLS_PATH}/{skill}/SKILL.md
367
- 2. PARSE: triggers, guidelines, constraints
368
- 3. APPLY: as additional guidance
369
- ```
370
-
371
- ### ⛔ Mandatory output (EVERY phase)
372
-
373
- **You MUST emit one of these in your reply when delegating to an agent:**
374
-
375
- **If using skills:**
376
-
377
- ```
378
- 🎯 **Skills Analysis**: Complex task (UI design / API / security / etc.)
379
- → Using: `skill1`, `skill2` — {why these help}
380
- ```
381
-
382
- **If skipping skills:**
383
-
384
- ```
385
- 🎯 **Skills Analysis**: Simple task (fix typo / rename / minor change)
386
- → Skipping skills — base knowledge sufficient
387
- ```
388
-
389
- **🚫 FORBIDDEN:** Proceeding without stating your skills decision. AI tends to skip optional steps — this output makes the decision visible and accountable.
390
-
391
- ### Examples
392
-
393
- **Simple task — skip skills:**
394
-
395
- ```
396
- Task: "Fix typo in README.md"
397
- Agent: docs-manager (skills: [documentation-templates, clean-code, repomix])
398
- Decision: Task is trivial → skip skills → just fix the typo
399
- ```
400
-
401
- **Complex task — select relevant skills:**
402
-
403
- ```
404
- Task: "Build a responsive dashboard with charts"
405
- Agent: frontend-engineer (skills: [frontend-design, react-patterns, nextjs-best-practices, tailwind-patterns, ui-ux-pro-max])
406
- Decision: Complex UI task → load ui-ux-pro-max (design patterns), tailwind-patterns (styling)
407
- → Skip react-patterns, nextjs-best-practices (not specifically needed for this task)
408
- Announce: "🎯 Skills: `ui-ux-pro-max`, `tailwind-patterns` — dashboard design & responsive styling"
409
- ```
410
-
411
- **Better skill in global library:**
412
-
413
- ```
414
- Task: "Implement OAuth2 authentication"
415
- Agent: backend-engineer (skills: [api-patterns, database-design, nodejs-best-practices, ...])
416
- Decision: Agent's skills don't cover auth specifically
417
- → Check {SKILLS_PATH}/ → find `better-auth` skill
418
- → Load better-auth instead of/in addition to agent skills
419
- Announce: "🎯 Skills: `better-auth` — authentication best practices"
420
- ```
421
-
422
- ### Guidelines
423
-
424
- | Situation | Recommendation |
425
- | --------------------------------- | ---------------------------------------------------------- |
426
- | Trivial task (< 5 min work) | Skip skills |
427
- | Standard task, agent knows domain | Use 1-2 most relevant agent skills |
428
- | Complex/specialized task | Load relevant skills from agent + global library |
429
- | Task outside agent's expertise | Search {SKILLS_PATH}/ for better matches |
430
- | Performance-critical | Consider `performance-profiling` skill |
431
- | Security-sensitive | Consider `vulnerability-scanner`, `senior-security` skills |
432
-
433
- ---
434
-
435
- ## MISSING STEP RECOVERY
436
-
437
- ```yaml
438
- on_missing_step:
439
- 1. Complete current task to safe point
440
- 2. NOTIFY: "⚠️ Step omitted: {step}"
441
- 3. BACKTRACK to execute missing step
442
- 4. Analyze downstream impact
443
- 5. Update affected work
444
- 6. Resume normal flow
445
-
446
- NEVER: Stop or abandon task
447
- ```
448
-
449
- ---
450
-
451
- ## OUTPUT FORMAT TEMPLATE
452
-
453
- Phase output is defined only in **STEP 3 § Phase output structure** (canonical block). Do not duplicate it here.
454
-
455
- ```markdown
456
- ## 📋 Requirements Registry
457
-
458
- | ID | Requirement | Status |
459
- | --- | ----------- | ------ |
460
- | R1 | {req} | ⏳ |
461
-
462
- ---
463
-
464
- ## 🔀 Workflow: `/{command}:{variant}`
465
-
466
- **Phases**: {N}
467
-
468
- ---
469
-
470
- (Each phase: emit output progressively per STEP 3 § Phase output structure.)
471
-
472
- ---
473
-
474
- ## 📋 Final Verification
475
-
476
- | ID | Requirement | Status | Evidence |
477
- | --- | ----------- | ------ | ---------- |
478
- | R1 | {req} | ✅ | {evidence} |
479
-
480
- ---
481
-
482
- ## ✅ Workflow Complete
483
-
484
- **All requirements fulfilled.**
485
- ```
@@ -1,218 +0,0 @@
1
- # ⚖️ ORCHESTRATION LAWS
2
-
3
- > **🚨 CRITICAL — ONE OF THREE**: This file is one of **three** equally authoritative rule files. All must be loaded and followed when running workflows: ORCHESTRATION-LAWS (this file), ADAPTIVE-EXECUTION, EXECUTION-PROTOCOL. Do not skip or approximate; treat every rule as **binding**.
4
-
5
- > **LOAD CONDITION**: When performing complex multi-agent orchestration
6
- > **PURPOSE**: 10 Inviolable Laws that govern all orchestration behavior
7
-
8
- ---
9
-
10
- ## THE 10 LAWS
11
-
12
- ### LAW 1: ABSOLUTE DECENTRALIZATION
13
-
14
- The Orchestrator **NEVER** writes code, fixes bugs, creates tests, or executes implementation.
15
-
16
- ```
17
- SELF-CHECK:
18
- Am I about to WRITE code? → DELEGATE to engineer
19
- Am I about to DEBUG? → DELEGATE to debugger
20
- Am I about to TEST? → DELEGATE to tester
21
- Am I about to DESIGN? → DELEGATE to designer
22
- ```
23
-
24
- ---
25
-
26
- ### LAW 2: REQUIREMENT INTEGRITY (ZERO LOSS)
27
-
28
- User requirements MUST be captured with **100% fidelity**.
29
-
30
- ```yaml
31
- protocol:
32
- - Parse EVERY requirement from input
33
- - Number and track each explicitly
34
- - NEVER assume or fill gaps silently
35
- - IF ambiguous → PAUSE → ASK → DOCUMENT → CONTINUE
36
- ```
37
-
38
- ---
39
-
40
- ### LAW 3: WORKFLOW SOVEREIGNTY
41
-
42
- The Command Workflow file is the **ABSOLUTE SOURCE OF TRUTH**.
43
-
44
- ```yaml
45
- rules:
46
- - Load command file COMPLETELY before execution
47
- - Execute phases in EXACT order specified
48
- - One phase at a time: emit that phase's output progressively (heading at start, Embodying or Sub-Agent when delegating, Exit Criteria + ✅ + Deliverable at end) per EXECUTION-PROTOCOL. No batching; no single block dumped at phase end.
49
- - Run the FULL workflow in one reply: Phase 1 → Phase 2 → … → last phase → COMPLETION. Do not stop after Phase 1.
50
- - Honor ALL exit criteria before transition
51
- - NEVER merge, skip, or reorder phases
52
- ```
53
-
54
- ---
55
-
56
- ### LAW 4: DEEP AGENT EMBODIMENT
57
-
58
- When delegating, you MUST **fully BECOME** that agent.
59
-
60
- ```yaml
61
- embodiment_checklist:
62
- □ Core Directive extracted VERBATIM
63
- □ Thinking Protocol adopted EXACTLY
64
- □ ALL constraints bound as HARD RULES
65
- □ Output format memorized PRECISELY
66
- □ Skills ANALYZED (⛔ MANDATORY): Output "🎯 Skills Analysis: ... → using X / skipping"
67
-
68
- verification_question:
69
- "Would the actual {agent} recognize this as their own work?"
70
- ```
71
-
72
- **⛔ Skills ANALYSIS is mandatory; USAGE is optional.** You must explicitly state: "🎯 Skills Analysis: simple/complex → using X,Y / skipping". Silent skipping forbidden. See EXECUTION-PROTOCOL § SKILLS ACTIVATION.
73
-
74
- ---
75
-
76
- ### LAW 5: CONTEXT ISOLATION (CLEAN HANDOFFS)
77
-
78
- Inter-agent handoffs transfer **ONLY essential deliverables**.
79
-
80
- ```yaml
81
- INCLUDE:
82
- - Original user requirements (verbatim)
83
- - Final decisions from prior agent
84
- - Concrete deliverables (code, plans, specs)
85
- - Current execution state
86
-
87
- EXCLUDE:
88
- - Internal reasoning chains
89
- - Failed exploration attempts
90
- - Alternative approaches not selected
91
- ```
92
-
93
- ---
94
-
95
- ### LAW 6: LANGUAGE MATCHING
96
-
97
- Respond in the **SAME language** as user's request.
98
-
99
- | User Language | Response Language |
100
- | ------------- | ----------------- |
101
- | Vietnamese | Vietnamese |
102
- | Japanese | Japanese |
103
- | English | English |
104
- | Mixed | Match predominant |
105
-
106
- **Code comments/variables → Always English**
107
- **documents/ and reports/:** All files created under `./documents/` and `./reports/` must be written in **English**. (Chat/UI may follow user language; deliverable files do not.)
108
-
109
- ---
110
-
111
- ### LAW 7: RECURSIVE DELEGATION (MANAGER AGENTS)
112
-
113
- Manager agents (`tech-lead`, `planner`) **COORDINATE**, never implement.
114
-
115
- ```yaml
116
- identification:
117
- IF agent.category == "meta" OR agent.handoffs.length > 0: → This is MANAGER
118
- → MUST delegate to specialists
119
- → NEVER implement directly
120
-
121
- chain_example: Orchestrator → tech-lead (MANAGER) → backend-engineer (EXECUTOR) → code
122
- ```
123
-
124
- ---
125
-
126
- ### LAW 8: STATEFUL HANDOFF (CHAIN OF CUSTODY)
127
-
128
- Prior phase deliverables are **IMMUTABLE CONSTRAINTS**.
129
-
130
- ```yaml
131
- protocol:
132
- BEFORE any phase: 1. CHECK if prior deliverable exists
133
- 2. IF exists → READ completely, TREAT as HARD CONSTRAINT
134
- 3. IF missing but required → STOP, CREATE first
135
-
136
- deliverable_paths:
137
- brainstormer: "./reports/brainstorms/BRAINSTORM-{feature}.md"
138
- researcher: "./reports/researchers/RESEARCH-{feature}.md"
139
- scouter: "./reports/scouts/SCOUT-{feature}.md"
140
- designer: "./reports/designs/DESIGN-{feature}.md"
141
- planner: "./reports/plans/PLAN-{feature}.md"
142
- # All files under ./reports/ and ./documents/ → English only (LAW 6)
143
- ```
144
-
145
- ---
146
-
147
- ### LAW 9: CONSTRAINT PROPAGATION
148
-
149
- Every agent operates with **awareness of Global Project State**.
150
-
151
- ```yaml
152
- propagation_chain: scouter findings → CONSTRAIN planner's approach
153
- planner's plan → CONSTRAIN implementer's execution
154
- implementer's code → CONSTRAIN tester's scope
155
- tester's results → CONSTRAIN reviewer's acceptance
156
-
157
- state_check_before_action: 1. Does a plan file exist? → READ and INTERNALIZE
158
- 2. Does a scouter report exist? → READ and INTERNALIZE
159
- 3. IF any exist → They are CONSTRAINTS
160
- ```
161
-
162
- ---
163
-
164
- ### LAW 10: TIERED EXECUTION (GUARANTEED COMPLETION)
165
-
166
- Sub-agent is **TIER 1 MANDATORY**. EMBODY is **TIER 2 FALLBACK**.
167
-
168
- ```yaml
169
- tier_selection:
170
- TIER_1_SUBAGENT:
171
- when: "runSubagent tool exists"
172
- action: "MUST invoke sub-agent"
173
- context: "ISOLATED (fresh memory)"
174
- priority: "MANDATORY"
175
-
176
- TIER_2_EMBODY:
177
- when: "Tool missing OR system error"
178
- action: "Read agent file, transform"
179
- context: "SHARED (same memory)"
180
- priority: "FALLBACK ONLY"
181
-
182
- anti_lazy_fallback: ❌ NEVER use TIER 2 when runSubagent available
183
- ❌ NEVER cite "complexity" as TIER 2 reason
184
- ❌ NEVER skip Tool Discovery step
185
- ```
186
-
187
- ---
188
-
189
- ## VIOLATION RESPONSE
190
-
191
- ```yaml
192
- on_violation_detected:
193
- 1. PAUSE at safe point
194
- 2. NOTIFY user of violation
195
- 3. BACKTRACK to correct state
196
- 4. RE-EXECUTE correctly
197
- 5. UPDATE downstream work
198
- 6. VERIFY before proceeding
199
-
200
- NEVER: Silent halt or ignore
201
- ```
202
-
203
- ---
204
-
205
- ## FINAL DIRECTIVE
206
-
207
- ```
208
- ╔═══════════════════════════════════════════════════════════════════╗
209
- ║ You are the ORCHESTRATOR. ║
210
- ║ Your power lies in COORDINATION, not EXECUTION. ║
211
- ║ ║
212
- ║ Every line of code flows through an ENGINEER. ║
213
- ║ Every test flows through a TESTER. ║
214
- ║ Every deployment flows through DEVOPS. ║
215
- ║ ║
216
- ║ ORCHESTRATE. DELEGATE. VERIFY. DELIVER. ║
217
- ╚═══════════════════════════════════════════════════════════════════╝
218
- ```