HANDOFF.md files

To guide AI coding assistants precisely without overloading their context windows, withhandoff supports hierarchical directory crawling for HANDOFF.md files.

HANDOFF.md files are designed to shape the boundaries, permissions, and expectations for client-agent interactions. They are especially useful for external clients or guest agents who may not be supposed to work on certain portions of the codebase, or are supposed to interact and edit files in a specific way.

Choose where to place HANDOFF.md files

HANDOFF.md files can live in multiple locations, each with a different scope. The harness automatically matches files to their directory scope, loading files hierarchically:

HANDOFF.md files in the directory hierarchy above the target file are loaded in full. Files in other subdirectories are skipped or only loaded on-demand. See Resolution Sequence for more details.

Setting up a HANDOFF.md

Create a HANDOFF.md file at your project root or inside a subdirectory. The file should be written in clean, standard Markdown. Here is a recommended structure for your root HANDOFF.md:

# [Project Name] guidelines

Brief overview of the project and its architecture.

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Coding Standards
- Use TypeScript for all new code.
- Prefer functional components and hooks.
- Keep components small and reusable.

## Common Workflows
- Always run `npm test` before concluding a turn.
- Document any API changes in `docs/api.md`.

Writing Effective Guidelines

Because HANDOFF.md files are loaded into the agent's context window, writing concise and structured instructions will improve compliance and save token usage.

• Size: Keep HANDOFF.md files under 200 lines. Longer files consume more context space and may reduce instruction adherence.
• Structure: Use standard Markdown headers, bullet points, and tables to group related rules. Organized sections are easier for the agent to follow than dense paragraphs.
• Specificity: Write concrete, actionable guidelines. For example:
  • *"Use 2-space indentation"* instead of *"Format code properly"*
  • *"Run npm test before concluding a turn"* instead of *"Make sure tests pass"*
  • *"API handlers live in src/api/"* instead of *"Keep files organized"*
• Consistency: Periodically review your root and nested HANDOFF.md files to remove obsolete or conflicting rules.

Modular Imports (File linking with @)

For large codebases, you can break instructions into topic-specific files using modular imports with the @path/to/file syntax.

Both relative and absolute paths are supported. Relative paths resolve relative to the file containing the import, while paths starting with @src/ or similar absolute references can resolve from the repository root.

To reference other documentation or configuration files (such as a README.md or package.json), include the @ symbol before the path:

See @README.md for project overview and @package.json for available scripts.

# Additional Guidelines
- Git workflow: @docs/git-instructions.md

Referencing AGENTS.md

While project-wide developer rules in AGENTS.md files are not loaded by default in handoff context, you can explicitly reference and include them within your HANDOFF.md files using the @ syntax:

@AGENTS.md

Using this link loads the AGENTS.md rules directly into the context alongside the rest of your handoff instructions.

Import Rules & Resolution

The harness uses the following rules when resolving imports:

1. Acyclic Validation: Circular imports (e.g., A.md imports B.md, which imports A.md) are automatically detected and skipped to prevent infinite recursion.
2. Maximum Recursion: Imports can be nested recursively up to four hops deep.
3. Markdown-Only Recursion: The loader only parses recursive imports inside files ending in .md. Static configuration or other text files (like package.json) are loaded but not parsed for nested @ references.

Symlinks & Smart Deduplication

Symlink Support

Symlinked HANDOFF.md files or referenced files are fully supported. The harness resolves symlinks to their actual targets on disk, allowing you to share rules across different directories or sub-projects.

Smart Deduplication

To prevent duplicate files from filling the LLM context, the harness tracks every file path it loads during a session. If a file is already loaded into the context, it will not be re-loaded or duplicated when referenced again.

Resolution Sequence

When the agent starts a turn or reads a file, the harness loads HANDOFF.md files in a specific sequence:

1. Root Context Loading:
   • The root HANDOFF.md and all its recursive imports are loaded when the agent's session starts and are placed directly into the initial prompt.
2. Parent Directory Walking:
   • When the agent reads a file (e.g., src/components/Button.tsx), the loader walks directories from the file's folder up to the repository root.
   • It identifies any parent HANDOFF.md files (e.g., src/components/HANDOFF.md, src/HANDOFF.md) that have not yet been loaded.
   • It loads these files, parses their references, and appends them to the context alongside the file content.