Skip to main content

Task Card Format

Purpose: Document the structure and field meanings of the agent task cards used on Octant v2 workflow pages. Audience: Developers using coding assistants on Octant v2 work; doc contributors adding task cards to new pages. Level: Reference Source of truth: This page for the task card format; [email protected] for contract behavior referenced inside task cards. Use this page when: you want to understand what a task card contains and why, or you are writing a new task card for a workflow page. Do not use this page for: the full list of anti-patterns (see Agent Anti-Patterns) or general guidance on pairing with coding assistants (see How to Use Coding Assistants).

What a task card is​

A task card is a collapsible block on a workflow page that gives a coding assistant structured context for one specific task. Each task card contains everything a coding assistant needs to start work — the goal, the exact files to touch, the files to leave alone, required environment setup, how to verify the result, and a pointer to the anti-patterns list.

Task cards are not narrative guides. They are dense, machine-readable context blocks intended to be copied or pasted directly into a coding-assistant session alongside the relevant source files.

On workflow pages, task cards appear as collapsed HTML details blocks so they do not interrupt the human reading flow:

<details>
<summary>Agent task card</summary>

...task card content...

</details>

Template​

The following is the full task card template. All fields are required unless otherwise noted.

<details>
<summary>Agent task card</summary>

**Goal:** One sentence describing the concrete output this task produces.

**Start repo:** The repository and branch or commit you should be working in.
Example: `octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec`

**Core target pin:** `<pinned-commit-hash>`
If the current HEAD of the start repo differs from this hash, stop and flag the discrepancy before proceeding.

**Files to edit:**
- `path/to/file-one.sol` — what to do in this file
- `path/to/file-two.sol` — what to do in this file

**Files NOT to edit:**
- `path/to/locked-file.sol` — reason this file must not be modified
- `path/to/another-locked-file.sol` — reason this file must not be modified

**Required setup:**
- Any environment variables that must be set before running commands
- Any submodule pinning or dependency steps required
- Any Foundry profile or config overrides required

**Verification:**
- The specific command(s) to run to confirm the task succeeded
- The expected output or exit condition
- Any fork-test requirements (e.g., `ETH_RPC_URL` must point to a mainnet archive node)

**Do not:** See [Agent Anti-Patterns](/docs/developers/agent_assisted_development/agent-anti-patterns) for the full list. Key items for this task: (list the one or two most relevant anti-patterns for this specific task).

</details>

Field reference​

Goal​

One sentence. Describes the concrete deliverable: a file that compiles, a test that passes, a function that matches a specific interface. Avoid vague goals such as "implement the strategy" — use specific ones such as "implement _deployFunds so that make test-contract contract=MySDAIStrategyTest passes all assertions".

Start repo​

The exact repository and the commit hash or release tag you should clone and work from. Always includes a pinned reference, never a bare branch name. If the task applies to octant-v2-core directly, say so explicitly; if it applies to the starter template, say so and include the template commit alongside the core submodule pin.

Core target pin​

A pinned octant-v2-core commit hash. This is the single most important field for detecting staleness.

When a workflow page is published, its task card targets a specific core commit. If the repository moves forward — new releases, interface changes, constructor signature updates — the task card may no longer be accurate. The "Core target pin" field makes that detectable: if the current core checkout or starter submodule differs from the pinned hash, a coding assistant should stop and flag the discrepancy rather than proceeding on assumptions.

Doc contributors must update this field whenever they move a task card to a newer core commit, and should separately re-run the page's verification commands before claiming end-to-end validation.

Files to edit​

An explicit list of every file the coding assistant is expected to modify, with a short note on what it should do in each file. If a task legitimately requires touching more than five or six files, consider splitting it into two task cards.

Being explicit here serves two purposes: it focuses the coding assistant on the right scope, and it makes it obvious when the assistant has drifted into files it should not be touching.

Files NOT to edit​

An explicit list of files that must not be modified, with a short reason for each. Common candidates include:

  • generated files (ABIs, typechain output)
  • files owned by the core protocol that custom strategies should not override
  • configuration files that are version-pinned and must not drift
  • test harness files shared across multiple strategies

If a coding assistant modifies a file on this list, that is a signal to stop and review the diff before continuing.

Required setup​

Any prerequisite steps that must be completed before the task's verification command will work. This includes environment variables (ETH_RPC_URL, repo-specific aliases such as TEST_RPC_URL, TEST_ASSET_ADDRESS), submodule pinning commands, Foundry profile settings, or dependency installation steps. Do not assume the reader has already run forge soldeer install or pinned the core submodule — state it explicitly if it is required.

Verification​

The exact command or commands to run to confirm the task is complete, plus the expected output. A task card without a concrete verification step is incomplete. Prefer commands that fail fast and clearly (forge test --match-contract YourTestName -vvv) over broad commands that pass even when the specific goal is not met.

If the verification command requires a fork, say so explicitly and name the required environment variable.

Do not​

A short, task-specific excerpt from the Agent Anti-Patterns list, naming the one or two anti-patterns most likely to occur in this task. Always link to the full anti-patterns page so a coding assistant can check the complete list.

This field is not a replacement for the full anti-patterns page — it is a reminder of the most relevant items for the specific task at hand.

Staleness and the "Core target pin" field​

Task cards age. Octant v2 is under active development, and constructor signatures, interface shapes, and file locations can change between releases.

The "Core target pin" field exists to make staleness detectable. When a reader opens a task card, they can compare the pinned hash against their local octant-v2-core checkout or starter submodule. If they differ, the task card may be out of date for that workspace and should not be followed without re-validation.

Doc contributors should treat a commit-hash mismatch as a trigger to re-test the task card end to end and update the pinned hash (and any fields that changed) before the page is published or merged.