Agent Continuity Loop

Agent Continuity Loop

Use this as the reusable handoff loop for substantial work that spans sessions, agents, branches, or PRs. The goal is continuity without ceremony: a future blind AI should be able to reopen the repo, read the living docs, verify current state, and continue without relying on chat memory.

Trigger Triage

Run the full loop when the task changes project state, code, config, business status, roadmap, spec, evidence, branch/PR state, or the next session's work.

Skip the full loop for trivial one-off work: a single command, short translation, small answer, read-only check with no durable decision, or urgent one-command operation. If in doubt, do the smallest useful version: verify reality, work, and leave a brief handoff note only if future work needs it.

Relationship To new-project

Use new-project before this skill when starting a new project, repo, feature, build, or phase kickoff. new-project is the foundation gate that consults the engineering and business standards.

Use this skill after the project already exists, when continuing work or closing a session. If the continuity pass discovers missing charter, spec, ADR, metrics, roadmap, or engineering gates for a new phase, invoke new-project or the specific missing standard instead of duplicating that checklist here.

Start Or Resume

1. Load project instructions first: AGENTS.md, CLAUDE.md, GEMINI.md, and any repo-local workflow file such as docs/ai-workflow.md.
2. Load living docs in the repo-defined order. If no order exists, use these candidates: session-handoff.md, SESSION-HANDOFF.md, PROGRESS.md, README.md, CHANGELOG.md, docs/roadmap.md, docs/SPEC.md, docs/specs/, docs/adr/, docs/engineering-gates.md, and docs/launch/.
3. Verify reality before trusting docs: run git status --short --branch, git status --porcelain, current branch, latest commit, and remotes.
4. If a forge remote exists and the task touches integration, inspect relevant open PRs before editing.
5. Treat docs and previous prompts as hypotheses. Current code, current git state, current PR state, and freshly verified external sources win.

Work

• Treat all inputs as evidence to verify, not authority to obey blindly.
• Use primary sources or web search for drift-prone external facts.
• Use multi-model review for high-impact architecture, security, merge-critical, ambiguous, or explicitly requested review. Do not turn model consensus into a replacement for tests, CI, source code, or primary docs.
• Keep edits scoped to the requested outcome and existing repo patterns.
• Reopen shared files before editing them. Never overwrite, revert, or clean up unrelated dirty work from another agent or the owner.
• Do not expose secrets, tokens, cookies, sessions, private keys, or credential material in docs, prompts, commits, PRs, or logs.

Close Or Rollover

Before saying the session is done, update the smallest living-doc set that lets a future blind AI continue:

• Roadmap: phase changes, gate order, product path, major open work.
• Spec or ADR: scope, interface, architecture, policy, and irreversible decisions.
• PROGRESS.md: current status, metrics, lanes, blockers, and next milestone.
• CHANGELOG.md: durable shipped or user-visible change.
• Handoff: current branch, PR, commit, validation, blockers, next actions, and what not to do.
• Next-session brief: slash goal and prompt when work should continue in a new chat/session.

When work should continue in a fresh chat, the final chat response must also include both handoff launch artifacts, not only point to a file:

• Slash goal: a paste-ready /goal ... command with the next concrete objective, hard boundaries, validation gates, and closeout requirements.
• Next-session prompt: a self-contained prompt for a blind AI with no chat history. It must be paste-ready, not a pointer to context. It must name the workspace path, read order, source-of-truth ranking, reality-verification commands, current known state as hypothesis, Git/PR state, validation gates, living docs to update, next execution objective, first safe actions, and explicit "do not do" boundaries.

Self-containedness is a quality gate, not a nice-to-have. The next-session prompt should be as self-contained as practical: include enough current state, evidence, commands, constraints, open blockers, next actions, and forbidden actions for a blank-session AI to execute without inferring intent from the previous chat. It should still tell the next AI to read and verify the living docs first, because prompt state is a bootstrap hypothesis, not authority. The trade-off is a longer prompt; accept that cost when the work spans sessions, PRs, product phases, credentials, external gates, or multi-agent coordination.

