Files

Hermes Agent f0ac28dd6b create-plan: v1.2.1 — change default save path to ~/workspace/plans/ (was ~/workspace/<current-workspace>/plans/)

2026-07-08 16:03:09 -05:00

39 KiB

Raw Blame History

name, description, version, author, license, platforms, metadata

name

description

version

author

license

platforms

metadata

create-plan

Multi-agent plan-build pipeline: brief → research → assembly → self-review → multi-model peer validation (Claude + general + dev) → URL re-verify → reconcile. Triggered by 'create plan for X', 'plan this', 'draft a plan for', 'build a plan for'.

1.2.1

Hermes Agent

MIT

linux

hermes

create-plan — Multi-Agent Plan-Build Pipeline (Dispatcher)

1. Overview

The create-plan skill is a thin dispatcher that orchestrates a multi-phase plan-build pipeline (Phase 0 through Phase 6, with optional Phase 4b/4c peer rounds). The dispatcher runs Phase 0 — an interactive brief with the operator — then spawns a peer ask-hermes curator session that owns Phases 1 through 6 end-to-end. The curator dispatches deep-research for current evidence, runs assembly itself using writing-plans methodology, dispatches ask-claude for the first adversarial pass, dispatches ask-hermes (general profile) and optionally ask-dev (dev profile) for additional cross-model peer validation, performs URL re-verification of the plan's specific cited claims, and reconciles the final plan.

Why multi-model peer validation (Phases 4a/4b/4c): Different models have different blind spots. Claude Opus on 10.0.0.28 catches structural issues and evidence-diff gaps. A peer on the general profile (minimax-m3 by default) catches implementation-level issues and applies the same "would the agent actually follow this?" check. A peer on the dev profile (deepseek-v4-pro) catches issues neither of the other two saw. The dev profile is intentionally a different model for this reason. In the operator's actual practice (4-round validation, July 2026), the dev peer caught a persistent-side-effect issue on a hermes config set call that neither Claude nor the general peer flagged — and was also wrong about a config-schema claim that a 5-second live test disproved. Both directions of value are real. See references/multi-model-peer-validation.md for the full pattern.

Output files: <topic>_plan.md (actionable, validated) and <topic>_research.md (evidence, with appended re-verify log). The 600-turn ceiling is a safety net, not a budget — the curator is allowed to take as long as it needs. Correctness > speed. The user resumes the curator (not the dispatcher) to iterate, add constraints, or request re-validation. Per ask-hermes Turn Budget section (and §5.3 below), the create-plan curator always uses --max-turns 600 --yolo; the default 20 is not appropriate for evidence-based plan builds.

Reconcile 2x: Phase 3 (curator self-review) catches obvious gaps before Claude sees them. Phase 6 (final reconcile) applies Claude's agreed changes and URL re-verify mismatches. Two reconciles are required because they catch different classes of issues — author-blindness (Phase 3) vs. evidence-diff failures (Phase 6).

Dispatcher scope — what this skill actually does. This skill is a thin dispatcher that runs ONLY Phase 0 (the interactive 10-question brief) and then hands control to a peer ask-hermes curator session that owns Phases 1–6. The dispatcher does not run research, assembly, or validation itself. For the dispatcher's trigger phrases, the Phase 0 brief script, and the exact hermes -p general chat ... command that spawns the curator (and how curator_session_id is captured from output line 1), see Section 5 below.

2. When to Use / When NOT to Use

Use when:

The operator wants a thorough, web-validated plan with current software versions, official docs, and adversarial review.
The plan is for: software implementation, infrastructure, integrations, profile setup, research-heavy deliverables, pipelines, OSINT, etc.
The operator is willing to let the curator take as long as it needs (no turn restriction).

Do NOT use when:

Single-step trivial change → use writing-plans directly.
A plan the operator will immediately execute → use writing-plans + subagent-driven-development.
The operator wants a quick sketch, not a validated plan.
No network or filesystem access to the operator's machine (the curator needs both).
Simple Q&A, factual lookups, code review, or general chat (this is not an advice skill).

3. The Pipeline (7 phases, 0-6)

