do-long-task

do-long-task

This is an entry skill oriented toward long-task execution. It is not responsible for deciding "what a big task should do" for you; rather, it is responsible for steadily driving an already-determined long task through to the end.

Prompt generation mode

When the user requests "generate a Claude Code /goal or Codex /goal prompt", "generate a long-task execution prompt", or "use do-long-task to write a prompt within 1500 characters", enter prompt generation mode.

Prompt generation mode does only one thing: output a long-task execution prompt that can be copied for use with Claude Code /goal or Codex /goal . Do not start executing that long task.

When generating a prompt:

Do not modify OpenSpec artifacts.
Do not create or update agent-progress.md / agent-findings.md。
Do not run tests, lint, typecheck, or validate commands.
Do not treat the chat checklist as the task source.
By default, keep the final prompt within 1500 characters; if the user specifies a shorter or longer character limit, the user's specification prevails.
If the user does not provide the openspec/changes/<change-name> or tasks.md path, do not fabricate a path; output a placeholder template with <change-name> and list the placeholders the user needs to fill in.

The prompt must preserve the core discipline of do-long-task: read OpenSpec artifacts, use only tasks.md as the sole task source, advance in small steps, dynamically fill in missed tasks, strictly locate agent-progress.md / agent-findings.md, maintain progress and failure records, check off completion only after verification, and pause only when truly blocked.

For detailed templates, placeholder strategies, and trimming rules, see references/codex-goal-prompt.md. According to the read routing of AGENT_LONGTASK.md , load only the relevant reference; do not mindlessly read all the long documents.

Collaboration statement

The global skill that requires collaboration is openspec. When executing an OpenSpec change, first use openspec to understand the artifact chain of proposal.md、design.md、specs/ and tasks.md .
If a project-level OpenSpec skill exists within the business project, it must be discovered and read before executing the change. Check first, by project root directory priority, the skill entries related to .claude/skills、.codex/skills、.agents/skills、.agent/skills in openspec ; read only the skills and references needed for the current task, and do not place the default rules of externally distributed skills above project rules.
When it is detected that the current task is under openspec/changes/<change> , the current OpenSpec artifact chain must prevail,tasks.md is the only executable task source.
When a missed task is discovered during long-task execution, first update the current change's tasks.md, then continue execution.
Do not only write the missed task in the chat checklist,agent-progress.md , or a subagent report.

Fixed artifact location gate

In execution mode, the unique OpenSpec change root directory must first be determined, then create or update agent-progress.md / agent-findings.md。

There are only two types of canonical locations:

The change currently being executed:openspec/changes/<change-name>/agent-progress.md and openspec/changes/<change-name>/agent-findings.md
An archived change:openspec/changes/archive/**/<change-name>/agent-progress.md and openspec/changes/archive/**/<change-name>/agent-findings.md

When determining the change root directory, judge by priority:

The openspec/changes/<change-name>、openspec/changes/<change-name>/tasks.md or a specific change directory under archive.
The current working directory is located within a certain openspec/changes/<change-name> or openspec/changes/archive/**/<change-name> .
Exactly one change directory is found that clearly matches the user's goal, thetasks.md title, or the current checkpoint.

If the change root directory cannot be uniquely determined, do not create these two files in the current directory, the repository root directory, theopenspec/changes/ top level, theopenspec/changes/archive/ top level, an ordinary reports directory, or a skill directory; first prompt the user to supply the change path.

Misplaced File Check and Migration

In execution mode, on every startup, after resumption, after context compaction, before creating fixed artifacts, and before completion, check whether misplaced files already exist in the workspace. You may use rg --files -g agent-progress.md -g agent-findings.md or an equivalent file search.

For each hit of agent-progress.md / agent-findings.md：

