@chrono-meta/fh-gate 1.1.0 → 1.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 (69) hide show
  1. package/.claude/agents/challenger.md +169 -0
  2. package/AGENTS.md +160 -0
  3. package/CATALOG.md +256 -0
  4. package/CHEATSHEET.md +367 -0
  5. package/CLAUDE.md +331 -0
  6. package/CONTRIBUTING.md +198 -0
  7. package/LICENSE +21 -0
  8. package/README.md +60 -7
  9. package/bin/fh-goal.js +9 -0
  10. package/bin/fh-run.js +9 -0
  11. package/docs/banner.png +0 -0
  12. package/docs/codex-compat.md +123 -0
  13. package/docs/pillars.svg +70 -0
  14. package/knowledge/shared/harness-core/fh_integration_contract.md +45 -28
  15. package/package.json +31 -6
  16. package/plugins/fh-commons/README.md +37 -0
  17. package/plugins/fh-commons/agents/quench-challenger.md +373 -0
  18. package/plugins/fh-commons/skills/convergence-loop/SKILL.md +155 -0
  19. package/plugins/fh-commons/skills/deliberation/SKILL.md +288 -0
  20. package/plugins/fh-commons/skills/mcp-circuit-breaker/SKILL.md +196 -0
  21. package/plugins/fh-commons/skills/token-budget-gate/SKILL.md +175 -0
  22. package/plugins/fh-meta/agents/fact-checker.md +121 -0
  23. package/plugins/fh-meta/agents/hub-persona-auditor.md +109 -0
  24. package/plugins/fh-meta/agents/persona-innovator.md +195 -0
  25. package/plugins/fh-meta/skills/agent-composer/SKILL.md +461 -0
  26. package/plugins/fh-meta/skills/agent-composer/SKILL_detail.md +464 -0
  27. package/plugins/fh-meta/skills/apex-review/SKILL.md +185 -0
  28. package/plugins/fh-meta/skills/asset-placement-gate/SKILL.md +135 -0
  29. package/plugins/fh-meta/skills/contention-layer/SKILL.md +127 -0
  30. package/plugins/fh-meta/skills/context-bridge-dispatch/SKILL.md +30 -0
  31. package/plugins/fh-meta/skills/context-bridge-dispatch/SKILL_detail.md +144 -0
  32. package/plugins/fh-meta/skills/context-doctor/SKILL.md +341 -0
  33. package/plugins/fh-meta/skills/cross-ecosystem-synergy-detection/SKILL.md +202 -0
  34. package/plugins/fh-meta/skills/deep-clarify/SKILL.md +144 -0
  35. package/plugins/fh-meta/skills/edit-manifest/SKILL.md +210 -0
  36. package/plugins/fh-meta/skills/field-harvest/SKILL.md +384 -0
  37. package/plugins/fh-meta/skills/frontier-digest/SKILL.md +272 -0
  38. package/plugins/fh-meta/skills/goal-quench/SKILL.md +509 -0
  39. package/plugins/fh-meta/skills/harness-doctor/SKILL.md +277 -0
  40. package/plugins/fh-meta/skills/harness-doctor/SKILL_detail.md +484 -0
  41. package/plugins/fh-meta/skills/harvest-loop/SKILL.md +231 -0
  42. package/plugins/fh-meta/skills/harvest-loop/SKILL_detail.md +201 -0
  43. package/plugins/fh-meta/skills/hub-cc-pr-reviewer/SKILL.md +129 -0
  44. package/plugins/fh-meta/skills/hub-cc-pr-reviewer/SKILL_detail.md +158 -0
  45. package/plugins/fh-meta/skills/install-doctor/SKILL.md +207 -0
  46. package/plugins/fh-meta/skills/install-wizard/SKILL.md +613 -0
  47. package/plugins/fh-meta/skills/marketplace-gate/SKILL.md +193 -0
  48. package/plugins/fh-meta/skills/memory-hygiene/SKILL.md +143 -0
  49. package/plugins/fh-meta/skills/meta-prompt-builder/SKILL.md +167 -0
  50. package/plugins/fh-meta/skills/meta-prompt-builder/SKILL_detail.md +37 -0
  51. package/plugins/fh-meta/skills/pipeline-conductor/SKILL.md +430 -0
  52. package/plugins/fh-meta/skills/plugin-recommender/SKILL.md +221 -0
  53. package/plugins/fh-meta/skills/plugin-recommender/SKILL_detail.md +220 -0
  54. package/plugins/fh-meta/skills/prompt-regression/SKILL.md +178 -0
  55. package/plugins/fh-meta/skills/public-surface-audit/SKILL.md +224 -0
  56. package/plugins/fh-meta/skills/return-path-gate/SKILL.md +257 -0
  57. package/plugins/fh-meta/skills/self-marketing-lint/SKILL.md +129 -0
  58. package/plugins/fh-meta/skills/sim-conductor/SKILL.md +364 -0
  59. package/plugins/fh-meta/skills/sim-conductor/SKILL_detail.md +337 -0
  60. package/plugins/fh-meta/skills/skill-splitter/SKILL.md +126 -0
  61. package/plugins/fh-meta/skills/skill-splitter/SKILL_detail.md +185 -0
  62. package/plugins/fh-meta/skills/source-grounding-audit/SKILL.md +230 -0
  63. package/plugins/fh-meta/skills/source-grounding-audit/SKILL_detail.md +182 -0
  64. package/plugins/fh-meta/skills/steel-quench/SKILL.md +226 -0
  65. package/plugins/fh-meta/skills/steel-quench/SKILL_detail.md +453 -0
  66. package/plugins/fh-meta/skills/verify-bidirectional/SKILL.md +238 -0
  67. package/scripts/fh-gate.sh +175 -40
  68. package/scripts/fh-goal.sh +182 -0
  69. package/scripts/fh-run.sh +269 -0
