Workflow Orchestration — Feedback Response + Next-Session Plan

Superseded by: docs/plans/phase-0-investigation/kh-sdlc-workflow.md (S47, 2026-05-15). The S45 synthesis of feedback into a 5-WP plan for S46. The decisions ratified here (spec-driven-development collapse, Astro+Starlight pivot, Warp docs skills port, DW.11 spike) all live in the canonical SDLC workflow doc; read that first.

Companion to workflow-orchestration-assessment-feedback.md. Tight: corrections, answers, open clarifying questions, next-session WP list.

1. Corrections to the assessment

The Explore subagent that surveyed skills under-reported in three places. Now confirmed on disk:

Item	Assessment said	Actual
`github-actions-templates`	NOT FOUND	EXISTS at `~/.agents/skills/github-actions-templates/SKILL.md`
`ci-cd-and-automation`	NOT FOUND	EXISTS at `~/.agents/skills/ci-cd-and-automation/SKILL.md`. Description: “Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines.”
`gitnexus`	”MCP server, not a skill”	Both. MCP server and 6 skill files at `/development/knowledge-hub/.claude/skills/gitnexus/`: `gitnexus-cli`, `gitnexus-debugging`, `gitnexus-exploring`, `gitnexus-guide`, `gitnexus-impact-analysis`, `gitnexus-refactoring`. These are the canonical KH-side wrapper.

Impact: §3.11 (“Listed-but-missing”) in the assessment overcounts gaps. Of the 7 using-agent-skills decision-tree references that I flagged as missing, two are actually present (ci-cd-and-automation, and arguably github-actions-templates covers the workflow-templates branch). The other 5 (frontend-ui-engineering, debugging-and-error-recovery, shipping-and-launch, security-and-hardening, performance-optimization, browser-testing-with-devtools, context-engineering) remain genuinely absent and need decision per §2 below.

Also: I was wrong about context-engineering not existing — it does (~/.agents/skills/context-engineering/SKILL.md). Only context-engineering-collection was found by the subagent on its first pass.

2. Answers to feedback questions

2.1 Workflow Roles

Taskmaster baseline agents at propel-pathways-39761/.claude/agents/ — three files: task-orchestrator.md (model: opus), task-executor.md (model: sonnet), task-checker.md (model: sonnet). All use mcp__task-master-ai__* MCP tools. Verdict: ADOPT as baseline. Their patterns map cleanly to our proposed roles:
- task-orchestrator → Workflow Orchestrator (analyses task queue + dependency graph + dispatches executors + reassesses on completion)
- task-executor → the sub-agent we dispatch via worktrees / session-driver-cmux
- task-checker → the verification-gate agent we already deploy per CLAUDE.md “Verification Gates” rule
Action: copy + KH-adapt during next-session WP1. Replace task-master show <id> references with KH commands + add KH-specific verification axes (Warm Meridian tokens, UK English, auth patterns, semantic-tokens).
context-engineering-collection + prompt-engineering-patterns + “Agent Development” for Auditor/Evaluator/Orchestrator — yes, ADOPT for all three. Specifically: Orchestrator uses context-engineering (per-session) when output quality degrades; Auditor uses context-engineering-collection (which is the meta-collection of skills for building agent systems) + prompt-engineering-patterns to review sub-agent prompts; Evaluator uses both + claude-md-management to assess CLAUDE.md drift.

2.2 Meta-skill and Additional Skills

Q: “Is the suggestion to use [the 7 missing skills] WITH the current SDLC skills or IN PLACE of them?”

Answer: WITH. They are additional slots in the orchestrator’s decision tree, not replacements. The proposal’s current SDLC matrix covers: planning, design, implementation, QA, testing, documentation, deployment. The 7 missing-skill names are slots for narrower concerns:

Missing skill	Covers what	Currently covered by?
`frontend-ui-engineering`	Production UI w/ a11y	`vercel-react-best-practices` + `web-design-guidelines` + `interaction-design` (split)
`context-engineering`	Per-session context setup when quality degrades	NOT covered. ADOPT — it’s already on disk.
`debugging-and-error-recovery`	Reproduce → localize → fix → guard	NOT covered. Either ADOPT (author one) or fold into `fix-errors` (KH-rewrite).
`shipping-and-launch`	Pre-launch checklist, monitoring, rollback	NOT covered. Adjacent to `commit-commands` + `ci-cd-and-automation` + `update-docs` but not the same. Recommend defer — author later if a deploy-gating gap surfaces.
`browser-testing-with-devtools`	Chrome DevTools MCP for runtime verification	Partially covered by `chrome-cdp`. Treat as equivalent.
`security-and-hardening`	OWASP, input validation, least privilege	Partially covered by `/security-review` slash command. Recommend defer — author if needed.
`performance-optimization`	Measure first, optimise only what matters	NOT covered. Adjacent to `supabase-postgres-best-practices` + `vercel-react-best-practices` but distinct. Recommend defer.

