# Author prompts that agents can follow

A codon runs without you. Once a hank starts, the agent receives your prompt, a workspace, and nothing else: no conversation, no clarification, no second chance to say what you actually meant. Everything the agent needs to do the task correctly has to be in the prompt text, and anything extra in that text costs tokens and attention without helping.

This page is about writing prompts that survive that arrangement. It covers the structure a reliable prompt tends to have, the workspace facts the agent cannot guess on its own, how to anchor file paths so the agent does not go searching, how to keep maintainer notes out of the model's context, where standing rules belong, and how to validate the wiring before you spend a run on it. The examples come from shipped fixtures, so you can check each one against a real prompt.

## Give every prompt four parts

A prompt gives a codon – one sealed agent task in the sequence – what it needs to work without us beside it. Four parts cover that need:

* **Context** – what the task is.
* **Process** – which steps to take.
* **Constraints** – what not to do.
* **Output** – what success looks like and which files to write.

Not every prompt needs all four as labeled sections. For a simple task, **Process** and **Output** are enough, folded into plain prose. For a fuller task, rename the parts to headings that fit the domain. The skeleton below is an illustrative template, not a shipped prompt:

```text
Context: <what this task is>
Process:
1. <step>
2. <step>
Constraints: <what not to do>
Output: <success condition and file to write>
```

The `minimal-single-provider` quickstart prompt shows the brief end of that range. It anchors the input and output, gives two requirements, preserves the source deadline, and sets a short line limit – all in a few sentences:

```markdown
# Summarize the meeting notes

Read the file `notes.txt` inside the `read_only_data_source` directory in your current working directory (use shell commands like `cat` — the directory may be a symlink).

Write `summary.md` in the current working directory containing:

1. A one-sentence summary of what the meeting decided.
2. Exactly three bullet points: one decision, one owner, one deadline — taken from the notes.

Keep the deadline's wording from the notes. Do not infer a month, year, calendar date, or other detail that the notes do not give.

Nothing else. Keep it under 15 lines.
```

The `anchor-hank` fixture shows the fuller end. Its prompt opens with role and context, then uses `Read`, `Extract`, and `Write` sections. In the excerpt below, a line containing `…` marks omitted source lines; it is not literal prompt or output content:

```markdown
# Normalize Aster (Datalab dialect)

You are the mechanical extraction stage for supplier **Aster Metals (AST)**. Aster submitted **two** documents against RFQ NC-RFQ-0042 — extract both, faithfully, and do not decide between them. Which one wins is a judgment call for the `validate-and-repair` codon, not you.

…

Use shell commands (`cat`, `ls`) to read from `read_only_data_source/` — it may be a symlink, so avoid the native Read/LS tools on it.

…

Write a single JSON array of the two envelope objects — the original document first, then rev2 — to `./envelope-aster.json` relative to the working directory returned by `pwd`. The agent workspace is already the current directory. Do not add an execution-directory prefix or write under `read_only_data_source/`. Before finishing, run `test -s ./envelope-aster.json`.

This file is the contract for `validate-and-repair`: it must be able to load `envelope-aster.json` and see both Aster submissions independently, with nothing pre-merged or pre-decided.
```

When precision matters, go further and prescribe the artifact itself. Require every field, copy source values verbatim, use `null` for a value the source lacks, and prohibit computing, converting, or inferring values. If an item does not resolve cleanly, route it to a named ledger – a file that records the item and its reason – rather than dropping it. Continuing should never mean silently omitting an item. We work through that rule in [validate and repair](/tutorial/3-validate-and-repair).

The anchor's failure-routing line and output headings make that rule visible:

```markdown
You check ALL normalized envelopes (eight suppliers: AST, BCN, CDR from the dialect codons; DVR, EMB, FJR, HBR, IRS from the extracts codon) plus the intake survey against the RFQ contract and the corpus lookups, repair what you can repair deterministically, and route everything else — including one deliberately unresolvable judgment call — to a typed exception ledger. **Continue must never mean silent omission**: if a line, a part, or a whole quote doesn't cleanly resolve, it must appear in `exception-ledger.json` with a reason. It may never simply vanish from your output.
…
**`validated-records.json`** — a JSON array, one object per line that survived Steps 1–3 (the losing Aster document's lines are dropped here, since Step 1 already logged that as a conflict), with exactly these fields:
…
**`exception-ledger.json`** — a JSON array, one object per exception you emitted above, with exactly these fields:
```