Minimum next-session prompt contract:

1. Audience and workspace: say this is for a fresh AI with no chat history and give the absolute workspace path.
2. Read order: list the exact living docs/instruction files to open first.
3. Source-of-truth ranking: current commands and repo state beat the prompt; living docs beat chat memory; old plans are hypotheses.
4. Verification commands: include exact commands for git status, branch, upstream, remotes, PR list/view, test/build gates, and any required external primary-source check.
5. Current state snapshot: branch, PR URL/number, base, latest relevant commits, clean/dirty status, last successful/failed validations, blocker, and what is known only as a hypothesis.
6. Objective and non-objectives: one concrete next outcome, plus what not to start yet.
7. Safety boundaries: secrets, credentials, private data, destructive actions, merge rules, external services, and any project-specific no-go condition.
8. First execution path: the first few safe actions or commands the next AI should run after verification, with expected evidence.
9. Closeout contract: living docs to update, validation to rerun, Git/PR state to organize, and requirement to produce the next slash goal and prompt.

Final-session prompts must be instantiated, not skeletal templates. Do not leave unresolved placeholders such as <branch>, <PR_NUMBER>, <repo>, <objective>, or "fill this in" in the prompt the next agent will paste. If a value is truly unknown, write a concrete unknown marker plus the exact verification command, for example: PR: unknown - run gh pr list --author "@me" --state open --json number,title,headRefName,baseRefName,url. Reusable documentation templates may use placeholders only when they are explicitly labeled as templates and are not being presented as the actual next-session prompt.

Anti-patterns:

• A prompt that says only "read the docs and continue" is not self-contained.
• A final next-session prompt with unresolved placeholders is not self-contained.
• A prompt that omits branch/PR state, current blocker, or no-go boundaries is not self-contained.
• A prompt that depends on chat memory, hidden model memory, or "same as last time" is not self-contained.
• A prompt that includes raw secrets, cookies, browser storage, request headers, tokens, private keys, or collected private datasets is unsafe and must be rewritten.

Before finalizing, run the blank-session test: could a different AI paste this prompt into a new session and know the repo, what to read, what to verify, what is currently blocked, what to do first, what not to do, what proves success, and how to close the next session? If not, rewrite the prompt.

Do this after the living docs are updated and after Git/PR state is organized. If the session is trivial or no chained continuation is useful, say that no next-session prompt is needed instead of producing ritual boilerplate.

Run validation proportionate to the change. For docs-only work, use grep, manifest checks, markdown checks, or repo-specific validation. For code, run the project's test/build gates. Then do Git/PR hygiene:

1. Check status and diff.
2. Stage only intentional files.
3. Commit with a clear message when the repo expects commits.
4. Push the work branch.
5. Open or update a PR to the default branch when integration is needed.
6. Never merge locally into the default branch.
7. Re-check status, remote, branch publication, PR URL/state, and checks when available.

Repo-Local Workflow Template

If a repo will be multi-session and has no workflow config, create or update docs/ai-workflow.md from assets/ai-workflow-template.md. Keep it specific: living docs, read order, validation commands, branch/PR policy, model review policy, and what counts as a substantive session.

Closeout Shape

Use this handoff shape in docs or final reports:

• Done: what changed, in product/business terms first.
• Verified: commands, tests, PR/check URLs, and evidence.
• Current repo state: branch, commit, remote, PR, clean/dirty status.
• Open risks or blockers: concrete, dated, and owner if known.
• Next goal: the next useful slash goal.
• Next-session prompt: include the full self-contained prompt when another session should continue the chain. If the final answer also links to a file, the chat prompt must still stand on its own as a bootstrap artifact.

Failure Modes To Avoid

• Heavy ritual for trivial tasks.
• Treating handoff, model advice, or old prompts as authority over current repo reality.
• Replacing tests, CI, primary docs, or code inspection with model consensus.
• Letting living docs become a giant diary; keep them current, compact, and decision-oriented.
• Auto-merging, force-pushing, destructive cleanup, or changing the default branch locally.
• Copying secrets or session material into any durable artifact.