long-goal

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, pursue a life condition until it's achieved, wait for external replies, escalate when stuck — that is an automation (read the automations 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.