---
name: forge:pause-work
description: Create context handoff when pausing work mid-phase
argument-hint: ""
allowed-tools:
  - Read
  - Write
  - Bash
---

<objective>
Create `.continue-here.md` handoff file to preserve complete work state across sessions.

Use when: You need to stop work mid-phase and want to resume later with full context preserved.
</objective>

<execution_context>
@state/STATE.json
@CLAUDE.md
</execution_context>

<context>
**Pause Work Workflow:**
1. Detect current phase from recent files
2. Gather complete state (position, completed work, remaining work, decisions, blockers)
3. Create handoff file with all context sections
4. Git commit as WIP
5. Provide resume instructions
</context>

<process>
**Execute pause-work workflow:**

1. **Detect Current Phase**
   - Check git status for recent changes
   - Identify phase from recent files
   - Check STATE.json for current phase

2. **Gather State**
   Use AskUserQuestion to capture:
   - **Current Position**: What were you working on?
   - **Completed Work**: What's done since last commit?
   - **Remaining Work**: What's left to do?
   - **Decisions Made**: Any decisions to remember?
   - **Blockers**: Anything blocking progress?
   - **Next Steps**: What to do when resuming?

3. **Create Handoff File**
   ```markdown
   # Continue Here — {timestamp}

   ## Phase
   **Phase:** {phase-name}
   **Status:** {in-progress|blocked|waiting}

   ## Position
   {current position in the work}

   ## Completed Work
   - [x] {completed item 1}
   - [x] {completed item 2}

   ## Remaining Work
   - [ ] {remaining item 1}
   - [ ] {remaining item 2}

   ## Decisions Made
   {important decisions to remember}

   ## Blockers
   {anything blocking progress}

   ## Next Steps
   1. {first step}
   2. {second step}

   ## Context Notes
   {any other context}

   ---
   **Paused:** {timestamp}
   **Resume:** Run `/forge:resume`
   ```

4. **Git Commit**
   - Stage all changes: `git add -A`
   - Commit as WIP: `git commit -m "wip: pause work - {phase-name}"`

5. **Submit Event**
   - Event type: WORK_PAUSED
   - Include: phaseId, handoffFile, timestamp
   - Write to state/events/

6. **Confirm**
   - Show handoff file location
   - Provide resume instructions
   - Confirm git commit created
</process>

<deliverables>
- .continue-here.md (complete handoff file)
- Git commit: "wip: pause work - {phase-name}"
- Event: WORK_PAUSED in state/events/
- STATE.json updated
</deliverables>

<next_steps>
- When ready to continue: `/forge:resume`
- Handoff file will be automatically loaded
- All context preserved
</next_steps>