┌─────────────────────────────────────────────────────────────────┐
│ Phase 0: Interactive brief (up to 10 Qs)        [dispatcher]    │
│   - dispatcher asks operator clarifying questions              │
│   - priority order: scope → constraints → success → unknowns    │
│     → users → out-of-scope → perf → security → integration     │
│     → timeline                                                 │
│   - min as needed, max 10; operator can stop at any Q          │
│   - Output: frozen brief passed to curator                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 1: Evidence gathering                      [curator →]    │
│   - curator dispatches deep-research                            │
│   - deep-research runs 6-move flow                              │
│   - curator captures output, writes <topic>_research.md         │
│   - 600-turn ceiling, mechanical saturation, disconfirmation    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 2: Plan assembly                            [curator]    │
│   - curator reads <topic>_research.md from disk                 │
│   - applies writing-plans structure (bite-sized tasks, exact    │
│     paths, code blocks, TDD per task)                          │
│   - Output: <topic>_plan.md v1                                  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 3: Curator self-review                      [curator]    │
│   - curator self-reviews plan, fixes obvious gaps               │
│   - Output: <topic>_plan.md v2                                  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 4a: Adversarial validation (Claude)        [curator →]   │
│   - curator dispatches ask-claude (Opus on 10.0.0.28)         │
│   - curator extracts the structured-claims/citations section    │
│     of <topic>_research.md (~10KB cap) and inlines BOTH the    │
│     full <topic>_plan.md AND the extracted claims               │
│   - Claude's prompt: "where does the plan assert something      │
│     the research extract does not support, or omit something   │
│     the extract flagged?"                                       │
│   - Output: validation report (release-blockers / med / low)    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 4b: Peer validation (general model)        [curator →]   │
│   - curator dispatches ask-hermes (general profile) for an     │
│     independent validation from a different model              │
│   - general peer reads the plan + researches live, can verify   │
│     things Claude structurally cannot (paths exist, config     │
│     accepted, distribution patterns)                           │
│   - Output: validation report from general peer                │
│   - Default: 1 round. Skip only if Phase 4a found zero findings │
│     AND the plan is short (<100 lines).                         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 4c: Peer validation (dev model, optional)   [curator →]   │
│   - curator dispatches ask-dev (dev profile) for a third-model  │
│     blindspot check                                             │
│   - dev peer is a different model (deepseek-v4-pro vs.         │
│     minimax-m3) and catches different issues than the first two │
│   - Only run if Phase 4a or 4b found release-blockers.          │
│   - Output: validation report from dev peer                     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 5: URL re-verification                      [curator]    │
│   - curator re-fetches URLs backing the SPECIFIC version        │
│     numbers, commands, and setup steps the PLAN cites            │
│     (cap at 3) — not "top 3 from research"                       │
│   - confirms those versions/commands/setup still match current   │
│     docs                                                        │
│   - Output: re-verify log appended to <topic>_research.md       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 6: Final reconcile                          [curator]    │
│   - curator reads ALL validation reports (4a, 4b, 4c if run)    │
│     + re-verify log                                            │
│   - applies agreed changes from each, runs disagreement scan     │
│     on each                                                    │
│   - Output: <topic>_plan.md final                               │
│   - reports: curator_session_id for resume                      │
└─────────────────────────────────────────────────────────────────┘

Per-dispatch command templates (see Section 5 + references/):

Phase 0 (dispatcher, no shell command): Inline interactive Q&A with operator. No dispatch. The 10-Q script and stopping rules are in §5.2.
Phase 1 (curator → deep-research): hermes -p research -s deep-web-research chat "..." — the curator runs this inside Phase 1, using the template at references/deep-research-dispatch-template.md.
Phase 4 (curator → ask-claude): scp + ~/claude/hermes_support/ask.sh --qfile ... — the curator runs this inside Phase 4, using the template at references/ask-claude-validation-template.md.
Phase 6 (curator finalize): write_file <plan_path> with reconciled content; the curator owns this and the clobber-guard logic (see §7).
Curator dispatch itself: hermes -p general chat -q "..." -Q --max-turns 600 --yolo — the exact invocation the dispatcher ships is in §5.3.

4. Dispatcher Q&A Script (Phase 0)

The dispatcher surfaces up to 10 clarifying questions in priority order. Min as needed, max 10 — the dispatcher only asks the load-bearing dimensions for this specific topic. Operator can say "ask all 10", "ask just Q5 and Q7", "skip", or "you decide" at any point.

The full 10-question table with priority order, exact wording, and stopping rules is in §5.2 — that is the authoritative copy. This section is a one-paragraph pointer; the operator-facing wording of the 10 questions is in §5.2 only.