For a task that produces a file, make writing part of success: require the agent to write the artifact's skeleton first, extend it in at least four write steps, and self-verify with `wc -l` before finishing. For tight-versus-loose prompt strategy and how to account for context the agent lacks, see [designing codons and handoffs](/author/designing-codons-and-handoffs).

## Explain the workspace before assigning work

The four parts tell the agent what to do; they do not tell it where it is. During a run, the agent's working directory is `agentRoot/`, a workspace inside the managed execution directory. Task inputs are exposed there as `read_only_data_source/`, and prompt-named outputs land in `agentRoot/`. The agent knows none of this unless the prompt says so. See [the runbook](/operate/runbook) for output management and [the execution directory](/reference/execution-directory) for link and store mechanics.

The `init-fixture` shipped scaffold states the convention directly:

```markdown
# Project Analysis (Haiku)

Please analyze the files in the `read_only_data_source` directory located in the current working directory and create a comprehensive analysis report.

Your analysis should include:

1. Very brief overview of the files in that directory

Please create your analysis in a file called `analysis-haiku.md` in the execution directory.
```

Explain the read method too. The data directory is exposed through a symlink at `agentRoot/read_only_data_source/`; when symlinking fails, a copy is used. The captured text prompts above use `cat` and `ls` to avoid native-tool symlink problems. Use that guidance for text when the harness provides an authorized shell, not as a universal replacement for every file-reading tool.

For an image, shell output from `cat image.png` is file bytes, not an image attachment the model can inspect. A native image read can expose visual content only when the selected model accepts images and the harness passes that format through as image content. Name the available image-reading tool in the prompt only after checking that route. If visual inspection is required but unavailable, the codon must report that limitation rather than claim it inspected the image. This is capability guidance, not a capture proving every image format or model route.

