Create and receive handoff documents for context transfer. Use when transferring work, resuming sessions, or filing bug reports. Trigger with /epa-handoff.
npx claudepluginhub emasoft/emasoft-plugins --plugin emasoft-programmer-agentThis skill uses the workspace's default tool permissions.
This skill enables the Emasoft Programmer Agent (EPA) to create and receive handoff documents for seamless context transfer between agents and sessions. Handoff documents are structured Markdown files with YAML frontmatter that capture work state, task context, bug reports, and checkpoint data. The EPA uses this skill whenever it receives delegated work from the Emasoft Orchestrator Agent (EOA)...
Writes or updates HANDOFF.md with project goal, current progress, what worked/didn't, and next steps for agent handoffs with fresh context.
Writes or updates structured handoff documents (HANDOFF.md) with Goal, First Action, Context, Progress, successes, failures, and next steps for resuming work with a fresh agent.
Generates next-session.md or phase-handoff.md from cwf-state.yaml, plan.md, lessons.md, and logs to preserve context across agent sessions or phases. Triggers on 'cwf:handoff'.
Share bugs, ideas, or general feedback.
This skill enables the Emasoft Programmer Agent (EPA) to create and receive handoff documents for seamless context transfer between agents and sessions. Handoff documents are structured Markdown files with YAML frontmatter that capture work state, task context, bug reports, and checkpoint data. The EPA uses this skill whenever it receives delegated work from the Emasoft Orchestrator Agent (EOA), needs to pass completed work to the Emasoft Integrator Agent (EIA), discovers bugs during implementation, or must save progress before a session ends. All handoff documents are stored under $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/ in a standardized directory structure that all agents in the ecosystem can read.
Before using this skill, ensure the following conditions are met:
localhost:23000 for inter-agent messaging notifications when handoffs are created or received.$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/. Create it with mkdir -p "$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/" if it does not exist.epa-<project>-<instance>), so that handoff notifications reach the correct recipient.$CLAUDE_PROJECT_DIR environment variable must be set to the root of the project directory. This variable is set automatically by Claude Code when a project is loaded.references/ relative to this skill, which contains the detailed operation guides for each handoff operation.Follow these numbered steps when performing handoff management:
references/ directory. Read the full guide before proceeding.mkdir -p "$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/epa-<task-name>/" to ensure the task-specific subdirectory is available.type, from, to, task, timestamp, and status.curl -X POST "http://localhost:23000/api/messages" with the handoff file path in the message body.current.md to the archive/ subdirectory with a timestamp suffix before writing the new version.Handoff documents preserve work state across:
This skill provides four core operations for handoff management:
File: op-read-handoff-document.md
Contents:
Use this operation when receiving work from EOA or resuming from a previous session.
File: op-create-handoff-document.md
Contents:
Use this operation when transferring work to another agent or ending a session.
File: op-write-bug-report.md
Contents:
Use this operation when discovering bugs during implementation work.
File: op-document-work-state.md
Contents:
Use this operation to save current work for later continuation.
All handoff documents are stored in a standardized location:
$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/
├── epa-<task-name>/
│ ├── current.md # Active handoff document
│ ├── archive/ # Previous handoff versions
│ └── bugs/ # Bug reports for this task
This skill integrates with AI Maestro for inter-agent messaging:
| Situation | Operation to Use |
|---|---|
| Received delegation from EOA | Read Handoff Document |
| Completing work, passing to next agent | Create Handoff Document |
| Found a bug during implementation | Write Bug Report |
| Need to pause work for later | Document Work State |
| Resuming after context clear | Read Handoff Document |
This skill produces the following artifacts:
current.md): Markdown files with YAML frontmatter stored at $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/epa-<task-name>/current.md. Contains task context, completed items, pending items, checkpoint state, and file references.bugs/<bug-id>.md): Structured bug reports stored in the bugs/ subdirectory of the task handoff folder. Each report includes reproduction steps, expected versus actual behavior, code references, and severity classification.archive/<timestamp>-current.md): Previous versions of handoff documents preserved with timestamp prefixes for audit trail and rollback capability.Copy this checklist and track your progress:
Common errors encountered during handoff management and their resolutions:
| Error | Cause | Resolution |
|---|---|---|
| Handoff directory does not exist | $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/ was never created | Run mkdir -p "$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/epa-<task-name>/" to create it |
| AI Maestro notification fails | AI Maestro is not running on localhost:23000 | Verify AI Maestro is running with curl -s "http://localhost:23000/api/health". If it returns an error, start AI Maestro before retrying |
| YAML frontmatter parse error | Missing --- delimiters or invalid YAML syntax in the handoff document | Re-read the handoff document and ensure the frontmatter starts and ends with --- on its own line, and all values are properly quoted if they contain special characters |
| Receiving agent not found | The to field in the handoff references an agent session name that is not registered with AI Maestro | Check the team registry at .emasoft/team-registry.json for valid agent session names, or ask EOA for the correct recipient |
| Handoff document is stale | A current.md already exists from a previous task iteration | Archive the existing document by moving it to archive/ with a timestamp suffix, then create the new handoff as current.md |
The EPA has finished implementing a feature and needs to pass it to EIA for code review:
---
type: handoff
from: epa-svgbbox-programmer-001
to: eia-svgbbox-reviewer
task: implement-bbox-calculation
timestamp: 2026-02-14T10:30:00Z
status: implementation-complete
---
# Handoff: implement-bbox-calculation
## Completed Items
- Implemented `calculate_bbox()` function in `src/bbox/calculator.py`
- Added unit tests in `tests/unit/test_calculator.py` (12 tests, all passing)
- Updated type annotations and docstrings
## Files Modified
- `src/bbox/calculator.py` (new file, 145 lines)
- `tests/unit/test_calculator.py` (new file, 210 lines)
## Pending Items
- Code review by EIA
- Integration test with SVG parser module
## Notes
- Used numpy for matrix operations as specified in architecture doc
- Edge case: zero-dimension bounding boxes return empty BBox object (see test_empty_bbox)
After writing this to $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/epa-implement-bbox-calculation/current.md, send a notification:
curl -X POST "http://localhost:23000/api/messages" \
-H "Content-Type: application/json" \
-d '{"to": "eia-svgbbox-reviewer", "subject": "Handoff ready: implement-bbox-calculation", "priority": "normal", "content": {"type": "handoff", "message": "Implementation complete. Handoff at thoughts/shared/handoffs/epa-implement-bbox-calculation/current.md"}}'
The EPA receives a message from EOA with a task delegation. The first step is to read the handoff:
# 1. Read the handoff document
cat "$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/eoa-refactor-parser/current.md"
# 2. Extract key fields from YAML frontmatter
# Look for: task, requirements, deadline, dependencies, checkpoint (if resuming)
# 3. Acknowledge receipt via AI Maestro
curl -X POST "http://localhost:23000/api/messages" \
-H "Content-Type: application/json" \
-d '{"to": "eoa-svgbbox-orchestrator", "subject": "Handoff received: refactor-parser", "priority": "normal", "content": {"type": "acknowledgment", "message": "EPA received handoff for refactor-parser. Starting work."}}'
While working on a feature, the EPA discovers a bug in an existing module:
---
type: bug-report
from: epa-svgbbox-programmer-001
task: implement-bbox-calculation
bug-id: BUG-2026-0214-001
severity: high
timestamp: 2026-02-14T11:15:00Z
---
# Bug Report: SVG path parser returns incorrect coordinates for arc commands
## Reproduction Steps
1. Load `tests/fixtures/arc-path.svg`
2. Call `parse_path(svg_content)` from `src/parser/path_parser.py`
3. Inspect the returned coordinate list for arc (`A`) commands
## Expected Behavior
Arc command coordinates should be absolute after conversion from relative coordinates.
## Actual Behavior
Arc commands retain relative coordinates, causing bbox calculation to be offset by the current pen position.
## Affected Code
- `src/parser/path_parser.py`, function `_parse_arc_command()`, line 87-102
## Related Tests
- `tests/unit/test_path_parser.py::test_arc_absolute_coords` (currently failing)
Save this to $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/epa-implement-bbox-calculation/bugs/BUG-2026-0214-001.md and escalate to EOA for triage.
Related skills, documents, and tools for handoff management:
http://localhost:23000/api/messages).emasoft/team-registry.json) -- Contains valid agent session names needed for the to field in handoff documents