diff --git a/create-plan/SKILL.md b/create-plan/SKILL.md index 27a68be..6c01b83 100644 --- a/create-plan/SKILL.md +++ b/create-plan/SKILL.md @@ -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) diff --git a/create-plan/references/ask-claude-validation-template.md b/create-plan/references/ask-claude-validation-template.md index 69b6193..331806d 100644 --- a/create-plan/references/ask-claude-validation-template.md +++ b/create-plan/references/ask-claude-validation-template.md @@ -89,48 +89,17 @@ The curator reads `_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 _plan.md) -==== PLAN ENDS ==== +# 1. Use write_file to create /tmp/curator-claude-prompt.txt +# Compose the prompt from §1, substituting and +# with the actual content. Do NOT use echo or $(cat) — use write_file. -==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ==== -$(cat ) -==== 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 diff --git a/create-plan/references/curator-framing-prompt.md b/create-plan/references/curator-framing-prompt.md index f1b8c6b..1139659 100644 --- a/create-plan/references/curator-framing-prompt.md +++ b/create-plan/references/curator-framing-prompt.md @@ -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 ==== -_plan.md v2> -==== PLAN ENDS ==== - -==== RESEARCH CLAIMS/CITATIONS EXTRACT BEGINS ==== -_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 "" --maxLength 5000 -# OR for docs that need a browser: -mcp_playwright_browser_navigate --url "" -``` +- Call `web_extract(urls=[""], char_limit=5000)` to fetch page content as markdown. +- For docs that need a browser (JavaScript-rendered pages), call `mcp__playwright__browser_navigate(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:** **Plan version:** v (final) -**Curator session:** — resume with `ask hermes --resume ` for iteration, expansion, or re-validation. +**Curator session:** — captured by the dispatcher at dispatch time. Resume with `ask hermes --resume ` for iteration, expansion, or re-validation. **Validation:** Claude evidence-diff applied ( release-blockers, medium, low). URL re-verifications, drift(s) fixed. **Disagreement scan:** items agreed+applied, agreed+skipped [reasons], disagreed+rejected [reasons]. **Failure notes:** @@ -374,7 +337,6 @@ wc -c /_plan.md /_research.md === CURATOR HANDOFF BEGIN === plan_path: _plan.md> research_path: _research.md> -curator_session_id: phases: 1. research — (research.md: ) 2. assembly — (plan.md v1: ) @@ -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 `_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 `_research.md` and `_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 , 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 `_research.md` and `_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 `_research.md` and `_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.