handoff-driven-development

Files (7)

• SKILL.md
• doc-templates.md · references/
• migration-v2-to-v3.md · references/
• neat-freak-interop.md · references/
• init_handoff_docs.py · scripts/
• validate_handoff_skill.py · scripts/
• test-prompts.json

SKILL.md (first lines)

# Handoff-Driven Development

Handoff-Driven Development is the project's **operational control plane**.

It answers:

> **Where are we now, where are we going, and what should happen next?**

It owns **current direction and current operational state**. It does not own project
history and it does not orchestrate other continuity skills.

## Source-of-Truth Contract

| Question | Source of Truth |
|---|---|
| What actually exists/works now? | verified code/runtime |
| Durable product north star and boundaries? | `docs/PROJECT_BRIEF.md` |
| Active milestone/slice/blocker/next work? | `docs/TASKS.md` |
| Current architecture/contracts/runtime strategy? | `docs/TECH_PLAN.md` + code |
| What has actually been verified? | `docs/QUALITY.md` or explicit evidence in `TASKS.md` |
| What must the next agent know **now**? | `docs/AGENT_HANDOFF.md` |
| Why did we get here / what failed before? | historical memory, outside this skill |
| Are knowledge surfaces mutually clean? | an auditor/reconciler such as `neat-freak` |

For **current-state** conflicts:

**verified code/runtime -> current operational docs -> historical material as context**.

Never preserve a stale operational claim merely because an older document or memory
entry says it was once true.

## Operational Docs

```text
docs/
├── PROJECT_BRIEF.md   # durable north star, users, boundaries, constraints
├── TASKS.md           # active milestone/slice, blocker, acceptance, near backlog
├── TECH_PLAN.md       # current architecture/contracts/runtime strategy
├── QUALITY.md         # optional verification evidence / quality gates
└── AGENT_HANDOFF.md   # concise current baton and exact next slice
```

Read `references/doc-templates.md` for templates and budgets.

## Ownership Boundaries

### This skill owns

- current project direction and boundaries;
- current milestone and active slice;
- current blocker/uncertainty;
- implementation versus verification state;
- current architecture/contracts when documented;
- exactly what the next agent should do next.

### This skill does not own

- historical narrative, old attempts, or why a superseded design once existed;
- per-session transcripts or changelogs;
- cleanup policy across unrelated docs/workspace artifacts;
- the user-facing orchestration of `project-memory`, this skill, and `neat-freak`.

A higher-level workflow such as `project-continue` may coordinate those components. When that
happens, perform only the current-state operation requested here and return control
to the orchestrator.

## Core Rules

1. Read operational docs before broad code exploration when aligning existing work.
2. Verify material current claims against code/runtime when stale state is plausible.
3. Keep one active slice unless parallel lanes are explicit.
4. State non-goals before implementation when scope could drift.
5. **Implemented** and **verified** are different states.
6. Update docs at meaningful planned/implemented/verified/handoff boundaries, not on
   every chat turn.
7. `TASKS.md` + `AGENT_HANDOFF.md` are the only owners of current next action.
8. `AGENT_HANDOFF.md` is a short baton, not a session transcript.
9. `PROJECT_BRIEF.md` changes only when durable product direction/boundaries change.
10. `TECH_PLAN.md` describes the current technical contract, not architecture history.
11. CLAUDE.md, AGENTS.md, rules, and similar instruction files contain durable
    constraints, commands, entry points, and pointers — not duplicate current status.

## Operation: Align / Resume Current State

Use when entering an existing project or when another workflow requests present-state
alignment.

1. Read current operational surfaces in this order:
   `AGENT_HANDOFF -> TASKS -> TECH_PLAN -> PROJECT_BRIEF -> QUALITY (if needed)`.
2. Inspect only enough code/git/runtime evidence to validate material or doubtful
   current claims.
3. Resolve contradictions explicitly using the Source-of-Truth Contract.
4. Report:
   - current direction;
   - current milestone and active slice;
   - recently verified result;
   - blocker, uncertainty, or unverified item;
   - exactly one recommended next action.
5. Do **not** infer historical rationale. If history is needed, tell the caller that a
   historical-memory layer should provide it.
6. If a higher-level orchestrator requested alignment, return the aligned state to it
   rather than starting unrelated work.

## Operation: Plan Current Slice

Define one observable goal with:

- scope;
- non-goals;
- acceptance criteria;
- verification method;
- blockers/dependencies;
- commit/review boundary when applicable.

Record it in `TASKS.md`. Keep the active slice small enough for another agent to
understand and verify independently.

## Operation: Implement / Diagnose

From edisoncgh/edison-daily-skills, MIT.

More from edisoncgh/edison-daily-skills