@@ -0,0 +1,464 @@
1
+ ---
2
+ name: agent-composer-detail
3
+ description: Detail file for agent-composer — format templates, bash scripts, edge cases. Load when executing a specific step.
4
+ load: on-demand
5
+ ---
6
+
7
+ # agent-composer — Detail Reference
8
+
9
+ > Load when executing a specific step. SKILL.md contains triggers, principles, mapping tables, and Done When.
10
+
11
+ ---
12
+
13
+ ## §Step-0 — NL Pattern Parsing + Cross-Install + Registry Lookup
14
+
15
+ ### Natural Language Pattern Parsing
16
+
17
+ | Natural language pattern | Mapped agent | Rationale |
18
+ |---|---|---|
19
+ | "report", "persuade", "review", "approval", "team lead", "executive", "CTO" | apex-review | Decision-maker simulation |
20
+ | "install skill", "install plugin", "setup" | install-wizard / plugin-recommender | Onboarding |
21
+ | "code review", "PR review", "check diff" | sim-conductor (D-code) | Code validation |
22
+ | "diagnose", "something feels off", "structural check" | harness-doctor | Structural diagnosis |
23
+ | "simulation", "scenario", "validate" | sim-conductor | Meta-simulation |
24
+ | "let's name it", "naming", "new frame" | persona-innovator | Naming exploration |
25
+
26
+ Mapping results merged with Step 1 composition table into final dispatch plan.
27
+
28
+ ### cross-install Detection
29
+
30
+ If external plugin installed (check `.mcp.json` or `CLAUDE.md`), include that plugin's skill triggers in mapping.
31
+ - `deep-insight` installed → include for "multi-perspective review"
32
+ - `glossary` from `fe-marketplace` → include for "define terms"
33
+ - Mark "(external plugin included)" at top of Step 2 composition plan.
34
+
35
+ ### LOCAL_SKILL_REGISTRY Lookup
36
+
37
+ ```
38
+ LOCAL_SKILL_REGISTRY lookup → extract skill list for relevant project
39
+ → "inline capable": directly dispatchable via Agent tool
40
+ → "requires cwd": must specify cwd path in agent brief
41
+ ```
42
+
43
+ Mark "(local skills included)" in Step 2 composition plan. Location: `.claude/registry/LOCAL_SKILL_REGISTRY.md`.
44
+
45
+ ---
46
+
47
+ ## §Clarification — Formats + Meta-Prompting Intervention
48
+
49
+ ### Clarification Format (maximum 2 questions)
50
+
51
+ When direction ambiguity detected:
52
+
53
+ ```
54
+ Direction clarification needed.
55
+ 1. Completion criteria: What does [X] look like when it's done?
56
+ (Inference: [inferred criteria] — confirm if correct)
57
+ 2. Scope: Which of [A / B / C] should take priority?
58
+ ```
59
+
60
+ Rules: Maximum 2 questions. Present inferable items as `(Inference: [X] — confirm if correct)`. Minimize choices.
61
+
62
+ ### 4-Question Structured Confirmation
63
+
64
+ Use only for "completely new tasks" / "full cross-project scope unclear" / "request under 1 sentence":
65
+
66
+ ```
67
+ Structured confirmation needed before composition.
68
+ 1. What is the final state you want to achieve with this task?
69
+ 2. Describe the completion criteria in one sentence.
70
+ 3. Is there anything that must absolutely not be done?
71
+ 4. Is there a time estimate or deadline?
72
+ ```
73
+
74
+ Proceed with composition plan after receiving all 4 answers.
75
+
76
+ ### Meta-Prompting Intervention (over-specified prompt detection)
77
+
78
+ **Detection signals**: Numbered step-by-step instructions · Excessive path/method/filename specification · "Do it like this: [detailed procedure]" pattern.
79
+
80
+ **Why it's a problem**: Over-specification removes the AI's reasoning space and lowers quality.
81
+
82
+ **Intervention format**:
83
+
84
+ ```
85
+ Meta-prompting recommended.
86
+ Current: [summary of procedural spec]
87
+ Suggestion:
88
+ Goal: [core objective in 1 line]
89
+ Done When: [completed state]
90
+ Constraints: [real constraints only — remove method specs]
91
+
92
+ Optimize with meta-prompt-builder? (Y: switch to meta version / N: proceed as-is)
93
+ ```
94
+
95
+ User selects N → allow execution as originally specified (respect user decision).
96
+ **Simplification guard**: Skip for single-file edits or clearly-stated fix requests.
97
+
98
+ ---
99
+
100
+ ## §Wave-0 — Self-Contained Brief + Deferred ToolSearch
101
+
102
+ ### Self-Contained Brief Requirement
103
+
104
+ Each agent brief does not assume shared context. Required contents:
105
+ - Goal (1-2 lines of clear task description)
106
+ - Target files/paths (absolute paths or clear criteria)
107
+ - Expected output format
108
+ - When using deferred tools: explicitly state `ToolSearch query "select:tool_name"` must be run first
109
+
110
+ ### Deferred ToolSearch Pre-Requisite
111
+
112
+ In Agent View environments, MCP tools (JIRA, Wiki, Slack) are loaded in **deferred** state. Always specify:
113
+
114
+ ```
115
+ First call the ToolSearch tool to load the required tool schema:
116
+ ToolSearch query "select:jira_search_issues"
117
+ Call the tool only after the schema is loaded.
118
+ ```
119
+
120
+ Omitting this causes `InputValidationError`.
121
+
122
+ ### Wave 0 Composition Criteria
123
+
124
+ - File/directory structure understanding → 1 recon agent (Read · Glob · Bash)
125
+ - Multiple project status check → independent recon agents per project, in parallel
126
+ - Single file read → allowed exception for direct execution (recon overhead > benefit)
127
+ - All tasks with new assets → mandatory fact-checker (A) in Wave 0
128
+
129
+ ---
130
+
131
+ ## §Model-Routing — Escalation Conditions + Default Architecture
132
+
133
+ ### Escalation Condition Evaluation
134
+
135
+ | Condition | Evaluation criteria |
136
+ |---|---|
137
+ | `cold_start` | First run after session start / MEMORY.md not loaded / no prior context |
138
+ | `cross_project` | Cross-cutting work across 3+ projects (tracks) |
139
+ | `adversarial` | steel-quench/devil/meta-devil mode active |
140
+ | `high_stakes` | Pre-external publish/deploy/PR merge/team presentation validation |
141
+ | `full_revalidation` | User requests "full re-review" or "start over" |
142
+ | `destructive` | Contains irreversible operations (push/force/delete/deploy/permission changes) |
143
+
144
+ ### Amplified Mode Audit Log
145
+
146
+ ```
147
+ [Model routing] orchestrator: opus (amplified — EXECUTION_TIER: full), executors: sonnet
148
+ ```
149
+
150
+ ---
151
+
152
+ ## §Worktree-Isolation — Step 3.1 Parallel Proposal Mode
153
+
154
+ **Activation condition**: 2+ agents in same Wave targeting overlapping file paths, each producing independent candidate outputs.
155
+
156
+ **Execution pattern**:
157
+
158
+ ```
159
+ 1. Before dispatch: create isolated worktree per agent
160
+ EnterWorktree(branch="proposal/{agent-name}-{slug}")
161
+ → each agent operates on its own branch, no shared file state
162
+
163
+ 2. After Wave completes: fan-in from each worktree
164
+ → compare outputs across branches
165
+ → winning proposal cherry-picked or merged to main branch
166
+ → losing worktrees discarded (auto-cleaned if unchanged)
167
+
168
+ 3. Composition plan output adds worktree marker:
169
+ [A] {agent name} — {role} [worktree: proposal/A-{slug}]
170
+ [B] {agent name} — {role} [worktree: proposal/B-{slug}]
171
+ ```
172
+
173
+ **Tool prerequisite**: Check with `ToolSearch query "select:EnterWorktree"` before dispatching.
174
+ **When to skip**: Read-only agents (recon, fact-checker), single-agent Waves, agents targeting disjoint files.
175
+
176
+ ---
177
+
178
+ ## §Wave-Adaptation — Adaptation Check Output Format
179
+
180
+ ```
181
+ [Step 3.5 — Wave Adaptation Check]
182
+ ① Premise reversal: {none / detected → Wave N+1 revision}
183
+ ② Repeated failure: {none / {agent name} failed 2x → alternative: {replacement skill}}
184
+ ③ Early-harvest: {none / {N} patterns detected → mini-harvest suggested}
185
+
186
+ → Wave N+1 revision exists: (Y: apply revision and proceed / E: revise manually / N: proceed as planned)
187
+ ```
188
+
189
+ "Runtime self-modification" FH implementation: Wave = FH execution unit; Wave-level strategy revision = functionally equivalent to runtime self-modification.
190
+
191
+ ---
192
+
193
+ ## §fan-in-Contract — loom Fan-in Contract Detail
194
+
195
+ Each finding returned by an agent must satisfy 3-field format as minimum unit. Results not meeting this format cannot enter Wave 4 judgment — mark "format non-compliant" and re-request or skip.
196
+
197
+ ```
198
+ | tier | location | fix suggestion |
199
+ |------|----------|----------------|
200
+ | M | plugins/fh-meta/skills/foo/SKILL.md:12 | change "bar" to "baz" |
201
+ | S | CLAUDE.md:L45 section | description needs strengthening |
202
+ ```
203
+
204
+ - **tier**: One of M / S / R (required)
205
+ - **location**: File path + line or section (required)
206
+ - **fix suggestion**: Specific action in 1 line (required)
207
+ - 1 finding = 1 row. Separate multiple fixes into individual rows.
208
+
209
+ ---
210
+
211
+ ## §Auto-Recording — Wave Execution Recording Format + Lightweight Mode
212
+
213
+ ### Wave Execution Recording Format
214
+
215
+ Auto-record in `tracks/_meta/agent_run_YYYYMMDD_{slug}.md` each time Wave 1+ completes:
216
+
217
+ ```markdown
218
+ ---
219
+ date: YYYY-MM-DD
220
+ wave_count: N
221
+ slug: {task summary slug}
222
+ ---
223
+
224
+ ## Wave N — {Wave purpose}
225
+ - Agents executed: {agent name list}
226
+ - Completed at: {HH:MM}
227
+ - Result summary:
228
+ - {agent A}: {1-line result}
229
+ - {agent B}: {1-line result}
230
+ - Failed agents: {none / agent name + failure reason}
231
+ ```
232
+
233
+ Trigger: Always record Wave 1+. Record even if failed. `tracks/_meta/` absent → skip + R-tier warning.
234
+
235
+ ### harvest-loop Lightweight Mode (mid-session)
236
+
237
+ Runs only Steps 1→2→5 of standard harvest-loop. Skip Steps 3/3.5/4.
238
+
239
+ ```
240
+ [mid-session harvest] field-harvest → contention-layer → verify-bidirectional
241
+ Time: ~3 min (50% reduction vs full loop)
242
+ ```
243
+
244
+ ### Human Decision Gate
245
+
246
+ - **Recording content decisions** (what to record / where): Show summary then get confirmation — no auto-save
247
+ - **Naming/direction decisions**: User confirmation required — auto-execution forbidden
248
+ - **Pipeline execution results** (file change lists, M/S/R aggregates): Auto-recording allowed
249
+
250
+ ---
251
+
252
+ ## §Wave4 — Entry Conditions + Judgment Output Format
253
+
254
+ ### Entry Conditions
255
+
256
+ - All stages of Waves 0~3 complete (including state transition output)
257
+ - PR creation or change history exists
258
+
259
+ If not met, auto-skip Wave 4.
260
+
261
+ ### Judgment Output Format
262
+
263
+ ```
264
+ [Wave 4 Judgment] PASS — 0 M-tier, {N} S-tier deferred to backlog
265
+ [Wave 4 Judgment] BLOCK — {N} M-tier remaining, fix and re-validate required
266
+ ```
267
+
268
+ Fixed format: 1 judgment line + 1 rationale line.
269
+
270
+ ### State Transition Output Format
271
+
272
+ ```
273
+ agent-composer — State Transition Evaluation
274
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
275
+ ① M-tier: {N} items → Wave next-M {Y/N}
276
+ ② Naming candidates: {N} items → Wave next-I {Y/N}
277
+ ③ External absorption signals: {N} items → Wave next-E {Y/N}
278
+ ⑤ Design conflicts: {N} items → Wave next-D {Y/N}
279
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
280
+ Run additional Wave? (Y: execute / N: end)
281
+ ```
282
+
283
+ ### Auto-Proposal After Judgment
284
+
285
+ ```
286
+ agent-composer — Wave 4 Final Judgment
287
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
288
+ [Wave 4 Judgment] {PASS / BLOCK}
289
+ Rationale: {1 line}
290
+
291
+ {If PASS} → field-harvest proposal: harvest patterns from this Wave?
292
+ {If BLOCK} → fix M-tier items then re-enter Wave 1.
293
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
294
+ ```
295
+
296
+ ---
297
+
298
+ ## §Round-Wrap — 6-1, 6-2, 6-3 Full Specs
299
+
300
+ ### 6-1. Completion Summary (3 lines)
301
+
302
+ ```
303
+ agent-composer — Round Completion Summary
304
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
305
+ ① {major completed task 1}
306
+ ② {major completed task 2}
307
+ ③ {major completed task 3 or "no issues confirmed"}
308
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
309
+ ```
310
+
311
+ ### 6-2. Next Round Suggestions (maximum 3)
312
+
313
+ ```
314
+ Next round candidates:
315
+ [1] {task name} — {reason in 1 line}
316
+ [2] {task name} — {reason in 1 line}
317
+ [3] {task name} — (omit if none)
318
+
319
+ Select items to continue (Y/N or number): ___
320
+ ```
321
+
322
+ If no clear follow-up tasks → omit suggestion (output "no follow-up tasks").
323
+
324
+ ### 6-3. fh_signal Persistence Confirmation
325
+
326
+ | Condition | Confirmation |
327
+ |---|---|
328
+ | New skill/pattern discovered | Record in `tracks/_meta/fh_signal_YYYYMMDD.md`? |
329
+ | Design decision made (including M-tier resolution) | Persist decision summary as fh_signal? |
330
+ | None | Skip persistence confirmation |
331
+
332
+ ```
333
+ fh_signal persistence: [discovered signal summary in 1 line]
334
+ Record? (Y: save to tracks/_meta/fh_signal_{date}.md / N: skip)
335
+ ```
336
+
337
+ ---
338
+
339
+ ## §CapabilityFit — Capability Fit Scoring Detail
340
+
341
+ ### How to Read Agent Registry Files
342
+
343
+ Agent registry files live in `.claude/agents/*.md`. Each file has a YAML frontmatter block. The fields relevant to capability fit scoring are:
344
+
345
+ | Field | Type | Meaning |
346
+ |---|---|---|
347
+ | `role` | string | Agent's declared functional role (e.g. `"challenger"`, `"fact-checker"`) |
348
+ | `subagent_type` | string | Specialization tag (e.g. `"challenger"`, `"persona"`, `"audit"`) |
349
+ | `allowed_tools` | list | Tools the agent is permitted to call |
350
+ | `writes` | bool | `true` = agent may edit/create files; `false` = read-only |
351
+ | `declared_capabilities` | list | Free-text capability labels (e.g. `["adversarial-review", "phantom-detection"]`) |
352
+
353
+ If `writes` is absent, default to `true` (conservative assumption — treat as potentially destructive).
354
+
355
+ ### Score Calculation Procedure
356
+
357
+ For each `(subtask, agent)` pair, compute `fit_score` (0.0–1.0) as follows:
358
+
359
+ ```
360
+ role_match = 0.40 if subagent_type or role matches subtask_type else 0.0
361
+ tools_overlap = 0.30 × (|required_tools ∩ allowed_tools| / |required_tools|)
362
+ (0.30 if required_tools is empty — tools not constraining)
363
+ writes_compat = 0.20 if writes flag is compatible with subtask write-need else 0.0
364
+ (subtask needs writes=true → agent writes=false → 0.0)
365
+ (subtask audit-only → agent writes=false → 0.20 bonus)
366
+ cap_bonus = 0.10 if any declared_capability keyword matches subtask_type else 0.0
367
+
368
+ fit_score = role_match + tools_overlap + writes_compat + cap_bonus
369
+ ```
370
+
371
+ Threshold: `fit_score < 0.5` → GAP. Trigger `/plugin-recommender` for that subtask.
372
+
373
+ ### Worked Examples
374
+
375
+ **Example 1 — Adversarial review subtask**
376
+
377
+ - Subtask type: `adversarial-review`
378
+ - Candidate agent: `quench-challenger` (`subagent_type="challenger"`, `writes=false`, `allowed_tools=["Read","Bash"]`, `declared_capabilities=["adversarial-review","artifact-attack"]`)
379
+
380
+ ```
381
+ role_match = 0.40 (subagent_type="challenger" matches "adversarial-review")
382
+ tools_overlap = 0.30 (Read+Bash sufficient; required_tools overlap = 1.0)
383
+ writes_compat = 0.20 (audit-only subtask, writes=false → bonus)
384
+ cap_bonus = 0.10 (declared_capabilities contains "adversarial-review")
385
+ fit_score = 1.00 → STRONG FIT
386
+ ```
387
+
388
+ **Example 2 — Code generation subtask**
389
+
390
+ - Subtask type: `code-generation`
391
+ - Candidate agent: `hub-persona-auditor` (`subagent_type="persona"`, `writes=false`, `allowed_tools=["Read"]`, `declared_capabilities=["persona-simulation"]`)
392
+
393
+ ```
394
+ role_match = 0.00 (subagent_type="persona" ≠ "code-generation")
395
+ tools_overlap = 0.00 (required_tools=[Edit,Bash]; allowed_tools=[Read] → overlap=0)
396
+ writes_compat = 0.00 (code-generation needs writes=true; agent writes=false)
397
+ cap_bonus = 0.00 (no matching declared_capability)
398
+ fit_score = 0.00 → GAP — do not assign
399
+ ```
400
+
401
+ **Example 3 — Phantom detection subtask**
402
+
403
+ - Subtask type: `phantom-detection`
404
+ - Candidate agent: `source-grounding-audit` skill (`declared_capabilities=["phantom-detection","source-trace"]`, `writes=false`)
405
+
406
+ ```
407
+ role_match = 0.40 (role matches "source-grounding-audit" → "phantom-detection")
408
+ tools_overlap = 0.30 (Read+Bash match; required_tools overlap = 1.0)
409
+ writes_compat = 0.20 (audit-only; writes=false → bonus)
410
+ cap_bonus = 0.10 (declared_capabilities contains "phantom-detection")
411
+ fit_score = 1.00 → STRONG FIT
412
+ ```
413
+
414
+ ### /plugin-recommender Query Format for Agent Discovery
415
+
416
+ When a GAP is detected (fit_score < 0.5 for a required-weight subtask), issue this query:
417
+
418
+ ```
419
+ /plugin-recommender "agent for [subtask_type] in [context]"
420
+
421
+ Examples:
422
+ /plugin-recommender "agent for adversarial-review in FH skill validation"
423
+ /plugin-recommender "agent for code-generation in Python refactor task"
424
+ /plugin-recommender "agent for persona-simulation in external user audit"
425
+ ```
426
+
427
+ Include in the query:
428
+ - The subtask type (from the scoring table)
429
+ - The task context (project type, domain, language if relevant)
430
+
431
+ The recommender searches: FH native agents + Codex marketplace + Claude Code marketplace.
432
+
433
+ **User response options after GAP report**:
434
+ - `install` → follow recommender install steps, then re-run Step 0.2
435
+ - `skip` → remove that subtask from composition plan (document the omission)
436
+ - `use general-purpose fallback` → assign a general-purpose agent AND mark `⚠️ degraded: [role]` in the composition plan
437
+
438
+ ---
439
+
440
+ ## §Identity — Full Agent Composition Layer Explanation
441
+
442
+ ### Automation Layer Division
443
+
444
+ | Human domain | System domain |
445
+ |---|---|
446
+ | What to build, why (direction + insight) | Which agents and how (composition + ordering) |
447
+ | Final adoption decision | Pipeline execution + result aggregation |
448
+ | Naming/framing | Recording + quality gates |
449
+
450
+ ### Brain/Hands Decoupling (Anthropic Independent Convergence)
451
+
452
+ - **Brain**: Goal parsing → skill mapping → Wave construction → gate decisions
453
+ - **Hands**: Agent tool dispatch → parallel execution → result collection → fan-in report
454
+
455
+ Rationale: Anthropic "Scaling Managed Agents" — Brain/Hands separation improves scalability, debugging, maintainability.
456
+
457
+ ### Curator Role (hermes-agent Convergence)
458
+
459
+ agent-composer also acts as Curator — surveys existing agents/skills/assets and proposes optimal combinations.
460
+
461
+ - **Curator mode**: Detects agent state (stale, pinned, deprecated) + proposes merge candidates for duplicate agents
462
+ - **External positioning**: Independent convergence with hermes-agent (Nous Research) curator.py pattern
463
+
464
+ > Architecture basis: Anthropic [Harness Design for Long-Running Apps](https://www.anthropic.com/engineering/harness-design-long-running-apps) — single agent ($9, fails) vs. multi-agent harness ($200, perfect). Cost gap justified by quality gap.
@@ -0,0 +1,185 @@
1
+ ---
2
+ name: apex-review
3
+ description: Reviews a technical proposal from the perspective of organizational decision-makers (CTO, technical lead, QA lead, conference reviewers, etc.) and generates an HTML presentation deck. Outputs approval gate results per persona and connects to sim-conductor for improvement suggestions.
4
+ user-invocable: true
5
+ allowed-tools: ["Read", "Write", "Bash", "Agent"]
6
+ model: opus
7
+ ---
8
+
9
+ # apex-review — Decision-Maker Review Layer
10
+
11
+ > Reviews proposals from the perspective of **top-level organizational decision-makers**, not field practitioners.
12
+ > Technically excellent and "this person will approve it" are different things.
13
+
14
+ **Role distinction from hub-persona-auditor**
15
+ - hub-persona-auditor: Validates **reader comprehension** of a finished asset (reading experience)
16
+ - apex-review: Evaluates **decision-maker approval likelihood** of a technical proposal (decision-making experience)
17
+
18
+ ---
19
+
20
+ ## Triggers
21
+
22
+ - `/apex-review`
23
+ - "Will this work for the decision-maker?", "Will the CTO approve this?", "What do I need to present to the team lead?"
24
+ - "Review from an executive perspective", "Generate presentation slides" (when decision-maker audience is specified)
25
+ - When agent-composer identifies a task requiring a decision-maker approval gate
26
+ - "Check this before I report to my manager"
27
+ - "Does this look convincing?"
28
+ - "Find objections they might raise in advance"
29
+ - "Review before the executive briefing"
30
+ - "Do you think this will pass?"
31
+
32
+ ---
33
+
34
+ ## Built-in Decision-Maker Personas
35
+
36
+ | Code | Role | Core Evaluation Criteria | Auto-Reject Triggers |
37
+ |:---:|---|---|---|
38
+ | `CTO` | Chief Technology Officer | Strategic alignment · competitive advantage · tech vision | "Everyone else is already doing this" / "Feels like a personal project" |
39
+ | `TD` | Technical Lead / Team Lead | Implementation risk · team capability · operational burden · cost | Vague timelines / conflicts with existing stack |
40
+ | `QAL` | QA Lead / Quality Owner | Quality standards · testability · rollback plan · compliance | No validation plan / failure scenarios not documented |
41
+ | `CONF` | Conference Organizer / External Reviewer | Novelty · demo-readiness · audience value · reproducibility | Overloaded with internal jargon / demo not possible |
42
+
43
+ If the user does not specify a target persona, it will be confirmed in Step 0.
44
+
45
+ ---
46
+
47
+ ## Step 0. Receive Topic + Target
48
+
49
+ If no input is provided:
50
+
51
+ ```
52
+ Please provide the apex-review target.
53
+
54
+ Proposal summary: (What are you seeking approval for?)
55
+ Target decision-maker: [CTO / TD (Technical Lead) / QAL (QA Lead) / CONF (Conference)] — multiple allowed
56
+ Proposal file: (provide path or paste content if available)
57
+ Output format: [HTML presentation deck (recommended) / Markdown report]
58
+ ```
59
+
60
+ If no proposal file is provided, collect content through conversation.
61
+
62
+ ---
63
+
64
+ ## Step 1. Structure the Proposal
65
+
66
+ Organize the received content into the following slide structure.
67
+
68
+ ```
69
+ [S1] One-line thesis — "What needs to be done and why"
70
+ [S2] Current state / problem — What is not working right now
71
+ [S3] Proposal — What changes and how
72
+ [S4] Expected outcomes — Quantified or verifiable change
73
+ [S5] Implementation plan — Phases, timeline, ownership
74
+ [S6] Risks + mitigations — Failure scenarios + rollback
75
+ [S7] Requests — What is needed from the decision-maker
76
+ ```
77
+
78
+ If any slide is missing during structuring, request the user to fill it in.
79
+
80
+ ---
81
+
82
+ ## Step 2. Generate HTML Presentation Deck
83
+
84
+ Generate as `apex_review_deck_YYYYMMDD.html`.
85
+
86
+ HTML structure rules:
87
+ - Each slide = `<section class="slide">` block
88
+ - Per slide: title + body + (if applicable) decision-maker attention note
89
+ - Navigation: keyboard ←→ or buttons
90
+ - Style: clean dark background / large headlines / emphasized key figures
91
+
92
+ ```html
93
+ <!-- Slide example -->
94
+ <section class="slide">
95
+ <h2>Current State · Problem</h2>
96
+ <p class="body">…</p>
97
+ <aside class="exec-note CTO">CTO attention: …</aside>
98
+ </section>
99
+ ```
100
+
101
+ Notify the user of the file path after saving.
102
+
103
+ ---
104
+
105
+ ## Step 3. Persona Review
106
+
107
+ Evaluate the proposal for each target decision-maker.
108
+
109
+ Output format:
110
+
111
+ ```
112
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
113
+ apex-review — Decision-Maker Review Results
114
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
115
+
116
+ [CTO Review]
117
+ Verdict: ✅ Approved / ⚠️ Conditional / ❌ Rejected
118
+ Rationale: …
119
+ Conditions (if conditional): …
120
+ Critical weaknesses: …
121
+
122
+ [TD Review]
123
+ Verdict: …
124
+
125
+ ```
126
+
127
+ ---
128
+
129
+ ## Step 4. Approval Gate
130
+
131
+ **All ✅ Approved**: Gate passed → proceed to Step 5
132
+ **1+ ⚠️ Conditional**: Output condition list → request user decision
133
+ **1+ ❌ Rejected**: Output rejection rationale + improvement directions → suggest revision and re-review
134
+
135
+ After gate verdict:
136
+
137
+ ```
138
+ Gate result: {Passed / Conditionally passed / Rejected}
139
+
140
+ Choose your next step:
141
+ A. Revise and re-review
142
+ B. Proceed to sim-conductor in current state (deep validation)
143
+ ← strongly recommended when verdict is "Conditionally passed"
144
+ C. Use HTML deck only (as reference)
145
+ D. Exit
146
+ ```
147
+
148
+ > **"Conditionally passed" → option B is the default path**: Conditions listed by personas remain unresolved until sim-conductor Area E runs devil/newcomer/power-user validation against them. Choosing C or D without sim-conductor leaves those conditions unverified — present B as the default choice and require explicit opt-out.
149
+
150
+ ---
151
+
152
+ ## Step 5. Deep Validation (Optional)
153
+
154
+ When option B is selected:
155
+
156
+ ```
157
+ Connect to sim-conductor Area E.
158
+ Target: apex_review_deck_YYYYMMDD.html
159
+ Evaluation criteria: Decision-maker perspective (CTO / TD / QAL / CONF personas)
160
+ Output: Improvement recommendations by M/S/R tier
161
+ ```
162
+
163
+ Incorporate sim-conductor results into the HTML deck and save the revised version.
164
+
165
+ ---
166
+
167
+ ## Operating Notes
168
+
169
+ - **Invocable without input**: Content collected through conversation in Step 0
170
+ - **Customizable personas**: If the user specifies "our executives prioritize X", it will be reflected
171
+ - **Iterative review**: After revision, re-run from Step 3 (HTML decks distinguished by version date)
172
+ - **Standalone or within agent-composer**: In complex tasks, agent-composer will automatically include this skill
173
+
174
+ ## Done When
175
+
176
+ ```
177
+ All steps 0–4 completed
178
+ + Verdict (✅/⚠️/❌) output for all target decision-makers
179
+ + Gate verdict (Passed / Conditionally passed / Rejected) stated
180
+ + User next step selection (A/B/C/D) confirmed
181
+ ```
182
+
183
+ **→ Mandatory next (Conditionally passed verdict): `/sim-conductor Area E`** — run against `apex_review_deck_YYYYMMDD.html` before the proposal is considered ready for submission. Skipping sim-conductor on a conditional pass means unresolved persona conditions go unverified; present option B as default and require the user to explicitly choose A/C/D to override.
184
+
185
+ Wait for sim-conductor Area E verdict before declaring the proposal submission-ready. (Conditionally passed path: proposal is not done until sim-conductor verdict folds back.)