carry-forward

name: carry-forward description: Resume, take over, or hand off a software project across AI coding-agent sessions by reading repo-local state docs, handoff notes, decisions, validation evidence, git status, branch/upstream state, recent commits, and relevant diffs before continuing. Use when the user says continue, resume, take over, 接管, 继续开发, 继续, read AGENTS.md/CURRENT_STATE/HANDOFF/DECISIONS/PROJECT_PLAN, sync with GitHub, create a handoff, preserve context, or avoid starting from zero. metadata: short-description: Resume coding-agent projects safely

Carry Forward

Use this skill when a fresh agent session needs to continue real project work without guessing from chat history. The core contract is:

establish current truth -> protect local work -> report state -> continue or hand off

Operating Modes

Infer the mode from the user request:

• Resume: Read continuity docs and git state, summarize the current state, then continue the requested work.
• Plan only: Read state and propose next steps, but do not edit files.
• Review only: Inspect and report findings, but do not modify files.
• GitHub sync: Fetch and compare local/remote state before any merge, rebase, or push.
• Create handoff: Capture the current state, validation, risks, and next concrete task for the next session.

If the user explicitly limits the mode, honor that limit.

Resume Workflow

1. Locate the project root from the user's path, current workspace, or git root.
2. Read the smallest useful continuity set:
   • Agent instructions: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, GEMINI.md, or similar.
   • Project overview: README.md, PROJECT_PLAN.md, issue/task docs.
   • State docs: docs/CURRENT_STATE.md, docs/HANDOFF.md, docs/DECISIONS.md, docs/VALIDATION.md, or similarly named files.
   • Git truth: git status --short, active branch, upstream, recent commits, and relevant diffs.
3. Reconcile docs against the current worktree:
   • Prefer current files and git state over stale handoff text.
   • Separate confirmed facts, assumptions, contradictions, blockers, and open questions.
   • Treat dirty files as user or other-agent work unless proven otherwise.
4. First response should briefly state:
   • current project state
   • active branch and dirty files
   • known decisions or constraints
   • contradictions or blockers
   • proposed next steps
5. Execute the requested next step unless the user asked only for a plan or review.

Read references/resume-checklist.md before a non-trivial resume. Read references/edge-cases.md when the repo state is missing, contradictory, dirty, or remote-diverged.

GitHub Sync Rules

When the user asks to pull, sync, continue from GitHub, or compare remote work:

1. Run git fetch --prune.
2. Inspect local branch, upstream, remote default branch, ahead/behind counts, and dirty files.
3. Report divergence before changing history or files.
4. Do not merge, rebase, reset, checkout over local changes, or push unless the user explicitly requested that action or the task clearly requires it and the local state is safe.
5. After a push or deployment, verify the remote status and record the commit, URL, or branch state in the handoff.

Creating A Handoff

Create or update a handoff when the user asks to pause, save state, preserve context, prepare for another agent, or when a meaningful milestone is complete.

Include:

• timestamp and timezone
• project path and branch
• latest commit and dirty files
• goal and current progress
• files changed in this session
• decisions confirmed this session
• validation commands and results
• blockers, risks, and assumptions
• exact next action for the next agent

Use references/handoff-template.md when writing a new handoff from scratch.

Working Rules

• Preserve unrelated local changes.
• Do not rewrite the handoff system just to make it neater.
• Prefer small, reviewable edits that match the current stack and conventions.
• Keep continuity docs factual. Separate confirmed state, assumptions, blockers, risks, and next actions.
• Update continuity docs only for facts that changed in this session.
• Avoid secrets in handoff files: API keys, tokens, passwords, private customer data, and sensitive internal URLs.
• Do not claim completion until validation evidence covers the actual requested scope.

Validation

Choose validation by blast radius:

• Docs or planning only: check paths, links, and internal consistency.
• Frontend code: run available lint/typecheck/build and browser checks when visual behavior matters.
• Backend code: run targeted tests first, then broader suites if shared behavior changed.
• Deployment or GitHub sync: verify remote status, URL, commit, or deployment result.
• If validation is unavailable or incomplete, state exactly what was not verified.

Output Shape

For a resume request:

I read the project instructions, state docs, handoff notes, decisions, and git state.
Current state: ...
Branch/dirty files: ...
Constraints/blockers: ...
Next I will ...

For a completed implementation:

• what changed
• where it changed
• validation commands and results
• remaining risks or follow-up implied by the project plan

For a handoff:

• write the handoff file if requested or appropriate
• then summarize the resume point, validation, and next concrete task