Project Execution Records and Handoffs

Use files as durable project memory, organized as Project → Goal → Task. The agent's native capabilities handle autonomous execution, tool use, and testing. This skill maintains the necessary goal context, execution records, error memory, work summaries, and handoffs.

Entry Points

Read only the reference relevant to the request. Templates live in this skill's assets/templates/ directory; resolve that location relative to the skill, not the workspace.

| User intent | Action and reference | |---|---| | Establish project records or start a Goal | Initialization, Execution and archiving | | Continue work, record progress or errors, close and archive work | Execution and archiving | | "Summarize new work since the last summary" | Work summaries, incremental mode | | "Summarize work from October 19 through 25" | Work summaries, date-range mode | | "Prepare the current work for another conversation" | Handoffs, prepare a handoff | | "Read this handoff and take over" | Handoffs, resume from a handoff |

Summarizing or reading existing records does not require goal mode. Do not create a Project, Goal, or Task just to produce a summary.

Hierarchy and Native Goal Mode

Project: The overall effort spanning stages and potentially conversations, with its scope and expected outcomes.
Goal: A stage with independently assessable completion criteria, corresponding to one execution objective in the agent's native goal mode.
Task: A meaningful unit of work within a Goal, such as implementing a feature or investigating a failure. Create records as needed, not once per tool call.

Once a Goal's scope, completion criteria, and context are clear, use them as input to native goal mode when authorized by the user and permitted by the environment. Selecting this skill or writing goal.md does not itself authorize starting that mode. Do not assume fixed tool names or replace an unrelated existing native goal. If native goal mode is unavailable, execute normally using the same documents. Record a native goal identifier only when the tool provides one.

Do not enforce a single Project or serial Task execution, or create all Task files in advance. project-state.md points to the current focus and identifies other concurrent work. Do not overwrite other agents' records in a shared filesystem.

Document Layout

<record-root>/
  project-state.md
  context.md
  err.md
  handoff.md                         # created when needed
  projects/P-001_<name>/
    project.md
    goals/G-001_<name>/
      goal.md
      tasks/T-001_<name>.md
  errors/E-001_<name>.md
  reports/
    summary-state.md
    <timestamp>_<summary-topic>.md
  archived/
    index.md
    projects/P-001_<name>/
      project.md                     # moved here when the Project ends
      goals/G-001_<name>/
        goal.md
        tasks/...
    handoffs/<timestamp>_<topic>.md

project-state.md: The current snapshot, valid paths, blockers, and next action, not a history log.
context.md: Lasting project conventions, environment versions, timezone, and rule sources. Distinguish each Project's scope. Reference existing repository rules rather than copying them in full.
err.md: Brief descriptions of applicable error lessons, their triggers, preventive actions, and links to details.
handoff.md: The current handoff entry point with self-contained takeover instructions.
Tasks hold execution details; Goals hold objectives, Task lists, decisions, and closing results; Projects hold overall scope and the Goal index.

State the base for paths in indexes. Resolve Markdown links relative to their containing document. IDs are unique within their owning hierarchy; execution entry IDs are unique throughout the record root. Repair links still in use after moving records into archives.

Resume and Record

For a specified handoff, first read its takeover instructions. Otherwise, read project-state.md, context.md, and err.md, followed by the current handoff if present. Load the current Goal, Task, and relevant error details as needed. Do not repeatedly reload unchanged files or scan the entire archive.

Record work when a meaningful stage ends, an important result emerges, an approach is ruled out, or work is paused or handed over. Do not defer all recording until the conversation ends. Capture actual work times, outcomes, failed attempts, and evidence. Mark unknown information as unknown; do not invent history. Append execution entries; add corrections as new entries referencing the original ID so incremental summaries can detect them.

Validation Boundaries

Concentrate comprehensive validation at Goal closure. Tasks do not require separate tests, builds, or acceptance checklists. During execution, perform only the minimum checks needed to make progress, such as diagnosing a failure or confirming a critical assumption. Honor necessary checks already required by the user, repository, or runtime without adding another layer of requirements from this skill.

At closure, validate according to the actual changes and reuse results that remain valid. If further changes occur, check only affected areas. Record actual states such as implemented, unvalidated, validation passed, or external acceptance pending. Do not mark a Goal complete before its completion criteria are satisfied. Cancelled or abandoned work may be archived with an explicit final status.

This skill provides no legacy-layout compatibility or migration entry point and does not automatically convert historical directories.