create-plan: v1.1.1 — fix tool names (web_extract/mcp__playwright__), echo metacharacter breakage, bash-wrapped tool calls, self-referential §6.2, add one-at-a-time rule
This commit is contained in:
Hermes Agent
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: create-plan
|
||||
description: "Multi-agent plan-build pipeline: brief → research → assembly → Claude evidence-diff → URL re-verify → reconcile. Triggered by 'create plan for X', 'plan this', 'draft a plan for', 'build a plan for'."
|
||||
version: 1.1.0
|
||||
version: 1.1.1
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux]
|
||||
@@ -168,6 +168,7 @@ The dispatcher surfaces up to **10** clarifying questions in **priority order**.
|
||||
- The operator can also steer: `ask all 10`, `ask just Q5 and Q7`, or `skip the rest`. Honor exactly.
|
||||
- The operator can say `proceed` at any point to freeze the brief immediately with whatever has been collected.
|
||||
- **Hard cap at 10.** Do not ask an 11th question.
|
||||
- **One at a time.** Never batch multiple questions into a single message. Each question is asked individually and the operator answers before the next is presented.
|
||||
- The dispatcher does NOT poll after handing off. Once the brief is frozen, dispatch and exit (see §5.3, §5.4).
|
||||
|
||||
**Load-bearing test (the only rule that matters):** before asking Q_n, ask yourself "is this dimension load-bearing for THIS topic?" If Q4 is asking about known unknowns and the operator's topic is a trivial 3-line config change, skip Q4. If Q8 is asking about security and the operator's topic is a local-only single-user shell alias, skip Q8. The operator is paying for every question; only ask the ones whose answer changes the plan.
|
||||
@@ -326,6 +327,8 @@ Before declaring the skill buildable, the dispatcher must empirically confirm th
|
||||
9. **The 10-Q brief widens the plan's claim surface.** A fuller brief (security, integration, perf answers) means the plan may cite more tools → Phase 5's 3-URL re-verify cap is a real under-coverage risk. If the plan cites many tools, the operator should resume the curator to request additional URL re-verification.
|
||||
10. **The session-id capture ("from output line 1") is positional parsing.** If the `ask-hermes` banner format changes (warning line, blank line, config notice) or if a different hermes version precedes the session id with extra output, the dispatcher captures garbage, prints a broken resume command, and the operator cannot resume the plan. **This is a first-run failure risk.** The skill SHOULD empirically verify line-1 capture against the deployed hermes version before declaring the skill buildable. If capture is unreliable, use a JSON-output flag or whatever documented mechanism `hermes` exposes to return the session id (out of scope for this skill to fix the underlying Hermes behavior).
|
||||
11. **Phase 4 (Claude evidence-diff) only sees the structured-claims extract, not the full research.md.** The curator's self-review (Phase 3) is the safety net for findings that fall outside the extract.
|
||||
12. **Tool names in Phase 5 must match the actual tool registry.** The curator framing prompt's Phase 5.2 references `web_extract` and `mcp__playwright__browser_navigate` (double underscore). If these change in a future Hermes version, the curator will error out on URL re-verification. Verify tool names against the current tool registry before shipping a skill update.
|
||||
13. **The turn-ceiling save must be proactive, not reactive.** The curator cannot "stop and write at turn 600" — the session terminates at the ceiling. The curator framing prompt instructs proactive save at ~590. If the turn budget changes, update both the ceiling value and the proactive-save threshold.
|
||||
|
||||
## 9. Verification Checklist (from plan §7, verbatim)
|
||||
|
||||
|
||||
@@ -89,48 +89,17 @@ The curator reads `<topic>_research.md` from disk and extracts **only the struct
|
||||
|
||||
## 3. The Dispatch Script (parameterized, ready to run)
|
||||
|
||||
**CRITICAL: Use `write_file`, not `echo` or `$(cat)` — shell metacharacters in the plan body (backticks, `$`, quotes) will break the command.** The prompt template is in §1 above. Compose it with `write_file`, then scp + run:
|
||||
|
||||
```bash
|
||||
# 1. Build the prompt (see §1 for the full template)
|
||||
PROMPT="==== PLAN BEGINS ====
|
||||
$(cat <topic>_plan.md)
|
||||
==== PLAN ENDS ====
|
||||
# 1. Use write_file to create /tmp/curator-claude-prompt.txt
|
||||
# Compose the prompt from §1, substituting <PLAN_BODY> and <RESEARCH_CLAIMS_EXTRACT>
|
||||
# with the actual content. Do NOT use echo or $(cat) — use write_file.
|
||||
|
||||
==== 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
|
||||
# 2. scp the file to the remote
|
||||
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
|
||||
|
||||
# 3. Run ask.sh on the remote
|
||||
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
|
||||
|
||||
@@ -200,47 +200,14 @@ The extracted section should include:
|
||||
|
||||
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):
|
||||
**Step 4.3:** Compose the validation prompt and write it to a temp file. **Use `write_file`, not `echo` or `$(cat)` — shell metacharacters in the plan body (backticks, `$`, quotes) will break the command.** Then scp the file to 10.0.0.28 and run via `ask.sh`:
|
||||
|
||||
```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
|
||||
# 1. Use write_file to create /tmp/curator-claude-prompt.txt with the composed prompt
|
||||
# (see ask-claude-validation-template.md §1 for the exact prompt template)
|
||||
# 2. scp the file to the remote
|
||||
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
|
||||
# 3. Run ask.sh on the remote
|
||||
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
|
||||
@@ -279,14 +246,10 @@ Claude is input, not a decision. You own the final call. Do not apply findings w
|
||||
|
||||
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:
|
||||
**Step 5.2:** For each of the ≤3 URLs, fetch the current content and check it against the plan's assertion. These are agent tool calls, not shell commands:
|
||||
|
||||
```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>"
|
||||
```
|
||||
- Call `web_extract(urls=["<URL>"], char_limit=5000)` to fetch page content as markdown.
|
||||
- For docs that need a browser (JavaScript-rendered pages), call `mcp__playwright__browser_navigate(url="<URL>")` followed by `mcp__playwright__browser_snapshot()`.
|
||||
|
||||
For each, verify:
|
||||
- Is the version number cited in the plan still the current/latest? If not, what's the new version?
|
||||
@@ -355,7 +318,7 @@ Update the plan header to reflect:
|
||||
**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.
|
||||
**Curator session:** <curator_session_id> — captured by the dispatcher at dispatch time. 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">
|
||||
@@ -374,7 +337,6 @@ wc -c <target_dir>/<topic>_plan.md <target_dir>/<topic>_research.md
|
||||
=== 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>)
|
||||
@@ -411,13 +373,13 @@ The dispatcher will relay this to the operator along with the resume command: `a
|
||||
- **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.
|
||||
- **Clobber guard:** the single source of truth is Phase 6, 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.
|
||||
- **Ceiling hit (600 turns):** **Proactive save required.** Monitor your turn count. At turn ~590, stop whatever phase you're in and immediately save the current plan state with header note `"turn ceiling approaching — plan saved at turn <N>, may be incomplete."` Do NOT wait for turn 600 — the session terminates at the ceiling and you cannot write after that. **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 the last completed phase.
|
||||
- **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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user