Stopping rules (summary):

Proceed as soon as Q1 (scope) is answered; later Qs are optional.
Operator can stop at any Q with "skip" or "you decide".
Hard cap at 10.
The dispatcher does NOT poll after handing off to the curator.

5. Dispatcher Behavior (trigger detection, Phase 0 brief, curator dispatch)

This section is the dispatcher's actual job. It defines how the dispatcher recognizes a "create plan" request, runs the Phase 0 interactive brief, composes and ships the curator dispatch command, and captures the curator_session_id for handoff.

Boundary: the dispatcher is responsible ONLY for Phase 0 + the curator handoff. It does NOT run Phases 1–6. Phases 1–6 are the curator's job, driven by references/curator-framing-prompt.md (curator identity + pipeline), references/deep-research-dispatch-template.md (Phase 1 dispatch), and references/ask-claude-validation-template.md (Phase 4 evidence-diff). The curator prompt embeds the two dispatch-template references inline; the dispatcher does not need to inline them itself.

5.1 Trigger phrases and trigger detection

The dispatcher fires when the operator's message contains any of these phrases (case-insensitive, substring match on the raw message):

create plan for — most common; e.g., "create plan for adding a cron job that backs up workspace daily"
plan this — used when the operator has just described a topic in the prior turn
draft a plan for — explicit synonym for create plan for
build a plan for — explicit synonym for create plan for

Parsing rule: when a trigger phrase matches, treat the noun-phrase that follows as the topic. Strip leading articles (a, an, the) and trailing punctuation. The remainder is the topic string that goes into the frozen brief. If the operator's message contains the trigger phrase but the topic is ambiguous (e.g., "create plan for the thing we discussed"), ask one short clarifying question to nail the topic down — do not guess.

Precedence note: writing-plans and create-plan both produce plans, but they are different skills. The operator-facing trigger for THIS skill is "create plan for X" (or synonyms above). If the operator says "write a plan for X" without "create" or "draft" or "build", prefer writing-plans (which is the lighter, non-validated planner). When in doubt, ask the operator which they want: validated multi-agent plan (create-plan) or quick writing-plans output.

5.2 Phase 0 — Interactive brief (the 10-Q script)

The dispatcher surfaces up to 10 clarifying questions in priority order. Min as needed, max 10 — only ask the dimensions that are load-bearing for THIS specific topic. The 10 canonical questions live HERE in this skill (not in writing-plans; writing-plans may reference but does not duplicate them).

The 10 questions (in priority order):

#	Dimension	Question
Q1	Scope	What are we building? What does "done" look like?
Q2	Constraints	Existing infrastructure? Must-use / must-avoid? Target environment?
Q3	Success criteria	How will we know it works? Acceptance tests?
Q4	Known unknowns	What are you uncertain about? Risks? Things that have bitten you before?
Q5	Target users / audience	Who's using it? Skill level?
Q6	Out of scope	Explicit non-goals? What are we NOT building?
Q7	Performance / scale	Expected load, latency, throughput targets?
Q8	Security / compliance	Auth, data sensitivity, regulatory constraints?
Q9	Integration points	External systems, APIs, or services this must work with?
Q10	Timeline / cost ceiling	Time constraint? Budget ceiling? Priority vs. other work?

Stopping rules (binding):

Proceed as soon as Q1 (Scope) is answered. Q1 is the only question that is always asked. Every question after Q1 is optional.
The operator can stop at any Q with skip or you decide — treat that dimension as "you decide" in the frozen brief.
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.

Mode flags (collected during the brief):

--no-research — skip Phase 1 and Phase 5. The curator goes straight from brief → assembly. Reflect this in the brief's Mode flags: line.

