SpeedyFoxAi/hermes-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ask-claude v2.6.1, ask-hermes v4.2.0, ask-dev v1.1.0, create-plan v1.1.0

Browse Source 
- ask-claude v2.4.0 -> v2.6.1: Added mandatory disagreement scan (Step 3.5) with web-reference demand + internal consistency check. Updated callouts for the paste-vs-path rule (now HARD RULE, not just example).
- ask-hermes v4.1.1 -> v4.2.0: Added mandatory disagreement scan mirroring ask-claude.
- ask-dev v1.0.0 -> v1.1.0: Added mandatory disagreement scan mirroring ask-claude.
- create-plan v1.1.0 (new): Multi-agent plan-build dispatcher. Trigger phrases, 10-Q brief script (min as needed, max 10), curator dispatch, capture/handoff format, all 6 failure modes. Companion references: curator-framing-prompt.md, deep-research-dispatch-template.md, ask-claude-validation-template.md, structured-brief-10q.md.

5 rounds of Claude validation on the design plan; final SHIP from ask-hermes peer review.
This commit is contained in:
Hermes Agent
2026-07-06 12:51:02 -05:00
parent c6d6db699c
commit 1533a6e8c3
12 changed files with 1775 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
create-plan/references/ask-claude-validation-template.md Normal file
View File

