Knowledge Hub SDLC Workflow

Knowledge Hub SDLC Workflow

RETIRED (S491): Describes the pre-Intent Planner/Executor/Checker SDLC harness — superseded by the no-planner Intent workflow (spec chain RESEARCH/PRODUCT/TECH per the canonical repo CLAUDE.md spec convention; plan/decomposition surface is the Intent workspace spec-note, DR-089). No longer canonical despite the status line below. Retained for historical context only.

Status: canonical. Single source of truth for the Spec → Plan → Implement → Verify → Curate workflow on this project.

Authored: S49 (2026-05-18). Supersedes the S47 v1 (kh-sdlc-workflow.md pre-2026-05-18) and the four S45–S46 source docs that v1 collapsed (kh-workflow-orchestration.md, kh-workflow-orchestration-assessment.md, workflow-orchestration-assessment-feedback.md, workflow-orchestration-feedback-response.md).

Lineage: S46 bootstrapped the workflow harness (session-driver-cmux + four baseline workflow agents). S47 wrote the first version of this doc. S48 produced five atomic research outputs (T1–T5) and 49 open questions. Liam ratified the open questions in s48-feedback.md; the four remaining items were resolved in s49-open-resolutions.md. This rewrite reflects those ratifications.

Operational truth: the role definitions live in .claude/agents/ and .claude/skills/. This doc reflects them; if the agent and skill files disagree with this doc, the agent/skill files win and this doc is out of date. The matching authorship work (skill bodies, agent frontmatter, agent file renames) lands as the ID-2/ID-3/ID-4 sub-agents alongside this rewrite.

---

1. Purpose

Audience: Liam (product owner) and Claude Code (development partner) working a 1-user, task-driven SDLC across the Knowledge Hub repo.

Scope of this doc:

• Defines the five workflow roles, their forms (skill vs agent), and the boundary between them.
• Defines the task-driven lifecycle — ID-N Tasks and ID-N.M Subtasks as the universal unit of work.
• Defines the per-role skill routing matrix (what each role’s baseline-loadout is, what it picks up on demand).
• Defines the dispatch primitives (worktree isolation, cmux fleet, the built-in Agent tool) and when each one is the right tool.
• Defines the verification and curation gates (Checker JSON output, binary in-scope-ness routing, the subtask state machine).
• Records where Taskmaster (TM) fits — KH adopts the TM JSON shape but not the TM tool. Linear is the future-state migration target, not TM.
• Records failure-handling patterns surfaced empirically.
• Records future roles (Auditor, Evaluator) deferred until ~10 orchestrated sessions exist to evaluate against, plus S50+ carry-forward work.

