Skip to main content

How to Use Coding Assistants with Octant v2

Purpose: Teach developers how to get the best results when pairing with a coding assistant on Octant v2 work. Audience: Developers who want to use Claude, Cursor, Copilot, or similar tools with Octant v2. Level: Beginner Source of truth: This page describes conventions used across the docs; the workflow pages themselves are authoritative. Use this page when: starting your first coding assistant session for Octant v2, or when the assistant produces incorrect results. Do not use this page for: learning Octant v2 architecture — use the concept pages and tutorials instead.

Introduction​

The Octant v2 docs are written for humans first, but they also include structure that helps coding assistants stay on track.

The most important pieces are:

  • llms.txt at the site root for global context and version pins,
  • task cards on workflow pages for scoped instructions,
  • workflow manifests for runnable setup flows,
  • labelled code blocks that distinguish complete files from fragments,
  • copy-paste bundles for recovery,
  • an anti-patterns list that defines hard boundaries.

This page explains how to use those conventions without letting the assistant drive past the actual engineering judgment you still need.

Starting a session​

Before you open a specific tutorial or guide, give your coding assistant the contents of llms.txt. This file lives at the site root and contains the pinned repository versions, the source-of-truth hierarchy, and the key constraints that apply to all Octant v2 work.

Loading this file first means the assistant starts with the correct version pins. It also learns the most important guardrails: the Deployed Addresses page is authoritative for team-confirmed deployment addresses, pinned source is authoritative for contract behavior, and the latest GitHub branch should not be treated as authoritative.

Once the assistant has llms.txt, navigate to the specific workflow page you want to follow. The combination of global context from llms.txt, page-specific context from the task card, and the matching workflow manifest for runnable setup pages gives the assistant everything it needs to stay on track.

Understanding the callouts​

Each workflow page opens with a coloured callout box that tells the assistant (and you) how to treat the page. There are three variants:

Variant A appears on starter-template tutorials like the Hello World Strategy page. It reads: "Ask the assistant to follow this page in order, edit only the files named in each step, and run the verification commands before moving on. It should not modify dependencies/octant-v2-core, invent contract addresses, or skip compatibility notes." This tells the assistant it is in a step-by-step mode where order matters and certain directories are off limits.

Variant B appears on integration guides. It tells the assistant to treat the page as a reference rather than a sequential walkthrough, adapting the code examples to the developer's specific integration target.

Variant C appears on setup and environment pages. It signals that the page is about configuring tooling rather than writing strategy code, so the assistant should focus on environment variables, dependency installation, and build verification.

When you paste a workflow page into your assistant, the callout is the first thing it reads after the header block. It sets the operating mode for the entire session.

Using task cards​

Most workflow pages include a task card — a collapsible <details> block with the summary "Agent task card." Inside it you will find structured fields: Goal (one sentence describing the deliverable), Start repo (the exact repository and commit to work from), Core target pin (the core commit the page targets), Files to edit and Files NOT to edit (explicit scope boundaries), Required setup (environment variables, submodule pins), Verification (the exact commands to run), and Do not (task-specific anti-patterns).

To use a task card, expand it and paste its contents into your assistant session alongside the tutorial text. The assistant can then use the "Files to edit" list to stay in scope and the "Verification" section to confirm each step succeeded. The Task Card Format page documents every field in detail if you want to understand the rationale behind the structure.

Pay particular attention to the Core target pin field. It is the single most important staleness detector in the docs. If your local core checkout or starter submodule is not at that pin, the task card may be out of date for your workspace. Flag this to your assistant and consider re-validating the steps before proceeding.

Machine-readable workflow manifests​

Runnable setup paths in this docs bundle now include machine-readable sidecars under 09_agent_assisted_development/workflow_manifests/. Each manifest records the exact repo pins, commands, required environment variables, success criteria, expected git-status snapshots, and stop conditions for one workflow.

Use these manifests when you want a coding assistant to stay grounded during setup work rather than inferring the workflow from prose alone. They are especially useful for the first ten minutes of a session, when an assistant has to decide whether the failure it sees belongs to tooling, network, RPC, docs drift, or code issue.

The docs bundle also ships a small helper script at 09_agent_assisted_development/scripts/reconcile-starter-pin.sh for the starter-template path. That helper re-pins dependencies/octant-v2-core to the docs target and rewrites the local foundry.lock entry so the lock contents match the same pin.

See Workflow Manifests for the human-readable index of those sidecars.

Code-block labels​

Code blocks on workflow pages carry one of five labels:

  • Complete file — The block contains an entire file from top to bottom. Your assistant can write it directly to disk, replacing whatever was there before.
  • Fragment — The block contains a section of a file that must be inserted at the indicated location. It lacks imports, contract declarations, or other scaffolding.
  • Patch — The block shows a diff-style change to apply to an existing file.
  • Command — The block contains a shell command to run, not Solidity code.
  • Illustrative only — The block exists to explain a concept. It is not meant to be copied into your project.

Mixing these up is one of the most common sources of errors. If your assistant pastes a fragment as a complete file, the result will be missing imports and won't compile. If it treats a complete file as a fragment, you'll end up with duplicate declarations. When something doesn't compile after the assistant edits a file, check whether the code block label matches how the assistant used it.

Copy-paste bundles​

At the end of longer tutorials you will find a collapsed section titled something like "Complete files." This contains the final, compilable state of every file the tutorial modified. Think of it as a checkpoint: if your assistant has gone off track — maybe it applied a fragment incorrectly or skipped a compatibility fix — you can paste the full bundle to reset all edited files to the known-good state and continue from there.

These bundles are especially useful when you are iterating. Rather than re-running the entire tutorial, you can jump to the bundle, let the assistant write all the files, run the verification command, and pick up where you left off.

The anti-patterns list​

The Agent Anti-Patterns page defines hard boundaries that coding assistants must not cross. It covers things like not editing autogenerated smart contract docs, not inventing deployment addresses, not modifying dependencies/octant-v2-core, and not treating tutorial code as production-audited. Each task card links to this page, but it is worth including the URL in any custom system prompt you build for your assistant so it always has access to these boundaries regardless of which workflow page you are following.

The prompt library​

The Prompt Library page provides ready-to-use prompts for common Octant v2 tasks. Each prompt includes the pinned repository versions, the relevant verification commands, and references to the anti-patterns list. If you don't want to assemble your own system prompt from scratch, start with one of these and adjust it to your needs.

Tips for effective sessions​

A few practical habits make a significant difference in session quality:

Always set up your .env file with a valid Ethereum mainnet RPC URL before starting any tutorial that involves fork testing. Without it, forge test --fork-url will fail silently or produce misleading results, and the assistant will waste time debugging a non-existent code problem.

After each step, ask the assistant to run the verification command listed in the task card. Don't let it move on until the command passes. If something fails, ask the assistant to report the exact error message rather than guessing at the cause — guessing tends to compound mistakes.

When a setup step fails before the first successful forge build, compare the error against the workflow manifest's stop conditions. If the manifest classifies it as tooling, network, or RPC, fix that layer first instead of asking the assistant to rewrite strategy code.

Check the "Core target pin" field at the start of every session. If the pinned commit in the task card no longer matches the core checkout or starter submodule you cloned, the task card may be stale for your workspace. Proceed with caution, or wait for an updated page.

If the assistant goes off track mid-tutorial, use the copy-paste bundle to reset all edited files to the known-good state. This is faster and more reliable than trying to manually undo a series of incorrect edits.

When building custom prompts, include links to both the anti-patterns page and llms.txt. The anti-patterns page gives the assistant hard constraints, and llms.txt gives it the version pins and source-of-truth hierarchy. Together they prevent the most common categories of errors.

What these docs do NOT cover​

The Octant v2 docs and their coding-assistant conventions are designed to help you learn and prototype. They do not generate production-ready code. Tutorial strategies are intentionally minimal — they omit slippage protection, oracle validation, access-control hardening, and emergency withdrawal paths. Any strategy you intend to deploy with real funds must go through a full security audit independent of these docs.

The docs also do not guarantee correctness for contracts that deviate from the tutorial patterns. If you change the underlying vault, swap the asset, or modify the yield-routing logic, the verification commands on the workflow page may still pass while the strategy behaves differently than expected. Treat the tutorials as a starting point, not a finish line.