@@ -0,0 +1,234 @@
# Ask-Claude Validation Template — `create-plan` Phase 4
> **This is the exact prompt + dispatch script the curator uses in Phase 4 to run the adversarial evidence-diff against `<topic>_plan.md` v2.** The curator fills in `<PLAN_BODY>` (full plan) and `<RESEARCH_CLAIMS_EXTRACT>` (~10KB cap) and dispatches to Claude Opus on 10.0.0.28. Output: a release-blockers / medium / low validation report. The curator applies agreed findings in Phase 6 — Claude does NOT rewrite the plan.
---
## 1. The Prompt (the exact text shipped to Claude)
The curator assembles this string, then writes it to a temp file (scp pattern — never inline in the SSH command; shell metacharacters in the plan body will break):
```
==== PLAN BEGINS ====
<PLAN_BODY>
==== PLAN ENDS ====
==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ====
<RESEARCH_CLAIMS_EXTRACT>
==== RESEARCH CLAIMS EXTRACT ENDS ====
You are reviewing an evidence-diff for a software plan. Below is:
1. The plan in full.
2. An extract of the structured claims, version numbers, official-URL
citations, and key code/config snippets from the research evidence.
CRITICAL CONSTRAINT: Do NOT propose new features, new architecture, or new complexity.
Your job is to find FLAWS in what's already proposed — not to add more. If you find
a problem, say what's wrong and suggest the SIMPLEST fix.
YOUR JOB IS AN EVIDENCE-DIFF, NOT A VIBE CHECK.
For each claim the plan makes, check whether the provided research extract supports it.
For each claim in the provided research extract, check whether the plan addresses it.
Specifically report:
- Plan assertions that the research extract does NOT support (hallucinated claims)
- Major research extract findings the plan OMITS (silent gaps)
- Internal contradictions in the plan
- Missing TDD discipline (failing test before code-producing task?)
- Tasks larger than 2-5 minutes of focused work
- Missing official doc citations for tools the plan uses
Report format:
- Release-blockers (must fix)
- Medium (should fix)
- Low (nice to have)
- Pass-criteria met / not met
Do not rewrite the plan. Just report findings.
```
### 1.1 Note on Claude's capabilities / scope
Claude (Opus on 10.0.0.28) has **no web access** and cannot read the curator's local filesystem. Do NOT ask Claude to verify URL currency or file existence — those are the curator's job in Phase 5. Claude's job here is purely a structured text-vs-text diff against the inlined payloads.
### 1.2 Why "2-3 concrete suggestions" from the upstream pattern is dropped
The upstream `ask-claude` plan-validation prompt ends with "give 2-3 concrete suggestions for how to make this plan better." That suggestion-generating mode is **incompatible** with our CRITICAL CONSTRAINT (no new features, no new architecture, no new complexity). Suggestions would either be empty (waste of Claude's pass) or contradict the constraint. The template is deliberately narrower than the upstream pattern: pure flaw-finding, no improvement generation. If the operator wants improvement suggestions, that's a separate dispatch, not this validation pass.
### 1.3 Payload delimiters (must be present, exactly)
| Delimiter | Purpose |
|---|---|
| `==== PLAN BEGINS ====` ... `==== PLAN ENDS ====` | Wraps the full `<topic>_plan.md` v2. |
| `==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ====` ... `==== RESEARCH CLAIMS EXTRACT ENDS ====` | Wraps the extracted claims/citations section. |
The framing text and validation instructions follow BOTH delimiters (not inside the plan or research payload). Claude reads the instructions last and knows the markers are structural, not part of the text being reviewed.
---
## 2. The Research Payload — Size Discipline (MANDATORY)
The curator reads `<topic>_research.md` from disk and extracts **only the structured-claims/citations section**, not the full document. Inline that extract, not the full research.md.
**Extract these sections from `<topic>_research.md`:**
- Key Findings (claim + source URL pairs)
- Version Numbers & Currency Notes
- Official Documentation Citations
- Key Code / Config Snippets (verbatim — do not paraphrase)
- Conflicts / Open Questions
**Skip these sections:**
- The narrative Summary (Claude cannot verify prose; the curator's self-review, Phase 3, already covered it)
- Any other long-form discussion paragraphs
**Cap the inlined research payload at ~10KB.** Claude's context is not free, and a 50KB research.md will burn tokens on prose Claude cannot meaningfully diff against the plan anyway. The full research.md remains on disk for the curator's reference.
**Accepted trade-off:** Claude cannot detect findings in the research that live outside the extracted claims/citations (long prose paragraphs, narrative context, exploratory tangents). This is a known limitation, not a bug. The structured-claims extract is the load-bearing evidence; the curator's self-review (Phase 3) is the safety net for the rest. Document this trade-off in the final plan header so future readers know what Claude actually saw.
---
## 3. The Dispatch Script (parameterized, ready to run)
```bash
# 1. Build the prompt (see §1 for the full template)
PROMPT="==== PLAN BEGINS ====
$(cat <topic>_plan.md)
==== PLAN ENDS ====
==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ====
$(cat <research_claims_extract.md>)
==== RESEARCH CLAIMS EXTRACT ENDS ====
You are reviewing an evidence-diff for a software plan. Below is:
1. The plan in full.
2. An extract of the structured claims, version numbers, official-URL
citations, and key code/config snippets from the research evidence.
CRITICAL CONSTRAINT: Do NOT propose new features, new architecture, or new complexity.
Your job is to find FLAWS in what's already proposed — not to add more. If you find
a problem, say what's wrong and suggest the SIMPLEST fix.
YOUR JOB IS AN EVIDENCE-DIFF, NOT A VIBE CHECK.
For each claim the plan makes, check whether the provided research extract supports it.
For each claim in the provided research extract, check whether the plan addresses it.
Specifically report:
- Plan assertions that the research extract does NOT support (hallucinated claims)
- Major research extract findings the plan OMITS (silent gaps)
- Internal contradictions in the plan
- Missing TDD discipline (failing test before code-producing task?)
- Tasks larger than 2-5 minutes of focused work
- Missing official doc citations for tools the plan uses
Report format:
- Release-blockers (must fix)
- Medium (should fix)
- Low (nice to have)
- Pass-criteria met / not met
Do not rewrite the plan. Just report findings."
# 2. Write locally → scp to remote → run via ask.sh (file-based, no shell escaping)
echo "$PROMPT" > /tmp/curator-claude-prompt.txt
scp -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 /tmp/curator-claude-prompt.txt n8n@10.0.0.28:/tmp/curator-claude-prompt.txt
RESP=$(ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 n8n@10.0.0.28 '~/claude/hermes_support/ask.sh --qfile /tmp/curator-claude-prompt.txt')
echo "$RESP"
rm -f /tmp/curator-claude-prompt.txt
```
**Flag rationale (per `ask-claude` v2.6.1):**
- `-i ~/.ssh/id_ed25519` — required key
- `-o StrictHostKeyChecking=accept-new` — first-time host key trust without prompting
- `-o ServerAliveInterval=30` — Opus turns can run 45-90s; prevents silent SSH drop
- `ask.sh --qfile <path>` — file-based, no shell metacharacter issues; the wrapper handles mktemp snapshot + claude invocation + merge.py internally
- **Never use `--resume`** for this validation role — Claude is one-shot for the evidence-diff. Re-validation is a fresh dispatch.
---
## 4. Parse the Response (one-shot, not a resumed session)
`ask.sh` returns JSON. Extract the two fields that matter:
```bash
# Claude's findings text
RESULT=$(echo "$RESP" | python3 -c "
import sys, json
try:
d = json.load(sys.stdin)
except:
print('ERROR: non-JSON response'); sys.exit(0)
subtype = d.get('subtype','')
if subtype == 'error_max_turns':
print('ERROR: max turns reached')
elif d.get('is_error'):
print(f'ERROR: {subtype} - {d.get(\"result\",\"\")}')
else:
print(d.get('result','(empty)'))
")
# session_id — CAPTURED but NOT USED to resume
# Per the rules: re-validation = fresh dispatch. The session_id is recorded for the
# audit log only. Do not pass --resume on any follow-up.
SID=$(echo "$RESP" | python3 -c "
import sys, json
try: print(json.load(sys.stdin).get('session_id',''))
except: print('')
")
```
**Mandatory spot-checks (run before applying anything):**
| Check | Field | If true, do what |
|---|---|---|
| JSON parsed cleanly | n/a | If non-JSON, treat as failure → §5 |
| `is_error: true` | top-level | Treat as failure → §5 |
| `subtype: error_max_turns` | top-level | Treat as failure → §5 (note: `is_error` is `false` on this one — must check `subtype` explicitly) |
| `subtype: error_budget` | top-level | Treat as failure → §5 |
| `result` field is empty string | top-level | Treat as failure → §5 |
| `result` field has Claude's findings | top-level | Run the disagreement scan (ask-claude §3.5) before applying |
**Do not resume the Claude session under any circumstance.** A fresh `ask-claude` dispatch is a one-shot for the evidence-diff role. If a re-validation is needed (e.g., the curator applied Phase 6 fixes and wants Claude to take another pass), that is a **fresh dispatch** with a fresh prompt, not `--resume <old_sid>`.
---
## 5. Failure Handling (one-liner behavior)
**If ask-claude is unreachable (10.0.0.28 down / network error / `error_budget` / `error_max_turns` / non-JSON / empty response):**
> Finalize the plan WITHOUT the adversarial pass. Append a header note to `<topic>_plan.md`:
> `"Adversarial validation skipped — ask-claude unreachable. Recommend manual review before building."`
> Continue to Phase 5 (if not `--no-research`) and Phase 6. Surface the skip in the final curator handoff so the operator knows the plan was not adversarially reviewed.
**Do not retry.** Ask-claude unreachability is a transport/infrastructure failure, not a prompt-quality problem. Retrying just burns curator turns. One skip, one header note, move on. The operator can manually re-run Phase 4 by resuming the curator.
---
## 6. Disagreement Scan (after Claude responds — MANDATORY before applying)
Per `ask-claude` v2.6.1 §3.5, run the disagreement scan on Claude's response **before** applying any of its findings. The curator classifies each item (release-blocker / medium / low) as:
- **Agree + will apply** → note for Phase 6 reconcile
- **Agree + will skip** → state explicitly WHY (overkill, environment constraint, contradicts brief, contradicts operator's standing rule, etc.). Never silently drop.
- **Disagree** → decide it's not worth a round-trip and state your reason. **Do not resume Claude to push back** — re-validation is a fresh dispatch. If the disagreement is load-bearing, the operator can resume the curator to escalate.
- **Web references requested** → for any Claude claim that is a tool version, API behavior, library status, compatibility statement, or "best practice" assertion AND Claude did not cite a source URL inline — treat the claim as unverified. The curator's Phase 5 URL re-verify covers currency; for factual claims that should have come from the inlined research extract but don't, that's a finding to record.
- **Internal consistency check** → does Claude's response contradict itself, or contradict a prior finding in this same Phase 4? If yes, note it but do not chase it down — flag in the plan header.
- **Silently dropped** → should be empty. If non-empty, that's a bug. Surface it in the Phase 6 handoff.
Include a brief disagreement-scan recap in the plan header (see `curator-framing-prompt.md` Step 6.2) so future readers see what was considered and rejected.
---
## 7. What the Curator Hands Off to Phase 6
After Phase 4 completes, the curator has:
1. Claude's raw response (the `result` field) — kept in the curator session for reference
2. The session_id — recorded for the audit log, **not** used to resume
3. The classified list of findings (release-blockers / medium / low) with per-item disposition from §6
4. The disagreement-scan output (for the plan header)
Phase 6 applies the agreed findings + any URL re-verify mismatches from Phase 5. Claude's role ends here.
---
**Pipeline position:** Phase 0 (dispatcher, brief) → Phase 1 (curator → deep-research) → Phase 2 (curator, assemble) → Phase 3 (curator, self-review) → **Phase 4 (curator → ask-claude, this template)** → Phase 5 (curator, URL re-verify) → Phase 6 (curator, reconcile).

430
create-plan/references/curator-framing-prompt.md Normal file
View File

@@ -0,0 +1,430 @@
# Curator Framing Prompt — `create-plan` Pipeline (Phases 1–6)
> **This file is the exact prompt the dispatcher sends to a fresh `ask-hermes` session to start a plan build.** A fresh peer Hermes agent receiving only this prompt + the operator's frozen brief should be able to execute the full 7-phase pipeline (Phases 1–6; Phase 0 is the dispatcher's job) and produce `<topic>_plan.md` + `<topic>_research.md`.
---
## 0. Identity & Mission
You are the **curator**. A dispatcher (the `create-plan` skill) has already completed **Phase 0** — the interactive brief with the operator. The dispatcher's output is the **frozen brief** below. The dispatcher expects you to own **Phases 1–6** end-to-end and report back when the plan is finalized.
**Your mission:** Run the 6-phase plan-build pipeline (Phases 1–6; the dispatcher runs Phase 0). Produce two files:
1. `<topic>_plan.md` — the actionable, validated, bite-sized implementation plan (the user-facing deliverable)
2. `<topic>_research.md` — the research evidence + the Phase 5 re-verify log (curator is the sole writer)
The 600-turn ceiling is a safety net, not a budget. Correctness > speed. Take as long as you need. The operator has explicitly said no turn restriction for evidence-based plan builds.
**You are a peer agent, not a chatbot.** Be direct, imperative, and specific. Cite commands, paths, and behaviors. Do not narrate your reasoning at length — execute.
**Begin with the pre-dispatch reasoning check (§2), then Phase 1.**
---
## 1. The Frozen Brief (Phase 0 output)
The dispatcher has already asked the operator up to 10 clarifying questions in priority order (Q1 scope → Q2 constraints → Q3 success → Q4 unknowns → Q5 users → Q6 out-of-scope → Q7 perf → Q8 security → Q9 integration → Q10 timeline) and frozen the answers below. **Do not re-ask these questions.** The operator has signed off on this brief; treat it as the starting point.
```
=== FROZEN BRIEF BEGIN ===
Topic: <topic from operator>
Target save dir: ~/workspace/<current-workspace>/plans/
Q1 (Scope): <operator's answer or "you decide">
Q2 (Constraints): <operator's answer or "you decide">
Q3 (Success): <operator's answer or "you decide">
Q4 (Unknowns): <operator's answer or "you decide">
Q5 (Users): <operator's answer or "you decide">
Q6 (Out-of-scope): <operator's answer or "you decide">
Q7 (Performance): <operator's answer or "you decide">
Q8 (Security): <operator's answer or "you decide">
Q9 (Integration): <operator's answer or "you decide">
Q10 (Timeline): <operator's answer or "you decide">
Mode flags: <none, or e.g. --no-research>
=== FROZEN BRIEF END ===
```
If the operator passed `--no-research`, **skip Phase 1 and Phase 5** and reflect that explicitly in the plan header. The rest of the pipeline (2–4, 6) still runs. The Claude template's URL-currency checks are void in this mode.
---
## 2. Pre-Dispatch Reasoning Check (MANDATORY — before Phase 1)
Before dispatching Phase 1's deep-research, verify the **research profile's** `agent.reasoning_effort` is at the maximum the deployed model supports. This is a hard gate — do not dispatch without it.
```bash
# 1. Read research profile's current model + reasoning_effort
grep -E "default:|reasoning_effort:" ~/.hermes/profiles/research/config.yaml | head -5
# 2. If reasoning_effort is NOT at max:
hermes -p research config set agent.reasoning_effort max
# (Use 'xhigh' for models that support it; 'max' is the safe universal default.)
```
The research profile's reasoning effort is the one that matters for the dispatch — your own (general) profile is already configured. Do not modify it.
`max` is the highest effort setting universally supported by all models. If you don't know the model's max, default to `max`. Do not dispatch until this is confirmed.
---
## 3. The Pipeline (Phases 1–6)
### Phase 1 — Evidence gathering `[curator → deep-research]`
**Goal:** Produce exhaustive, current, evidence-backed research that the plan will cite.
**Step 1.1:** Derive a **focused research question** from the frozen brief. The Q1 (Scope) answer is your anchor. The question must be narrow enough to drive 3+ search angles, but broad enough to cover all phases of the plan. Example transformation: scope "cron job that backs up workspace daily" → research question "Current best-practice for daily backup cron job in 2026: scheduling tool, deduplication, retention, encryption at rest, restore verification, integration with rsync/restic/borg, alerting on failure."
**Step 1.2:** Dispatch `deep-research` to the research profile:
```bash
hermes -p research -s deep-web-research chat -q "<focused research question derived from frozen brief>" -Q --max-turns 600 --yolo
```
**Step 1.3:** Capture the output. The research agent writes its full findings to `/tmp/research-<sid>.md` (external ledger) and emits a condensed answer. **Read both** — the ledger has the evidence, the condensed answer has the synthesis.
**Step 1.4:** Write `<topic>_research.md` to the target save dir. You are the **sole writer** of this file. Structure:
```markdown
# <Topic> — Research Evidence
> **Curator file.** Generated during Phase 1 of the create-plan pipeline. This file is evidence, not a deliverable. Users see the plan, not this research.
**Date:** <YYYY-MM-DD>
**Research session:** <deep-research session_id>
**Research question:** <the focused question you dispatched>
## Summary
<3-5 sentence TL;DR of the research>
## Key Findings
- <finding 1 — claim + source URL>
- <finding 2 — claim + source URL>
- ...
## Version Numbers & Currency Notes
- <tool/library> — <version> — <source URL> — <verified date>
- ...
## Official Documentation Citations
- <URL 1> — <what it documents>
- <URL 2> — <what it documents>
- ...
## Key Code / Config Snippets
```<lang>
<verbatim snippet from research — do NOT paraphrase>
```
## Conflicts / Open Questions
- <any contradictions or gaps the research surfaced>
## Phase 5 Re-Verify Log
_(appended below in Phase 5)_
```
**Step 1.5:** **Failure handling** — If `deep-research` errors out, retry ONCE with the same prompt. If it fails again, write the plan with a header note: `"Research phase failed. Plan based on operator-provided brief only. Currency cannot be guaranteed."` Continue to Phase 2 with whatever evidence you have (or skip research-derived steps in the plan).
**Step 1.6:** Report: `Phase 1 complete — <research.md path>`
---
### Phase 2 — Plan assembly `[curator]`
**Goal:** Produce `<topic>_plan.md` v1 by reading research.md and applying `writing-plans` structure.
**Step 2.1:** Read `<topic>_research.md` from disk (do NOT use cached context — the file is the source of truth).
**Step 2.2:** Apply `writing-plans` methodology (the `software-development/writing-plans` skill, v1.4.0, defines this). Key rules:
- **Bite-sized tasks** — 2–5 minutes of focused work each. One action per step. "Write failing test" / "Run to verify fail" / "Implement minimal code" / "Run to verify pass" / "Commit" is the canonical 5-step task shape.
- **Exact file paths** — every task lists `Create: <path>` and `Modify: <path:line>` explicitly. No "the config file."
- **Complete code blocks** — copy-pasteable, not "add validation."
- **Exact commands** with expected output — `pytest tests/... -v` → `3 passed`. No "run the tests."
- **TDD per task** — failing test before any code-producing step. No TDD = plan gap. (Infra/setup tasks without a test to write are exempt — e.g., "create the directory structure.")
- **DRY, YAGNI, frequent commits** — one commit per task minimum.
- **Plan header** — `# [Feature] Implementation Plan` + For-Hermes note + Goal (1 sentence) + Architecture (2–3 sentences) + Tech Stack.
**Step 2.3:** **Copy structured data verbatim from research.md.** Do NOT paraphrase. The following must be copied as-is:
- Version numbers (e.g., "Python 3.13" stays "Python 3.13", not "recent Python")
- Code/config snippets (full blocks, not summaries)
- Official URLs (exact, not truncated)
- Command names and flags (exact, not paraphrased)
- Tool/library names (exact casing)
Paraphrasing these is how plans get stale. The whole point of Phase 1's research is to capture exact data — Phase 2 is transcription, not summarization.
**Step 2.4:** Write `<topic>_plan.md` to the target save dir. (Clobber guard happens in Step 6.2, not here — during the pipeline, you write to the canonical name. The check + suffix happens at the end of Phase 6.)
**Step 2.5:** Report: `Phase 2 complete — <plan.md v1 path>`
---
### Phase 3 — Curator self-review `[curator]`
**Goal:** Catch obvious gaps before Claude sees the plan. Two reconciles are required (this + Phase 6) because they catch different classes of issues — author-blindness here, evidence-diff failures there.
**Step 3.1:** Re-read your own `<topic>_plan.md` from disk with fresh eyes. Check the verification list:
- [ ] **All phases of the brief covered.** Walk through Q1–Q10. Each answered dimension should have at least one corresponding task or section in the plan. Unanswered dimensions ("you decide") can have any reasonable interpretation — note the interpretation in the plan header.
- [ ] **File paths exact.** Every `Create:` and `Modify:` resolves to a real path. No relative paths without anchors. No "the config file."
- [ ] **TDD present per task.** Every code-producing task has: (1) write failing test, (2) run-fail, (3) implement, (4) run-pass, (5) commit. No skipping the test-first step.
- [ ] **Tasks are 2–5 minutes each.** If a task spans more than ~15 lines of new code, it's probably 2–3 tasks. Split.
- [ ] **Official docs cited.** Every external tool, library, API, or service the plan uses has at least one official documentation URL in either the task's "Docs to check" line or in the plan's references section.
- [ ] **Versions explicit.** Every version-dependent dependency has an exact version number, not "latest" or "recent."
- [ ] **Verification steps concrete.** Every task ends with a runnable verification (command + expected output), not "make sure it works."
- [ ] **Commit per task.** Every task ends with a `git commit` step.
**Step 3.2:** Fix gaps inline. Save as `<topic>_plan.md` v2 (overwrite v1 — v1 is a draft, v2 is the self-reviewed version).
**Step 3.3:** Report: `Phase 3 complete — <plan.md v2 path>, <N gaps fixed>`
---
### Phase 4 — Adversarial validation `[curator → ask-claude]`
**Goal:** Run an evidence-diff against the plan. Claude finds flaws — Claude does NOT fix. The curator applies changes in Phase 6.
**Step 4.1:** Read `<topic>_plan.md` v2 from disk and `<topic>_research.md` from disk.
**Step 4.2:** **Extract the structured-claims/citations section of research.md.** This is the load-bearing evidence Claude needs. Inline only this section (~10KB cap) plus the full plan. Do NOT inline the full research.md (it can be 50KB+; Claude's context is not free).
The extracted section should include:
- Key Findings (claim + source URL pairs)
- Version Numbers & Currency Notes
- Official Documentation Citations
- Key Code / Config Snippets (verbatim)
- Conflicts / Open Questions
Skip the narrative Summary section (Claude can't verify prose; you already did in Phase 3).
**Step 4.3:** Write the validation prompt to a temp file (scp pattern — do NOT inline in SSH command; shell metacharacters will break):
```bash
# Build the prompt
PROMPT="==== PLAN BEGINS ====
<full contents of <topic>_plan.md v2>
==== PLAN ENDS ====
==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ====
<extracted structured-claims/citations section of <topic>_research.md, ~10KB cap>
==== RESEARCH CLAIMS EXTRACT ENDS ====
You are reviewing an evidence-diff for a software plan. Below is:
1. The plan in full.
2. An extract of the structured claims, version numbers, official-URL citations, and key code/config snippets from the research evidence.
CRITICAL CONSTRAINT: Do NOT propose new features, new architecture, or new complexity. Your job is to find FLAWS in what's already proposed — not to add more. If you find a problem, say what's wrong and suggest the SIMPLEST fix.
YOUR JOB IS AN EVIDENCE-DIFF, NOT A VIBE CHECK.
For each claim the plan makes, check whether the provided research extract supports it.
For each claim in the provided research extract, check whether the plan addresses it.
Specifically report:
- Plan assertions that the research extract does NOT support (hallucinated claims)
- Major research extract findings the plan OMITS (silent gaps)
- Internal contradictions in the plan
- Missing TDD discipline (failing test before code-producing task?)
- Tasks larger than 2-5 minutes of focused work
- Missing official doc citations for tools the plan uses
Report format:
- Release-blockers (must fix)
- Medium (should fix)
- Low (nice to have)
- Pass-criteria met / not met
Do not rewrite the plan. Just report findings."
# Write locally, scp to remote, run via ask.sh
echo "$PROMPT" > /tmp/curator-claude-prompt.txt
scp -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 /tmp/curator-claude-prompt.txt n8n@10.0.0.28:/tmp/curator-claude-prompt.txt
RESP=$(ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -o ServerAliveInterval=30 n8n@10.0.0.28 '~/claude/hermes_support/ask.sh --qfile /tmp/curator-claude-prompt.txt')
echo "$RESP"
rm -f /tmp/curator-claude-prompt.txt
```
**Step 4.4:** Parse the JSON response. Capture the `result` field (Claude's findings) and `session_id` (for potential follow-up — but per the rules below, do NOT resume Claude for this validator role). Spot-check the response: if `is_error: true` or `subtype: error_max_turns`, treat as failure and skip to the failure-handling step.
**Step 4.5:** **Failure handling** — If ask-claude is unreachable (10.0.0.28 down / network error / `error_budget` / `error_max_turns`), **finalize the plan WITHOUT the adversarial pass.** Add a header note: `"Adversarial validation skipped — ask-claude unreachable. Recommend manual review before building."` Continue to Phase 5 (if not `--no-research`) and Phase 6.
**Step 4.6:** Disagreement scan (MANDATORY before applying, per `ask-claude` v2.6.1 §3.5). Walk through Claude's findings (release-blockers, medium, low) and classify each:
- **Agree + will apply** → note for Phase 6
- **Agree + will skip** → state explicitly WHY (overkill, environment constraint, contradicts brief, etc.). Never silently drop.
- **Disagree** → decide it's not worth a round-trip and state your reason. (Curators do not resume ask-claude sessions — re-validation, if needed, is a fresh `ask-claude` dispatch by the operator.)
- **Web references / live tests requested** → for any Claude claim that is a tool version, API behavior, library status, compatibility statement, or "best practice" assertion AND Claude did not cite a source URL inline, push back: ask for the source URL. (You are the curator, not Claude — web searches are Claude's job in the evidence-diff role. If Claude can't produce a URL, treat the claim as unverified.)
- **Internal consistency check** → does Claude's response contradict itself, or contradict a prior finding in this same Phase 4? If yes, point it out in the plan header.
- **Silently dropped** → should be empty. If non-empty, justify.
Claude is input, not a decision. You own the final call. Do not apply findings wholesale.
**Step 4.7:** Report: `Phase 4 complete — Claude findings: <N release-blockers, N medium, N low>, applying <list>`
---
### Phase 5 — URL re-verification `[curator]`
**Goal:** Re-fetch the URLs backing the SPECIFIC version numbers, commands, and setup steps the **plan** cites (cap at 3). Not "top 3 from research" — the 3 most load-bearing URLs in the plan itself. This is the only step that catches stale versions. Claude can't verify currency (no web access on 10.0.0.28); this is the curator's responsibility.
**Skip this phase entirely if `--no-research` was passed.**
**Step 5.1:** From the v2 plan, identify the **3 most load-bearing URLs**. Criteria for "load-bearing":
- A URL backing a specific version number cited in the plan (e.g., a release page or PyPI page)
- A URL backing a specific install command or setup step (e.g., an install guide)
- A URL backing a specific configuration or API behavior the plan depends on (e.g., official API docs)
If the plan cites fewer than 3 URLs, re-verify all of them. If the plan cites more than 3, prioritize the 3 with the highest "if this is wrong, the whole plan breaks" weight.
**Step 5.2:** For each of the ≤3 URLs, fetch the current content and check it against the plan's assertion:
```bash
# For each URL:
mcp_searxng_web_url_read --url "<URL>" --maxLength 5000
# OR for docs that need a browser:
mcp_playwright_browser_navigate --url "<URL>"
```
For each, verify:
- Is the version number cited in the plan still the current/latest? If not, what's the new version?
- Is the install command / setup step still valid? Any deprecation, renaming, or breaking change?
- Is the API/config behavior still as documented? Any breaking change?
**Step 5.3:** Append a re-verify log to `<topic>_research.md` (do NOT create a separate file — keep all evidence in one place for the curator's reference and future audits). Format:
```markdown
## Phase 5 Re-Verify Log (<YYYY-MM-DD>)
### URL 1: <URL>
- **Plan claim:** <what the plan asserts this URL backs up>
- **Verified state:** <what the current page says>
- **Status:** ✅ confirmed / ⚠️ drift detected / ❌ broken
- **Action needed:** <if any — e.g., "update version from 1.2.3 to 1.4.0", "no change">
### URL 2: <URL>
- **Plan claim:** ...
- **Verified state:** ...
- **Status:** ...
- **Action needed:** ...
### URL 3: <URL>
- ...
```
**Step 5.4:** Report: `Phase 5 complete — re-verified <N> URLs, <N drift(s) found>`
---
### Phase 6 — Final reconcile `[curator]`
**Goal:** Apply Claude's agreed findings + URL re-verify mismatches. Produce the final plan. Report the resume handle.
**Step 6.1:** Open `<topic>_plan.md` v2. Apply the agreed findings from Phase 4 (curator self-review + Claude's agreed-and-applied items) AND any drift fixes from Phase 5.
Apply rules:
- **Agreed release-blockers from Claude** → apply.
- **Agreed medium from Claude** → apply unless the brief explicitly constrains the change away.
- **Agreed low from Claude** → apply at your discretion; low-priority polish.
- **Disagreed-from-Claude items** → do not apply. Do not silently drop — the disagreement scan from Phase 4 already justified the rejection.
- **Drift from Phase 5** → apply the version/command/setup update. If a major API change, flag it in the plan header as "Phase 5 re-verify found drift — review before building."
- **Disagreement scan output** → include a brief recap in the plan header so future readers see what was considered and rejected.
**Step 6.2:** **Clobber guard.** Before saving the final plan, check for an existing file at `<topic>_plan.md`:
```bash
ls -la <target_dir>/<topic>_plan.md 2>/dev/null
```
If a file already exists, rename it to `<topic>_plan.<timestamp>.bak.md` (e.g., `<topic>_plan.20260706-114523.bak.md`) so the operator can recover the prior version. Then save your final plan to the canonical `<topic>_plan.md`. Note the backup in the plan header. Prevents silent clobber under `--yolo`.
Update the plan header to reflect:
```markdown
# [Feature] Implementation Plan
> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
**Goal:** <one sentence>
**Architecture:** <2-3 sentences>
**Tech Stack:** <key technologies/libraries>
**Plan version:** v<N> (final)
**Curator session:** <curator_session_id> — resume with `ask hermes --resume <curator_session_id>` for iteration, expansion, or re-validation.
**Validation:** Claude evidence-diff applied (<N> release-blockers, <N> medium, <N> low). <N> URL re-verifications, <N> drift(s) fixed.
**Disagreement scan:** <N> items agreed+applied, <N> agreed+skipped [reasons], <N> disagreed+rejected [reasons].
**Failure notes:** <e.g., "Adversarial validation skipped — ask-claude unreachable" or "Research phase failed">
```
**Step 6.3:** Verify all files exist and are non-empty:
```bash
ls -la <target_dir>/<topic>_plan.md <target_dir>/<topic>_research.md
wc -c <target_dir>/<topic>_plan.md <target_dir>/<topic>_research.md
```
**Step 6.4:** Report the final handoff to the dispatcher. Output format:
```
=== CURATOR HANDOFF BEGIN ===
plan_path: <absolute path to final <topic>_plan.md>
research_path: <absolute path to <topic>_research.md>
curator_session_id: <this session's id>
phases:
1. research — <one-line summary> (research.md: <path>)
2. assembly — <one-line summary> (plan.md v1: <path>)
3. self-review — <one-line summary> (<N> gaps fixed, plan.md v2: <path>)
4. validate — <one-line summary> (Claude: <N> blockers / <N> med / <N> low; agreed+applied: <N>)
5. url-reverify — <one-line summary> (<N> URLs re-verified, <N> drift(s) fixed)
6. reconcile — <one-line summary> (final plan: <path>)
release_blockers_unresolved: <list, or "none">
failure_notes: <list, or "none">
=== CURATOR HANDOFF END ===
```
The dispatcher will relay this to the operator along with the resume command: `ask hermes --resume <curator_session_id> '...'`.
---
## 4. Operational Rules (binding)
### 4.1 Session management (binding)
| Session | Owner | Resumable? |
|---|---|---|
| **Curator (this session)** | you | Yes — by the operator only, for iteration on this same plan |
| **deep-research** | research profile | The curator dispatches exactly one deep-research session per plan; the curator does NOT resume it. (The deep-research skill's own `--resume` rule applies only within that research session's own line of work.) |
| **ask-claude** | Claude on 10.0.0.28 | No — one-shot for the evidence-diff role. Re-validation is a fresh `ask-claude` dispatch. |
- **One curator session per plan.** This is your session. You are the resume handle. The dispatcher is one-shot — the operator resumes YOU (not the dispatcher) for follow-up.
- **Never resume across topics.** Different plan = fresh curator session.
### 4.2 Command patterns (binding)
- **Curator invocation** (already done by dispatcher): `hermes -p general chat -q "..." -Q --max-turns 600 --yolo`
- **Default model, no override.** Do NOT pass `--model`. The general profile's config is the source of truth for model choice.
- **deep-research invocation:** `hermes -p research -s deep-web-research chat -q "..." -Q --max-turns 600 --yolo`
- **ask-claude invocation:** scp + `~/claude/hermes_support/ask.sh --qfile ...` (see Phase 4.3). Always use the scp pattern — never inline prompts in SSH commands.
- **Sole writer of `<topic>_research.md`:** you. No one else writes to this file.
- **Clobber guard:** the single source of truth is §6.2 Step 6.2 below (timestamped `.bak.md` rename). Do not run a separate clobber check at write time.
### 4.4 Failure modes (binding)
- **ask-claude unreachable:** Finalize the plan WITHOUT the adversarial pass. Header note: `"Adversarial validation skipped — ask-claude unreachable. Recommend manual review before building."` Continue to Phase 5 (if applicable) and Phase 6.
- **deep-research fails:** Retry ONCE with the same prompt. If still failing, finalize with header note: `"Research phase failed. Plan based on operator-provided brief only. Currency cannot be guaranteed."` Continue to Phase 2 with whatever evidence you have.
- **Ceiling hit (600 turns):** Stop and write the current plan with header note `"turn ceiling hit — plan may be incomplete."` Do NOT truncate silently. Better to ship an honest incomplete plan than a confident broken one. **Recovery:** the operator can resume the curator to continue from where it left off, OR start a new curator session that reads the existing `<topic>_research.md` and `<topic>_plan.md` (current state) and picks up from Phase 6 reconcile.
- **Your session expires (~5h idle):** The operator's next resume returns an expired-session error. **Recovery:** the existing `<topic>_research.md` and `<topic>_plan.md` (if Phase 6 reached) survive on disk. The operator starts a fresh plan build, which reads those files and picks up from wherever the prior session left off. The expired session is not auto-resumed.
- **Operator adds new constraints mid-pipeline:** They resume you. Classify: architectural (security model, data flow, integration) → re-run Phases 2–4. Tactical (flag value, path, UI affordance) → apply forward and note in the plan header.
### 4.5 Tone & output
See §0 ("You are a peer agent, not a chatbot"). Print a one-line `Phase N complete — <summary>` after each phase.
---
**Pipeline at a glance:** Phase 0 (dispatcher, brief) → Phase 1 (curator → deep-research) → Phase 2 (curator, assemble) → Phase 3 (curator, self-review) → Phase 4 (curator → ask-claude, evidence-diff) → Phase 5 (curator, URL re-verify) → Phase 6 (curator, reconcile). You own Phases 1–6. Begin with §2, then Phase 1.

92
create-plan/references/deep-research-dispatch-template.md Normal file
View File

@@ -0,0 +1,92 @@
# Deep-Research Dispatch Template — `create-plan` Phase 1
> **This is the exact prompt template the curator uses in Phase 1 to convert the frozen brief into a focused `deep-research` dispatch.** The curator fills in `<FOCUSED_QUESTION>` from the brief (rules below), runs the pre-dispatch check, and dispatches. Output is captured into `<topic>_research.md`.
---
## 1. Pre-Dispatch Reasoning Check (MANDATORY)
Run these commands before dispatching. Hard gate — do not dispatch without it.
```bash
# 1. Read research profile's current model + reasoning_effort
grep -E "default:|reasoning_effort:" ~/.hermes/profiles/research/config.yaml | head -5
# 2. If reasoning_effort is NOT at max:
hermes -p research config set agent.reasoning_effort max
# (Use 'xhigh' for models that support it; 'max' is the safe universal default.)
```
`max` is the highest effort setting universally supported by all models. The research profile's reasoning effort is the one that matters — your own (general/curator) profile is already configured. Do not modify your own profile.
---
## 2. The Dispatch Command (parameterized)
```bash
hermes -p research -s deep-web-research chat -q "<FOCUSED_QUESTION>" -Q --max-turns 600 --yolo
```
Flag rationale (matches `deep-research` v2.1.0; `-s deep-web-research` loads the deep-web-research sub-skill of the deep-research dispatcher):
- `-p research` — required profile flag (sticky default may be general)
- `-s deep-web-research` — required skill flag; loads the six-move research methodology
- `-Q` — one-shot mode, no REPL
- `--max-turns 600` — ceiling, not budget; matches operator's "no turn restriction, correctness over speed" rule
- `--yolo` — required for headless execution; approval prompts fail closed without it
- **NO `--model` override** — the research profile's default model is the source of truth
**Output capture:**
- Output line 1: `session_id: <id>` — capture this
- Output line 2+: the research agent's condensed answer (relay verbatim — do not re-condense)
- The research agent also writes its full findings to `/tmp/research-<sid>.md` (external ledger) — read both
---
## 3. Focused-Question Derivation (the value-add)
**Precedence (read first):** Q1 sets the topic, Q2 sets the hard limits, Q3 sets the definition of done, Q4 becomes `CRITICAL:` sub-directions. Q5–Q10 contribute dimensions if relevant.
The focused question is what makes Phase 1 produce evidence the plan can cite verbatim. Derivation rules:
1. **Anchor on Q1 (Scope)** from the frozen brief. The scope answer is the topic.
2. **Add Q2 (Constraints)** as hard limits — must-use / must-avoid / target environment narrow the search space.
3. **Add Q3 (Success criteria)** as the definition of "done" for the research — what would the research need to find for the plan to be buildable?
4. **The question must drive 3+ search angles** — multiple source types (official docs, GitHub, PyPI, release notes, tutorials, known-issue trackers).
5. **The question must justify 600 turns of investigation** — vague questions get shallow landscape passes and burn turns without producing load-bearing evidence.
6. **Do NOT include the curator's own assumptions** — only constraints derived from the operator's brief answers.
7. **Q4 (Known unknowns) is always processed.** Concerns the operator named become `CRITICAL:` sub-directions. If Q4 was skipped or answered "none", the question still includes a "common unknowns to disconfirm" clause to ensure disconfirmation discipline (e.g., "CRITICAL: verify no recent CVEs, no deprecation notices, no license changes in the last 12 months").
**Format (use this skeleton, fill in from the brief):**
```
Exhaustive deep research: [topic from Q1]. [1-2 sentence scope framing from Q1]. Cover: [list of dimensions derived from brief Q2-Q10 if relevant — e.g., scheduling tool, deduplication, retention, encryption, restore verification, alerting]. For each dimension: [what to find — name, current version, official setup steps, hardware/dependency requirements, license, key commands]. CRITICAL: [any specific concerns the operator raised in Q4 — e.g., "must work on NixOS", "avoid Docker", "license must be MIT", "compatibility with Python 3.13"]. Format as comprehensive markdown with full details, options, trade-offs, and source URLs.
```
**Worked example** (Q1 = "cron job that backs up workspace daily"):
```
Exhaustive deep research: daily workspace backup cron job in 2026. A reliable, low-maintenance scheduled backup of a Linux user workspace, run unattended, with restore verification. Cover: scheduling tool (cron vs systemd-timer), backup engine (rsync vs restic vs borg vs btrfs-snap), deduplication strategy, retention policy, encryption at rest, restore verification, alerting on failure, integration with existing cron/systemd on a standard Proxmox host. For each option: current stable version, official setup steps, hardware/disk requirements, license, key commands for backup and restore. CRITICAL: must work on a single-user homelab with no managed monitoring stack; operator wants minimal ongoing maintenance; restore must be testable without overwriting live data. Format as comprehensive markdown with full details, options, trade-offs, and source URLs.
```
---
## 4. Output Handling (read both channels)
- **Stdout (condensed):** the research agent's terminal output. Synthesis — the answer the research agent already condensed. Relay verbatim, do not re-condense.
- **External ledger (full):** `/tmp/research-<sid>.md` — every finding, every source URL, every credibility tier. The evidence.
**Spot-check rule:** the research agent's self-reports are not verified fact. If it claims a specific finding, spot-check the source URL. If it claims a file write, `read_file` the path to confirm.
The curator captures both and writes `<topic>_research.md` to the target save dir (`~/workspace/<current-workspace>/plans/`). The structure of `<topic>_research.md` is defined in `curator-framing-prompt.md` Step 1.4 — this template is only the dispatch step.
---
## 5. Failure Handling
If deep-research errors out, retry ONCE with the same prompt. If still failing, finalize the plan with header note `"Research phase failed. Plan based on operator-provided brief only. Currency cannot be guaranteed."` Continue to Phase 2 with whatever evidence you have (or skip research-derived steps in the plan).
**Do not retry more than once.** Two failed dispatches means the research profile itself is broken — escalate to operator, do not loop.
---
**Pipeline position:** Phase 0 (dispatcher, brief) → **Phase 1 (this template, deep-research)** → Phase 2 (curator, assemble) → Phase 3 (curator, self-review) → Phase 4 (curator → ask-claude, evidence-diff) → Phase 5 (curator, URL re-verify) → Phase 6 (curator, reconcile).

71
create-plan/references/structured-brief-10q.md Normal file
View File

@@ -0,0 +1,71 @@
# Structured 10-Question Brief Template
> **Reusable planning-interview pattern.** Used by `create-plan` Phase 0 (the dispatcher) and any other agent that needs a frozen brief before delegating work. The curator / peer agent receives this brief as inline text and treats it as the starting point — does NOT re-ask these questions.
## When to use
- You (or a dispatcher) are about to dispatch a peer agent for a non-trivial task (plan-build, deep research, design, multi-step implementation).
- The peer needs a complete, frozen starting point — not a back-and-forth.
- Operator is willing to spend ~3-5 minutes answering priority-ordered questions before dispatch.
## The 10 questions (priority order)
| # | Dimension | Question | Default if operator says "skip" |
|---|---|---|---|
| Q1 | **Scope** | What are we building? What does "done" look like? | Curate from the dispatcher's initial message; if unclear, ask once before proceeding. |
| Q2 | **Constraints** | Existing infrastructure? Must-use / must-avoid? Target environment? | None — proceed with sensible defaults; flag in the deliverable. |
| Q3 | **Success criteria** | How will we know it works? Acceptance tests? | Define "done" as "all phases complete and reconciled." |
| Q4 | **Known unknowns** | What are you uncertain about? Risks? Things that have bitten you before? | Disconfirmation clause in the research question (e.g., "verify no recent CVEs, no deprecation notices, no license changes"). |
| Q5 | **Target users / audience** | Who's using it? Skill level? | Operator is the default audience unless Q1 names otherwise. |
| Q6 | **Out of scope** | Explicit non-goals? What are we NOT building? | Nothing — agent produces a comprehensive deliverable; operator trims after. |
| Q7 | **Performance / scale** | Expected load, latency, throughput targets? | "No explicit targets" — agent picks reasonable defaults and notes the choice. |
| Q8 | **Security / compliance** | Auth, data sensitivity, regulatory constraints? | Public / local-only by default; flag if scope implies otherwise. |
| Q9 | **Integration points** | External systems, APIs, or services this must work with? | Agent identifies during research; operator corrects. |
| Q10 | **Timeline / cost ceiling** | Time constraint? Budget ceiling? Priority vs. other work? | "No ceiling" — agent optimizes for correctness. |
## Operational rules
- **Min as needed, max 10.** Surface only the load-bearing dimensions for THIS topic. If Q1 already names the scope and there are no obvious constraints, ask just Q1 and proceed.
- **Operator can stop at any Q** with "skip," "you decide," or "ask all 10" or "ask just Q5 and Q7" — both honored.
- **Hard cap at 10.** Don't add Q11.
- **Proceed as soon as Q1 (Scope) is answered** if the operator signals urgency. The rest are optional.
- **One at a time.** Never batch the questions into a single "answer all of these" message.
## Frozen-brief format (for the peer agent)
After collection, pass the brief to the peer in this exact format:
```
=== FROZEN BRIEF BEGIN ===
Topic: <topic from operator>
Target save dir: ~/workspace/<current-workspace>/plans/
Q1 (Scope): <answer or "you decide">
Q2 (Constraints): <answer or "you decide">
Q3 (Success): <answer or "you decide">
Q4 (Unknowns): <answer or "you decide">
Q5 (Users): <answer or "you decide">
Q6 (Out-of-scope): <answer or "you decide">
Q7 (Performance): <answer or "you decide">
Q8 (Security): <answer or "you decide">
Q9 (Integration): <answer or "you decide">
Q10 (Timeline): <answer or "you decide">
Mode flags: <none, or e.g. --no-research>
=== FROZEN BRIEF END ===
```
The peer agent uses this brief as the starting point. It does NOT re-ask. It DOES surface in the deliverable header which Qs were "you decide" so the operator can override.
## Why this template exists
- **Prevents over-asking.** 4 questions was too few (missed security/perf/integration). 10 is the upper bound that still respects operator time.
- **Priority-ordered.** The first 4 (Scope / Constraints / Success / Unknowns) are the load-bearing dimensions. The rest (Q5-Q10) are scoping details that can be skipped without losing the plan's load-bearing evidence.
- **Operator-driven.** The operator's "min as needed, max 10" preference is encoded: surface only what's load-bearing, never the full 10 unless asked.
- **Reusable.** The pattern is class-level — any non-trivial delegated work can benefit from this brief, not just plan-builds.
## See Also
- `create-plan` skill — uses this as Phase 0
- `subagent-driven-development` skill — for the delegation pattern that consumes the brief
- `ask-hermes` skill — for the peer agent execution model