Net add to adopt now: context-engineering (already on disk). Defer the other six until a concrete gap surfaces. Decision-tree references in the orchestrator-routing meta-skill will be edited to either point to KH equivalents or be removed.

Q: “How is using-agent-skills utilised — adapted, or replaced?”

Answer: adapted. Confirmed once we settle the workflow shape in next session WP2. Copy to .claude/skills/orchestrator-routing/SKILL.md, edit decision tree per §2 of assessment, add Taskmaster integration block.

Taskmaster context in meta-skill: put it in the meta-skill (orchestrator-routing), not in session-driver-cmux. Reason: session-driver-cmux is a worker-dispatch primitive (orthogonal to task-management). Taskmaster is the what-to-work-on layer; session-driver-cmux is the how-to-spawn-the-worker layer. They compose.

2.3 GitBook → Astro/Starlight pivot

Agreed. Confirmed: Warp’s open-sourced docs repo (github.com/warpdotdev/docs) is Astro + Starlight. README explicitly says so. The .warp/skills/ directory exists and covers “style linting, link checking, changelog updates, terminology syncing.” Specific skill file names (review-docs-pr, update-changelog, sync-error-docs, missing_docs, check_for_broken_links, docs-seo-audit) are confirmed by the open-sourcing blog post but not all visible on the README page.

Q: “Does Astro pivot still use .github/actions/docubot/?”

Likely yes, but evolved. The open-sourced repo has .github/workflows/ and .warp/skills/. Need to inspect the repo directly in next-session WP3 to confirm — the README hints that “some skills depend on internal Warp repositories.” Probable architecture:

Public-side: .github/workflows/*.yml triggers + a Warp-CLI / agent-SDK invocation against PR diff
Skills in .warp/skills/<name>/SKILL.md are loaded by the agent automatically per file changed

Q: “Does update-docs become obsolete?”

Partially. update-docs covers four things: (a) roadmap JSON, (b) state-of-the-product, (c) generated stats (bun run stats, bun run generate:mcp-inventory), (d) product backlog. Of those, (a)+(b)+(d) are docs the docubot pattern could maintain on PR-merge. (c) is generated-from-code — needs to remain a build step.

Recommendation: retire update-docs as a manual end-of-session ritual once Astro+Starlight + docubot pattern lands. Replace with: (i) docubot-on-PR-merge for narrative docs; (ii) bun run stats + bun run generate:mcp-inventory as CI steps on merge to main; (iii) keep /handoff (continuation prompt is session-scoped, not doc-scoped).

Q: “Why not adopt Warp’s full skill suite?”

Should. Recommend adopt all six of Warp’s docs skills (review-docs-pr, update-changelog, sync-error-docs, missing_docs, check_for_broken_links, docs-seo-audit). Each closes a real drift gap we’ve hit. Sequence: docubot foundation (Phase 1) → port the six skills with KH-adaptation (Phase 2). Per next-session WP3.

Ontology pipeline + auto-sync to Astro/Starlight: noted. Production-readiness track picks up the Astro+Starlight setup; ontology pipeline + sync workflow is main-track scope using cocoindex. This converges with §2.4 below.

2.4 SDLC Skill Workflow detail questions

Q: spec-driven-development vs spec-driven-implementation — crossover?

Yes, partial. Per DW.10 §2 in the dw-subagent report:

spec-driven-development = “Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet.” Decides specs are warranted.
spec-driven-implementation = “Orchestrator: decides if specs are worth it (large/risky/cross-cutting → yes; small fixes/UI tweaks → no). Then drives the chain.”

Overlap. Both decide “are specs warranted.” spec-driven-implementation then continues into orchestration. Recommendation: collapse to one. Either keep spec-driven-implementation (Warp-ported, more complete — it has the chaining logic) and drop spec-driven-development, or rewrite spec-driven-development to call out to spec-driven-implementation. Lower-friction: drop spec-driven-development from the workflow; document that spec-driven-implementation is the entry skill. Open: confirm in next-session WP2.

Q: Should write-product-spec / write-tech-spec / spec-driven- be under Planning?*

Currently in §3.3 “Implementation” but yes — they precede implementation. Recommendation: rename §3.3 to “Spec / Implementation” or split:

§3.3a Spec authoring: spec-driven-implementation, write-product-spec, write-tech-spec
§3.3b Implementation execution: implement-specs, incremental-implementation, test-driven-development

This makes the chain explicit. Will apply in next-session WP2 doc consolidation.

Q: How does context-engineering fit?

Orchestrator-level and sub-agent level. Two distinct triggers:

Orchestrator at session start: load right context (project-specific docs, mempalace recall, taskmaster state).
Sub-agent at dispatch: orchestrator includes the right per-task context slice in the dispatch prompt. This is prompt-engineering-patterns territory more than context-engineering.

Recommendation: orchestrator-routing meta-skill mandates context-engineering at session start (this is what start-session already does); per-dispatch context-shaping is the orchestrator’s responsibility using prompt-engineering-patterns as a reference.

Q: Do incremental-implementation + TDD work with write-product-spec / write-tech-spec?

Yes. They are orthogonal:

write-product-spec / write-tech-spec = produce PRODUCT.md / TECH.md before coding.
incremental-implementation = once implementing, deliver in thin slices.
test-driven-development = within each slice, failing test → green → refactor.

The chain is: spec → (planning-and-task-breakdown) → tasks → (per task) (incremental-implementation × test-driven-development) → verify against spec.

Q: Crossover between incremental-implementation and implement-specs?

Yes, both implement. Difference of level:

implement-specs = “given approved PRODUCT.md + TECH.md, build the feature, keep specs in-sync, verify with tests in same PR.” Spec-anchored, feature-scoped.
incremental-implementation = “build any change in thin vertical slices.” Slice-scoped, can apply within implement-specs.

So: implement-specs calls incremental-implementation as a discipline. Not duplicates; nested.

Q: Where does TDD fit re: specs + Taskmaster?

Inside the slice loop. Taskmaster splits a task into subtasks via a prompt. When subtasks are split, TDD applies per subtask. Taskmaster integration concern: Taskmaster’s automated TDD behaviour needs to be inspected — does it author failing tests as subtasks? If yes, we wire test-driven-development skill at the executor role level (per the propel-pathways task-executor.md agent). Next-session WP1 investigation.

Q: Rewrite fix-errors to KH-generic — agreed?

Yes. Currently Warp-Rust-specific. KH-generic version: detect-type-of-error (build / lint / type / test) → run appropriate KH tool (bun lint, bun run test, bun run build, tsc --noEmit) → diagnose → fix. Roll into next-session WP2 or do as a follow-up; not blocking.

Q: Does warp-integration-test cover anything we don’t?

No. It’s Warp-internal Rust integration-test discipline. KH covers integration tests via bun run test:integration + the test-philosophy + verification-gate workflow. Drop.

Q: git-workflow-and-versioning AND resolve-merge-conflicts — both?

Yes, both. They are level-different:

git-workflow-and-versioning = atomic commits, branch hygiene, history shape — applied throughout.
resolve-merge-conflicts = specific procedure when a merge/rebase/cherry-pick stops on conflicts.

Adopt both. Port resolve-merge-conflicts from Warp; it’s language-agnostic.

Q: create-pr/review-pr references in other skills — sweep?

Yes, sweep when we update or copy any Warp-ported skill into KH. Probably most relevant for implement-specs and spec-driven-implementation. Worth a quick grep in next-session WP2.

2.5 OQ Responses — my replies

OQ#	User reply	My reply
1	Roles can defer MVP but only days	OK — keep Orchestrator MVP, Auditor + Evaluator authored after first 2-3 sessions of real usage.
2	Astro/Starlight pivot covers	Agreed. Astro+Starlight setup is a next-session WP.
3	`docs/specs/` provisional	Confirm in WP2 after Astro+Starlight settled (paths may need to align with Starlight’s docs/ tree).
4	superpowers session-driver source available	Reviewed — at `~/.claude/plugins/cache/superpowers-marketplace/claude-session-driver/1.0.1/`. Has `skills/driving-claude-code-sessions/SKILL.md` (model: docs only, no model field), `hooks/{approve-tool.sh, emit-event.sh, hooks.json}`, `scripts/`, `tests/`. Hooks emit lifecycle events (SessionStart, Stop, UserPromptSubmit, SessionEnd) and PreToolUse-approval, into a JSONL events file. Our cmux variant has this plumbing via symlinks. Next-session WP1 action: author project-local SKILL.md mirroring this pattern + adapt scripts for cmux + author hook config that emits to a project-local events dir.
5	Remove Graphify if cocoindex+gitnexus confirmed	Confirmed. Adopt cocoindex + gitnexus + ccc. Drop graphify from KH workflow.
6	kpf + gsd retirement agreed, plus others	Confirmed conditional retirements. Other candidates may surface during WP3/4 investigation.
7	AST data-flow via cocoindex+cocoindex-code+supabase ourselves?	Plausible — needs spike. Cocoindex’s `@coco.fn` primitives can extract structured data from any source — including Tree-sitter AST. A custom flow could emit `(source_file, function, parameter)` → `(source_file, function, return-or-callee)` edges using ts-morph or the TypeScript compiler API as the AST source, then sync to Postgres for query. This would be authoring a new tool, not adopting existing one. Tradeoff: effort vs. ts-morph + LSP (ts-morph alone gets you ~80% there without cocoindex pipeline overhead). Recommendation: spike in 1–2 days; defer until concrete need surfaces. Add to backlog.

2.6 Additional feedback

create-skill + update-skill for any new/modified skills — agreed, will enforce in WP2.
Caveman + cocoindex-code overlap — different layers. Caveman compresses output text (LLM → human/log). Cocoindex-code compresses input context (codebase → LLM). They compose multiplicatively; both stay valuable. Keep caveman.
GitNexus skill files exist — noted/corrected in §1 above.
Plannotator = user-only — noted; orchestrator doesn’t invoke directly.
Remove GitBook skill — confirmed; the skill is at /development/knowledge-hub/.claude/skills/gitbook/ and can be deleted in WP3 setup. Author Astro+Starlight equivalent.

3. Resolved decisions (post-Q)

Decisions ratified 2026-05-14:

spec-driven-development collapsed. Drop spec-driven-development in favour of spec-driven-implementation as the single entry skill. Will reflect in orchestrator-routing meta-skill + remove from §3.3 in assessment when WP2 lands.
Six Warp docs skills — port all six in WP3. Foundation + six skills together, single round-trip. WP3 scope expands accordingly.
Taskmaster project-shape — per-feature PRDs in principle, deferred to WP1. Investigate Taskmaster CLI/MCP behaviour in WP1 first; ratify per-feature PRD shape post-investigation.
DW.11 — WP5 investigation, parallel to wave 1. Goal: determine whether cocoindex-based extractor is viable OR ts-morph + LSP is the route, before deciding to defer. Status stays OPEN until WP5 spike completes; cocoindex angle is now extra-valuable because the main track’s ontology pipeline auto-sync to Astro/Starlight is the same shape of problem (extract structured graph → emit somewhere queryable). WP5 elevated from “stretch” to “parallel to WP1”.

4. Proposed next-session WP list (Session 46)

Suggested structure for next session. Each WP is a 1–2h slot. Sequence assumes one orchestrator session driving sub-agents; could parallelise WP1+WP3 if desired.

WP1 — Worker dispatch + Taskmaster integration

Goal: stand up the dispatch primitive + understand how Taskmaster fits.

Tasks:

Review superpowers session-driver: skills/driving-claude-code-sessions/SKILL.md + hooks/* + scripts/* + tests/*. Document hooks pattern.
Author .claude/skills/session-driver-cmux/SKILL.md (project-local) + copy/adapt the four scripts. Add wait-for-fleet.sh for multi-worker waits.
Copy Taskmaster baseline agents from propel-pathways-39761/.claude/agents/ → KH-adapt as .claude/agents/workflow-{orchestrator,executor,checker}.md. Replace task-master show <id> references with KH-equivalent commands.
Inspect Taskmaster CLI/MCP: install, init, see what mcp__task-master-ai__* tools exist. Determine PRD shape (global vs per-feature).
Determine Taskmaster ↔ existing KH task-management bridge: do we keep docs/reference/product-backlog.json and product-roadmap.json alongside Taskmaster, or migrate them?

Verification: working launch-worker + converse cycle from orchestrator (this session) to a test sub-agent.

WP2 — Workflow shape consolidation

Goal: lock down the SDLC matrix + author the orchestrator-routing meta-skill.

Tasks:

Consolidate decisions: spec-driven-development collapse (per §3 Q2); SDLC phase layout (per §2.4 spec/impl split); 7 missing-skill verdicts (per §2.2 table).
Author .claude/skills/orchestrator-routing/SKILL.md — adapted from using-agent-skills. Include: KH-specific decision tree, KH lifecycle prologue/epilogue, verification-gate primitive, wave-dispatch primitive (via session-driver-cmux from WP1), Taskmaster integration block (PRD → tasks → subtasks → executor dispatch).
Grep + sweep: references to create-pr / review-pr / GitBook / Graphify in any imported skills; update to KH equivalents.
Update CLAUDE.md “Implementation Workflow” section to point at orchestrator-routing as the canonical entry.

Verification: orchestrator session reads orchestrator-routing.md, dispatches a test sub-agent through full flow (skill route → executor dispatch → checker verify → merge).

WP3 — Astro+Starlight setup + docubot foundation

Goal: stand up the docs platform + the bot that maintains it.

Tasks:

Inspect github.com/warpdotdev/docs directly: .github/workflows/*.yml, .warp/skills/*, Astro/Starlight config, deploy pipeline.
Decide same-repo vs separate-repo for KH docs sink (default: same-repo + docs/ migration to Astro structure; revisit if Starlight requires it).
Scaffold Astro+Starlight under docs/ (or new docs-site/) — port content tree, wire deploy.
Author .github/workflows/docubot.yml + .github/actions/docubot/{action.yml, prompt.txt} (KH-adapted from Warp’s). Pilot on one PR merge end-to-end.
Author or extend update-docs → keep-docs-in-sync skill that the agent loads.
Determine ontology-pipeline ↔ Astro/Starlight sync contract (coordination with main track).

Verification: docubot triggered on a test PR opens a docs-PR, comments back, tags author.

WP4 — Port Warp docs skills + Auditor/Evaluator role authoring

Goal: ship the six Warp docs skills + start Auditor/Evaluator roles.

Tasks:

Port + KH-adapt the six docs skills: review-docs-pr, update-changelog, sync-error-docs, missing_docs, check_for_broken_links, docs-seo-audit. Each as .github/workflows/<name>.yml + skill.
Author Workflow Auditor agent (.claude/agents/workflow-auditor.md): inspects session transcripts (mempalace recall) for workflow-adherence; references claude-md-management + create-skill + update-skill.
Author Workflow Evaluator agent (.claude/agents/workflow-evaluator.md): rubric-based scoring of orchestrator sessions; references context-engineering-collection + prompt-engineering-patterns.
Drop graphify, gitbook, webapp-testing, warp-integration-test from KH workflow; remove from skill list. Run bun run knip after.

Verification: all six docs skills trigger correctly; Auditor + Evaluator runs on one prior session.

WP5 — AST data-flow investigation (parallel to WP1)

Goal: be certain on the approach for DW.11 — cocoindex-based extractor vs ts-morph + LSP — even if the implementation decision is still to defer. Useful because the main track’s ontology pipeline auto-sync to Astro/Starlight is structurally similar (extract structured graph → emit queryable).

Tasks:

Inspect cocoindex’s @coco.fn primitives + Tree-sitter integration: can it emit (file, fn, param) → (file, fn, return) edges using ts-morph or the TypeScript compiler API as AST source? What’s the integration cost?
Inspect ts-morph alone: scope a minimal AST data-flow extractor for one KH subset (e.g. lib/coverage/). Estimate effort.
Cross-reference with main-track ontology pipeline architecture (currently being scoped) — would the cocoindex variant share infrastructure with the ontology pipeline?
Recommend: (a) cocoindex-based extractor (effort estimate + scope), (b) ts-morph + LSP, (c) defer with clear path-of-least-resistance documented.

Verification: decision document at docs/plans/phase-0-investigation/dw11-ast-data-flow-route.md recording chosen approach + effort estimate + when it’s worth building.

5. Items addressable in THIS session before handoff

Before the handoff, the following are tractable in this session (request user authorisation):

(a) Update kh-workflow-orchestration-assessment.md §3.11 + §11 to correct the missed skills (ci-cd-and-automation, github-actions-templates, gitnexus skill files, context-engineering).
(b) Confirm the next-session WP list above (or amend based on user feedback).

Otherwise, defer to next session and /handoff now.

6. Suggested handoff scope

Next-session continuation prompt should anchor on:

This response document + the feedback doc + the assessment doc as the inputs.
Open clarifying questions in §3 resolved up-front (5 Q’s, all yes/no/option).
WP1–WP4 sequenced as above; WP5 stretch.
Track: production-readiness. Counter: kh-prod-readiness-s46.
Critical rules from this session: (a) the 3 corrections to the assessment; (b) Astro+Starlight pivot confirmed; (c) Taskmaster baseline agents adopted (propel-pathways); (d) session-driver source confirmed at superpowers cache.

End of response.