Workflow Guide

Workflow Guide

Use .agent as the concise, durable source of truth for ongoing work. This skill coordinates state through files; it does not itself authorize spawning subagents, changing task scope, or committing files.

Locate the workspace

1. In a Git worktree, use the repository top level (git rev-parse --show-toplevel). Otherwise use the current working directory.
2. Check for <workspace>/.agent before substantive work.
3. If .agent exists, do not ask whether to initialize it. Read .agent/README.md, then PROGRESS.md, PLAN.md, and HANDOFF.md; consult DECISIONS.md, ANALYSIS.md, and FAILURES.md as relevant. Reconcile stale notes against the actual workspace and the user's latest instructions.
4. If .agent does not exist, ask the user one concise question before creating it: “This workspace has no .agent memory. Should I enable persistent agent orchestration here?” Do not create it unless the user agrees.
5. After agreement, run python3 <skill-dir>/scripts/init_agent_memory.py --root <workspace>. Never replace an existing .agent wholesale.

If the user already explicitly requested creation or setup of .agent, that is agreement; initialize without asking again. For a trivial read-only question where no continuing work is implied, mentioning the option is enough and initialization may be deferred.

Resume before acting

Treat the files as a handoff from another capable agent, not as unquestionable truth.

• Follow the newest explicit user instruction when it conflicts with stored notes.
• Verify important claims against files, Git state, tests, or other authoritative sources.
• Preserve useful history. Correct stale information explicitly instead of silently rewriting history.
• Continue the first actionable item in HANDOFF.md or PLAN.md when it remains valid.
• If the task recorded there is already complete, say so and update the memory rather than repeating work.

Maintain memory during work

Keep the files concise and useful to an agent with no conversation history:

• PROGRESS.md: current objective, status, completed outcomes, active work, blockers, and verification results. This is the primary snapshot.
• PLAN.md: ordered work items with stable IDs and statuses (pending, in_progress, blocked, done). Keep only the active plan plus a short completed section.
• ANALYSIS.md: durable findings, constraints, hypotheses, evidence, and small relevant log excerpts with commands or file locations.
• DECISIONS.md: consequential decisions, alternatives considered, rationale, and implications.
• FAILURES.md: failed approaches, exact symptoms, likely cause, and what should or should not be retried.
• HANDOFF.md: the smallest restart packet—where things stand, exact next action, files to inspect, commands to run, and open questions.

Update memory at meaningful checkpoints: after planning, after a significant discovery or decision, after a failure that could recur, after verification, and before ending or handing off. Do not log every command or narrate routine actions. Prefer timestamps with timezone and append chronological entries where history matters; rewrite snapshot sections when the current truth changes.

Before pausing or finishing, ensure:

1. PROGRESS.md accurately distinguishes done, active, and blocked work.
2. PLAN.md statuses match reality.
3. Reusable evidence, decisions, and failures are captured in their canonical files.
4. HANDOFF.md names one concrete next action, or says that no action remains and records the verification proving completion.

Safety and repository hygiene

• Never store credentials, tokens, private keys, personal data, or unredacted sensitive logs in .agent.
• Keep large logs, generated artifacts, and binary files elsewhere; record a path and a short redacted excerpt instead.
• Do not invent work history. Label uncertainty and record only observed or user-provided facts.
• Avoid duplicating the same fact across files; link to the canonical entry.
• Do not add .agent to .gitignore or commit it without the user's request. The user decides whether this memory is shared through version control.
• Preserve user edits and unknown custom files inside an existing .agent.