hk-breadcrumb-creator

Name: hk-breadcrumb-creator
Author: deepklarity

84stars12forks

How to install hk-breadcrumb-creator?

deepklarity/harness-kit/hk-breadcrumb-creator

$npx -y skills add deepklarity/harness-kit --skill hk-breadcrumb-creator

Installs into the current project.

Summary

Traces a workflow end-to-end through the harness-kit monorepo and creates a breadcrumb analysis doc in docs/breadcrumb_analysis/. Use this skill whenever the user wants to document a flow, trace a workflow, understand how a feature works across layers (frontend → backend → worker

Files · 1

View on GitHub

SKILL.md

1	# /hk-breadcrumb-creator — Workflow Breadcrumb Analysis
2
3	Traces a workflow through the harness-kit monorepo and produces a compact debugging reference. The output is for devs and agents who need to find where things break — not for onboarding docs or architecture overviews.
4
5	## Context
6
7	<flow_context> $ARGUMENTS </flow_context>
8
9	If the context above is empty, ask: "Which flow do you want to trace? Describe it in terms of the user action or system event that kicks it off."
10
11	## Step 0: Check existing breadcrumbs
12
13	Before scoping anything, read `docs/breadcrumb_analysis/_INDEX.md` to see what already exists. This file lists every breadcrumb folder and what it traces.
14
15	Compare the user's request against the existing entries and make one of three decisions:
16
17	1. Already covered — The flow is substantially documented in an existing breadcrumb. Tell the user which one covers it and what it contains. Ask if they want to update/extend that existing doc instead of creating a new one.
18
19	2. Partially overlapping — An existing breadcrumb covers part of the flow (e.g., user asks about "task execution" and `spec-task-lifecycle/02-execute-and-dispatch/` covers the dispatch side but not the harness execution internals). Options:
20	- Extend the existing breadcrumb (add sections to its FLOW/DETAILS/DEBUG files, or add a new sub-flow folder)
21	- Create a new breadcrumb that covers the non-overlapping portion, cross-referencing the existing one
22
23	3. New territory — Nothing in the index covers this flow. Proceed to Step 1.
24
25	When extending an existing breadcrumb, read its current FLOW.md first so you don't duplicate content. Add new information that complements what's there — don't rewrite sections that are already accurate.
26
27	When creating a new breadcrumb that's adjacent to an existing one, add cross-references in both directions (a "See also" line in the new doc pointing to the existing one, and optionally a note in the existing doc pointing to the new one).
28
29	Present your decision to the user before proceeding. Something like:
30
31	```
32	Existing breadcrumbs I checked:
33	- spec-task-lifecycle/02-execute-and-dispatch — covers DAG dispatch, task status transitions
34	- harness-isolation-testing — covers harness CLI construction, MCP config, streaming
35
36	Your request overlaps with <X> in these areas: <list>.
37	I recommend: <extend existing / create new focused on Y / already covered>.
38	```
39
40	## Step 1: Scope the flow
41
42	Before touching any code, define the boundaries:
43
44	```
45	FLOW: <name — short, kebab-case, used as folder name>
46	TRIGGER: <what kicks it off — button click, API call, CLI command, cron>
47	LAYERS: <which layers it touches — fe, api, celery, odin, db>
48	END STATE: <what the user/system sees when it completes>
49	```
50
51	If the flow is large (touches 5+ files per layer, or has multiple independent branches), break it into sub-flows. Each sub-flow gets its own folder. Create a parent `_INDEX.md` that links them.
52
53	Example of when to split:
54	- "spec execution" → split into: `spec-planning`, `spec-task-dispatch`, `spec-task-execution`, `spec-assembly`
55	- "task creation" → probably fine as one flow (FE form → API → DB → response)
56
57	Ask the user to confirm the scope before proceeding.
58
59	## Step 2: Trace the flow
60
61	Work through each layer the flow touches, in execution order. For each hop, record:
62
63	1. Source file and function — where the action originates
64	2. What it does — one line, no fluff
65	3. What it passes — key data (payload shape, IDs, status values)
66	4. Where it goes next — the next file/function/service in the chain
67
68	Use the codebase directly. Read the actual code. Don't guess from file names.
69
70	### Tracing tips
71
72	- Frontend → Backend: Search for the API URL in the frontend service files (`src/services/`). Match it to the Django URL conf and view.
73	- Backend → Celery: Search for `.delay(` or `.apply_async(` calls. Check `config/celery.py` and any `tasks.py` files.
74	- Backend → Odin: Look for `subprocess` calls to `odin` CLI or check `dag_executor.py` for execution strategy routing.
75	- Odin internals: Follow from `cli.py` → `orchestrator.py` → harness `execute()` methods.
76	- Signal/hook chains: Check Django signals, DRF `perform_create`/`perform_update` overrides, and model `save()` methods for side effects.
77
78	## Step 3: Create t

People who liked this also viewed

6 picks

Type

hk-breadcrumb-creator

84stars12forks

View on GitHub

How to install hk-breadcrumb-creator?

deepklarity/harness-kit/hk-breadcrumb-creator

$npx -y skills add deepklarity/harness-kit --skill hk-breadcrumb-creator

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /hk-breadcrumb-creator — Workflow Breadcrumb Analysis
2
3	Traces a workflow through the harness-kit monorepo and produces a compact debugging reference. The output is for devs and agents who need to find where things break — not for onboarding docs or architecture overviews.
4
5	## Context
6
7	<flow_context> $ARGUMENTS </flow_context>
8
9	If the context above is empty, ask: "Which flow do you want to trace? Describe it in terms of the user action or system event that kicks it off."
10
11	## Step 0: Check existing breadcrumbs
12
13	Before scoping anything, read `docs/breadcrumb_analysis/_INDEX.md` to see what already exists. This file lists every breadcrumb folder and what it traces.
14
15	Compare the user's request against the existing entries and make one of three decisions:
16
17	1. Already covered — The flow is substantially documented in an existing breadcrumb. Tell the user which one covers it and what it contains. Ask if they want to update/extend that existing doc instead of creating a new one.
18
19	2. Partially overlapping — An existing breadcrumb covers part of the flow (e.g., user asks about "task execution" and `spec-task-lifecycle/02-execute-and-dispatch/` covers the dispatch side but not the harness execution internals). Options:
20	- Extend the existing breadcrumb (add sections to its FLOW/DETAILS/DEBUG files, or add a new sub-flow folder)
21	- Create a new breadcrumb that covers the non-overlapping portion, cross-referencing the existing one
22
23	3. New territory — Nothing in the index covers this flow. Proceed to Step 1.
24
25	When extending an existing breadcrumb, read its current FLOW.md first so you don't duplicate content. Add new information that complements what's there — don't rewrite sections that are already accurate.
26
27	When creating a new breadcrumb that's adjacent to an existing one, add cross-references in both directions (a "See also" line in the new doc pointing to the existing one, and optionally a note in the existing doc pointing to the new one).
28
29	Present your decision to the user before proceeding. Something like:
30
31	```
32	Existing breadcrumbs I checked:
33	- spec-task-lifecycle/02-execute-and-dispatch — covers DAG dispatch, task status transitions
34	- harness-isolation-testing — covers harness CLI construction, MCP config, streaming
35
36	Your request overlaps with <X> in these areas: <list>.
37	I recommend: <extend existing / create new focused on Y / already covered>.
38	```
39
40	## Step 1: Scope the flow
41
42	Before touching any code, define the boundaries:
43
44	```
45	FLOW: <name — short, kebab-case, used as folder name>
46	TRIGGER: <what kicks it off — button click, API call, CLI command, cron>
47	LAYERS: <which layers it touches — fe, api, celery, odin, db>
48	END STATE: <what the user/system sees when it completes>
49	```
50
51	If the flow is large (touches 5+ files per layer, or has multiple independent branches), break it into sub-flows. Each sub-flow gets its own folder. Create a parent `_INDEX.md` that links them.
52
53	Example of when to split:
54	- "spec execution" → split into: `spec-planning`, `spec-task-dispatch`, `spec-task-execution`, `spec-assembly`
55	- "task creation" → probably fine as one flow (FE form → API → DB → response)
56
57	Ask the user to confirm the scope before proceeding.
58
59	## Step 2: Trace the flow
60
61	Work through each layer the flow touches, in execution order. For each hop, record:
62
63	1. Source file and function — where the action originates
64	2. What it does — one line, no fluff
65	3. What it passes — key data (payload shape, IDs, status values)
66	4. Where it goes next — the next file/function/service in the chain
67
68	Use the codebase directly. Read the actual code. Don't guess from file names.
69
70	### Tracing tips
71
72	- Frontend → Backend: Search for the API URL in the frontend service files (`src/services/`). Match it to the Django URL conf and view.
73	- Backend → Celery: Search for `.delay(` or `.apply_async(` calls. Check `config/celery.py` and any `tasks.py` files.
74	- Backend → Odin: Look for `subprocess` calls to `odin` CLI or check `dag_executor.py` for execution strategy routing.
75	- Odin internals: Follow from `cli.py` → `orchestrator.py` → harness `execute()` methods.
76	- Signal/hook chains: Check Django signals, DRF `perform_create`/`perform_update` overrides, and model `save()` methods for side effects.
77
78	## Step 3: Create t

People who liked this also viewed

6 picks

Type