# Workflow Guide > Establish and maintain a workspace-local `.agent` directory as durable project memory so work can resume across cleared contexts, agent changes, or later sessions. Use when beginning work in any Git repository or ordinary directory, when the user asks for agent orchestration or persistent progress tracking, or when an existing `.agent` should be resumed. - Skill: `souravmohapatra/workflow-guide` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add souravmohapatra/workflow-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/souravmohapatra/workflow-guide/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: souravmohapatra (https://skillmd.com/u/souravmohapatra) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/souravmohapatra/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 `/.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 /scripts/init_agent_memory.py --root `. 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`.