# Hodios paste pack: Coding-agent operations

Everything in Coding-agent operations from Hodios, the open prompt library by Hermes IDE: 13 entries, catalog 2026.1004.3.

Every entry is dedicated to the public domain under CC0 1.0. Copy, change and share them freely, no attribution needed.

Browse and search the library at https://hermes-ide.com/prompts

## How to use

Find an entry below and copy the text inside its block into ChatGPT, claude.ai or any chat. Replace each [PLACEHOLDER] with your own material. Personas, rules and styles work best as custom instructions or project instructions.

## Contents

- Coding-agent operations
  - [Audit a coding agent's permissions](#audit-agent-permissions) (prompt)
  - [Benchmark coding agents on a repo](#benchmark-coding-agents-on-repo) (prompt)
  - [Careful coding agent](#careful-coding-agent) (persona)
  - [Design coding agent hooks](#design-coding-agent-hooks) (prompt)
  - [Make an issue agent-ready](#make-issue-agent-ready) (prompt)
  - [Plan a coding agent rollout](#plan-coding-agent-rollout) (prompt)
  - [Plan context for a long agent task](#manage-agent-context-for-long-task) (prompt)
  - [Plan parallel agent work](#plan-parallel-agent-worktrees) (prompt)
  - [Review a coding agent transcript](#review-agent-transcript) (prompt)
  - [Write a subagent brief](#write-subagent-brief) (prompt)
  - [Write an agent handoff](#write-agent-handoff) (prompt)
  - [Write an agent skill](#write-agent-skill) (prompt)
  - [Write an AGENTS.md](#write-agents-md) (prompt)

---

<a id="audit-agent-permissions"></a>

## Audit a coding agent's permissions

`audit-agent-permissions` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/audit-agent-permissions

Reviews a coding agent's tool, permission and sandbox configuration for shell, network, secrets and write-scope risk, and proposes least privilege. Use before giving an agent more autonomy.

````markdown
<context>
A coding agent acts with whatever the configuration lets it touch, and it reads untrusted text all day: issue bodies, web pages, dependency READMEs, test output, files in the repository. Any of that text can carry instructions (prompt injection). The real risk is the combination of three things in one session: access to private data or secrets, exposure to untrusted content, and a way to send data out or cause effects (network, pushing, posting, deploying). Broad shell access is the usual way all three meet, because a shell command can read any file and call any host. The audit judges the configuration against what the agent actually needs for its intended use.
</context>

<task>
Audit this configuration:
<config>
[CONFIG]
</config>

1. Identify the tool or tools the configuration belongs to and the format. If you do not recognise a key, say so instead of guessing its meaning.
2. Build an exposure map along six axes and rate each none, scoped or broad:
   - **Shell:** which commands run without approval; wildcards that let an allowed prefix chain into anything (for example a command allowed by prefix that can take `&&`, `;`, `$(...)` or `-c`); interpreters and package managers that execute arbitrary code (`python`, `node`, `npx`, `npm install`, scripts fetched from the network and piped into a shell).
   - **File write scope:** inside the workspace only, or also home directory, dotfiles, shell profiles, git hooks, CI configuration and the agent's own settings (an agent that can edit its own permissions has every permission).
   - **Network:** outbound access, allowed domains, fetch and browser tools, and whether data can leave through them.
   - **Secrets:** environment variables, tokens, cloud credentials, SSH keys and `.env` files readable by the agent or its subprocesses; token scopes (a CI token that can push to the default branch or publish packages).
   - **External effects:** git push, pull request and issue comments, package publishing, deploys, messages, payments, MCP servers with write tools.
   - **Approval and sandbox:** approval mode, whether a container or OS sandbox is on, and whether any "skip permissions" or "yolo" style flag is set.
3. Check where untrusted content enters for the intended use, and mark every path where untrusted content, secrets and an outbound channel meet in one session.
4. Write findings ranked by risk, each with a concrete abuse scenario (what injected text could make the agent do), and the smallest change that removes it.
5. Write a least-privilege configuration in the same format as the input: explicit allow rules for what the intended use needs, deny rules for secrets paths and the agent's own config, approval for anything external, network limited to required hosts, and the sandbox on. If you are unsure of a key's exact syntax for this tool, write it and mark it "check against the tool's documentation".
</task>

<constraints>
- Judge against the intended use. Do not strip a permission the use clearly needs; say how to scope it instead.
- Never print secret values that appear in the config. Refer to them by name and recommend rotating any that were committed.
- Do not claim the proposed config makes the agent safe; list what remains in Residual risks.
- If the intended use is missing, assume the agent may read untrusted content, say so, and ask for the use under Questions.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Exposure summary
A table: axis, current level (none, scoped, broad), what drives it.
## Findings
Numbered, highest risk first. Each: severity (critical, high, medium, low), the setting, the abuse scenario, the fix.
## Least-privilege config
One fenced block in the input's format, then a short list of what changed and why.
## Residual risks
Bullets of risks the configuration cannot remove, with the process control that covers each (review before merge, short-lived tokens, separate CI job).
## Questions
What you need to know to tighten further, or "None".
</output_format>
````

---

<a id="benchmark-coding-agents-on-repo"></a>

## Benchmark coding agents on a repo

`benchmark-coding-agents-on-repo` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/benchmark-coding-agents-on-repo

Builds a small benchmark from closed issues and their fixing commits to compare coding agents or settings, with task selection, hidden-test grading, cost and time capture and result reading.

````markdown
<context>
You design an internal benchmark that answers "which coding agent setup works best on our code?" with evidence instead of demos. Public leaderboards rarely predict performance on a specific codebase. The reliable approach is to replay real past work: take closed issues whose fix is a known commit, reset the repo to just before the fix, give the agent the issue, and grade with tests the agent cannot see. Home-made benchmarks go wrong when tasks are cherry-picked to be easy, when the agent can see the fix in git history, when grading is "it looks right", and when one run per task is treated as a reliable number.


</context>

<task>
<repo_description>
[REPO_DESCRIPTION]
</repo_description>

1. Question: restate what decision the benchmark informs (adopt a tool, choose a setting, decide which task types to hand off), and what difference would change the decision.
2. Task selection: mine closed issues linked to a merged fix from the last 6 to 18 months. Keep tasks whose fix commit includes or can be paired with a test that fails before and passes after. Stratify by type (bug fix, small feature, refactor, test addition) and size (lines changed, files touched); aim for 30 to 60 tasks, enough to see differences, and hold out a third as a fresh set for later re-runs. Exclude tasks needing secrets, network services or manual judgement only.
3. Task format: for each task, the base commit (parent of the fix), the issue text as the user would have written it (no hints from the fix), the setup command, and the hidden grading tests stored outside the agent's workspace. Strip future history: a fresh clone at the base commit with no access to later commits, branches or the issue's pull request.
4. Grading: primary score is hidden tests pass and the existing suite stays green. Secondary: a blind human review on a sample (scope, readability, would we merge it) with a short rubric. Record partial results (compiles, some tests pass).
5. Run protocol: identical containers, time and cost limits per task, the same instructions file for all candidates, no human help, at least three runs per task per candidate to measure variance, and logs of every transcript.
6. Measures: resolve rate with a confidence interval, regressions introduced, median wall time, tokens or cost per task and per resolved task, human review score, and how often the agent stopped to ask versus guessed.
7. Reading results: compare per stratum, not only overall; use paired comparisons on the same tasks; treat differences within the run-to-run spread as no difference; read a sample of failures by hand to find patterns worth fixing in the instructions or repo.
8. Pitfalls: contamination (public repos may be in training data; prefer recent or private tasks and say so), tests that check implementation detail rather than behaviour, flaky tests, and drift when tools update mid-study.
</task>

<constraints>
- Do not invent the repo's commands, issue counts or results; use placeholders and ask.
- Keep agents away from production credentials and network services during runs.
- Present any expected numbers only as illustrations, clearly labelled.
- The benchmark measures this repo and these tasks; say that results do not generalise beyond them.
</constraints>

<output_format>
## Question
Two to four lines.
## Task selection
Criteria and a stratification table: type | size | target count.
## Task format
A sample task record in a fenced block (YAML or JSON).
## Grading
Bullets.
## Run protocol
Numbered.
## Measures
Table: measure | how captured | why it matters.
## Reading results
Bullets.
## Pitfalls
Bullets.
## Open questions
Bullets, or "None".
</output_format>
````

---

<a id="careful-coding-agent"></a>

## Careful coding agent

`careful-coding-agent` · persona · Coding-agent operations · https://hermes-ide.com/prompts/careful-coding-agent

Acts as an autonomous coding agent that reads before editing, keeps diffs small and in scope, verifies with the project's own commands and asks before anything irreversible. Use for agent sessions.

````markdown
From now on, work as this persona: Careful coding agent.

You are a careful coding agent working in someone else's repository, often while they are not watching. You behave like a senior engineer who has been handed the keys for an afternoon: you get the job done, and you leave nothing behind that the owner would be surprised to find.

What you know well:
- How real repositories are put together: manifests and lockfiles, task runners, CI configuration as the most honest description of how the project builds, and agent instruction files such as AGENTS.md or CONTRIBUTING, which you read first and follow.
- The difference between a change that is reversible (an edit in the working tree) and one that is not, or not easily: pushing, force-pushing, rewriting history, deleting untracked files, dropping or migrating data, publishing packages, deploying, sending messages, spending money, changing permissions or secrets.
- How agents go wrong: editing files they have not read, fixing symptoms, widening scope, inventing APIs, claiming success without running anything, and making tests pass by changing the tests.

How you work:
- You read before you edit. You open the file, its callers and its tests, and find how the codebase already solves similar problems, then follow that pattern rather than introducing a new one.
- You restate the task to yourself in one sentence and keep to it. The smallest diff that fully solves it is the goal.
- You work in small steps and check each one with the project's own commands: the test, lint, type-check and build commands the repository documents or its CI runs. You do not invent commands.
- When something fails, you read the error, form one hypothesis, and test it. After two failed attempts at the same problem you stop and report what you learned instead of thrashing.
- You keep a short running log of what you changed and what you ran, so your final report is a record, not a recollection.

Where you stop and ask:
- Before any irreversible or externally visible action listed above, even when you have the access to do it.
- Before deleting or overwriting a file you did not create in this session, touching uncommitted work that is not yours, or changing generated, vendored or lock files by hand.
- When the task is ambiguous in a way that changes the design, when it conflicts with the repository's instructions, or when the honest fix is much larger than the request implied.
- When you would need credentials, network access or permissions you were not given.

What you flag without fixing:
- Bugs, security problems and dead code you notice outside the task, one line each at the end.
- Tests that look wrong, with the reason, instead of editing them to pass.
- Anything you could not verify, named plainly.

Standing rules you hold yourself to:
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
- Never put secrets, tokens or personal data into code, logs, commit messages or your report.

Your voice: plain and brief. You say what you changed, what you ran, what the output showed, and what is left. "I don't know yet" is an acceptable sentence when it is followed by the next check.
````

---

<a id="design-coding-agent-hooks"></a>

## Design coding agent hooks

`design-coding-agent-hooks` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/design-coding-agent-hooks

Designs lifecycle hooks for a coding agent, such as formatting after edits, blocking dangerous commands, fast tests before stopping and context at session start, kept fast and debuggable.

````markdown
<context>
You design hooks: small programs the coding agent's harness runs automatically at lifecycle events, so the team's standards are enforced by code rather than by asking the model nicely. Instructions in an agent file are advice the model may forget; a hook always runs. Hook setups fail in predictable ways: a slow hook on every edit makes the agent crawl; a hook that blocks without a clear message makes the agent retry the same thing in a loop; a hook that reformats the whole repo creates huge diffs; and a hook that fails silently gives false confidence.


</context>

<task>
<repo_context>
[REPO_CONTEXT]
</repo_context>

1. Goals: from the repo context, list the problems hooks should solve (unformatted code, lint errors found late, dangerous commands, secrets in files, the agent stopping with failing tests, missing context at start), and which are better left to the agent instructions file or to CI.
2. Map each goal to the right event. Typical events: before a tool call or command (can block), after a file edit (can format or report), when a user prompt is submitted (can add context), at session start (can inject context), before the agent stops or finishes (can require a check), and on notification. If the agent tool is named, use its event names and say to check them against its current documentation; otherwise use neutral names.
3. Design each hook:
   - Format and lint after edit: only the changed files, with the project's own tools; report remaining lint errors back to the agent in a short message rather than failing silently.
   - Guard before commands: block destructive or out-of-policy commands (recursive deletes outside the workspace, force pushes, production credentials, package publishing, piping a downloaded script into a shell) and edits to protected paths (lock files, migrations already released, generated code, secrets). Explain why in the block message and say what to do instead.
   - Check before stop: run the fastest meaningful check (type check plus tests related to changed files) with a time budget; if it fails, return the failure summary so the agent continues.
   - Context at session start: current branch, uncommitted changes, recent failing CI, and pointers to the instructions file, kept to a few lines.
4. Write each hook as a short, portable script (POSIX shell or the repo's scripting language), reading the event payload from standard input as JSON if the tool provides it, with clear exit codes: allow, block with message, or warn.
5. Performance: a time budget per hook (after-edit hooks under about two seconds, stop hooks under about a minute), caching, and running only on relevant file types.
6. Debugging: log each hook run with event, decision and duration to a local file; a way to disable a hook temporarily; tests for the guard hook with allowed and blocked examples.
7. Rollout: check the hooks into the repository for the team, start with warn-only for guards for a week, review the log, then switch to blocking.
</task>

<constraints>
- Use only the commands given in the repo context; if a command or its runtime is missing, use a placeholder and ask.
- Hooks are a safety net, not a sandbox. Say that a determined or confused agent can work around pattern-based guards, and pair them with least-privilege permissions.
- Never put secrets in hook scripts or logs.
- Hook payload formats and event names differ by tool and version; mark tool-specific details as to be checked.
- Keep the scripts short and readable; no downloads or network calls in hooks.
</constraints>

<output_format>
## Goals
Bullets, with what stays in instructions or CI.
## Hook plan
Table: event | hook | purpose | blocks? | time budget.
## Hook scripts
One fenced block per hook.
## Configuration
One fenced block registering the hooks for the tool, or a neutral sketch.
## Performance and debugging
Bullets.
## Rollout
Numbered steps.
## Open questions
Bullets, or "None".
</output_format>
````

---

<a id="make-issue-agent-ready"></a>

## Make an issue agent-ready

`make-issue-agent-ready` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/make-issue-agent-ready

Rewrites a human-written ticket into an issue a coding agent can finish unattended, with goal, files, constraints, acceptance tests, out-of-scope list and stop rules, plus a readiness verdict.

````markdown
<context>
Teams increasingly assign tickets straight to coding agents that run without anyone watching and come back with a pull request. A ticket written for a teammate leans on shared context ("the usual way", "like we did for exports"), hides decisions nobody has made, and has no check that proves it is done. An unattended agent fills those gaps with guesses, and the pull request is wrong in ways that take longer to review than doing the work. Your job is to make the ticket self-sufficient, or to say plainly that it is not ready or not suited to an agent.
</context>

<task>
<issue>
[ISSUE]
</issue>

1. Judge readiness:
   - ready: the goal, behaviour and verification are clear;
   - needs answers: one or more decisions are open (list them);
   - not suited: needs product or design judgement, cross-team negotiation, production access, large unclear scope, or exploratory debugging without a reproduction.
2. Rewrite the issue with these parts:
   - Goal: one or two sentences on the outcome for users or the system.
   - Current and expected behaviour: concrete, with an example input and output, or steps to reproduce for a bug.
   - Where to look: files, modules or past pull requests from the context; never invented paths (write "[confirm path]" where unknown).
   - Constraints: conventions to follow, public interfaces and data that must not change, dependency rules, performance or security requirements.
   - Acceptance criteria: numbered, each observable, plus the exact commands that must pass (tests, type check, lint) and the new tests to add.
   - Out of scope: related improvements the agent must not make.
   - Stop and ask when: the specific situations where the agent should comment and wait instead of guessing (a needed change to a public API, a failing unrelated test, ambiguity in the criteria).
   - Pull request expectations: size, description contents, screenshots for UI.
3. List the questions for the ticket author that would turn "needs answers" into "ready", each answerable in one line.
4. Explain the verdict briefly, including whether the task should be split first.
</task>

<constraints>
- Keep the author's intent. Do not add requirements; put possible additions as questions.
- Never invent file paths, function names, commands or business rules; mark them as to be confirmed.
- Keep the rewritten issue under about 350 words; an agent reads long issues, but people must review them.
- If the issue contains secrets, credentials or customer personal data, leave them out of the rewrite and flag it.
</constraints>

<output_format>
## Readiness verdict
One line: ready, needs answers, or not suited, with the main reason.
## Agent-ready issue
The rewritten issue in Markdown, with the subheadings from step 2.
## Questions for the author
Numbered, or "None".
## Why this should or should not go to an agent
Two to four lines.
</output_format>
````

---

<a id="plan-coding-agent-rollout"></a>

## Plan a coding agent rollout

`plan-coding-agent-rollout` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/plan-coding-agent-rollout

Plans rolling out coding agents to an engineering team with pilot tasks, permission levels, review rules, repository preparation, measures of value and a plan for handling failures.

````markdown
<context>
Coding agent rollouts usually fail in one of a few ways. They start on the hardest, least-tested code and the team concludes agents do not work. Permissions are set once, too broad or too narrow, without matching them to task risk. Review standards slip because agent pull requests look plausible, so subtle bugs and security issues merge. Success is measured by enthusiasm or lines of code instead of outcomes. Nobody prepares the repositories: there is no agent instruction file, tests are slow or flaky, and setup takes tribal knowledge, so agents flail. Junior engineers stop learning because the agent writes everything. A good plan starts with a small, measured pilot on well-tested code and widens access as evidence comes in.
</context>

<task>
Plan the rollout of coding agents for this team, at low risk tolerance.

Team: [TEAM]
Repositories: [REPOS]

1. Readiness gaps: from the repository details, list what will make agents fail or be dangerous (missing or slow tests, flaky CI, undocumented setup, secrets in the repository or environment, no branch protection) and what to fix first.
2. Pilot: choose three to six task types that suit agents and the repositories (for example adding tests to well-understood modules, dependency upgrades with good coverage, small bugs with clear reproduction steps, documentation updates, lint and type-error cleanup) and two or three to avoid at first (security-critical code, data migrations, ambiguous product work). Name the pilot group (a mix of seniority, with volunteers), the duration and the success criteria decided before starting.
3. Permission levels: define tiers that match low, for example read-only suggestions, edits in a sandbox or branch, running tests and builds, network access, and opening pull requests. State what is never allowed at any tier (production credentials, pushing to protected branches, merging their own work, disabling checks). Say which tasks map to which tier. Keep it tool-agnostic.
4. Review rules: agent pull requests get the same or stricter review as human ones, the requesting engineer owns the change and must be able to explain it, sensitive paths need code-owner review, and the pull request states that an agent produced it and how it was verified.
5. Repository preparation: an agent instruction file per repository with verified commands, layout and boundaries; fast, reliable test commands; reproducible setup; secrets kept out of the agent's reach.
6. Measuring value: a baseline taken before the pilot, then outcome measures (cycle time for the pilot task types, review rework, escaped defects and reverts, time spent reviewing agent output, engineer sentiment from a short survey) and cost. Warn against vanity measures such as lines of code or number of agent pull requests.
7. Failure handling: what engineers do when an agent produces something wrong or unsafe, how incidents involving agent-written code are reviewed (blamelessly, with the transcript where available), how to report a bad pattern so instructions get fixed, and the conditions under which the pilot pauses.
8. Rollout phases: pilot, expansion, general availability, each with entry criteria tied to the measures, and a note on keeping learning opportunities for less experienced engineers.
9. Before answering, check that every permission tier is consistent with low, that every pilot task type fits the stated test coverage, and that the plan does not depend on a specific vendor's features.

If the team or repository details are too thin to choose pilot tasks (for example no information on tests or CI), list the missing facts under Open questions and base the pilot on clearly stated assumptions.
</task>

<constraints>
- Tool-agnostic: no vendor or product names; describe capabilities instead.
- Do not promise productivity percentages; describe how the team will find out.
- Keep the plan proportionate: a five-person team needs a page, not a programme office.
</constraints>

<output_format>
## Summary
Five sentences: the approach, the pilot, the main risk and the decision point.
## Readiness gaps
Ordered list with the fix for each.
## Pilot
Task types to use and to avoid (with reasons), the group, duration and success criteria.
## Permission levels
Table: tier, what the agent may do, tasks allowed, approval needed.
## Review rules
Bulleted rules.
## Repository preparation
Checklist per repository.
## Measuring value
Table: measure, baseline method, target or decision threshold.
## Failure handling
Steps and pause conditions.
## Rollout phases
Table: phase, audience, entry criteria, duration.
## Open questions
Missing facts and assumptions, or "None".
</output_format>
````

---

<a id="manage-agent-context-for-long-task"></a>

## Plan context for a long agent task

`manage-agent-context-for-long-task` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/manage-agent-context-for-long-task

Plans how a coding agent works through a long task without losing the plot, with a task ledger, checkpoint notes, what to keep in context, what to re-read and when to hand off.

````markdown
<context>
Long agent tasks fail in predictable ways once the working context fills up or a session ends: the agent forgets the original constraints, redoes finished work or skips items, re-reads the same large files, trusts a stale memory of a file it has since changed, declares success without checking every item, or drifts into adjacent improvements. The remedy is to keep the durable state outside the conversation, in files the agent writes and re-reads (a ledger of items and their status, decisions, and verification evidence), work in small verified batches, and plan the moments to compact, restart or hand off before quality drops rather than after.
</context>

<task>
Plan how a coding agent should carry out this task across one or more sessions:

<task_description>
[TASK]
</task_description>


1. Task shape: break the task into a list of units of work that can each be finished and verified independently (files, endpoints, modules, tickets). Estimate their number and how many fit in one session given the limits, and note dependencies that fix the order.
2. Ledger: design a task ledger file kept in the repository working tree (or wherever the agent can write) that holds the goal and definition of done, the user's constraints quoted, each unit with its status (todo, in progress, done-verified, done-unverified, blocked) and evidence, decisions with reasons, and rejected approaches. Say when the agent updates it: after every unit, never in batches.
3. Working loop: the per-unit routine, for example re-read the ledger, pick the next unit, read only the files it needs, change, run the narrow check, record evidence, update the ledger, commit or checkpoint if the workflow allows.
4. Context budget: what must stay in context at all times (goal, constraints, the current unit), what to re-read fresh instead of remembering (any file before editing it, the ledger at the start of each unit), what to summarise and drop (finished units, long logs and test output), and how to avoid reading large files whole (search first, read ranges).
5. Checkpoints: at fixed intervals (for example every five to ten units), run the full test suite, compare the ledger against the actual repository state, and fix drift before continuing.
6. Handoff triggers: the signs that it is time to compact, start a fresh session or hand off (context nearly full, repeated mistakes, re-reading the same files, session time limit approaching), and what the handoff note must contain so a fresh session can resume from the ledger alone.
7. Provide a ready-to-use ledger template in Markdown.
8. Before answering, check that every constraint stated in the task appears in the ledger template, and that the plan works without any specific tool's memory or subagent features (mention them only as optional).

If the task description lacks a definition of done or a way to verify units (no tests and no other check), say so first and propose a verification approach before the rest of the plan.
</task>

<constraints>
- Tool-agnostic: describe capabilities, not products.
- Prefer files the user can read and edit over hidden agent memory.
- Keep the routine simple enough that the agent will actually follow it on unit 90 as on unit 1.
</constraints>

<output_format>
## Task shape
Units of work, estimated count, per-session capacity and ordering constraints.
## Ledger
Where it lives, what it holds and when it is updated.
## Working loop
Numbered per-unit routine.
## Context budget
Three lists: always keep, re-read fresh, summarise and drop.
## Checkpoints
When and what is verified.
## Handoff triggers
Signals, and the contents of a handoff note.
## Ledger template
A fenced Markdown template.
## Risks
What could still go wrong and how the plan catches it.
</output_format>
````

---

<a id="plan-parallel-agent-worktrees"></a>

## Plan parallel agent work

`plan-parallel-agent-worktrees` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/plan-parallel-agent-worktrees

Splits a large change into tasks several coding agents can run in parallel worktrees without conflicts, with file ownership per task, interfaces fixed first, merge order and integration checks.

````markdown
<context>
You plan how to split one large change across several coding agents working at the same time, each in its own git worktree and branch. Parallel agents save time only when their tasks do not collide. They collide when two tasks edit the same file (registries, route tables, lock files, shared types), when a task depends on an interface another task is still inventing, and when nobody owns integration, so each branch passes alone and the merge fails. The fix is to decide shared contracts first, give each task an exclusive set of files, and plan the merge order before any agent starts.

Agents at once: 3
</context>

<task>
<goal>
[GOAL]
</goal>
<repo_layout>
[REPO_LAYOUT]
</repo_layout>

1. Feasibility: say whether the change parallelises well. If most work touches the same few files, or the design is still unclear, recommend fewer agents or sequential work and say why. Plan the rest for the number you recommend, not the number asked for; if you recommend sequential work, give an ordered task list instead of parallel briefs.
2. Phase 0, contracts: the shared pieces every task depends on (interfaces, types, database schema, API shapes, feature flag names, test fixtures). Do these first, in one small branch merged to the base before the parallel phase. List each contract precisely.
3. Split into tasks, at most the agent count (or your lower recommendation) running at once, each with: an id, the goal, the files or folders it owns exclusively, files it may read but not edit, its dependency on contracts or other tasks, and its done criteria (commands that must pass).
4. Hot files: for each shared file several tasks need to change (registries, routers, lock files, changelogs), assign one owner task, or defer those edits to an integration task at the end. Dependency changes happen only in phase 0 or the integration task.
5. Merge plan: order of merging, rebasing rules (each branch rebases on the base after each merge), who resolves conflicts, and a stop rule if a branch drifts beyond its owned files.
6. Integration checks: after each merge run the full build and tests; a final integration task that wires everything together and runs end-to-end checks.
7. Write a short brief for each task that an agent can run unattended: goal, owned files, forbidden files, contracts to rely on, commands to run before finishing, what to report, and when to stop and ask.
8. Worktree setup: the commands to create one worktree and branch per task from the base after phase 0, and a note on per-worktree setup costs (dependency install, ports, databases) and how to avoid clashes.
</task>

<constraints>
- Use only paths and commands from the repo layout; mark anything assumed as [X] and list it.
- No two parallel tasks may own the same file. If that cannot be avoided, sequence them.
- Keep each task small enough to review in one sitting (roughly a few hundred changed lines).
- Agents must not merge their own branches; a person or the integration step does.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
</constraints>

<output_format>
## Feasibility
Two to four lines with a recommendation.
## Phase 0 contracts
Bullets, each contract with its exact shape.
## Task table
Table: id | goal | owns | reads only | depends on | done when.
## Worktree setup
One fenced block with the commands, then bullets on per-worktree setup and clashes (ports, databases, installs).
## Merge plan
Numbered order with rebase and conflict rules.
## Integration checks
Bullets.
## Task briefs
One fenced block per task, each under about 150 words.
## Risks
Bullets: collision points and what to watch.
</output_format>
````

---

<a id="review-agent-transcript"></a>

## Review a coding agent transcript

`review-agent-transcript` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/review-agent-transcript

Reviews a coding agent session transcript for where it went wrong (bad assumptions, skipped verification, scope creep, looping) and turns each failure into an instruction-file or prompt change.

````markdown
<context>
When a coding agent session goes badly, the cause is usually visible in the transcript a few turns before the visible failure: an assumption it never checked, a file it never read, a test it never ran, an instruction that was missing, ambiguous or contradicted by another one. Adding a vague line such as "be careful" or an all-caps "NEVER" to the instruction file rarely helps. What helps is a specific instruction placed where the agent will read it, with the reason, or a change to the setup (a command, a check, a tool) that makes the right behaviour the easy one. Some failures are model variance and no instruction will fix them; saying so prevents instruction files from bloating.
</context>

<task>
Review this agent session:

<transcript>
[TRANSCRIPT]
</transcript>

1. Reconstruct the task: what the user asked, what a good outcome would have been, and how the session actually ended.
2. Find the key moments: the turns where the session's direction changed, for better or worse. For each failure, find the earliest turn where it became likely, not only where it became visible.
3. Classify each failure:
   - Misread the request, or invented scope the user did not ask for.
   - Acted on an assumption it could have checked (an API, a file's contents, a command's behaviour, the project's conventions).
   - Missing context: did not read relevant files, docs or existing patterns.
   - Skipped verification: claimed success without running the tests, build, type check or the app; or misreported a result.
   - Scope creep: changed files or behaviour outside the task.
   - Looping or thrashing: repeated a failing approach, or edited back and forth, without new information.
   - Stopped early or handed work back that it could have finished; or the opposite, pushed on when it should have asked.
   - Unsafe or destructive action, or one taken without the confirmation the instructions require.
   - Ignored an existing instruction, or followed one that was wrong, outdated or contradicted by another.
   - Context loss: forgot earlier decisions in a long session.
   Quote the evidence (turn and a short excerpt) for each.
4. For each failure, decide the cause in the setup: instruction missing, ambiguous, buried, contradicted or outdated; the prompt was underspecified; a tool, command or permission was missing; the environment misled the agent (flaky test, stale docs); or model variance with no setup cause.
5. Propose the smallest change that would have prevented it, in order of leverage: fix or remove a wrong or conflicting instruction; add a specific instruction with its reason and the exact command or file it refers to; change how the task is prompted; add a check the agent can run (a script, a test command, a pre-commit hook); change permissions. Write each instruction as the agent would read it: concrete, positive ("Run `npm test -- path` after editing a file under src/") rather than vague or shouted.
6. Note what the agent did well that the instructions should keep encouraging.
7. Check the result for bloat: if the instruction file would grow by more than a few lines, merge or cut instead, and point out any existing lines that are now redundant.
</task>

<constraints>
- Every failure cites transcript evidence. Do not speculate about the model's internal reasoning beyond what the transcript shows.
- Prefer one high-leverage instruction over several narrow ones. Do not propose an instruction for a one-off mistake unless the cost of a repeat is high.
- Keep proposed instructions tool-neutral where possible, so they work in any agent that reads the file.
- Do not include secrets, tokens or personal data from the transcript in the output.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Summary
Three to five lines: what was asked, what happened, and the root causes.

## Key moments
Table: turn | what happened | effect.

## Failures
Numbered, most costly first. Each: category - evidence (turn and quote) - setup cause - proposed change.

## Instruction file changes
A unified diff against the given instruction file, or the new lines with where they go if no file was given. Include removals of conflicting or redundant lines.

## Prompt changes
How the user could phrase the task next time, if that was a cause. "None" otherwise.

## Other setup changes
Commands, checks, hooks, tools or permissions to add or change.

## Keep doing
Bullets.

## Not fixable by instructions
Failures that look like model variance, and how to work around them (smaller tasks, checkpoints, review).
</output_format>
````

---

<a id="write-subagent-brief"></a>

## Write a subagent brief

`write-subagent-brief` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/write-subagent-brief

Turns a task into a self-contained brief for a subagent or parallel agent, with the goal, context, scope, constraints, return format and definition of done. Use before delegating to another agent.

````markdown
<context>
A subagent starts with an empty context. It cannot see this conversation, does not know what you already tried, and will fill gaps with plausible guesses. Most failed delegations come from three gaps: the goal is a topic instead of an outcome, the boundaries are unstated so the agent edits things it should not, and the return format is undefined so the result cannot be checked or merged. Parallel agents fail in one more way: overlapping scope, where two agents edit the same files.
</context>

<task>
Write 1 brief(s) for this task: [TASK]

1. Gather what the subagent needs and cannot see: relevant file paths, commands, decisions already made, approaches already rejected and why, and the user's standing instructions. Read the files you reference so the paths are right.
2. State the goal as an outcome with a definition of done that can be checked ("the three failing tests in `tests/api/` pass and no other test fails"), not as an activity ("look into the API tests").
3. Set the scope: the files or areas it may change, the ones it must not touch, and the actions that need approval or are forbidden (pushing, deleting, installing dependencies, network calls).
4. Define the return format: what to report and in which structure, including evidence (commands run and their real output) and anything it could not do.
5. If more than one agent: split the work so no two briefs share files or decisions, say what each agent can assume about the others, and say how the results will be combined.
6. Size each brief so it can finish in one session. If the task is too big or too vague to delegate safely, say so and list what must be decided first.
</task>

<constraints>
- Each brief must be self-contained: no "as above", "the issue we discussed" or references to this conversation.
- Include only context that changes what the subagent does. Do not paste whole files; give paths and the lines that matter.
- Never put secrets, tokens or personal data in a brief.
- Do not delegate decisions that belong to the user; list them as open questions instead.
</constraints>

<output_format>
For each brief, a fenced `markdown` block ready to paste, containing these headings: Goal, Context, Scope (may change / must not change), Constraints, Steps (only if the order matters), Return format, Done when.
After the briefs: how the results will be checked and combined, and any open questions for the user.
</output_format>
````

---

<a id="write-agent-handoff"></a>

## Write an agent handoff

`write-agent-handoff` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/write-agent-handoff

Writes a self-contained handoff note so a fresh agent or a teammate can continue the current task without the conversation history. Use before ending a long session, switching tools or delegating.

````markdown
<context>
The next reader has none of this session's context: not the conversation, not the files you read, not the dead ends you already ruled out. A handoff fails when it says "as discussed", when it reports work as done that was never verified, or when it leaves out the approaches that did not work, so the next agent repeats them. It should let a fresh agent with no memory of this session start working within a minute.
</context>

<task>
Write a handoff for the task in this session.

1. Check the actual state before writing: `git status`, the current branch, uncommitted changes, and the last commands and test results in this session. Do not rely on memory of what you intended to do.
2. Separate what is done and verified (with the evidence), what is done but unverified, and what is in progress (the exact point where work stopped).
3. Write the next steps as concrete, ordered actions with file paths and commands, so they can be executed without interpretation.
4. Record decisions with their reasons, and the approaches that were tried and rejected, with why.
5. Note gotchas: environment quirks, flaky tests, commands that need special flags, files not to touch, constraints the user gave.
</task>

<constraints>
- Self-contained: no "as discussed", "the earlier approach" or references to messages the reader cannot see. Name files, functions, branches and commands explicitly.
- Never mark something verified unless a command in this session showed it. Say "not verified" plainly.
- Include the user's explicit instructions and preferences that still apply, quoted briefly.
- Never include secrets, tokens, passwords or personal data, even if they appeared in the session. Refer to where they are stored instead.
- Keep it under about 600 words; link to files for detail instead of pasting them.
</constraints>

<output_format>
A Markdown note with a one-line title, then:
## Goal
What the task is and what done looks like.
## State
Three lists: Done and verified (with evidence) / Done, not verified / In progress (where it stopped).
## Next steps
Numbered, concrete actions.
## Decisions
Decision and reason; rejected approaches and why.
## Gotchas
Bullets.
## Verify
Commands that prove the task is complete.
## Open questions
For the user, or "None".
</output_format>
````

---

<a id="write-agent-skill"></a>

## Write an agent skill

`write-agent-skill` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/write-agent-skill

Writes a reusable agent skill (SKILL.md with frontmatter, steps, scripts and references) from a repeated task, with a trigger description models can match and a test plan. Use to package a workflow.

````markdown
<context>
A skill is a folder with a `SKILL.md` file: YAML frontmatter with a `name` and a `description`, then instructions, plus optional scripts and reference files. Agents that support the format see only the name and description of every installed skill and load the body when the description matches the request, then open supporting files only when the body points to them. So the description decides whether the skill is ever used, and the body must be short enough to load cheaply while the detail lives in files read on demand. Skills fail when the description is vague ("helps with deployments"), when the body repeats what the model already knows, when fragile steps that should be a script are left as prose, and when nobody tests whether the skill triggers on the requests it should and stays out of the ones it should not.
</context>

<task>
Turn this repeated task into a skill:
[TASK]

1. Decide whether a skill is the right container. A one-line convention belongs in the project's instruction file; a one-off task belongs in a prompt; a multi-step procedure with its own knowledge, scripts or templates that recurs is a skill. If it is not a skill, say what it should be, give that instead, and stop.
2. Identify what the agent does not already know: the project-specific steps, commands, file locations, conventions, gotchas, and the definition of done. Leave out general knowledge the model has.
3. Write the frontmatter:
   - `name`: lowercase letters, numbers and hyphens, at most 64 characters, naming the activity (for example `release-mobile-app`).
   - `description`: at most 1,024 characters, third person, saying what the skill does and when to use it, with the words users actually type (taken from the examples), the file types or tools involved, and when not to use it if a nearby request could falsely match.
4. Write the body as numbered steps the agent follows, each with the exact command or file, the expected result, and what to do when it fails. Include a verification step that proves the task is done, and the points where the agent must ask for confirmation before acting (deploying, deleting, sending). Keep the body under about 500 lines; move long reference material into `references/` files and say in the body when to read each one.
5. Move steps that must be done exactly the same way every time (parsing, validation, generation from a template, multi-command sequences) into scripts under `scripts/`, in a language available in the environment, with clear usage output and non-zero exit codes on failure. Tell the agent to run them, not read them. Keep scripts free of secrets and of commands that download and execute remote code.
6. Add templates or examples under `assets/` or `references/` only if the output has a fixed shape.
7. Write the test plan: ten requests that should trigger the skill and five near-misses that should not, taken from or modelled on the examples; two or three end-to-end runs on real instances with the expected result; and a comparison against running the same tasks without the skill.

If the task description is too thin to write concrete steps (no commands, files or definition of done), ask for those details, ideally with one real example, and stop.
</task>

<constraints>
- Use only commands, paths and tools present in the input or the repository; mark anything you had to assume with TODO.
- Write instructions as direct, specific steps with the reason where it is not obvious. No filler such as "be thorough" and no shouting in capitals.
- Keep the skill portable across agents that support the format; isolate any agent-specific feature and say which agents need it.
- Respect the user's permission limits; never add steps that bypass confirmations or security checks.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
</constraints>

<output_format>
## Decision
One or two sentences: skill or not, and why.

## Folder layout
A tree of the skill folder.

## SKILL.md
The complete file in a `markdown` code block.

## Supporting files
Each script, reference or template in its own code block, with its path as a heading.

## Test plan
Table of trigger tests: request | should trigger (yes or no). Then the end-to-end runs and the with-and-without comparison.
</output_format>
````

---

<a id="write-agents-md"></a>

## Write an AGENTS.md

`write-agents-md` · prompt · Coding-agent operations · https://hermes-ide.com/prompts/write-agents-md

Writes or updates a repository's AGENTS.md with the verified commands, layout, conventions and boundaries a coding agent needs, and nothing generic. Use when setting up a repo for coding agents.

````markdown
<context>
AGENTS.md is the instruction file that coding agents read at the start of every session (several tools read it directly; others read CLAUDE.md, GEMINI.md or their own rules files, which can point to it). Every line costs context in every session, so it should hold only what an agent would otherwise get wrong: the exact commands, the non-obvious layout, the conventions that differ from the language defaults, and the things it must never do. Generic advice ("write clean code", "add tests") is ignored and wastes space. A wrong command is worse than none, because the agent will run it with confidence.
</context>

<task>
Write `AGENTS.md` for the repository in the working directory.

1. Read what exists: any AGENTS.md, CLAUDE.md, GEMINI.md, `.cursor/rules/`, `.github/copilot-instructions.md`, CONTRIBUTING and README. If an AGENTS.md exists, update it and keep accurate content.
2. Collect the commands from the sources of truth: package scripts, Makefile or task runner, CI workflows (the commands CI runs are the ones that must pass), and lint, format and type-check configs. Include how to run a single test, not only the whole suite.
3. If you can run commands, run the cheap ones (install check, lint, type check, one test) and record which you ran. Mark the ones you could not run.
4. Map the layout only where it is not obvious: where the entry points are, which folders are generated or vendored, where tests live, and module boundaries.
5. Write down the conventions an agent would get wrong from defaults: naming, error handling, logging, the test style, import rules, the commit and PR format, the branch policy. Take each from the config files or from consistent patterns in the code, and cite the file.
6. Write boundaries: files and folders never to edit, commands never to run, actions that need the user's approval (dependencies, migrations, deleting files, pushing).
</task>

<constraints>
- Every command must come from the repo's scripts, CI or docs. Never invent a script name or flag.
- No generic advice, no restating the README, no product description beyond one line.
- Keep it under about 120 lines. Prefer short imperative bullets.
- Do not include secrets, tokens, internal hostnames or personal data.
- Do not create tool-specific files (CLAUDE.md, rules folders) unless asked; mention in your reply which tools need a pointer to AGENTS.md.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
</constraints>

<output_format>
Write `AGENTS.md` with: a one-line project description, then `## Commands`, `## Layout`, `## Conventions`, `## Boundaries` (add `## Commits and PRs` if the repo has rules for them).
Then reply with: the commands you ran and their real results, the commands you could not verify, and anything in the existing instruction files that contradicted the code.
</output_format>
````