Use when coordinating coding work through Hermes Code Workflow: brainstorm designs, classify intent, route work to Claude Code, Codex, OpenCode, Gemini, or Agent Client Protocol workers, run Python adapters when useful, verify outputs with evidence, and iterate before reporting.
Instalación
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Use when coordinating coding work through Hermes Code Workflow: brainstorm designs, classify intent, route work to Claude Code, Codex, OpenCode, Gemini, or Agent Client Protocol workers, run Python adapters when useful, verify outputs with evidence, and iterate before reporting.
A narrower sibling once focused on Claude-Code-centric workflow patterns. Treat that material as part of the broader Hermes Code Workflow class rather than a separate discoverability target. If you encounter a ccw artifact in the user-local skill tree, absorb any unique heuristics into this section or a support file and archive the narrow sibling.
Multi-agent workflow notes
Use this umbrella alongside multi-agent-dev-workflow / subagent-driven-development style support material when the task is specifically about delegation topology or review stages, but keep the main discoverability surface here at the class level.
Hermes Code Workflow is the house workflow for software development with Hermes as the control plane. It adapts the strongest ideas from Claude Code Workflow, Everything Claude Code, and Superpowers while staying native to Hermes: tool calls, skills, persistent memory, session search, cron jobs, delegation, terminal/process management, and Python helper adapters.
Core rule: workers execute; Hermes accepts or rejects. A coding agent, command-line interface, software development kit, or Agent Client Protocol session can implement, analyze, or review, but Hermes owns routing, scope control, verification, iteration, and user-facing reporting.
Iron Law: No completion claims without fresh verification evidence. If you haven't run the verification command in this turn, you cannot claim it passes.
coordinate multiple workers such as Claude Code, Codex, OpenCode, Gemini, Qwen, or other Agent Client Protocol/software development kit agents
create a repeatable workflow rather than a one-off manual edit
compare multiple implementations or ask one worker to review another
turn a vague request into a plan, execution pass, validation loop, and final report
Do not use Hermes Code Workflow as a substitute for explicit user approval on risky actions. If the next step is destructive, deploys to production, exposes credentials, force-pushes, or commits files the user has marked local-only, stop and confirm scope.
Roles
Human partner
defines goals and final preferences
approves high-risk changes and publishing decisions
can override this workflow at any time
⚠️ Publishing rule (user correction): NEVER auto-publish content (articles, posts, social media) without explicit user confirmation. Always preview first, wait for "发"/"ok"/"publish", then publish to draft — not directly to production. User has been burned by auto-publishing resulting in published content that couldn't be easily modified.
Hermes
clarifies only when ambiguity changes execution
classifies intent and chooses workflow chain
runs brainstorm phase for non-trivial work (see Brainstorm Phase below)
prepares worker briefs with constraints and acceptance checks
coordinates workers through native Hermes tools, Agent Client Protocol, official command-line interfaces, or software development kit adapters
verifies observable results before declaring success (see Verification Gate below)
captures durable lessons as skills when the work reveals a reusable pattern
Workers
Workers include coding command-line interfaces, software development kit-backed agents, Agent Client Protocol agents, and Hermes subagents. They may analyze, implement, review, test, or package work, but they do not self-certify completion.
Worker operational constraints:
Scope-locked. Only touch files named in the brief. If a dependency is missing, report it; do not silently edit extra files.
Goal-faithful. Implement exactly what the brief describes. Do not add features, refactor surrounding code, or "improve" things not in scope.
No self-certification. Worker success claims are input to verification, never proof. The worker must paste evidence; Hermes re-runs the check.
No silent skipping. If a step fails or is impossible, report what was tried, the exact error, and what is believed necessary. Never omit a step without explanation.
Preserve context. When output is truncated or a command produces excessive logs, paste the last 20 lines (or enough to show the outcome) rather than summarizing.
Brainstorm Phase
Hard gate: Do NOT dispatch any worker for implementation until the brainstorm phase is complete for non-trivial work. Quick chain (typos, single-line fixes, obvious changes) skips brainstorm.
When to brainstorm
New features, components, or significant behavior changes
Multi-file refactoring or architectural changes
Anything where "what exactly are we building?" is not 100% clear
Bug fixes with unknown root cause
Skip criteria — brainstorm may be skipped when ALL of these hold
Change is a single file or a small, self-contained set of files (at most three)
Goal is unambiguous: the user stated exactly what to change and what success looks like
No architectural decision, dependency trade-off, or design question is open
Risk is low: no security, data-migration, or public-facing contract change
The quick chain is the intended chain (typos, config edits, obvious one-liners, renames)
If any condition fails, brainstorm is mandatory.
Brainstorm process
Explore project context — check files, docs, recent commits, existing patterns. For deeper context, see huashu methodology: deep context gathering — scan for exact config values, architecture markers, entry points, and dependency descriptors.
Ask clarifying questions — one at a time, prefer multiple choice, understand purpose/constraints/success criteria
Propose 2-3 approaches — with trade-offs and your recommendation. Use huashu methodology: variations by dimension to ensure each approach explores a distinct architectural axis, not just cosmetic differences.
Present design — sections scaled to complexity, get approval after each section
Write design doc — save to .hcw/sessions/<session-id>/design.md
Spec self-review — check for placeholders, contradictions, ambiguity, scope
User reviews spec — wait for approval before proceeding
Transition to planning — create implementation plan or dispatch to planning worker
Brainstorm done criteria
Brainstorm is complete and Hermes may proceed to planning or dispatch when all of the following are true:
Goal is one sentence and testable. The user has confirmed what success looks like in observable terms.
Scope is bounded. The files, components, or areas to change are listed. No open question about "where does this live?"
Approach is chosen. At least two approaches were compared (or one was presented and accepted). Trade-offs are recorded.
Constraints are explicit. Performance, security, compatibility, or style constraints are written down, not implied.
Acceptance checks are defined. At least one runnable command or observable outcome that proves the work is done.
Open questions are resolved or parked. No blocking question remains unanswered. Parked items are listed with an owner and a deadline or decision rule.
User has approved the design. Explicit approval, not silence. If the user said "looks good" or "go ahead," that counts. No response does not count.
If any item above is not met, Hermes must continue the brainstorm phase — ask the missing question, propose the missing approach, or request the missing approval — before dispatching any worker.
Brainstorm termination guard
Brainstorm must not loop indefinitely. Apply these hard stops:
Question round limit. After 5 rounds of clarifying questions without reaching done criteria, stop. Present the human partner with a summary of what is resolved, what remains open, and a recommended default for each open item. Ask the partner to decide: accept defaults, answer remaining questions, or simplify scope.
Time budget. If the brainstorm phase has consumed more than 15 minutes of wall-clock time (or 20 conversational turns), pause and present the same summary. The partner may extend, simplify, or cancel.
Repeated question detection. If the same question is asked twice without a new answer, Hermes must stop and propose a default instead of asking again.
Scope growth detection. If the scope has grown by more than 50% compared to the original request (measured by number of files, components, or acceptance checks), stop and ask the partner whether to split into multiple sessions.
When any termination guard triggers, Hermes must not silently continue. Present the state and let the partner choose the next action.
Repair-loop termination guard
Repair loops in the dispatch-verify-iterate cycle are bounded:
Maximum repair rounds. Three rounds per failure type. A "round" is one dispatch of a focused repair brief followed by one verification attempt. After three rounds on the same failure, escalate to the human partner with a summary: original failure, what each round tried, and the persistent symptom.
Regression detection. If a repair round fixes the original failure but introduces a new failure in a previously passing check, count that as a new failure type with its own three-round budget. If two or more regressions accumulate, stop and escalate.
No-progress detection. If two consecutive repair rounds produce identical verification output (same error message, same exit code, same failure line), stop immediately. Repeating the same repair is a signal that the brief or approach is wrong, not that more attempts will help.
Total repair budget. Across all failure types, a session must not exceed 8 total repair rounds. After 8 rounds, escalate regardless of progress.
When escalating, include: the original goal, each failure type encountered, what was tried per round, and what verification evidence was collected.
For projects that include HCW's scripts/ directory, use hcw_design.py to automate the design phase.
The script implements patterns from huashu-design methodology:
deep context scanning, variations by architectural dimension, Junior Designer assumptions,
structured 5-dimension critique with Quick Wins.
# 1. Create design session with goal + constraints
python3 scripts/hcw_design.py init \
--goal "Add rate limiting to gateway" \
--constraints "Must use Redis""Must not add latency"# 2. Scan codebase for structure, languages, entry points
python3 scripts/hcw_design.py explore --dir . --session .hcw/sessions/<id>
# 3. Generate 2-3 design proposals with trade-off stubs
python3 scripts/hcw_design.py propose \
--goal "Add rate limiting" --approaches 2 --session .hcw/sessions/<id>
# 4. Produce final design.md from artifacts
python3 scripts/hcw_design.py finalize \
--session .hcw/sessions/<id> \
--scope "gateway/middleware/ratelimit.py" \
--criteria "pytest tests/test_ratelimit.py"# 5. Review design.md for completeness (8 checks)
python3 scripts/hcw_design.py review --design .hcw/sessions/<id>/design.md
Also see templates/design.template.md for a standalone design-document template.
Visual Design: huashu-design integration
When the task is UI/UX prototype, slide deck, animation, infographic, or design critique,
the submodule at skills/huashu-design/ provides a complete visual design skill.
Use hcw_design.py visual to create structured briefs:
Primary worker fails → next enabled worker → Hermes-native execution. Always preserve artifacts when switching workers.
Worker Transports
Agent Client Protocol workers (Planned — integration not yet wired)
Use Agent Client Protocol when the worker supports it and structured agent-process control helps.
Known pattern:
Gemini command-line interface can support Agent Client Protocol mode
future Agent Client Protocol-compatible tools should be routed here
Hermes usage:
Use delegate_task with Agent Client Protocol command fields when the environment exposes the worker as Agent Client Protocol.
Use Agent Client Protocol for long-lived structured worker conversations, strongly isolated tasks, and cross-model analysis.
Ensure the prompt is self-contained because Agent Client Protocol/delegated workers do not inherit chat context.
Official command-line interface / software development kit workers
Use vendor-supported interfaces rather than ad-hoc wrappers.
Examples:
Claude Code: official command-line interface and official software development kit-supported behavior where available
Codex: official command-line interface / software development kit-backed flow
OpenCode: official command-line interface
Other coding workers with official software development kits or command-line interfaces
Hermes usage:
Use terminal / process for command-line interface jobs.
Use Python adapters under scripts/ when software development kit orchestration needs structured input and output, retries, redaction, or result normalization.
Prefer bounded one-shot modes for simple tasks and tmux/background sessions for multi-turn work.
Semantic command-line interface invocation
Users can semantically specify command-line interface tools in prompts. Hermes auto-invokes the corresponding command-line interface:
User phrase
Hermes action
"用 Gemini 分析 auth 模块"
Route to Gemini in analyze mode
"让 Codex review 这段代码"
Route to Codex in review mode
"Gemini 设计，Claude Code 实现"
Multi-worker chain: Gemini analyze → Claude Code implement
"三个工具都看看"
Parallel dispatch to Gemini, Codex, Claude Code
Hermes-native workers
Use Hermes tools directly when that is simpler and safer:
delegate_task for reasoning-heavy subagents and parallel analysis
terminal for builds, tests, git, package managers, and command-line interfaces
read_file, search_files, patch, write_file for verification and controlled edits
todo for workflow state
cronjob only for durable scheduled follow-up, not recursive worker spawning
Python Adapter Layer
Hermes Code Workflow may include Python helper scripts to bridge Hermes with Agent Client Protocol/command-line interface/software development kit workers. Python adapters should be small, auditable, and transport-focused.
Use Python adapters for:
Model dispatch — calling a specific model (e.g. gpt-5.5) when the session model is wrong. See references/model-dispatch-python-adapter.md for the full recipe.
normalizing worker outputs into JavaScript Object Notation
launching software development kit-backed agents with stable options
adding timeout/retry/redaction around command-line interfaces
collecting repo context before dispatch
writing session artifacts such as .hcw/sessions/<session-id>/manifest.json
comparing worker results and producing a verification checklist
Do not use Python adapters to hide risky behavior. They must print the commands they run or write clear structured logs, and they must not embed secrets.
Recommended adapter conventions:
scripts/
hcw_dispatch.py # run one worker from a JSON brief
hcw_verify.py # run configured validation checks and emit JSON evidence
hcw_session.py # create/read/update Hermes Code Workflow session artifacts
hcw_design.py # automated design phase: explore, propose, review, finalize
hcw_summarize.py # summarize artifacts for final report
See references/model-dispatch-python-adapter.md for the model-dispatch adapter pattern (calling a specific model when the session model is wrong). See references/huashu-methodology.md for scaffolded design-agent adapters.
Dispatching to a specific model via Python adapter
When Hermes is running on model X but the task explicitly requires model Y (user preference, special capability, cost constraint), use a Python adapter to call the target model's API directly — do not use the session's model as a fallback.
When to use this pattern:
The user says "用 " and that model differs from the session model
Worker CLIs (Codex, Claude Code, OpenCode) don't support the target API endpoint
The task is prompt-based (document rewrite, analysis, generation) — not code execution
You've been corrected for using the wrong model earlier in the session
Procedure:
Discover available models via GET /v1/models with the user's API key
Test with a minimal prompt before the full task (saves minutes on bad model names)
Write a Python adapter using stdlib urllib (no pip needed) — see references/model-dispatch-python-adapter.md for a complete recipe
Run via execute_code (clean, isolated, no side effects)
Verify output quality before claiming completion
Key constraint: The adapter is for prompt-based LLM work. For code-heavy tasks (builds, tests, multi-file changes), use existing worker CLIs. If no CLI supports the required model, decompose the task: use Hermes for prompts and CLI workers for code.
Default Routing
Unless the user explicitly chooses a worker:
Implementation-heavy work: route first to Claude Code.
Architecture, diagnosis, broad analysis: route to Gemini/Agent Client Protocol or a Hermes reasoning subagent, then hand implementation to Claude Code.
Second opinion / review: route to Codex or OpenCode.
Provider fallback: if one worker fails due to quota/provider/runtime issues, switch worker and preserve artifacts.
Final acceptance: Hermes verifies directly.
Greenfield project bootstrap under HCW
When the user asks to create a brand-new project from an existing upstream implementation or reference repo, treat it as a plan-execute chain with mandatory brainstorm even if the end goal sounds straightforward.
Required sequence:
Inspect the upstream/reference repo directly with tools before proposing architecture.
Create the target project directory immediately when the user has already named it and there is no destructive ambiguity.
Save a concrete implementation plan under the new project's local planning path, for example docs/plans/....
Prefer a first-pass parity port before cleanup when the user explicitly wants a reimplementation of an existing tool. Preserve behavior first; refactor second.
Be explicit about the verification boundary. For exploit, privilege, kernel, or destructive tooling, distinguish:
build/test verification you can safely run now
live runtime validation you are intentionally not executing
If subagents are used in parallel on the same new repo, reconcile their outputs against the actual working tree before reporting status. Do not trust a subagent summary that says the repo is still scaffold-only once local file inspection shows implementation landed.
Recommended user-choice frame when the target is a port/rewrite:
A: 1:1 behavior-first port
B: idiomatic rewrite with behavior parity
C: minimal single-arch/single-mode starter
D: 1:1 first, then refactor
Default recommendation: D when the user wants an HCW-style implementation of an existing upstream tool and future cleanup is acceptable.
Chain Selection Decision Aid
Use this table to pick the right chain. Read top to bottom; the first matching row wins.
Condition
Chain
Why
Committing, pushing, or releasing is the goal
Ship chain
Shipping has its own validation gates; skip it only if the user says "don't commit yet."
The task is a failure, crash, regression, or unknown root cause
Debug chain
Diagnosis before fixing; do not guess and patch.
The task is small, low-risk, single-file or trivially scoped, and the user did not ask for planning
Quick chain
Skip brainstorm and worker overhead.
Tests are meaningful for the new logic (new feature, bug fix with reproduction, library, application programming interface)
test-first development chain (compose with plan-execute or subagent-driven)
Write failing test first, then implement.
The plan has three or more independent tasks that can run in parallel
Subagent-driven chain
Fresh subagent per task, parallel execution, per-task review.
The user asked for multi-perspective analysis, second opinions, or high confidence
Multi-worker chain
Gemini analyze → Claude Code implement → Codex/OpenCode review.
When in doubt, prefer plan-execute chain — it is the safe default. Compose chains when conditions overlap: for example, a non-trivial feature where tests matter uses plan-execute with test-first development embedded in the dispatch step.
Chain-selection scoring heuristic
When the decision matrix above does not produce a clear winner, score each candidate chain on four dimensions. Weights reflect operational impact: getting the chain wrong on a high-risk task costs more than picking a slightly slower chain on a trivial one.
Dimension
Weight
What to measure
Risk
0.35
Security, data integrity, public-facing contract, production deployment. Low = 1, Medium = 2, High = 3.
Scope
0.25
Number of files and cross-module dependencies. 1 file = 1, 2-3 files = 2, 4+ files or cross-module = 3.
Test leverage
0.20
How much value tests add. No meaningful tests = 1, regression guard = 2, core correctness proof = 3.
Parallelism
0.20
Number of independent sub-tasks. Single task = 1, 2 tasks = 2, 3+ independent tasks = 3.
Tie-breaking: when two chains score within 0.3 of each other, prefer the chain with more verification stages. When the risk dimension alone is 3 (high), always use at least plan-execute regardless of the total score.
Recursive decomposition heuristic
When a task is too large for a single worker dispatch, decompose it. Use these thresholds to decide when decomposition is needed and when to stop:
Decompose when any of these hold:
The plan has more than 7 discrete steps.
The brief would need to list more than 10 relevant files.
The estimated worker time exceeds 20 minutes (or 30 conversational turns).
The task spans more than two distinct programming languages or frameworks.
The acceptance checks require more than 5 distinct commands.
Decomposition procedure:
Split along module, file-group, or concern boundaries — not along temporal steps.
Each sub-task must have its own goal sentence, relevant files list, and acceptance checks.
Sub-tasks should be independently verifiable. If sub-task B cannot be verified without sub-task A completing first, they are sequential steps, not decomposition targets.
Target 3-7 sub-tasks per decomposition. Fewer than 3 means the task was not actually too large. More than 7 means the decomposition itself needs further splitting.
Stop decomposing when:
Each sub-task fits within a single mini brief (1-2 files, one sentence goal, 1-2 acceptance checks).
The sub-task can be completed by one worker in under 10 minutes.
Further splitting would create sub-tasks with no independent verification value.
Decomposition output format:
.hcw/sessions/<session-id>/
decomposition.md # list of sub-tasks with dependencies, ordering, and per-task acceptance checks
Orchestration depth limit
Orchestration depth is the number of nested delegation layers: Hermes dispatches a worker, which may internally spawn subagents, which may spawn further subagents. Depth is measured from the original user request to the leaf worker.
Task risk
Maximum depth
Rationale
Low
3 layers
Simple tasks need minimal delegation overhead.
Medium
4 layers
Multi-step work may need subagent splitting.
High
5 layers
Complex, high-stakes work benefits from deep specialization, but each layer adds verification cost.
Depth counting rules:
Hermes dispatching a worker counts as layer 1.
A worker spawning a subagent counts as layer 2, and so on.
Hermes-native tool calls (read_file, search_files, terminal) do not count as depth layers — they are direct actions, not delegation.
Parallel dispatches at the same depth count as one layer, not one per dispatch.
When the depth limit is reached:
Do not spawn another delegation layer. Instead, the current worker must complete the task using its own tools and reasoning.
If the worker cannot proceed without deeper delegation, it must report this as a blocker with the specific capability gap.
Hermes may then restructure the task (re-decompose, change chain, or escalate to the human partner).
Depth escalation path:
If a task's natural decomposition requires more depth than the risk level allows, Hermes should either:
Increase the risk classification (and document why), or
Flatten the decomposition (merge sub-tasks to reduce nesting), or
Escalate to the human partner with a recommendation.
Workflow Chains
Quick chain
Use for small, low-risk changes. Skips brainstorm phase.
Inspect relevant files and git status.
Dispatch one worker or edit directly only if user explicitly wants Hermes to do it.
Verify diff and run the smallest meaningful check.
Report changed files, checks, and risks.
Plan-execute chain
Use for non-trivial features or multi-file changes.
Plan — produce concise plan with files, steps, checks, and risks. Save to .hcw/sessions/<session-id>/plan.md.
Dispatch — Claude Code or selected worker with the plan.
Verify — Hermes runs verification gate.
Iterate — until acceptance or blocker.
Multi-worker chain
Use when confidence matters.
Brainstorm — design phase with Hermes.
Analyze — dispatch to Gemini/Agent Client Protocol for strategic analysis.
Implement — dispatch to Claude Code with analysis output.
Review — dispatch to Codex/OpenCode for independent review.
Cross-validate — Hermes reconciles findings, requests fixes if needed.
Verify — final verification gate.
Subagent-driven chain
Use for plans with multiple independent tasks. Inspired by Superpowers subagent-driven development.
Read plan — extract all tasks with full text and context.
Per task:
a. Dispatch fresh implementer subagent (isolated context, no session pollution).
b. Implementer reports: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.
c. Dispatch spec compliance reviewer subagent.
d. If spec issues found → implementer fixes → re-review.
e. Dispatch code quality reviewer subagent.
f. If quality issues found → implementer fixes → re-review.
g. Mark task complete.
Final review — dispatch reviewer for entire implementation.
Verify — Hermes runs verification gate.
test-first development chain
Use for new logic, bug fixes, libraries, application programming interfaces, or anything where tests can be meaningful.
Define expected failing test.
Worker writes/runs failing test.
Worker implements minimal fix.
Worker runs tests to green.
Hermes verifies test evidence and diff.
Debug chain
Use for failures and unknown root causes.
Reproduce or collect the exact failure.
Identify hypotheses; do not patch blindly.
Test the strongest hypothesis.
Implement the smallest fix.
Run regression checks.
Capture the root cause in final report.
Ship chain
Use only when committing/pushing/releasing is in scope.
Inspect git status and ensure only approved files are included.
Run full project validation.
Prepare commit with configured identity and sign-off when required.
Push only when user has requested or approved it.
Report commit hash and remote branch.
Failure Routing
When a chain step fails, Hermes decides the next action based on the failure type. Do not re-dispatch blindly; route based on what actually happened.
Failure type
Symptom
Hermes action
Worker runtime crash
Worker process exits non-zero, times out, or produces no output
Retry once with the same brief. If it fails again, switch to the fallback worker and preserve any partial artifacts.
Acceptance check failure
Worker output claims success but the command fails or output does not match
Send the exact failure message back to the same worker with a focused repair brief (not the original full brief). Limit to three repair rounds.
Spec compliance failure
Reviewer finds the implementation does not match the goal or violates constraints
Return specific gaps to the implementer with line references. Re-run spec compliance review after fixes.
Code quality failure
Reviewer finds maintainability, safety, or idiomatic issues
Return issues to the implementer. If issues are low severity and the user wants speed, flag them as known and proceed.
Scope creep
Worker modified files or behavior outside the brief
Revert out-of-scope changes. Re-dispatch with a tighter brief or add the scope explicitly if the change is justified.
Ambiguous or missing context
Worker reports it cannot proceed because the brief is incomplete
Hermes gathers the missing context, updates the brief, and re-dispatches.
After three repair rounds on the same failure, stop and escalate to the human partner with a summary of what was tried and the persistent failure.
Session Artifacts
For substantial work, maintain artifacts under a local, gitignored path unless the repo intentionally tracks them:
Design session artifacts (when using hcw_design.py)
When the design phase runs before implementation, it produces its own session tree that feeds into the implementation session above:
.hcw/sessions/DSN-YYYYMMDD-HHMMSS/
manifest.json # goal, context, constraints, status
events.jsonl # design event log
exploration/
codebase.json # codebase scan: structure, languages, entry points
proposals.json # 2-3 design approaches with trade-offs
review.json # review verdict and check results
design.md # final design document
If a project already has an established planning/session directory, use that instead. Do not commit Hermes Code Workflow artifacts unless the user asks.
Agent Development Brief (multi-phase, agent-to-agent handoff)
For large-scale rewrites, ports, or greenfield builds that span multiple phases and will be handed to another agent for execution, use Agent Development Brief format — not the standard Dispatch Brief.
When to use
Full-stack rewrite (e.g., Node.js → Go backend)
Multi-month refactoring projects
Any task the user says "给agent去开发" or explicitly wants a self-contained document for another agent
Full architecture, interface specs, code templates
Tasks
One dispatch unit
Phase-by-phase with 10-60+ tasks
Tests
Mentioned as checks
Full test templates with httptest/mock examples
Docs
Not included
Documentation requirements per task
Required sections
Getting Started (from scratch) — clone, checkout, build, smoke test, dev loop
Architecture — ascii/mermaid diagram + directory layout with every file's purpose
Golden Rules — hard constraints the agent must follow
Phases — each phase has:
Task list with file paths, Go interface signatures, code templates
Provider/API priority matrix
Testing requirements with examples
Documentation requirements — GoDoc, API comments, user-facing docs per task
Build & Run — compile, test, vet, docker commands
Pre-commit checklist — vet, test, format, secrets scan
Example
The Go backend rewrite plan at plan/go-backend-rewrite.md in the BoosAPI repo demonstrates this format. It includes:
Bootstrap steps (clone → build → curl healthz)
60+ tasks across 5 phases with Go interface signatures
Provider priority matrix
httptest test templates
Documentation requirements per task
Pre-commit checklist
All in English
User preference embed
When the user says "合并成一个文档", "写好提示词", or "给agent去开发":
Merge all separate plan docs into ONE English markdown file
Include from-scratch bootstrap steps (clone, install deps, build, smoke test)
Lead with Golden Rules the agent must follow
Keep task descriptions concrete (file paths, function signatures, expected output)
Save as plan/<descriptive-name>.md and commit if the user wants it tracked
Dispatch Brief Template
Every worker brief should include the sections below. Hermes fills every bracket before sending; no field may be left as a placeholder.
You are a worker in Hermes Code Workflow. Hermes is the orchestrator and will verify your output.
Do not commit, push, or publish unless the brief explicitly says so.
Repository: <absolutepath>
Session: <sessionidentifier>
Mode: analyze | implement | review
## Goal<oneprecisesentencedescribingwhatsuccesslookslike>## Environment Context- Branch: <currentbranch>- Language/runtime: <primarylanguageandversion>- Build tool: <buildcommand>- Test command: <testcommand>- Lint/format command: <commandor "none">## Relevant Files<listeveryfiletheworkershouldreadormodify, withabsolutepaths><ifdiscoveryisneeded, stateexactlywhattosearchforandwhere>## Constraints- Only modify files listed above unless discovery reveals a necessary dependency; if so, list it in your output.
- Follow project conventions for naming, structure, and error handling.
-<project-specificstylerules, ifany>-<forbiddenareas:generatedcode, vendoreddependencies, lockfiles, etc.>## Acceptance Checks<listconcretecommandstheworkermustrunandwhatsuccesslookslikeforeach>
Example:
-`npm run build` exits 0 with no errors
-`pytest tests/test_auth.py` exits 0 with 0 failures
- Diff touches only files under src/auth/
## Required Output
When finished, produce this exact structure:
-**summary**: one paragraph describing what was done
-**files changed**: list of file paths with one-line description per file
-**checks run**: each command executed, its exit code, and outcome (pass/fail)
-**evidence**: paste the last 10 lines of test or build output showing the result
-**blockers**: anything that prevented full completion, with what was attempted and what actually happened
-**risks**: anything the orchestrator should verify or watch for
If you cannot complete a step, report what you tried, the exact error, and what you believe is needed. Do not skip silently.
## When Stuck1. Report the blocker with the exact error message or unexpected behavior.
2. State what you tried and why you expected it to work.
3. Propose one or two next steps.
4. Do not guess or patch blindly; the orchestrator will decide how to proceed.
Brief quality checklist (Hermes checks before dispatch)
Every bracket in the template above is filled with a concrete value
Goal is one sentence, testable, and scoped to what the worker can observe
Relevant files list is complete; no discovery left implicit
Acceptance checks are runnable commands, not vague descriptions
Constraints call out every forbidden directory or file pattern
No secrets, tokens, or environment variables are embedded in the brief
Dispatch Brief Tiering
Hermes chooses between two brief tiers based on task complexity. The tier decision is made before filling the template.
Mini brief — use when ALL of these hold
Single file or at most two closely related files
Goal fits in one sentence with no open design questions
No architectural decision or dependency trade-off
Acceptance checks are one or two commands at most
Risk is low: no security, data-migration, or public-facing contract change
What the mini brief omits compared to the standard brief:
Section
Mini brief treatment
Environment Context
Omit build tool, lint command, and language/runtime if the worker can infer them from the repo
Relevant Files
May list a single file or directory instead of every path
Constraints
May collapse to one line: "Follow existing project conventions. Only modify files listed above."
Required Output
May reduce to: summary, files changed, checks run, evidence
When Stuck
May omit entirely for trivial tasks
The mini brief always includes: Repository, Session, Mode, Goal, and Acceptance Checks. These five fields are never optional.
Standard brief — use for everything else
Use the full template defined above. When in doubt, use the standard brief; a slightly longer brief costs less than a failed dispatch and repair loop.
Tier selection rules
If the quick chain is the intended chain, default to mini brief.
If brainstorm was required, default to standard brief.
If the worker is in review mode and the diff is small (under 50 lines), a mini brief is acceptable.
If the task involves more than two files, always use the standard brief.
If the task touches security-sensitive code, always use the standard brief with the full Constraints section.
Verification Gate
Iron Law: No completion claims without fresh verification evidence.
Hermes must verify before final success:
BEFORE claiming any status or expressing satisfaction:
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
- If NO: State actual status with evidence
- If YES: State claim WITH evidence
5. ONLY THEN: Make the claim
Skip any step = lying, not verifying
Red flags — STOP
Claim
Requires
Not sufficient
Tests pass
Test command output: 0 failures
Previous run, "should pass"
Build succeeds
Build command: exit 0
Linter passing, logs look good
Bug fixed
Test original symptom: passes
Code changed, assumed fixed
Agent completed
version control system diff shows changes
Agent reports "success"
Requirements met
Line-by-line checklist
Tests passing
Verification mapping — claim to evidence
Claim type
Hermes must run
Acceptable evidence
Tests pass
The test command from the brief (e.g. npm test, pytest)
Exit code 0, zero failures, output matches expected count
Build succeeds
The build command from the brief (e.g. npm run build, cargo build)
Exit code 0, no errors in stderr or stdout
Lint/format clean
The lint or format-check command
Exit code 0, no warnings or errors reported
Bug is fixed
A reproduction command or test that previously failed
Exit code 0, output no longer shows the original symptom
Files changed as expected
git diff --name-only
Only files listed in the brief appear; no unintended additions or deletions
No secrets in diff
git diff scan for token/key patterns
No matches for common secret patterns (API keys, passwords, tokens)
Feature works end-to-end
The acceptance check commands from the brief
All commands exit 0 with expected output
Dependency install succeeds
Package manager install command
Exit code 0, lock file updated if applicable
If a claim type is not listed above, Hermes must define the verification command before accepting the claim.
If verification fails, use an iterative repair loop with the concrete failure message.
Review Gate
For non-trivial code changes, use two review dimensions (inspired by Superpowers two-stage review):
Spec compliance: Does the implementation satisfy the stated goal and constraints? No over-building, no missing requirements.
Code quality: Is it maintainable, safe, idiomatic, tested, and scoped?
Use separate workers or separate review passes when possible. Spec compliance must pass before code quality review begins.
Spec compliance checklist (run first; must pass before code quality review)
## Spec Compliance Review
Reviewer: <workerorHermes>
Session: <sessionidentifier>
Brief goal: <copytheone-sentencegoalfromthebrief>### Goal coverage- [ ] Every acceptance check in the brief was run and passes
- [ ] The implemented behavior matches the stated goal — not more, not less
- [ ] No requirements from the brief are missing
### Scope discipline- [ ] Only files listed in the brief (or justified dependencies) were modified
- [ ] No unrelated refactors, style changes, or "while I was here" edits
- [ ] No new dependencies added without being listed in constraints
### Constraint adherence- [ ] Every constraint from the brief is satisfied
- [ ] Forbidden files, directories, or patterns were not touched
- [ ] Project-specific style rules (if any) were followed
### Acceptance evidence- [ ] Worker pasted command output (not a summary) for every acceptance check
- [ ] Exit codes match what Hermes observes when re-running the same commands
- [ ] No placeholder or stale evidence (output is from this run, not a previous one)
### Verdict
PASS — proceed to code quality review.
FAIL — return specific gaps with line references to the implementer for repair.
Code quality checklist (run after spec compliance passes)
## Code Quality Review
Reviewer: <workerorHermes>
Session: <sessionidentifier>### Correctness- [ ] Logic is correct for all expected inputs and edge cases
- [ ] Error handling is explicit — no silent swallowing, no empty catch blocks
- [ ] No hardcoded secrets, credentials, or tokens
### Safety- [ ] User input is validated at system boundaries
- [ ] No injection risks (command, SQL, path traversal, cross-site scripting)
- [ ] No unsafe type casts, unchecked array access, or off-by-one errors in security-sensitive paths
### Maintainability- [ ] Functions are focused (under 50 lines preferred)
- [ ] Files are cohesive (under 800 lines preferred)
- [ ] No deep nesting (under 5 levels)
- [ ] Names are descriptive; no single-letter variables outside loops
- [ ] No dead code, commented-out blocks, or debug statements left behind
### Testing- [ ] New or changed logic has test coverage
- [ ] Tests cover the happy path and at least one failure or edge case
- [ ] Tests are deterministic — no reliance on external state, order, or timing
### Verdict
PASS — implementation is ready for final report.
FAIL — return issues to the implementer. If issues are low severity and the user wants speed, flag them as known and proceed.
Model Selection
Use the least powerful model that can handle each role to conserve cost and increase speed.
Task type
Model tier
Examples
Mechanical implementation (1-2 files, clear spec)
Fast/cheap
Isolated function, config change
Integration and judgment (multi-file)
Standard
Feature with dependencies
Architecture, design, review
Most capable
System design, security review
Chain Selection Scoring Heuristic
Use the decision aid above first. When multiple chains still look plausible, score the task so Hermes has a repeatable tie-breaker.
Inputs
Rate each dimension from 0 to 3:
risk — security, data, deployment, and public-surface impact
scope — number of files, components, and moving parts
test leverage — how much confidence can be gained from writing or running tests early
parallelism — how naturally the task splits into independent tracks
references/agent-development-brief.md — agent-to-agent handoff brief format
references/model-dispatch-python-adapter.md — dispatching to a specific LLM model via Python adapter when the session model doesn't match the task requirement
Common Pitfalls
Letting a worker self-certify. Worker success is input to verification, not proof.
1b. Forgetting bilingual docs (zh-CN). When the user's project maintains en/zh-CN doc pairs (README.md + README.zh-CN.md, docs/.md + docs/.zh-CN.md), updating only the English variant is an incomplete change. Always mirror the update to the Chinese counterpart in the same commit. This applies to Hermes-Code-Workflow and any project that follows the same pattern.
Skipping context discovery. Always inspect enough repo state to avoid wrong assumptions.
Skipping brainstorm phase. "Simple" projects are where unexamined assumptions cause the most wasted work.
Over-orchestrating tiny tasks. Use the quick chain when the scope is small.
Under-orchestrating risky work. Use plan/review/verification gates for production, security, data, and deployment changes.
Mixing local artifacts into commits. Keep Hermes Code Workflow session files, helper scripts, and plans uncommitted unless approved.
Using vague prompts. Give workers exact goals, paths, constraints, and checks.
Treating Agent Client Protocol/software development kit/command-line interface as equivalent. Pick the transport based on reliability, observability, and official support.
Starting code quality review before spec compliance passes. Wrong order — spec first, quality second.
Don't delete apparently-unused files without understanding context. A file that isn't imported anywhere may still be valuable (Web3 providers, app-wide wrappers, layout components). Before removing, check:
Is the file part of a pattern (e.g. providers → layout → app)?
Does it export something that could be used dynamically or via config?
If unsure, ask the user — do not assume "unused = safe to delete."
When you do get corrected, restore the file AND its deps, then build.
Leaking real IPs, names, or credentials in test data. Never use real IP addresses, hostnames, usernames, or other sensitive identifiers in test code, examples, or YAML configs committed to git. Use placeholder values (10.0.0.x, node-a/node-b, example.com, test-user). If sensitive data was committed:
Single recent commit: git commit --amend && git push --force-with-lease
Multiple commits / full history cleanup: git checkout --orphan clean-branch && git add -A && git commit -m "..." && git branch -D main && git branch -m clean-branch main && git push -f origin main — this creates a single clean commit with no history
- Single commit:git commit --amend && git push --force-with-lease
- Multiple commits (full history wipe preferred):git checkout --orphan clean-branch && git add -A && git commit -m "..." && git branch -D main && git branch -m clean-branch main && git push -f origin main
- A new commit on top still exposes the old data in git history — force push is required.
Confusing agent-local plans with team-facing plans. In projects with a dual-plan convention (e.g. BoosAPI/metapi):
When the user says "写进plan", look for a top-level plan/ directory. When they say "规划" or "设计文档", use docs/plans/ or .hcw/sessions/.
If unsure which to use, ask — mixing them up wastes time.
Using the wrong model for HCW tasks. When Hermes is running on model X but the user's workflow requires model Y, dispatching or executing work with model X is a workflow error — expect a correction. Before dispatching any worker or doing Hermes-native execution, check whether the session model matches the user's expected model for this task. If it doesn't match:
Use a Python adapter to call the target model's API directly (see references/model-dispatch-python-adapter.md)
Do not ask "should I switch models" — figure it out from context or user preference
Check User-specific workflow notes below for this user's model preference
Live example of this failure: user said "等等 怎么是用deepseek-v4写的啊" after HCW dispatched work with the wrong session default instead of gpt-5.5. This is a first-class correction signal — update HCW's model handling if it happens more than once.
User-specific workflow notes
Gitea-only project infrastructure
This project runs entirely on self-hosted Gitea at git.boos.lat. All documentation, plan files, code module paths, Go import paths, and repository URLs must reference the Gitea instance only — never GitHub. When the user says "不要出现github的 只用我们自己的gitea", that means:
This user expects gpt-5.5 (via api.boos.lat/v1, key sk-boos4721) for any development/documentation work dispatched through HCW. If the session model is gpt-5.5, dispatch workers directly. If it is something else (e.g. deepseek-v4-flash, any other default), use the Python adapter pattern (references/model-dispatch-python-adapter.md) to call gpt-5.5 directly — do not use the session's model for HCW tasks.
Live example from this user's sessions: User said "等等 怎么是用deepseek-v4写的啊" after HCW dispatched work using the session default model instead of gpt-5.5. The fix was a Python adapter calling gpt-5.5 directly via the OpenAI-compatible API at api.boos.lat/v1.
Scope discipline: "全部写完" means ALL items in the plan
When the user says "全部写完" (write all of them), "全部", or references a plan with an expectation of full implementation, implement EVERY outstanding item listed in the plan — do not pick a subset. This user's communication is ultra-brief; if they reference a plan's remaining items list and say "全部写完", they mean implement every uncompleted item, not just the first one or the easiest ones. If the scope is too large for a single session, mention the total items and ask "一个一个来还是全部?" rather than silently choosing a subset.
High-risk local exploit validation on real hosts
When the user asks to validate a local exploit or privilege-escalation proof of concept on the current machine, do not stop at build success or theoretical analysis. If the user explicitly requests a live test, Hermes should:
perform prerequisite environment discovery first:
identify the target binary path and whether it is a symlink
inspect the live file permissions and readability as the intended unprivileged user
check whether the implementation's file-open strategy matches the real target layout
create a dedicated unprivileged demo user when safe and appropriate for local testing
run the binary as that demo user and collect real evidence
if it fails, use strace or equivalent syscall tracing to locate the exact failing syscall before proposing fixes
report clearly whether the failure is:
an implementation bug
an environment incompatibility
or a target precondition mismatch
Important pitfall discovered in practice:
On Alpine/BusyBox-style systems, /bin/su may be a symlink to /bin/bbsuid with mode 4111 (---s--x--x), which means an unprivileged user can execute it but cannot open it read-only.
A copy-fail style implementation that assumes File::open("/bin/su") or equivalent O_RDONLY access will fail early with EACCES before reaching the AF_ALG / splice overwrite path.
In that environment, the right next step is to compare with the reference implementation and/or add explicit preflight checks for target readability and target-path compatibility instead of claiming the exploit path itself failed.
Verification pattern to preserve:
build the candidate binary
create a dedicated demo user
execute the binary as that user against the live target
if failure occurs, capture the exact syscall transcript showing the failure point
include the target file mode, symlink resolution, and the failing syscall in the final report
Gemini dispatch with prompt review
When dispatching Gemini (gemini CLI = Claude Code) for BoosAPI coding tasks:
Prompt must be reviewed. Before launching Gemini, present the prompt text to the user for approval. Wait for explicit go-ahead before running.
Use pty mode. Always launch Gemini with pty=true and background=true — the CLI requires a pseudo-terminal.
Alpine quirk. Gemini's run_shell_command tool is not available on Alpine Linux. If it gets stuck on that error, kill the process and do the remaining fixes manually.
Prompt style. Keep prompts concise (bullet points), list exact files to modify, and include acceptance checks (e.g. cargo check). Gemini has already explored the project structure, so no need to re-explain the full codebase.
Monitor progress. After dispatching, use process(action='wait') or process(action='poll') to track progress. Gemini runs can take 2-10 minutes.
Verify after completion. Always run cargo check / npx tsc --noEmit after Gemini finishes. Fix any compilation errors it introduced.
Pre-dispatch (before sending the brief)
Relevant skills loaded before acting
Intent classified and chain selected
Brainstorm phase completed for non-trivial work (design approved)
Worker transport chosen deliberately: Agent Client Protocol, official software development kit/command-line interface, or Hermes-native