determine whether the path is located in the canonical active change root directory or archive change root directory.
If the path is not canonical, immediately warn the user: list the relative path, why it is not canonical, which change directory it is to be migrated to, and what the evidence of attribution is.
If the current task has uniquely determined the active change, migrate or merge the misplaced content into the corresponding file in that change root directory; if the target file already exists, append a ## Migrated from <relative-path> on <YYYY-MM-DD> section, preserving the original text and the reason for migration.
If the content belongs to an archived task, and the specific change directory under archive can be uniquely identified, migrate or merge the content into the corresponding file in openspec/changes/archive/**/<change-name>/ .
If multiple candidate changes exist, attribution cannot be identified from the content, or migration may overwrite existing records, stop and ask the user; do not guess, and do not keep accumulating multiple long tasks into the same file.
After migration, read back the target file to confirm the content exists, then delete the misplaced source file; if it cannot be confirmed, keep the source file and record the risk in the target agent-findings.md or the current report.

Do not interpret migration as "organizing into reports". These two files are attached state files of an OpenSpec change and may only follow a specific active change or archive change.

When to use

Development, fix, refactoring, migration, or acceptance tasks that need to be continuously advanced across multiple steps.
The task will undergo context compaction, session interruption, test failure, and resumed continuation.
The task must write plans, progress, findings, failures, and verification into files, and cannot rely on chat memory.
The task already has a clear, unique primary task source, usually OpenSpec's tasks.md。

When not to use

Small single-file changes or one-off formatting.
Merely answering questions, explaining solutions, or still doing requirements exploration.
Short tasks such as writing changeset, commit messages, or changelogs.
Simple operations that do not need checkpoints, resumed continuation, or failure records.

What to read first

Before starting, read these files first, then begin:

AGENT_LONGTASK.md(if it exists)
Read the routing-selected AGENT_LONGTASK.md according to references/*.md
The current skill's SKILL.md
In the business project, the OpenSpec-related project-level skills in .claude/skills、.codex/skills、.agents/skills、.agent/skills .
The current OpenSpec change's proposal.md
The current OpenSpec change's design.md
The current OpenSpec change's specs/*/spec.md
The current OpenSpec change's tasks.md
First scan for and handle misplaced agent-progress.md / agent-findings.md
change root directory's agent-progress.md
change root directory's agent-findings.md

If any of these files are missing, fill them in first, then continue.

Core discipline

Use only one task source. If the project uses OpenSpec, use openspec/changes/<change-name>/tasks.md as the sole task list.
Do not create a second task system, and do not treat a temporary checklist in chat as the primary task source.
Handle only one clear task or one clear checkpoint at a time.
Do not skip unfinished tasks.
Do not mark unverified content as complete.
After code changes, relevant verification must be performed.
The OpenSpec artifact chain must be maintained completely: first read proposal.md、design.md、specs/*/spec.md、tasks.md, then start work; if a missed task is found, first extend tasks.md; if user-visible behavior is changed, first sync specs/*/spec.md; if the technical approach is changed, first sync design.md。
If process reports, progress documents, or research documents need to be saved within the current OpenSpec change, they must be placed in tasks.md or a subdirectory explicitly specified by the project OpenSpec specification, and use YYYY-MM-DD-*.md naming; markdown must not be scattered in the change root directory.
The change root directory should only retain OpenSpec core artifacts,agent-progress.md、agent-findings.md and root-level files explicitly allowed by the project specification; do not write stage reports, verification reports, or research records directly to the root directory.
agent-progress.md is fixed in the change root directory and cannot be moved, renamed, or dated; it only records checkpoints, the current task, core progress, verification summaries, and next steps, and does not carry excessively long execution logs.
agent-findings.md is fixed in the change root directory and cannot be moved, renamed, or dated; it only records core pain points, risks, failure indexes, prohibited repeated paths, and to-do entry points, and does not carry complete long reports.
Before creating, reading, or writing these two files, the location gate must be passed first; if misplaced files are found in the repository root directory, an ordinary reports directory, a skill directory, or shared by multiple tasks, warn first and migrate them to the specific active/archive change, then continue execution.
When agent-progress.md or agent-findings.md is too long, first compress it into a summary and index; migrate detailed logs, evidence, or research content into tasks.md the specified dated subdirectory or evidence file.
Do not ask the user whether to continue at every small step unless a real blocker is encountered.
Pause and request user intervention only when encountering permission issues, destructive risks, requirement conflicts, product decision issues, or 3 consecutive failures of the same kind.

State file harness control

agent-progress.md and agent-findings.md are handoff state files, not event logs, chat dumps, or raw output repositories. Violating the following write contract will create context noise:

`agent-progress.md`: overwrite snapshot

Update the current snapshot at each checkpoint or task boundary; modify the existing state, and do not append item by item according to commands or conversations.
The snapshot only retains: the current checkpoint, current task, status, latest verification summary, blockers, next steps, and evidence index.
The default soft limit is 40 lines; after exceeding it, duplicate content must first be merged and expired status deleted before continuing to write. Blank lines or large log sections must not be used to evade the limit.
Only retain the most recent 3 evidence indexes; complete command output must remain in command results,tasks.md the specified dated evidence file, or another project-specified location.

`agent-findings.md`: deduplicated persistent findings

Every finding must answer: what the conclusion is, where the evidence is, what the status is, and what the next action is.
For status, use only active、superseded、resolved; when new evidence overturns an old judgment, update or delete the old entry rather than appending the same finding again.
Keep only root causes, risks, failure indexes, forbidden repeated paths, and to-do entry points that would change the subsequent agent's decisions; do not record chat summaries, full tracebacks, duplicate version trees, or ordinary success logs.
The default soft limit is 80 lines or 20 valid findings; when either limit is reached, first compress, merge, or remove resolved entries.

Pre-write gate

Before writing, check item by item:

Would the next agent take a different action because of this information? If not, do not write it.
Is there an evidence index or a clear status? If not, verify it first or mark it as pending verification; do not write it as a conclusion.
Does an equivalent entry already exist? If so, update the original entry; do not add a duplicate entry.
Does it belong to the task list? If so, write it into tasks.md; do not hide it in the status file.

At the end of each checkpoint, you must overwrite and update agent-progress.md, and perform a deduplication and expired-entry cleanup on agent-findings.md ; neither file is allowed to turn into a long-term running log.

Standard workflow

Refresh the file status before starting.
Determine the single change root directory, and scan, warn about, and migrate misplaced agent-progress.md / agent-findings.md。
Select one task.
Clarify the task's acceptance criteria and verification commands.
Check whether this round needs to sync design.md、specs/*/spec.md or supplement tasks.md; maintain the artifact chain before implementing.
If a process report, progress document, or research document needs to be generated, first confirm that tasks.md or the project OpenSpec specification has already defined the location and naming rules.
Make only the minimal verifiable change.
Run the relevant tests, lint, typecheck, OpenSpec validate, or other necessary verification.
Write the checkpoint, file changes, and verification summary into the specification change root directory's agent-progress.md。
Write the failure index, risks, and paths that must not be repeated into the specification change root directory's agent-findings.md。
Only check off a task as complete when the acceptance criteria are met.
Before moving on to the next task, re-read the file status.

Pre-completion check

Before marking complete, confirm that all of the following hold:

The code has been implemented.
The task's acceptance criteria have been met.
The relevant verification commands have passed, or an alternative method for what cannot be automatically verified has been explicitly recorded.
agent-progress.md has recorded this round's progress and verification results.
agent-findings.md has recorded important findings, failed attempts, or remaining risks.
Newly added markdown documents are not scattered in the change root directory; all process reports, progress documents, and research documents are located in tasks.md or in date-based subdirectories or evidence files defined by the project OpenSpec specification.
agent-progress.md and agent-findings.md are still in the change root directory, not moved, not renamed, not date-stamped, and retain only summaries, checkpoints, indexes, and core risks.
The workspace has no misplaced agent-progress.md / agent-findings.md; if misplaced files were found, they have been warned about, migrated to the single active/archive change, and re-read for confirmation.
There are no unresolved CRITICAL issues.

Things you need to remember

Long tasks rely on files, not on chat memory.
Keep only one task source.
Advance in small steps.
Every step must be recoverable.
Verify first, then complete.