Skip to content

worked-example.md

Latest commit

 

History

History
147 lines (101 loc) · 3.44 KB

worked-example.md

File metadata and controls

147 lines (101 loc) · 3.44 KB
Raw

Worked Example

This example shows the full handoff loop on a small feature so the workflow is concrete instead of abstract.

Scenario

You want to add a --json flag to an existing CLI command.

1. Initialize the feature

handoff init json-output

This creates the workspace:

.handoff/
  current -> features/json-output
  features/json-output/
    FEATURE.md
    SPEC.md
    DESIGN.md
    STATE.md
    SESSION.md
    DECISIONS.md

2. Write the feature brief

Start with .handoff/current/FEATURE.md.

Example:

# Feature: json-output

## Goal
Add a `--json` flag to `handoff status` so scripts can consume the current state.

## Requirements
- Preserve the existing human-readable output by default.
- Return deterministic JSON keys.
- Fail with a clear error if no active feature exists.

## Non-Goals
- Do not redesign `handoff status`.
- Do not add network behavior.

3. Use the default workflow

For most features, use:

handoff run --copy

handoff run decides what prompt comes next:

  • if planning is incomplete, it emits a planning prompt
  • if the execution plan is ready, it emits an execution prompt

Use:

handoff next
handoff status

to see the current state without generating another prompt.

4. Planning artifacts take shape

After planning, the feature workspace should converge toward:

  • SPEC.md: clear behavioral requirements and acceptance criteria
  • DESIGN.md: optional implementation notes when the change is complex enough
  • STATE.md: execution plan with exactly one [>] current step while work remains
  • SESSION.md: continuation-safe summary of what changed and what comes next
  • DECISIONS.md: durable decisions that should survive future sessions

Example execution plan:

# Current Step
Implement JSON serialization for `handoff status`.

# Execution Plan
- [x] Add CLI flag parsing for `--json`.
- [>] Return JSON output from the status command.
- [ ] Add tests for no-active-feature and healthy-status cases.

5. Execute with continuity

Once the plan is ready, either:

handoff run --copy

or:

handoff start --copy
handoff continue --copy

Use run when you want handoff to choose automatically. Use start and continue when you want to drive the execution flow directly.

6. Keep artifacts current during execution

During implementation:

  • mark completed steps as [x]
  • record evidence in STATE.md for completed steps
  • keep exactly one [>] if work remains
  • rewrite SESSION.md after meaningful progress
  • update DECISIONS.md when a durable product or architecture choice changes
  • use handoff validate when you need a hard readiness check

7. Finish cleanly

When all planned steps are done:

  • every execution step should be [x]
  • completed steps should include evidence for changed files and validation
  • SESSION.md should summarize what shipped and any follow-up items
  • handoff next should stop pointing to more execution work

Use handoff drift --copy if you want an audit prompt that compares the saved spec, plan, session, decisions, and implementation before closing the feature.

Why This Example Matters

The product is not just “prompt generation.”

The value is the saved state on disk:

  • the feature brief survives
  • the plan survives
  • the execution ledger survives
  • the continuation context survives
  • the decision history survives

That is what lets a later AI session resume without starting over.