notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/pl-pause-write-templates.md
View on GitHub# Pause-Work Write Templates
Verbatim Phase 4 (WRITE) templates for HANDOFF.json and .continue-here.md, plus WIP commit guidance.
## Step 1: Write HANDOFF.json
Write to `{project_root}/HANDOFF.json` with UTC ISO 8601 timestamps for unambiguous parsing across time zones and system clocks. Include the `drafted_adrs` field from Phase 3 — omit the field entirely (not null, not `[]`) if no ADRs were drafted, so `/resume-work` can detect absence reliably.
Include `agent_outputs` only when a parallel agent wave (fan-out dispatch) was interrupted mid-flight and some agents already returned. It caches per-agent output keyed by a deterministic input hash so `/resume-work` can reuse finished agents' output instead of re-dispatching them (saving tokens). Omit the field entirely when no agent wave was in progress. Compute each key with `scripts/feature-state.py`'s `agent_input_hash(prompt, inputs, paths)` (SHA256 over the normalized dispatch input plus the content of every file in `paths=`; list every repo file the agent read but did not write, so an edit before resume forces a re-dispatch; leave out files the agent writes, because its dispatch-time key covers their old bytes and the agent would always miss on resume and re-apply edits already on disk) and write entries with `store_agent_output`. Compute each agent's key at dispatch time, before the agent runs, and keep it with the dispatch record; at pause, store each returned agent's output under the key captured at its dispatch. Do not recompute the key at pause: another agent in the same wave, or the orchestrator, may have edited a listed file after this agent read it, and a pause-time hash would then cover the edited bytes while the cached output judges the old ones, so resume reuses a stale verdict. Hash at pause only when no file in `paths=` could have changed since dispatch (no agent in the wave writes files and nothing else edited the repo); if you cannot rule that out and have no dispatch-time key, omit that agent's entry so resume re-dispatches it — keeping hashing deterministic in code rather than guessed in prose:
```json
{
"created_at": "<ISO 8601 UTC timestamp>",
"task_summary": "<Brief description of the overall task>",
"completed_tasks": [
"<Specific completed item 1>",
"<Specific completed item 2>"
],
"remaining_tasks": [
"<Specific remaining item 1>",
"<Specific remaining item 2>"
],
"blockers": [
"<Blocker if any, or empty array>"
],
"decisions": {
"<Decision 1>": "<Reasoning>",
"<Decision 2>": "<Reasoning>"
},
"uncommitted_files": [
"<file1>",
"<file2>"
],
"next_action": "<Specific next action with file paths and integration points>",
"context_notes": "<Mental model, rejected approaches, gotchas, assumptions>",
"branch": "<current branch name>",
"base_branch": "main",
"false_completions": [
"<file:line — placeholder marker found, if any>"
],
"drafted_adrs": [
{"number": "<N>", "path": "adr/<N>-<slug>.md", "title": "<title>"}
],
"agent_outputs": {
"<input_hash>": {
"output": "<agent's returned output>",
"label": "<agent name or role, e.g. security-reviewer>",
"timestamp": "<ISO 8601 UTC timestamp>"
}
}
}
```
The `agent_outputs` map is the resume cache for interrupted agent waves. Each key is the deterministic `agent_input_hash(prompt, inputs, paths)` of the agent's dispatch input and the files it read; the value records its output, a human-readable `label`, and when it was captured. Omit the whole field when no agent wave was interrupted. A handoff missing this field loads as an empty cache, so older artifacts keep working.
## Step 2: Write .continue-here.md
Write to `{project_root}/.continue-here.md` because humans need prose-form state before committing to `/resume-work`. Include the ADR section only if `drafted_adrs` is non-empty — an empty section wastes the reader's attention and signals noise:
```markdown
# Continue Here
## What I was doing
[Prose description of the task, current state, and approach being taken]
## What's done
- [Completed item 1]
- [Completed item 2]
## What's next
[Specific next action — what to do, which files, why this step]
## Key decisions
- [Decision 1]: [Why]
- [Decision 2]: [Why]
## Watch out for
- [Blockers, gotchas, dead ends already explored]
- [False completions found: file:line — marker]
## Uncommitted work
- [file1 — brief description of changes]
- [file2 — brief description of changes]
## ADRs Drafted from Session Learnings
- [ADR-N: Title — adr/N-slug.md]
```
Omit the "ADRs Drafted from Session Learnings" section entirely when `drafted_adrs` is empty.
## Step 3: Suggest WIP commit if needed
If there are uncommitted changes (from Phase 1 Step 3), display a warning because uncommitted work can be lost if the worktree is cleaned up. However, let the user decide whether to commit because auto-committing removes the user's ability to decide — changes may be experimental, broken, or intentionally staged for review.
```
WARNING: Uncommitted changes detected in N file(s):
- file1
- file2
Consider a WIP commit before ending the session:
git add <files> && git commit -m "wip: <description>"
Uncommitted work can be lost if the worktree is cleaned up.
```
## Step 4: Optional commit of handoff files
If `--commit` flag was provided:
```bash
git add HANDOFF.json .continue-here.md
git commit -m "chore: session handoff artifacts"
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |