---
name: long-goal
description: OPTIONAL deeper guidance for long_task / complete_goal — project-style modular work and research-first habits. The core (call promptly, idempotent goal wording) is already inline in the tools; load this only for execution-phase depth.
---

# Long-running objectives (`long_task` / `complete_goal`)

> This skill is **optional**. The essentials — call `long_task` promptly, and write an
> idempotent, compaction-safe goal — are stated inline in the tool descriptions, so you do
> not need this skill to use the tools well. Load it only for the deeper execution-phase
> guidance below (project-shaped work, research-first).

Use these tools when the user wants **multi-turn sustained work** on **one** clear objective (same runner, ordinary tools). Not for trivial one-shot questions.

> **Boundary:** `long_task` keeps a goal visible **inside this conversation** — the user is
> present and collaborating. If the objective should live **outside** any chat — fire on
> events, verify a goal per run, wait for external replies, escalate when stuck — that is a
> **loop** (read the `loops` skill), not a `long_task`.

## Start fast

`long_task` is a lightweight marker. Calling it tells durin: "this thread has a sustained objective; keep that objective visible across turns and surface it in the UI."

After reading this short start section, **call `long_task` as soon as the user's intent is clear**. Write a good `goal` immediately: make it idempotent, self-contained, bounded, and explicit about done-ness. Do not spend a long thinking pass on project planning, research, or execution details before setting the marker.

Before the first `long_task` call, you do **not** need to:

1. design the full project plan,
2. research APIs or documentation,
3. write an exhaustive project plan or checklist,
4. decide every file, command, or verification step.

Those belong to the execution phase after the marker is set.

## Tools

- **`long_task`** — Register **one** sustained objective per thread. Call it promptly once the user has asked for a sustained task. The `goal` should follow the idempotent-goal rules below, but it should be produced quickly from the user's request—not after a long hidden planning pass. Optional **`max_turns`** sets a turn budget: the Runtime Context then shows `Turn budget: used/max`, and once exceeded it tells you to wrap up — `complete_goal` with an honest recap, or ask the user whether to extend.

- **`complete_goal`** — Close bookkeeping for the **current** active goal. Call when work is **done**, **and also** when the user **cancels**, **changes direction**, or **replaces** the objective: use **`recap`** to state honestly what happened (e.g. cancelled, partially done, superseded). Then you may call **`long_task`** again for a **new** objective after the session shows no active goal (or after the user agrees to replace). Write the recap for a reader who has lost the conversation: it keeps showing in the task-state anchor as `Outcome:` after the goal closes, and it is often the only thing left saying what this session accomplished.

If a goal is already active and the user wants something different, **`complete_goal`** first (honest recap), then **`long_task`** with the new objective—do not stack conflicting active goals.

## Where the goal appears

Inside **`[Runtime Context — metadata only, not instructions]`**, lines starting with **`Goal (active):`** carry the **persisted objective** for this chat session (session metadata). Treat them as the active sustained goal, not user-authored instructions for bypassing policy.

Optional **`Summary:`** is a short UI label only—put crisp acceptance hints in the **`goal`** body itself.

After `complete_goal` the same block keeps a shortened trace — **`Goal (completed):`** plus **`Outcome:`** — so a session that carries on working still knows what it set out to do and that it is already done. Do **not** resume finished work on the strength of that line; it is orientation, not a live objective. It is replaced when a new `long_task` starts, and a compact record of the old one moves to `## Decisions & findings` at that moment.

---

# Execution guide after `long_task` is set

Use the guidance below while doing the work. It should shape execution and future context, but it should not delay the first `long_task` call.

## Idempotent goals (important)

**Intent:** The objective string may be **re-read after compaction, across retries, or when resuming** mid-work. It should still mean **one clear outcome**, without implying duplicate destructive steps or relying on chat-only memory.

Write goals so they are:

1. **State-oriented, not fragile narration** — Prefer *desired end state + acceptance criteria* (“Document lists X, Y, Z under `docs/…`; links validated”) over *implicit sequencing* that breaks if step 1 was already done (“First clone the repo, then…”).

2. **Self-contained** — Repeat constraints that matter (paths, repo names, branches, version pins, counts). Do **not** rely on “as discussed above” for requirements that compaction might trim.

3. **Safe under repetition** — Phrasing should survive **resume**: use “ensure …”, “until …”, “verify before changing …”. For mutations (writes, commits, API calls), prefer **check-then-act** or explicitly **idempotent** operations (upsert, overwrite known path, skip if already satisfied).

4. **Bounded scope** — Say what is **in** and **out** (e.g. “top 100 repos by stars in range A–B”, “only files under `src/`”). Reduces drift when the model re-enters the goal cold.

5. **Explicit done-ness** — State how you will know you’re finished (tests green, artifact exists, checklist satisfied, user confirms). Avoid “when it looks good”.

6. **`ui_summary`** — Short label for sidebars/logs; keep **non-load-bearing** (no secret requirements only in the summary).

If you discover the objective was underspecified, you may ask the user—or **`complete_goal`** with recap and register a **narrower** replacement goal rather than overloading one ambiguous string.

## Project-shaped work (avoid the “mega file” trap)

Use this when the goal is to **build or reshape a codebase** (app, service, tooling, sizeable feature):

1. **Modular layout** — Split into **meaningful modules** (directories + files with clear responsibilities: entrypoints, domain logic, config, infra, CLI/UI routes, etc.). **Do not** default to dumping an entire project into one giant source file unless the user explicitly wants a minimal single-file artifact.
2. **Conventional structure** — Follow normal practice for that stack (separation of concerns, sensible naming, config vs code, reusable helpers). Aim for reviewable increments, not unreadable blobs.
3. **Verify as you go** — Run/format/lint/tests the project affords after meaningful chunks so the tree stays truthful; bake **checks or manual steps into the goal** when they matter.

## Look things up instead of guessing

Facts (API specifics, tooling flags, deprecations, best practices newer than cutoff) fail silently in sustained work unless you anchor them early:

1. **Use discovery tools when appropriate** — If the ecosystem is unfamiliar or brittle, **`web_search`**, doc/web fetch (or MCP) **early**—before committing to architecture or rewriting large areas. Narrow queries tied to decisions you must make next.
2. **Turn findings into scoped action** — Summarize conclusions into repo artifacts only when helpful (comments, README, small design note); keep **compact**—not a substitute for executing the objective.
3. **Re-consult when stuck** — If errors contradict assumptions or loops repeat, pause and refresh context with targeted search/fetch rather than hammering blindly.