Frozen brief format (the exact text the curator receives — the curator prompt's === FROZEN BRIEF === block):

=== FROZEN BRIEF BEGIN ===
Topic: <topic from operator>
Target save dir: ~/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 ===

5.3 Curator dispatch (the actual `hermes` command)

After the brief is frozen, the dispatcher composes the full prompt by concatenating, in this order:

The curator framing prompt — the verbatim contents of references/curator-framing-prompt.md. Read it from disk with read_file; do not paraphrase, do not summarize.
The frozen brief block — the === FROZEN BRIEF BEGIN ... END === block from §5.2 above, with the operator's actual answers substituted in.

The composed prompt is one string. It is passed to the curator via the standard ask hermes one-shot invocation:

hermes -p general chat -q "<COMPOSED_PROMPT>" -Q --max-turns 600 --yolo

Flag rationale (matches ask-hermes skill v4.2 conventions):

-p general — required profile flag; the curator runs on the general profile, not dev/research.
chat -q "..." — headless one-shot, no interactive REPL. The REPL mode produces unreadable ANSI redraw noise.
-Q — one-shot mode, no REPL.
--max-turns 600 — the operator's "no turn restriction, correctness over speed" rule. 600 is a safety net, not a budget. The create-plan curator always uses 600 (per ask-hermes Turn Budget section, override for plan-building).
--yolo — required for headless execution; approval prompts fail closed (60s timeout → deny) without it. The hardline blocklist still applies.
NO --model override. The general profile's default model is the source of truth. Do not pass --model. The curator must NOT receive a model override.

Pre-dispatch reasoning check (MANDATORY — run before dispatching):

Before invoking the command above, verify the general profile's agent.reasoning_effort is at the maximum the deployed model supports. (The references/curator-framing-prompt.md does an analogous check for the research profile inside Phase 1; the dispatcher does the general-profile check here before spawning the curator.)

# 1. Read general profile's current model + reasoning_effort
grep -E "default:|reasoning_effort:" ~/.hermes/profiles/general/config.yaml | head -5

# 2. If reasoning_effort is NOT at max for the model:
#    - minimax-m3:cloud → 'xhigh' (supports it)
#    - deepseek-v4-pro:cloud / glm-5.2:cloud → 'max' (xhigh rejected)
#    - if unsure → 'max' (safe universal default)
hermes -p general config set agent.reasoning_effort xhigh
# OR for models that reject xhigh:
hermes -p general config set agent.reasoning_effort max

Hard gate: do not dispatch the curator without this check. The ask-hermes skill v4.2 documents this exact check (Pre-Dispatch Reasoning Check section); the dispatcher runs it once at the top of the curator dispatch.

Prompt composition rule (binding): the composed prompt is the curator framing prompt + the frozen brief, concatenated. Do NOT inline references/deep-research-dispatch-template.md or references/ask-claude-validation-template.md in the dispatcher's prompt — the curator framing prompt already references them inline. The dispatcher does not pre-dispatch the research or claude calls; the curator does that itself in Phases 1 and 4. One curator session per plan. (See §6 Session Management.)

5.4 Capture and handoff (curator_session_id is the resume handle)

When the hermes -p general chat -q "..." -Q --max-turns 600 --yolo command runs, the output has this shape:

session_id: <id>
<the curator's response — usually a one-line "acknowledged, starting Phase 1" or a focused question back to the operator>

Capture rule (binding): Output line 1 is session_id: <id> — capture that exact value. This is the curator_session_id. The operator resumes the curator with this id; the dispatcher does not poll, does not process the curator's response further, does not run any follow-up turns.

Empirical verification requirement (per plan_skill_plan.md §6 pitfall #10 and §7 verification checklist): before declaring this skill buildable, the dispatcher (or its first-run tester) must empirically confirm that line 1 of ask-hermes output IS the session id. This is a first-run failure risk: if the ask-hermes banner format changes (warning line, blank line, config notice, or 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. If capture is unreliable, fall back to 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).

Handoff output (the dispatcher's final response to the operator):

=== CREATE-PLAN DISPATCH COMPLETE ===
curator_session_id: <id from line 1>
frozen_brief_topic: <the topic string>
target_save_dir: ~/workspace/plans/
mode_flags: <none | --no-research | etc.>

The curator now owns Phases 1–6 (research → assemble → self-review → Claude evidence-diff → URL re-verify → reconcile).
The dispatcher will not poll. To check progress, add constraints, or request re-validation:

  ask hermes --resume <curator_session_id> '...'

Resume the curator (NOT this dispatcher) for any follow-up. Expected deliverables:
- <topic>_plan.md (actionable, validated)
- <topic>_research.md (evidence + Phase 5 re-verify log)
=== CREATE-PLAN DISPATCH COMPLETE ===

What the dispatcher does NOT do after this:

Does NOT poll the curator.
Does NOT process the curator's response further (it may be a one-line "Phase 1 starting" or a focused clarifying question — relay verbatim or, if a question, surface it to the operator; either way, do not run a --resume turn on the operator's behalf).
Does NOT itself run deep-research, ask-claude, or any other dispatch.
Does NOT write <topic>_plan.md or <topic>_research.md — the curator is the sole writer of those files.
Does NOT execute the plan (out of scope for this skill).

5.5 Cross-references (the three references/ files)

The curator prompt embeds the two dispatch-template references inline; the dispatcher itself does not inline them. The full set of references/ files the curator prompt pulls from:

references/curator-framing-prompt.md — the curator identity + pipeline + frozen-brief block + Phase 1–6 instructions. The dispatcher reads this file and concatenates it with the frozen brief to compose the dispatch prompt (§5.3).
references/deep-research-dispatch-template.md — referenced from the curator prompt; used inside Phase 1 to dispatch deep-research. The dispatcher does NOT touch this file.
references/ask-claude-validation-template.md — referenced from the curator prompt; used inside Phase 4 to dispatch the ask-claude evidence-diff. The dispatcher does NOT touch this file.

references/structured-brief-10q.md is the reusable 10-question brief template (see See Also).

6. Session Management

One curator session per plan. Capture curator_session_id from output line 1 of the ask-hermes dispatch.
Resume the curator for: continuing the brief, adding sections, requesting re-validation, asking the curator to expand a phase.
Never resume across topics. Same plan = resume, different plan = fresh curator session.
deep-research sessions are NOT resumed by the curator. Curator captures the <topic>_research.md output and moves on; the research session expires naturally.
ask-claude sessions are NOT resumed. Claude is one-shot for the evidence-diff pass. Re-validation = fresh Claude session.
ask-hermes and ask-dev peer sessions (Phase 4b/4c) are NOT resumed either. Each is a one-shot validation round. Re-validation = fresh peer session, possibly on a different profile.
Dispatcher is one-shot. The dispatcher does NOT poll. Operator resumes the curator for follow-up.

Pre-build check — verify line-1 capture (per ~/workspace/general/plan_skill_plan.md §7, pitfall #10):

Before declaring the skill buildable, the dispatcher must empirically confirm that line 1 of ask-hermes output is the session id. This is a first-run failure risk: 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. If capture is unreliable, fall back to 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).

7. Output Files

<topic>_plan.md — the actionable plan. Pinned filename. Date in frontmatter, not filename. Single writer: the curator.
<topic>_research.md — the research evidence. Pinned filename. Curator is the sole writer. Phase 5 re-verify log is appended in-place.
Default save location: ~/workspace/plans/. Override with explicit path in the brief.
Phase 5 validation log: appended to <topic>_research.md (not a separate file). Contains: re-fetched URL, what was confirmed, any version/command drift found.

Same-topic clobber guard (per ~/workspace/general/plan_skill_plan.md §7.5): The curator checks for an existing <topic>_plan.md in the target dir. If found, the curator renames the existing file to <topic>_plan.<timestamp>.bak.md and saves the new plan to the canonical <topic>_plan.md. The operator can recover the prior version from the .bak.md file. Prevents silent clobber under --yolo.

8. Common Pitfalls (from plan §6, verbatim)

Don't dispatch deep-research without a focused question. Phase 0's brief (especially Q1 scope) must produce a focused research question. Vague → deep-research burns turns on landscape.
Don't paraphrase the research in assembly. Phase 2 copies structured data verbatim. Versions, code blocks, official URLs — copy as-is. Summarizing these is how plans get stale.
Don't skip Phase 3 (curator self-review). The first assembly is rough. The curator's self-review catches obvious gaps before Claude sees them.
Don't ask Claude to fix the plan — only to find flaws. The curator applies changes. Claude's role is adversary, not editor.
Don't resume across topics. Same plan = resume. Different plan = fresh curator session.
Don't try to use the dispatcher session for follow-up. The dispatcher is a one-shot. Resume the curator.
The research.md is evidence, not a deliverable. Users see the plan, not the research. research.md is for the curator's reference and future audits. Curator is the SOLE writer of this file.
Don't skip Phase 5 (URL re-verify) — that's the only step that catches stale versions. Claude can't verify currency; the curator must re-fetch official URLs and confirm.
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.
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).
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.
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.
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.
When a plan creates a new skill, verify the real distribution pattern before proposing it. Hermes skills ship as real per-profile file copies, not symlinks. Each profile has its own ~/.hermes/profiles/<p>/skills/<category>/<skill>/SKILL.md (separate inodes). The dispatcher MUST verify this empirically (stat -c %i on an existing shared skill like searxng-smart-search across profiles) before writing a plan that says "symlink the new skill to all profiles" — the assumption is wrong and the plan will produce a broken distribution. Reference: hermes-config-bulk-update/references/skill-replication-across-profiles.md. Plan template: "write the SKILL.md once to a canonical source, then cp to each target profile's skills/<category>/<skill>/ directory."
Live hermes config set is authoritative; web-searched config docs are not. When validating whether a Hermes config value, flag, or schema is valid, ALWAYS demand a live test (e.g., hermes -p <profile> config set <key> <value> and check exit code + output) rather than relying on web-searched documentation. The mintlify / hermes-agent.nousresearch.com docs can be stale, refer to a different schema, or omit valid values. Real example (July 2026): a peer agent claimed reasoning_effort: max was not a valid value based on web docs, but hermes config set agent.reasoning_effort max accepted it with exit 0 — max is in fact the current value of both the general and research profile configs. Rule: if a peer or Claude asserts "X is invalid config" without showing a live test output, push back and demand the test. Five seconds of hermes config set beats five minutes of arguing about docs.
Multi-model peer validation is the operator's de facto practice; do not skip Phase 4b/4c reflexively. For non-trivial plans (anything crossing 3+ files, architectural changes, anything that touches operator-standing rules), Phase 4a (Claude) alone has repeatedly missed things the general peer and dev peer caught. Default: run 4a + 4b for every non-trivial plan. Run 4c only if 4a or 4b found release-blockers. The cost is ~2-5 minutes per extra round; the leverage is real (cross-model blindspots are NOT a theoretical concern). See references/multi-model-peer-validation.md.

9. Verification Checklist (from plan §7, verbatim)

Phase 0 brief captured (1-10 operator answers, or operator said "you decide")
curator_session_id capture verified — empirically confirmed that line 1 of ask-hermes output is the session id (per pitfall #10; do this BEFORE declaring build complete)
Dispatcher Section 5 has trigger phrases (5.1), 10-Q script (5.2), curator dispatch command (5.3), and capture/handoff format (5.4) — the dispatcher can fire on the four trigger phrases, ask up to 10 questions with the documented stopping rules, dispatch hermes -p general chat -q "..." -Q --max-turns 600 --yolo after the brief is frozen, capture the curator_session_id from output line 1, and print the resume instruction to the operator.
<topic>_research.md exists with research evidence
<topic>_plan.md exists. Every task is 2-5 min of focused work, has exact file paths, complete code blocks, and a TDD cycle (failing test → run-fail → implement → run-pass → commit).
ask-claude validation report received (release-blockers / med / low)
Phase 5 URL re-verify log appended to <topic>_research.md
All release-blockers and agreed changes applied
curator_session_id returned to user
No execution of the plan attempted (out of scope for this skill)

Conditional on --no-research: If operator passed --no-research, the <topic>_research.md requirement and Phase 5 URL re-verify are SKIPPED. The Claude template's "URL currency" checks are also void in this mode. Final plan reflects this explicitly in its header.

10. Failure Modes (from plan §7.5, verbatim)

ask-claude unreachable (10.0.0.28 down / network error / session budget): Curator finalizes the plan WITHOUT the adversarial pass. Appends a header note: "Adversarial validation skipped — ask-claude unreachable. Recommend manual review before building." Continues to Phase 6.
deep-research errors out: Curator retries ONCE with the same prompt. If still failing, finalizes plan with header note: "Research phase failed. Plan based on operator-provided brief only. Currency cannot be guaranteed."
curator's own session expires (~5h idle): On the operator's next resume, the ask-hermes session returns an expired-session error. The operator starts a fresh plan build. The expired session is not auto-resumed.
same-topic plan already exists: The curator checks for an existing <topic>_plan.md in the target dir. If found, the curator renames the existing file to <topic>_plan.<timestamp>.bak.md and saves the new plan to the canonical <topic>_plan.md. The operator can recover the prior version from the .bak.md file. Prevents silent clobber under --yolo.
operator adds new constraints mid-pipeline: Operator resumes the curator. Curator classifies the constraint: if it affects the plan's architecture (security model, data flow, integration points), re-run Phases 2-4. If it's tactical (a flag value, a path, a UI affordance), apply forward and note the change in the plan header.

39 KiB Raw Blame History Unescape Escape