handoff

Name: handoff
Author: tranhieutt

69stars41forks

How to install handoff?

tranhieutt/software_development_department/handoff

$npx -y skills add tranhieutt/software_development_department --skill handoff

Installs into the current project.

Summary

Generates the lightweight 3-field handoff summary for cross-domain work and optionally persists a formal handoff artifact for High-risk transfers.

Files · 1

View on GitHub

SKILL.md

1	# Handoff
2
3	Generate the lightweight handoff summary (`what was built`, `what's missing`,
4	`acceptance criteria`) and, when needed, save a formal handoff artifact to
5	`.tasks/handoffs/`. The receiver verifies the summary before starting work.
6
7	## Steps
8
9	### 1. Parse arguments
10
11	Extract from `$ARGUMENTS`:
12
13	\| Positional \| Required \| Description \|
14	\| :--- \| :--- \| :--- \|
15	\| `<from-agent>` \| yes \| Sending agent name (e.g. `backend-developer`) \|
16	\| `<to-agent>` \| yes \| Receiving agent name (e.g. `qa-engineer`) \|
17	\| `<artifact>` \| yes \| Primary file or path being handed off \|
18	\| `[task_id]` \| no \| Task ID to link checkpoint — auto-detected from active checkpoint if omitted \|
19
20	\| Flag \| Default \| Description \|
21	\| :--- \| :--- \| :--- \|
22	\| `--risk` \| `Medium` \| Risk tier: `Low`, `Medium`, `High` \|
23	\| `--status` \| `complete` \| Artifact status: `complete`, `partial`, `draft` \|
24	\| `--criteria` \| prompt \| Acceptance criteria strings (can be multi-value) \|
25	\| `--formal` \| off \| Force writing a durable handoff file even when risk is not High \|
26
27	If `from-agent`, `to-agent`, or `artifact` are missing, print usage and stop:
28
29	```text
30	Usage: /handoff <from-agent> <to-agent> <artifact> [task_id] \
31	[--risk Low\|Medium\|High] \
32	[--status complete\|partial\|draft] \
33	[--criteria "criterion 1" "criterion 2"] \
34	[--formal]
35
36	Example:
37	/handoff backend-developer qa-engineer src/api/auth.ts 042 \
38	--risk Medium --criteria "POST /auth returns 201" "Invalid creds → 401"
39
40	Schema reference: .claude/docs/handoff-schema.md
41	```
42
43	### 2. Validate agents
44
45	Check that `<from-agent>.md` and `<to-agent>.md` exist in `.claude/agents/`.
46	If either is missing, warn but continue:
47
48	```text
49	⚠️ Agent "<name>" not found in .claude/agents/ — check spelling.
50	```
51
52	### 3. Resolve task_id and context_snapshot
53
54	- If `task_id` was provided, check if `.tasks/checkpoints/<task_id>.md` exists.
55	If yes, set `context_snapshot` to that path.
56	- If `task_id` was NOT provided, scan `.tasks/checkpoints/` for the most recently
57	modified `.md` file (excluding `.gitkeep`) and use it as a suggestion.
58	- If no checkpoint exists, set `context_snapshot` to `null`.
59
60	### 4. Collect acceptance criteria
61
62	If `--criteria` flags were provided, use them directly.
63
64	If no criteria were provided, prompt:
65
66	```text
67	📋 Enter acceptance criteria for this handoff (one per line, blank line to finish):
68	>
69	```
70
71	Require at least 1 criterion. Reject vague criteria and ask for a rewrite:
72
73	- Contains "works correctly", "looks good", "should be fine", "seems OK" → reject
74	- Must describe a concrete, testable outcome
75
76	### 5. Get session info
77
78	Run `git branch --show-current` to get the current branch for the `session` field.
79	Get current ISO timestamp for `ts`.
80
81	### 6. Generate handoff summary
82
83	Build the 3-field summary per `.claude/docs/handoff-schema.md`:
84
85	```markdown
86	## Handoff Summary
87	- What was built: <artifact> is available with its current behavior/status
88	- What's missing: remaining gaps, partial work, or "Nothing blocking in current scope"
89	- Acceptance criteria:
90	- <crit1>
91	- <crit2>
92	```
93
94	Also prepare the formal JSON payload only when:
95	- `risk_tier` is `High` and the handoff crosses domains, or
96	- the caller passes `--formal`
97
98	When the formal artifact is needed, use this JSON:
99
100	```json
101	{
102	"from": "<from-agent>",
103	"to": "<to-agent>",
104	"task_id": "<task_id or null>",
105	"artifact": "<artifact>",
106	"artifact_status": "<status>",
107	"acceptance_criteria": ["<crit1>", "<crit2>"],
108	"context_snapshot": "<path or null>",
109	"risk_tier": "<risk>",
110	"ts": "<ISO>",
111	"session": "<branch>"
112	}
113	```
114
115	### 7. Save formal contract when required
116
117	If formal persistence is required, write to
118	`.tasks/handoffs/<from-agent>-to-<to-agent>-<task_id>.json`.
119	If `task_id` is null, use timestamp:
120	`.tasks/handoffs/<from-agent>-to-<to-agent>-<ts-compact>.json`.
121
122	If formal persistence is not required, do not create a file. The markdown
123	handoff summary is the default artifact.
124
125	### 8. Ledger entry (Medium / High risk only)
126
127	If `risk_tier` is `Medium` or `High`, append to `production/traces/decision_ledger.jsonl`:
128
129	```jsonl
130	{"ts":"<ISO>","session":"<branch>","agent_id":"<from-agent>","task_id":"<task_id>","request":"Handoff to <to-agent>","reasoning":"Artifact <artifact> is <status> — transferring ownership","choice":"Handoff summary prepared","outcome":"pass","risk_tier":"<risk>","duration_s":0

People who liked this also viewed

6 picks

Type

handoff

69stars41forks

View on GitHub

How to install handoff?

tranhieutt/software_development_department/handoff

$npx -y skills add tranhieutt/software_development_department --skill handoff

Installs into the current project.

Summary

Generates the lightweight 3-field handoff summary for cross-domain work and optionally persists a formal handoff artifact for High-risk transfers.

Files · 1

View on GitHub

SKILL.md

1	# Handoff
2
3	Generate the lightweight handoff summary (`what was built`, `what's missing`,
4	`acceptance criteria`) and, when needed, save a formal handoff artifact to
5	`.tasks/handoffs/`. The receiver verifies the summary before starting work.
6
7	## Steps
8
9	### 1. Parse arguments
10
11	Extract from `$ARGUMENTS`:
12
13	\| Positional \| Required \| Description \|
14	\| :--- \| :--- \| :--- \|
15	\| `<from-agent>` \| yes \| Sending agent name (e.g. `backend-developer`) \|
16	\| `<to-agent>` \| yes \| Receiving agent name (e.g. `qa-engineer`) \|
17	\| `<artifact>` \| yes \| Primary file or path being handed off \|
18	\| `[task_id]` \| no \| Task ID to link checkpoint — auto-detected from active checkpoint if omitted \|
19
20	\| Flag \| Default \| Description \|
21	\| :--- \| :--- \| :--- \|
22	\| `--risk` \| `Medium` \| Risk tier: `Low`, `Medium`, `High` \|
23	\| `--status` \| `complete` \| Artifact status: `complete`, `partial`, `draft` \|
24	\| `--criteria` \| prompt \| Acceptance criteria strings (can be multi-value) \|
25	\| `--formal` \| off \| Force writing a durable handoff file even when risk is not High \|
26
27	If `from-agent`, `to-agent`, or `artifact` are missing, print usage and stop:
28
29	```text
30	Usage: /handoff <from-agent> <to-agent> <artifact> [task_id] \
31	[--risk Low\|Medium\|High] \
32	[--status complete\|partial\|draft] \
33	[--criteria "criterion 1" "criterion 2"] \
34	[--formal]
35
36	Example:
37	/handoff backend-developer qa-engineer src/api/auth.ts 042 \
38	--risk Medium --criteria "POST /auth returns 201" "Invalid creds → 401"
39
40	Schema reference: .claude/docs/handoff-schema.md
41	```
42
43	### 2. Validate agents
44
45	Check that `<from-agent>.md` and `<to-agent>.md` exist in `.claude/agents/`.
46	If either is missing, warn but continue:
47
48	```text
49	⚠️ Agent "<name>" not found in .claude/agents/ — check spelling.
50	```
51
52	### 3. Resolve task_id and context_snapshot
53
54	- If `task_id` was provided, check if `.tasks/checkpoints/<task_id>.md` exists.
55	If yes, set `context_snapshot` to that path.
56	- If `task_id` was NOT provided, scan `.tasks/checkpoints/` for the most recently
57	modified `.md` file (excluding `.gitkeep`) and use it as a suggestion.
58	- If no checkpoint exists, set `context_snapshot` to `null`.
59
60	### 4. Collect acceptance criteria
61
62	If `--criteria` flags were provided, use them directly.
63
64	If no criteria were provided, prompt:
65
66	```text
67	📋 Enter acceptance criteria for this handoff (one per line, blank line to finish):
68	>
69	```
70
71	Require at least 1 criterion. Reject vague criteria and ask for a rewrite:
72
73	- Contains "works correctly", "looks good", "should be fine", "seems OK" → reject
74	- Must describe a concrete, testable outcome
75
76	### 5. Get session info
77
78	Run `git branch --show-current` to get the current branch for the `session` field.
79	Get current ISO timestamp for `ts`.
80
81	### 6. Generate handoff summary
82
83	Build the 3-field summary per `.claude/docs/handoff-schema.md`:
84
85	```markdown
86	## Handoff Summary
87	- What was built: <artifact> is available with its current behavior/status
88	- What's missing: remaining gaps, partial work, or "Nothing blocking in current scope"
89	- Acceptance criteria:
90	- <crit1>
91	- <crit2>
92	```
93
94	Also prepare the formal JSON payload only when:
95	- `risk_tier` is `High` and the handoff crosses domains, or
96	- the caller passes `--formal`
97
98	When the formal artifact is needed, use this JSON:
99
100	```json
101	{
102	"from": "<from-agent>",
103	"to": "<to-agent>",
104	"task_id": "<task_id or null>",
105	"artifact": "<artifact>",
106	"artifact_status": "<status>",
107	"acceptance_criteria": ["<crit1>", "<crit2>"],
108	"context_snapshot": "<path or null>",
109	"risk_tier": "<risk>",
110	"ts": "<ISO>",
111	"session": "<branch>"
112	}
113	```
114
115	### 7. Save formal contract when required
116
117	If formal persistence is required, write to
118	`.tasks/handoffs/<from-agent>-to-<to-agent>-<task_id>.json`.
119	If `task_id` is null, use timestamp:
120	`.tasks/handoffs/<from-agent>-to-<to-agent>-<ts-compact>.json`.
121
122	If formal persistence is not required, do not create a file. The markdown
123	handoff summary is the default artifact.
124
125	### 8. Ledger entry (Medium / High risk only)
126
127	If `risk_tier` is `Medium` or `High`, append to `production/traces/decision_ledger.jsonl`:
128
129	```jsonl
130	{"ts":"<ISO>","session":"<branch>","agent_id":"<from-agent>","task_id":"<task_id>","request":"Handoff to <to-agent>","reasoning":"Artifact <artifact> is <status> — transferring ownership","choice":"Handoff summary prepared","outcome":"pass","risk_tier":"<risk>","duration_s":0

People who liked this also viewed

6 picks

Type