Out of scope of this doc: the bodies of individual skills and the contents of individual agent files. Those live alongside in .claude/skills/*/SKILL.md and .claude/agents/*.md. This doc tells you which roles invoke which skills under which conditions; the skills themselves carry their own procedures.

Reading order if you are joining mid-stream: §2 (roles) → §3 (lifecycle) → §7 (Taskmaster shape) gives you 80% of the model. §4 (skill routing), §5 (dispatch primitives), §6 (gates) fill in the operational detail. §8 (failure handling) and §9 (future work) on a need-to-know basis.

---

2. Roles

Five roles. Three forms: skills are invoked in the conversation that needs them; agents are dispatched into their own context window; the main session itself can carry an orchestrator’s responsibilities without a separate agent file.

Role	Form	Operational file	What it does	What it never does
Workflow Orchestrator	Skill (body, not agent) — .claude/skills/workflow-orchestration/SKILL.md	Main session (Claude + Liam together) loads this skill at session start. Decomposes the session into Tasks; classifies session mode (CONTINUE / EXTEND / AUTHOR); dispatches Planner, Executor, Checker, Curator; sequences wave merges; routes findings; runs start-session / update-docs / handoff.	Writes production code. Audits commits itself. Edits roadmap/backlog.
Task Planner	Agent — .claude/agents/task-planner.md	opus-4-7 with thinking: 'max'. Per-spec / per-task-breakdown (not persistent). One Planner writes PRODUCT.md (subtask {N.2}); a fresh Planner reviews + writes TECH.md (subtask {N.3}); a separate Planner may run planning-and-task-breakdown to populate implementation subtasks {N.5+} after spec ratification.	Implements code. Audits its own output. Sets subtask status.
Task Executor	Agent — .claude/agents/task-executor.md	sonnet-4-6. Implements ONE subtask brief at a time. Reads only the spec slice the brief references. Commits per subtask. Reports back to Orchestrator. Escalates on unexpected production behaviour.	Decomposes work in-flight. Reads full PRODUCT.md / TECH.md. Sets subtask status to done. Audits other branches. Edits roadmap/backlog.
Task Checker	Agent — .claude/agents/task-checker.md	sonnet-4-6. Read-only audit per Executor commit. Two variants in the agent body: standard (spec compliance + KH conventions) for per-subtask gating, quality-review (broader quality, may invoke security-and-hardening / performance-optimization / type-design-analyzer based on findings) for end-of-task gating. JSON-shaped output. Can set subtask status to done if zero further findings.	Edits files. Decides where findings go. Sets Task status to done.
Workflow Curator	Agent — .claude/agents/workflow-curator.md	Triages out-of-scope findings via triage-finding; promotes to subtask / roadmap / backlog / no-action via update-roadmap-backlog. Retains workflow- prefix because it operates above any single task.	Writes production code. Dispatches Executors. Sets subtask status.

Naming convention

• task-* prefix for per-Task scope: Planner, Executor, Checker.
• workflow-* prefix for session-/wave-level scope: the Curator agent and the workflow-orchestration skill.
• The S47 v1 used workflow-executor/workflow-checker; those files are renamed to task-executor/task-checker as part of ID-3. The prior Orchestrator agent file is deleted (see §9.4) — its responsibilities move into the workflow-orchestration skill body loaded by the main session.

Session entry pattern

The default entry pattern is option (ii) from S47/S48: the main session (Claude + Liam in conversation) is the Orchestrator. No separate orchestrator agent file. The main session loads workflow-orchestration at session start, then chains to session-driver-cmux and the dispatch primitives as needed. Option (i) (separate orchestrator in its own cmux terminal) remains the escalation path if a session’s complexity threshold crosses the human-supervisable bar; not the default.

Verification gates are not optional

After every Executor commit, the Checker runs. After every Checker FAIL or PASS_WITH_NOTES, findings route: in-scope → fix-Executor; out-of-scope → Curator. All findings are addressed before a Task is closed, per the KH project rule that anything less creates technical debt (per ratification A3).

Out-of-scope findings always route to the Curator

When an Executor surfaces an observation that isn’t in the current subtask’s scope, or a Checker flags scope creep, the Orchestrator skill routes the finding to the Curator rather than carrying it in working memory. The Curator’s triage-finding decision goes to subtask / roadmap / backlog / no-action; if a ledger promotion, update-roadmap-backlog writes the JSON. This keeps the main session’s context lean across multi-wave sessions.

---

3. Lifecycle

Six task-driven phases. ID-N (Task) and ID-N.M (Subtask) are the universal terminology — every cross-doc reference uses this convention (task list, backlog, roadmap, workflow prompts).

SESSION
├── start-session                              (skill — bootstrap)
│
├── TASK ID-N
│   ├── Subtask {N.1} RESEARCH.md             (Executor or Planner; conditional)
│   ├── Subtask {N.2} PRODUCT.md              (Planner → Checker → fix-Planner loop)
│   ├── Subtask {N.3} TECH.md                 (Planner → Checker → fix-Planner loop)
│   ├── Subtask {N.4} PLAN.md                 (Planner via planning-and-task-breakdown; conditional)
│   │                                         ── ratification gate ──
│   ├── Subtask {N.5+} implementation         (Executor → Checker per subtask)
│   ├── code-simplification pass              (Executor, end-of-task)
│   ├── quality-review pass                   (Checker, end-of-task)
│   └── Task close                            (Orchestrator gates → done)
│
├── ...
│
└── update-docs → handoff                      (skills — close)

3.1 Task creation

Triggered by the spec-driven-implementation skill (rewritten under ID-4 per A2). When the Orchestrator detects a new feature, new significant capability, or roadmap/backlog item moving to active work, it invokes spec-driven-implementation which creates a TM-shaped Task with the spec-authoring subtask chain:

• {N.1} RESEARCH.md (when warranted by domain complexity)
• {N.2} PRODUCT.md
• {N.3} TECH.md
• {N.4} PLAN.md (conditional — only when planning-and-task-breakdown decomposition is needed to populate implementation subtasks)

Implementation subtasks {N.5+} are not populated at this stage. They land later, after the {N.1}-{N.4} chain is ratified.

3.2 Spec authoring

Each spec-authoring subtask follows the same loop: Planner authors → Checker (standard variant) audits → fix-Planner loop until PASS.

• {N.1} RESEARCH.md (when warranted) — Planner with the domain skills Liam loads into .claude/skills/ for this Task (see §4 Planner skills). Output: a research doc the spec subtasks can reference.
• {N.2} PRODUCT.md — Planner invokes write-product-spec directly (not via spec-driven-implementation). Output: numbered, testable Behavior invariants per the skill’s mandated structure.
• {N.3} TECH.md — Fresh Planner instance (per Q-PLANNER-2 ratification: “the next reviews and writes TECH.md”). Invokes write-tech-spec directly. Output: migration plan + Proposed changes per invariant.

Each Planner is opus-4-7 with thinking: 'max' (per Q-PLANNER-1 ratification). One Planner = one subtask. Planners are NOT persistent across waves.

3.3 Decomposition (conditional)

When the ratified PRODUCT.md + TECH.md pair has compound invariants, multiple migrations, multiple adapter kinds, chain-dependent subtasks, or estimated effort > 2h, a fresh Planner invokes planning-and-task-breakdown against the ratified spec pair to populate implementation subtasks {N.5+}.

Sibling-only dependency constraint (A6 forcing function): Implementation subtasks within a Task may depend on other subtasks of the same Task only. If the Planner finds it needs to express “subtask of Task M depends on subtask of Task N”, the Task boundary is wrong; either split or merge the Tasks. Cross-Task dependencies live at the Task level (Task.dependencies[]), not the Subtask level.

Subtask brief (TM details field): the Planner is responsible for populating each subtask’s details field with the dispatch brief: file paths, function names, “verify X” lines, spec-slice references. This brief is what the Executor receives — the spec itself is read only via the details-referenced slice path, not the whole document.

testStrategy per Subtask: the Planner also populates each subtask’s testStrategy (one-line acceptance prose is acceptable).

3.4 Implement

One Executor per logical subtask group, not one per individual subtask (per A7). A subtask group is a contiguous sequence of subtasks that share file ownership and can be committed atomically — typically {N.5}, {N.6}, {N.7} together if they all touch the same module.

The Orchestrator skill body determines parallel-vs-serial dispatch based on file-ownership boundaries between groups: groups touching disjoint files dispatch concurrently in isolated worktrees; groups touching overlapping files dispatch sequentially.

Each Executor:

• Reads only the subtask brief (details field) and the spec slice it references.
• Implements via implement-subtask (NEW skill landing in ID-4 per A1) as entry point. Internally invokes test-driven-development for any behaviour change and incremental-implementation for multi-file changes — explicitly, not auto-routed.
• Commits per subtask via commit-commands (NOT git-workflow-and-versioning — Executors do not own merges, per B9).
• Appends an <info added on YYYY-MM-DDTHH:MM:SS.sssZ> journal block to the subtask details field on completion (per A6 / A10 ratification).
• Moves subtask status pending → in-progress. Never sets done (per B12).

25-subtask soft ceiling per Task (A7): if a Task approaches 25 subtasks, the Planner should split. The empirical TM data (see §7) shows 5/7 example Tasks at exactly 25; KH treats this as a strong signal of a Task-boundary problem rather than a hard cap.

3.5 Verify

Two Checker variants, dispatched at different cadences (per B5):

• standard variant — after every Executor commit, gates the subtask group. Audits spec compliance + KH conventions (UK English, auth helper pattern, getAuthorisedClient { success } shape, design tokens, no barrel re-exports, no silent Supabase failures). Output JSON-shaped per §6.1. Can set the subtask group’s subtasks to done if verdict is PASS with zero findings.
• quality-review variant — after code-simplification Executor pass at end-of-task. Broader pass; invokes security-and-hardening / performance-optimization / type-design-analyzer based on the task kind and findings. Runs before Task close.

Both variants are the same agent file (task-checker.md) with variant selection via the dispatch brief. JSON output schema in §6.1.

3.6 Curate

Findings from any Checker variant route through a binary in-scope-ness rule (per B10, expressed in the workflow-orchestration skill body):

• In-scope finding → Orchestrator dispatches a fix-Executor with the finding packet. Fix-Executor follows one of three fix-flows (per N1):
  • Type (a) — missed-but-correctly-detailed: fix-Executor implements the missing piece against the existing subtask brief.
  • Type (b) — functionally incorrect: fix-Executor re-implements against the spec slice.
  • Type (c) — straightforward inline fix: fix-Executor applies the fix directly with the Checker’s fix_recommendation. Plus a fourth case where implementation discovery requires spec amendment — Orchestrator re-engages a Planner to update PRODUCT.md / TECH.md, then re-decomposes.
• Out-of-scope finding → Orchestrator dispatches the Curator with the finding packet. Curator runs triage-finding; if the decision is roadmap or backlog, the Curator invokes update-roadmap-backlog to write the JSON ledger. For subtask decisions, the Curator appends the subtask to the current Task (or a future Task) and reports back.

The state machine (per B12):

• Executor moves subtask status pending → in-progress only.
• Checker moves subtask status to done if and only if zero further findings require Executor action.
• Orchestrator moves Task status in-progress → done after wider context checks: backlog/roadmap implications, sibling-Task dependencies, any open Curator triage decisions.

---

4. Per-phase skill routing

Per-role baseline skill loadouts and on-demand skill invocations.

4.1 Planner skills

Core set (always loaded via agent frontmatter skills: per FX-10):

• write-product-spec — for {N.2} PRODUCT.md authoring.
• write-tech-spec — for {N.3} TECH.md authoring.
• planning-and-task-breakdown — for {N.4} PLAN.md authoring (when needed).
• documentation-and-adrs — for any decision-recording side-output during research / spec authoring.

Task-specific skills (added on demand to .claude/skills/ by Liam, per Q-PLANNER-SKILLS-1 ratification): the project doesn’t try to keep every potentially-useful skill loaded constantly. When a Task lands that’s AI-tilted, Liam adds claude-api; when CI-tilted, Liam adds diagnose-ci-failures; when Supabase-tilted, supabase-postgres-best-practices; when frontend-tilted, vercel-react-best-practices / web-design-guidelines / interaction-design / mobile-design; etc. This stays user-driven for now; an automation opportunity may surface once enough orchestrated sessions exist to monitor (Evaluator role, deferred per §9.2).

4.2 Executor skills

Entry point:

• implement-subtask (NEW skill landing in ID-4 per A1). Single entry point for spec-anchored Executor work. Reads the subtask brief from the details field, reads only the spec slice the brief references, executes against that slice, appends an <info added on …> block to details on completion.

Support skills (invoked explicitly when warranted, not auto-routed):

• test-driven-development — for any behaviour change. Mandatory if the subtask touches logic with observable behaviour.
• incremental-implementation — for multi-file changes that benefit from interleaved commit boundaries.
• commit-commands — for the commit at subtask completion. Replaces git-workflow-and-versioning for Executors (per B9: Executors invoke commit-commands per subtask and don’t have git-workflow-and-versioning available).
• resolve-merge-conflicts — if a fix-Executor lands on a worktree with conflicts (skill ported from Warp into .claude/skills/ during ID-0).

Forbidden for Executors:

• In-flight planning-and-task-breakdown invocation. Decomposition happens during the Planning phase only; an Executor that thinks it needs to decompose further must escalate.
• Reading full PRODUCT.md / TECH.md. Only the spec slice that the subtask details field references is in scope.
• Setting subtask status to done. Executor moves pending → in-progress only.

4.3 Checker skills

Reading order for any variant (per N4): the relevant spec section(s) → the subtask details + testStrategy (acceptance criteria) → the <info added on …> journal notes left by the Executor → then the actual implementation diff. No separate evidence-collation skill — the ordering is the Checker’s own discipline.

standard variant (per-subtask):

• code-review-and-quality — for the actual review pass against the five-axis rubric (Correctness, Readability, Architecture, Security, Performance). The Checker reuses this skill but the verdict gating is against the subtask testStrategy and spec slice, not the standalone pre-merge use described in the skill body.

quality-review variant (end-of-task, after code-simplification):

• code-review-and-quality — broader pass over the full Task’s commit set.
• security-and-hardening — invoked when findings or task kind warrant (e.g. new auth surface, new public API).
• performance-optimization — invoked when findings or task kind warrant (e.g. hot path, new SQL query, list-rendering subtask).
• type-design-analyzer — invoked when the Task introduced or refactored types (per FX-6).

The silent-failure-hunter agent (existing in .claude/agents/) remains available for the Checker to dispatch at PR/Task-close if the Task touched the Supabase/error-handling surface. Not auto-invoked.

4.4 Orchestrator skills (in the workflow-orchestration skill body)

The Orchestrator is a skill, not an agent. Its body (authored in ID-2) encodes the main session’s core loop. It composes:

• Session bootstrap: start-session, context-engineering. Session mode (CONTINUE / EXTEND / AUTHOR) is computed per Task at session-plan time from TM state, not declared in the continuation-prompt header (per B6 ratification). Multi-mode sessions are allowed: a single session may span Tasks of different modes.
• Dispatch: session-driver-cmux (when fleet > 1 Executor needed), dispatching-parallel-agents (pattern), using-git-worktrees (worktree-creation primitive — kept separate per A4).
• Wave merging: git-workflow-and-versioning per B9 (Orchestrator owns merges). Wave-merge cadence (sequential, one wave at a time). Cherry-pick-not-merge for parallel agent branches (per CLAUDE.md Worktree Gotchas). Post-merge worktree cleanup (git status + git checkout -- . + git clean -fd). resolve-merge-conflicts on conflict.
• Finding routing logic (per B10, N6): the binary in-scope-ness rule expressed as an Orchestrator-evaluable predicate.
• Promotion gates (per N3): the integration-tier-promotion logic (subtask passed → task pass → wave pass) lives in this skill body, not as a separate skill.
• Spec triggering: spec-driven-implementation when a new Task with unspec’d surface area is queued.
• CI gate: diagnose-ci-failures (ported from Warp during ID-0) on failing CI for a PR.
• End-of-session: update-docs, handoff.

Phase-specific Orchestrator skills added on demand by Liam: same pattern as Planner — claude-md-management when CLAUDE.md edits are the session output; brainstorming / idea-refine when the session opens with requirements gathering rather than execution. Liam adds these to .claude/skills/ per task need.

4.5 Curator skills

• triage-finding — for the in-scope-ness / promotion decision.
• update-roadmap-backlog — for the JSON ledger write. Per N7 this skill is to be extended to CRUD (not just append); the CRUD extension is a S50+ carry-forward.

---

5. Dispatch primitives

Three layered primitives — they compose, they don’t substitute. Harmonised (not amalgamated) per A4.

5.1 dispatching-parallel-agents (pattern)

Abstract pattern: identify independent task domains, compose focused sub-tasks, run in parallel, integrate results. Used by the workflow-orchestration skill body when planning a wave with >1 Executor.

5.2 using-git-worktrees (workspace-isolation primitive)

Concrete worktree-creation primitive with safety contract: git check-ignore for the worktree path, baseline-test gate before the worker starts, post-merge cleanup hooks. Used by workflow-orchestration for single-Executor worktree creation.

5.3 session-driver-cmux (fleet dispatch implementation)

One concrete dispatch implementation: cmux terminals + Claude sub- sessions + per-worker git worktree + JSONL event stream (.claude/cmux-events/<session-id>/events.jsonl).

Harmonisation (per A4 ratification): all three primitives produce worktrees that pass the same safety checks. session-driver-cmux launch-worker.sh (post-ID-3 cleanup) adopts the same worktree-creation contract as using-git-worktrees: git check-ignore for the worktree path, baseline-test gate before workers start.

Latent bug (per A5): the existing session-driver-cmux SKILL.md references upstream read-events.sh and controller approve-tool.sh that hard-code /tmp/claude-workers/ and silently miss KH-located events. Fix lands in ID-3 as the hard-fork cleanup pass.

Worker-variants section deleted from the S47 v1. A minimal-worker agent and --worker-mode minimal flag previously existed; both are removed in ID-3 (per B8 ratification — bare mode is headless-only and unsuitable for KH’s workflow). Context-economy concerns surface through per-dispatch allowedTools and per-dispatch skill list (already supported by Anthropic agent frontmatter), not a separate agent file. See §9.4 for the full deletion record.

5.4 Pick-the-primitive table

Scenario	Primitive
Parallel wave of Executors, each long-running	session-driver-cmux per Executor
Single short Executor on one subtask group	Built-in Agent tool with isolation: "worktree" (composes with using-git-worktrees)
Multi-turn worker reused across subtasks	session-driver-cmux (cmux preserves state)
Checker on one subtask group	Built-in Agent tool (single-turn, no fleet)
Curator on one finding	Built-in Agent tool (no isolation needed; ledger writes happen in main repo)

Critical first action for any worktree sub-agent: git reset --hard <track-branch> — isolation: "worktree" branches from a historical commit, not the current track HEAD (CLAUDE.md “Worktree agents start stale” gotcha).

---

6. Verification & curation gates

6.1 Checker output schema

Checker output is JSON-shaped (per Q-CHECKER-OUT-1 ratification) so the workflow-orchestration skill body can route findings mechanically without re-reading prose.

{
  "subtaskId": "ID-15.7",
  "verdict": "PASS" | "PASS_WITH_NOTES" | "FAIL",
  "findings": [
    {
      "severity": "blocker" | "important" | "nit" | "fyi",
      "scope": "in-scope" | "out-of-scope",
      "axis": "spec-compliance" | "code-quality" | "test-quality" | "design-tokens" | "type-design" | "silent-failure" | "performance" | "security",
      "location": "path/to/file.ts:42",
      "description": "Free-text description of the finding.",
      "fix_recommendation": "Free-text recommendation, or null if Curator-triage required."
    }
  ]
}

Verdict mapping:

• PASS — zero findings of any severity. Checker may set the subtask group’s subtasks to done.
• PASS_WITH_NOTES — only nit / fyi findings; Orchestrator routes them via §6.2 but the subtask group is not blocked.
• FAIL — at least one blocker or important finding. Orchestrator must dispatch fix-Executor(s) before the subtask group can close.

6.2 Binary in-scope-ness routing

The Orchestrator-evaluable predicate (per B10):

A finding is in-scope if and only if its location (file path) falls within the file-ownership set of the current subtask brief, OR the finding’s axis is spec-compliance against the subtask’s spec slice.

• In-scope → fix-Executor (one of the three fix-flows from §3.6).
• Out-of-scope → Curator triage via triage-finding. Curator decision: subtask / roadmap / backlog / no-action.

Severity is the Checker’s verdict input. Ambiguity is a Curator decision input, not an Orchestrator routing input — if the Orchestrator can’t decide in-scope vs out-of-scope, the finding goes to Curator.

6.3 Subtask state machine (per B12)

State	Set by	Trigger
pending	Planner	Subtask creation
in-progress	Executor	Executor accepts the dispatch brief
done	Checker only	PASS verdict with zero further-action findings
deferred	Orchestrator	Subtask parked (e.g. blocked on external precondition) — per A10

Task state machine:

State	Set by	Trigger
pending	Orchestrator	Task creation via spec-driven-implementation
in-progress	Orchestrator	First subtask moves to in-progress
done	Orchestrator only	All subtasks done + Curator triage complete + roadmap/backlog implications recorded
cancelled	Orchestrator	Task abandoned (deferred to later, scope removed, etc.)

6.4 Merge cadence

Once a subtask group is PASS (or PASS_WITH_NOTES with all notes resolved):

1. Merge each worktree branch sequentially onto the track branch via cherry-pick (per CLAUDE.md Worktree Gotchas — parallel agent branches are cherry-picked, not merged).
2. After each merge: git status (check for leaked files); then bun run test for full regression. If conflicts surface, resolve-merge-conflicts skill.
3. If a merge fails or tests regress, halt the wave and dispatch a fix-Executor.
4. After the final merge, bun run knip if files were added/removed.

Sequential, never parallel. This is the only way to keep the track branch deterministic when multiple worktree branches all touched adjacent areas.

---

7. Where Taskmaster fits

Decision (per A6 ratification in s49-open-resolutions.md): KH adopts the Taskmaster (TM) JSON shape, not the TM CLI or MCP tool. The forward trajectory is Linear — TM is a shape donor, not a future install target.

Source-of-truth for the shape: docs/reference/taskmaster-schema-reference.md.

7.1 Shape adoption

Concern	KH adoption
Task id	Stringified integer ("15") — matches TM, round-trippable.
Subtask id	Bare integer (1) — matches TM, local to parent.
Composite-id prose	ID-15.1 (KH-native, per B2). Maps to TM’s 15.1.
Task dependencies	string[] of other Task ids.
Subtask dependencies	int[] of sibling Subtask ids — sibling-only constraint kept as a forcing function. If you need cross-Task subtask deps, Task boundaries are wrong; split or merge.
details field on Subtask	Load-bearing dispatch brief (markdown, file paths, function names, “verify X” lines). The Executor’s primary input.
testStrategy per Subtask	One-line acceptance prose acceptable. Populated by Planner at decomposition.
<info added on …> journal	Append-only annotation in details. Adopted as the Executor / Checker journal pattern within details.
parentId: "undefined"	Vestigial. Do not populate. Parent linkage is positional.
PRODUCT.md / TECH.md	Stay as separate artefacts. details references the spec slice path; spec content is not stuffed into JSON.
Hierarchy depth	Tasks → Subtasks only (max 1 nesting level). No sub-subtasks.
25-subtask soft ceiling	Adopted as a guideline. If a Task naturally has >25 subtasks, split — that’s a Task-boundary signal.
Status enum (Task)	pending / in-progress / done / cancelled.
Status enum (Subtask)	Wider set: pending / in-progress / done / deferred (per A10).
Priority	high / medium / low at Task level only. Subtasks inherit.

7.2 What KH forgoes (acceptable cost)

• TM CLI / MCP install. No. Manual decomposition via planning-and-task-breakdown + Planner work remains the path.
• PRD → tasks auto-expansion.
• Built-in complexity-analysis.
• Built-in dependency-ID validation CLI.

7.3 Linear is the future-state

TM shape is a stepping stone toward generic structured-task discipline. Linear’s data model will diverge but the decomposition habits transfer. Scoping the Linear migration is a S50+ carry-forward (per §9).

7.4 Roadmap + Backlog alignment (S50+ carry-forward)

KH’s product-roadmap.json and product-backlog.json will align to the same TM shape — section restructure (§3 phases as top-level Tasks) bundled with the N10 label-reversal migration. Per s48-feedback.md general comments on the TM schema reference:

• Items currently on the KH Roadmap (which is actually the Backlog; concepts reversed) will be restructured so that each phase of Roadmap Section 3 has its own top-level Task ID, not the current 3.1, 3.12 etc. (which matches the current Backlog config).
• effort/effort_estimate field is dropped (irrelevant once the item decomposes to subtasks).
• dueDate/deadline field is dropped (workflow-doc-side concern).

7.5 What the v1 §7 said that this rewrite supersedes

The S47 v1 §7 had a conditional rule for “when to invoke planning-and-task-breakdown” against a hand-decomposed 20-Task canonical pipeline. That rule (compound invariant / multiple migrations / multiple adapter kinds / chain-dependent subtasks / effort > 2h) is preserved as Planner heuristic for the {N.4} decomposition subtask. But the rule is now a Planner concern, not an Orchestrator concern — the Orchestrator just dispatches the Planner with the ratified spec pair, and the Planner decides whether to invoke planning-and-task-breakdown for the Task at hand.

---

8. Failure handling

Recorded patterns observed empirically; restated here so they survive next to the lifecycle.

• Executor commits but produces failing tests → Orchestrator dispatches a fix-Executor with the test output. New commit, never --amend (CLAUDE.md “Git Safety Protocol”).
• Executor exits mid-commit (token budget) → Orchestrator checks the worktree’s git status before tearing it down. Rescue uncommitted changes with a manual commit on the worktree branch (CLAUDE.md “Sub-agents can blow their token budget”).
• Checker FAILs on the same subtask group three times → Orchestrator escalates to Liam (likely a spec / plan defect, not implementation defect; re-engage Planner to amend PRODUCT.md / TECH.md).
• Worktree leakage on merge → git status after each merge; if untracked files appear, git clean -fd and re-verify the merge produced the expected files (CLAUDE.md “Worktree isolation rules”).
• Sub-agent escalation → an Executor that finds production behaviour contradicting the brief stops and reports. The Orchestrator treats this as a scope renegotiation, not a workaround opportunity (CLAUDE.md “Agent escalation rule”). If the discovery requires spec amendment, Orchestrator re-engages a Planner.
• Worktree CWD drift — after a Read on a worktree file, subsequent Bash git commands silently run in the wrong tree. Mitigated by cd <main-repo-path> && prefix on main-repo git ops after any worktree Read. Applies to sub-agents too (CLAUDE.md “Bash CWD drifts into worktree dirs after Read”).
• Worktree branches start stale — isolation: "worktree" branches from a historical commit, not the current track HEAD. The agent’s first action must be git reset --hard <track-branch> (CLAUDE.md “Worktree agents start stale”).
• Plugin invisibility — .claude/plugins/* is gitignored except knowledge-hub/. Agents needing other plugins must cp from the parent repo after git reset --hard <track-branch> (CLAUDE.md “Anthropic plugin files invisible to worktree agents”).

The workflow-orchestration skill body (ID-2) encodes the dispatch logic for each of these failure modes. This section is the narrative reference; the skill is the operational truth.

---

9. Future roles & deferred work

9.1 Workflow Auditor (deferred, per F4-9 + X5)

Audits the workflow (not the implementation) — verifies the workflow itself is being followed across sessions, surfaces refinement opportunities. Skills referenced: claude-md-management, create-skill, update-skill.

Per B5 clarification: “Role of the Auditor has been confused — Auditor audits the workflow, not the implementation.” The Checker audits implementation; the Auditor audits the workflow. Distinct roles.

Defer until ~10 orchestrated sessions of work exist to audit against.

9.2 Workflow Evaluator (deferred, per F4-10 + X5)

Finds context-economy automation opportunities (where bare-mode-like efficiencies could land in CI / non-headless surfaces in future) per Q-BARE-2 ratification. Skills referenced: context-engineering-collection, prompt-engineering-patterns.

Defer until the Auditor surfaces concrete evaluation needs.

9.3 S50+ carry-forwards (referenced in s49-open-resolutions.md)

• Worktree collapse (per B3 ratification) — the four current long-lived worktrees (main, production-readiness, kh-knowledge-platform, ast-dataflow) land their in-flight work via standard merge to main over the next 3–4 sessions. Liam owns the merge/collapse timings. Once collapsed, future work uses TM-tracked Tasks → feature branches off main → worktree-isolated Executor dispatch.
• Per-track primers dropped (per Q-WORKTREES-2) — docs/tracks/*.md files retire when their tracks merge. Any persisting context promotes to CLAUDE.md or a per-Task TM description.
• Single global session counter (per Q-COUNTER-1) — kh-s49, kh-s50, … with no track prefix. Replaces the track-prefixed counter scheme from the multi-track era.
• Roadmap §3 restructure to top-level Tasks — per s48-feedback.md general comments on the TM schema reference. Each phase of Roadmap Section 3 becomes its own top-level Task ID.
• Roadmap + Backlog schema alignment to TM shape — same migration as above; aligns product-roadmap.json and product-backlog.json to the Task/Subtask shape with details / testStrategy fields.
• N10 label-reversal migration — KH’s roadmap and backlog concepts are currently reversed in the JSON filenames. The Curator labels entries by target semantics; the file-swap migration is bundled with the schema alignment above.
• update-roadmap-backlog CRUD extension (per N7) — current skill appends only; extending to CRUD when roadmap+backlog alignment lands.
• fix-errors KH-adaptation — Warp-port skill is Rust-tilted; KH needs TS + Python parity. Adapt when first Executor needs it.
• <info added on …> journal pattern operationalisation — adopt the convention when the first orchestrated session runs an Executor that needs to append to subtask details.
• Linear migration scoping — when KH is ready to leave manual JSON behind.

9.4 Deletions from the S47 v1

This rewrite removes two structures that the S47 v1 carried:

• Worker variants section — the S47 v1 §8 (full Executor profile vs minimal Executor profile) is deleted entirely. The workflow-worker-minimal agent file and --worker-mode minimal flag are removed in ID-3 (per B8 ratification). Context-economy is managed via per-dispatch allowedTools + per-dispatch skill list on the standard Executor, not a separate agent type.
• Orchestrator agent file — the S47 v1 listed workflow-orchestrator.md as one of four canonical agent files. Per B1 + B11 ratification, the role is now a skill loaded by the main session (workflow-orchestration skill body, authored in ID-2). The prior agent file is deleted in ID-3.

---

10. References

Operational truth (read these to act)

• .claude/skills/workflow-orchestration/SKILL.md (lands in ID-2)
• .claude/skills/implement-subtask/SKILL.md (lands in ID-4)
• .claude/skills/spec-driven-implementation/SKILL.md (rewrite lands in ID-4)
• .claude/agents/task-planner.md (lands in ID-3)
• .claude/agents/task-executor.md (renamed from workflow-executor.md in ID-3)
• .claude/agents/task-checker.md (renamed from workflow-checker.md in ID-3)
• .claude/agents/workflow-curator.md (retains workflow- prefix)
• .claude/skills/session-driver-cmux/SKILL.md
• .claude/skills/triage-finding/SKILL.md
• .claude/skills/update-roadmap-backlog/SKILL.md

Ratification provenance

• docs/plans/phase-0-investigation/s49-open-resolutions.md — A6, N2, A1, B5 resolutions.
• docs/plans/phase-0-investigation/s48-feedback.md — Liam’s 49-question ratification table (Sections 1+2 fully reflected above).
• docs/plans/phase-0-investigation/kh-sdlc-workflow-open-questions.md — Q-ID master table.
• docs/plans/phase-0-investigation/kh-sdlc-workflow-feedback-structured.md — atomic feedback decomposition (Q-ID traceability).

TM shape reference

• docs/reference/taskmaster-schema-reference.md — empirical TM schema source-of-truth for §7.

Project-level rules

• CLAUDE.md → “Implementation Workflow” + “Gotchas” sections.
• docs/reference/test-philosophy.md — six test-audit criteria.
• docs/design/warm-meridian-implementation-spec.md — design tokens.

Source docs superseded by this rewrite

• The S47 v1 of this document (the pre-2026-05-18 contents of this file). Provenance preserved in git history.
• The four S45–S46 source docs that the S47 v1 already collapsed (kh-workflow-orchestration.md, kh-workflow-orchestration-assessment.md, workflow-orchestration-assessment-feedback.md, workflow-orchestration-feedback-response.md).

Related plans

• docs/plans/phase-0-investigation/dw11-ast-data-flow-route.md — AST data-flow approach decision (Approach B selected; in-flight on a separate track).
• docs/plans/phase-0-investigation/taskmaster-canonical-pipeline-decomposition.md — S47 hand-decomposition of the canonical pipeline; reference for the §7.5 supersession note.
• docs/specs/id-9-astro-starlight-docs-foundation/PRODUCT.md and TECH.md — S47 output for the docs platform; implementation deferred.

---

End of canonical SDLC workflow doc. Update this file when role definitions, lifecycle phases, or skill routing change. Update the agent and skill files in .claude/agents/ and .claude/skills/ first if the change is operational; reflect it here second.