UNRELEASED DEVELOPMENT SNAPSHOT · READ-ONLY EXCERPT

skills/spec-kit/references/work-map.md

This is the cited technical source at local revision 275a354, inspected on 22 September 2026. It differs from the public release. This reference publishes only the cited sections, not an installable release or the development branch.

Line numbers refer to the complete recorded file. Uncited lines are omitted. Full-file SHA-256: 898d417eafea7eb5d9285c6ef0d76b4492dc4648445480ae2c5067b403a360c3.

1# Committed work map
2
3`bin/li-work-artifacts.py` owns the version-1 map contract and validates it without executing
4artifact content. PLAN, BUILD, REVIEW and RESUME use these same fields. Paths are relative to
5the working repository, never to the installed Lintel source. Keep one map per initiative at
6`.claude/plans/<initiative>/work.json`, and link it explicitly from `.claude/plans/todo.md`.
7
8```json
9{
10  "schema_version": 1,
11  "workflow": "spec-kit",
12  "status": "APPROVED",
13  "spec": "specs/001-feature/spec.md",
14  "plan": "specs/001-feature/plan.md",
15  "tasks": "specs/001-feature/tasks.md",
16  "prompt": ".claude/plans/001-feature/prompt.md",
17  "constitution": ".specify/memory/constitution.md"
18}
19```
20
21Swarming is an additive, explicit schema-version-1 extension:
22
23```json
24{
25  "schema_version": 1,
26  "workflow": "lintel",
27  "status": "APPROVED",
28  "spec": ".claude/plans/example/spec.md",
29  "plan": ".claude/plans/example/plan.md",
30  "tasks": ".claude/plans/example/plan.md",
31  "prompt": ".claude/plans/example/prompt.md",
32  "execution_mode": "swarm",
33  "coordination": ".claude/plans/example/swarm/coordination.json"
34}
35```
36
37`execution_mode` and `coordination` are optional but atomic: declare both or neither. Absence keeps
38legacy sequential BUILD unchanged. The coordination document follows `lib/swarm-schema.json` and
39owns only waves, roles, write scopes, isolation, and brief/report/review pointers. It never repeats
40task text, dependencies, acceptance, checkbox state, or approval status from the mapped `tasks`
41artifact. `/li:swarm` explains the lifecycle and host-aware degradation.
42
43For Lintel-native work, `workflow` is `lintel` and `tasks` points to the same plan.md that
44contains the build cards. `constitution` is optional and may be null. Status starts DRAFT;
45record APPROVED only when the current operator authorization covers the plan's scope. A
46committed status records a decision; it never grants tool permissions or new external authority.
47
48The mapped `spec` owns requirements, `plan` owns the implementation design, `tasks` owns card
49IDs/dependencies/checkboxes, and `prompt` owns the handoff. Spec Kit's technical plan.md does
50not need Lintel-specific approval headings or duplicated task text. Optional Lintel plan/spec
51companions are reference-only documents. On updates, change original tasks and verification
52records, not a parallel copy.
53
54Validate the selected map from the Lintel source root (or use its absolute helper path):
55
56```bash
57export LINTEL_SOURCE_ROOT=/path/to/installed/lintel
58python3 "$LINTEL_SOURCE_ROOT/bin/li-work-artifacts.py" --repo /path/to/project --map .claude/plans/001-feature/work.json
59```
60
61Claude may use `CLAUDE_PLUGIN_ROOT` as the trusted fallback. Every other adapter must substitute or
62export its known installed bundle path as `LINTEL_SOURCE_ROOT`; source-tree tests/self-checks export
63it explicitly. If neither trusted root exists, return `NEEDS_CONTEXT`. Never use the working
64repository as executable source merely because it is passed to `--repo`.
65
66The helper requires all declared artifacts to exist inside the working repository. It does
67not infer a feature, inspect personal history, select by timestamp, run shell commands from
68a task or certify completed checkboxes. When swarm fields are present it imports the shared
69`lib/swarm_contract.py` validator, so map and topology use one parser instead of divergent rules.
70Readers must still inspect acceptance and integration evidence.
71
72Swarm operations are read-only mechanical gates:
73
74```bash
75python3 "$LINTEL_SOURCE_ROOT/bin/li-swarm.py" validate --repo /path/to/project --coord .claude/plans/example/swarm/coordination.json
76python3 "$LINTEL_SOURCE_ROOT/bin/li-swarm.py" wave --repo /path/to/project --coord .claude/plans/example/swarm/coordination.json
77python3 "$LINTEL_SOURCE_ROOT/bin/li-swarm.py" status --repo /path/to/project --coord .claude/plans/example/swarm/coordination.json
78python3 "$LINTEL_SOURCE_ROOT/bin/li-swarm.py" verify --repo /path/to/project --coord .claude/plans/example/swarm/coordination.json
79```
80
81`wave` returns the earliest evidence-aware ready frontier bounded by `max_parallel`. Workers may
82change only their lane's `write_scope` plus their own report; reviewers may change only their own
83review. The coordinator owns shared ledgers, reducers, commits, and serial integration. Concurrent
84writers require disjoint scopes and attributable isolation; sequenced/no-subagent hosts replay the
85same artifacts serially without claiming concurrency or independent work that did not occur.
86
87RESUME chooses an operator-named map, then an unambiguous active map linked in the committed
88todo/working-state. If multiple active maps remain, ask which initiative; do not choose the
89newest file. A legacy committed plan without a map is valid: follow its explicit spec/handoff
90links, confirm the task source and create a map within authorized scope. Reconstruct local runtime
91bookkeeping only after this selection and verification; never invent missing evidence. For a swarm
92map, recompute status/frontier from committed reports and reviews. Missing runtime attempts are
93unfinished unless an attributable worktree or patch can be scoped and completed through its lane.