Keep three layers separate when writing tool instructions: the **model** supplies reasoning and input modalities; the **harness** supplies the actual tools and session behavior; the **execution host** supplies installed programs, credentials, filesystem access, and network access. A model name does not guarantee a browser, image reader, shell executable, or the same tools as your authoring environment. See [models and harnesses](/reference/models-and-harnesses#two-harnesses-one-dispatch-rule).

`agentRoot/` is a working directory, not a sandbox. Likewise, `read_only_data_source` is a convention: its symlink or copy does not enforce read-only filesystem permissions. The Claude Agent SDK route sets `permissionMode: "bypassPermissions"` for harness permission prompts; that does not grant operating-system privileges, change mount permissions, or override host/tool policy. Enforce isolation with the host's permissions and deployment controls, and keep prompt prohibitions as an additional instruction rather than a security boundary.

Give the agent an inventory instead of asking it to explore:

```text
- read_only_data_source/: read-only inputs
- <current directory> (the agent workspace)/: files to create
- <utility directory>/: utility scripts
- <template path>/: template
```

Then add the context the agent lacks – where it sits in the sequence and where its output goes next:

```text
Previous step: <what was produced>
This step: <what to do>
Next step: <who consumes this output>
Boundary: Your job is transformation only. Don't analyze or draw conclusions.
```

If a task has a held-out answer key – reference material the task must not inspect – follow [designing codons and handoffs](/author/designing-codons-and-handoffs) for the prohibition and its reason; use that page's anchored-line format.

## Anchor every file path you name

The #1 cause of wasted agent turns is a prompt that names a file without saying where it is. Without an anchor, the agent may wander through `find`, `ls`, or `grep` before it starts the actual work. Anchor both sides of the task: the reads and the writes.

Use directory-only template tokens. `<%AGENT_ROOT%>` means the agent's current working directory, and `<%DATA_DIR%>` means `read_only_data_source`. These tokens anchor paths; they cannot include a file's contents in the prompt. See the complete [four-variable table](/reference/hank-json#replace-paths-with-template-variables) when choosing a token.

When a required file is known to exist, say "this file always exists; do not search elsewhere." Do not ask the agent to read it back to confirm; that invites another round of reads.

Anchor writes as carefully as reads. The agent workspace is already the current directory – name the write target relative to that directory, do not add an execution-directory prefix, and say that the target is **not** under `read_only_data_source/` when that distinction matters.

## Test each sentence before keeping it

Once a prompt draft exists, apply the "why" test to every sentence: does the agent need it to do the task? If yes, keep it; if no, cut it. Ask the inverse too: what does the agent need that isn't here? Missing instructions can do more damage than the excess.

Here is the test applied to the minimal prompt from earlier. Each instruction is marked **keep** when it supplies a needed input, action, constraint, or success condition:

1. "Read the file `notes.txt` inside the `read_only_data_source` directory in your current working directory" – **keep**: it anchors the input.
2. "Use shell commands like `cat` – the directory may be a symlink" – **keep**: it selects the read method for this workspace.
3. "Write `summary.md` in the current working directory" – **keep**: it anchors the output.
4. "A one-sentence summary of what the meeting decided" – **keep**: it defines one success condition.
5. "Exactly three bullet points: one decision, one owner, one deadline – taken from the notes" – **keep**: it defines the shape and source of the remaining output.
6. "Keep the deadline's wording from the notes. Do not infer a month, year, calendar date, or other detail that the notes do not give." – **keep**: it prevents unsupported date detail.
7. "Nothing else. Keep it under 15 lines." – **keep**: it limits the artifact.

Every line survives the test, which is what a tight prompt looks like. The inverse question is where this one falls short: the prompt does not specify what to do when `notes.txt` is missing. Treat that omission as a design gap instead of guessing a behavior.

In [designing codons and handoffs](/author/designing-codons-and-handoffs), we see what happened when a prompt named the wrong supplier set: the codon followed the hardcoded enumeration, not the author's intent.

## Keep author notes out of agent context

A prompt file often serves two audiences: the model that executes it and the maintainer who edits it months later. Put a maintainer note in an HTML comment (`<!-- … -->`) when the agent does not need it. Hankweave strips single- and multi-line comments before sending the prompt to the model, consumes the trailing newline so blank lines do not accumulate, and applies the same stripping to system prompts. It replaces template variables first, then strips comments from the assembled content.

The file below documents a prompt without sending those notes to the LLM (the language model receiving the prompt):

```markdown filename="prompts/refactor.md"
# Refactoring Task

Refactor the authentication module to use JWT tokens.

<!-- CONTEXT: Migrating from sessions to JWT for mobile app.
     See ENG-234 for requirements. -->

Preserve backward compatibility with /api/v1/\* endpoints.

<!-- WARNING: Don't touch OAuth flows - separate ticket (ENG-256). -->
```

The agent receives the prompt without those comments:

```markdown filename="prompts/refactor.md"
# Refactoring Task

Refactor the authentication module to use JWT tokens.

Preserve backward compatibility with /api/v1/\* endpoints.
```

This keeps the prompt self-documenting for maintainers without spending tokens on notes the agent does not need.

Use YAML frontmatter at the beginning of a prompt Markdown file for labeling only. Its allowed fields are `name`, `description`, `tags`, `version`, and `author`; it is not configuration. At prompt build, an unknown field fails the build with `Invalid prompt frontmatter:` followed on the next line by `Unknown frontmatter field(s): <keys>. Allowed fields: name, description, tags, version, author`.

Hankweave strips frontmatter before sending the prompt. With multiple files in a `promptFile` array, it parses and strips each file's frontmatter but retains only the first file's frontmatter. Do not confuse this labeling metadata with the hank's `meta` field: prompt frontmatter can surface in terminal user interface (TUI) display and event metadata, while `meta` identifies the hank and requires `name` and `version`. See [reference/hank-json](/reference/hank-json).

## Put standing rules in system prompts

Some context belongs in every run, and some belongs to one task. Put persistent context such as coding standards, style guidelines, and role framing in a system prompt. Keep task-specific instructions and information that can change between runs, such as files, in the task prompt instead.

Use the global level for context shared by every codon. At the root of `hank.json`, configure it with `globalSystemPromptFile` or `globalSystemPromptText`. Append codon-specific context with `appendSystemPromptFile` or `appendSystemPromptText`. The global text comes first, and the parts are joined with a blank line. When nothing is configured, no system prompt is sent.

For codon prompts, the runtime requires at least one truthy `promptFile` or `promptText`; if both are set, `promptFile` wins. The two codon append fields, `appendSystemPromptFile` and `appendSystemPromptText`, are mutually exclusive, as are the two hank-level global system-prompt fields. These are separate rules, not one universal XOR rule. Do not transfer the codon rule to sentinel prompt fields; use [sentinel configuration](/reference/sentinel-config) for that contract. For strict file references and the remaining field contract, see [reference/hank-json](/reference/hank-json).

For deciding whether discovered knowledge belongs in the global system prompt, a codon system prompt, a codon prompt, a rig, or a prerequisite check, use [discover before you freeze](/author/discover-before-you-freeze).

## Wire prompt files and validate the counts

With the prompt written, the remaining work is mechanical: reference the file correctly and confirm the wiring before running. Keep prompt files inside the hank directory – the directory containing `hank.json` and `prompts/`. In 0.10.0, `promptFile` names them with relative POSIX paths (using `/` separators). The strict path/ref contract, including rejection of absolute paths, `..` escapes, and symlinks for both prompt and system-prompt file fields, belongs to [reference/hank-json](/reference/hank-json#the-pathref-contract-r1--r2--r3).

> **VersionNote:** In 0.10.0, prompt and system-prompt file references are strict hank references. Absolute, `..`, and symlinked spellings that loaded on 0.9.x now fail validation. See [reference/hank-json](/reference/hank-json#the-pathref-contract-r1--r2--r3).

Use `promptText` for a short prompt. Put a longer prompt in `promptFile` so `hank.json` stays clean and the prompt remains editable and version-controlled. `promptFile` accepts one string or an array; an array concatenates its files in order with a blank line between them.

Run from the hank directory. Validate first, then start a headless run (without an interactive terminal) with a new execution:

```sh
bunx hankweave@0.10.0 hank.json data/ --validate
bunx hankweave@0.10.0 hank.json data/ --headless --start-new -o out
```

The two positional arguments are the hank path and data path. The first command checks the prompt wiring. The second starts the run and copies its outputs to `out`. The steps below walk through what to check at each stage.

1. **Validate from the fixture root.** Run validation before spending a run on the task.

**Check-it:** the captured output includes the per-codon prompt count and the `GOOD TO RUN!` box.

```text
      model: haiku │ mode: fresh │ prompts: 1 (13 lines)
…
╭─ GOOD TO RUN! ─────────────────────────────────────────────────────╮
│  1 codons • 1 prompts • 0 system prompts • 0 rigs • 1 checkpoints  │
╰────────────────────────────────────────────────────────────────────╯
```

2. **Start the headless run.** Use the explicit hank and data paths. The run writes the prompt-named artifact in the execution workspace; `-o out` copies it out.

**Check-it:** the captured output file contains one sentence followed by exactly three bullets.

```markdown
# Meeting Summary

The team decided to proceed with the Calloway vendor quote for the packaging line refit based on lower total cost and included installation.

- **Decision:** Go with the Calloway quote for packaging line refit
- **Owner:** Devon
- **Deadline:** PO issued by Friday the 12th
```

3. **Inspect the run banner and copied output.** The banner identifies `Source → data` and `Exec → ~/.hankweave-executions/<exec-id>`. The execution directory contains the agent workspace, `agentRoot/`, where the codon's prompt-named output lands. `-o out` copies outputs to a CWD-relative directory; without it, outputs stay in `agentRoot/`.

**Check-it:** the captured banner shows the source and execution paths.

```text
╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯
Created new execution directory: ~/.hankweave-executions/<exec-id>
New execution: <exec-id>
  Source → data
  Exec   → ~/.hankweave-executions/<exec-id>
```

4. **Break the path on purpose.** Point `promptFile` at a missing file and validate. Validation reports the codon and whether the path does not exist, is not a regular file, or is not readable.

**Check-it:** `--validate` exits 1 and names the codon and missing file.

```text
   • Codon 1 (write-line): promptFile "<workspace>/fixtures/scenarios/ref-violations/prompts/does-not-exist.md" does not exist
exit=1
```

Two details in the validation output are worth knowing before they surprise you. Validation counts `content.split("\n").length` for each codon's prompt file. A trailing newline produces an additional split entry, so the visible 12-line `summarize.md` appears as `13 lines`. The `system prompts` number counts `appendSystemPromptFile` files across codons; it excludes inline append text and the global system prompt. A displayed `0 system prompts` therefore does not prove that no system instructions will be sent. Check the global-setting indicator and the configured fields; [troubleshooting](/operate/troubleshooting#separate-misleading-messages-from-real-failures) also indexes this misleading label.

Validation warnings are not errors: an empty prompt file yields `<codon>: Prompt file "…" is empty`, while a prompt file over one megabyte yields `… is large (X.XXMB)`. A missing, non-regular, or unreadable `promptFile` or `appendSystemPromptFile` fails validation with the corresponding `does not exist`, `is not a regular file`, or `is not readable: …` wording. For misspelled field names, use the loader's did-you-mean guidance in [reference/hank-json#typos-and-suggestions](/reference/hank-json#typos-and-suggestions).

> **Pitfall:** A prompt that asks for analysis without a mandatory write protocol can finish with no file written. Require the artifact, incremental writes, and self-verification.