KH Workflow Orchestration — Assessment

KH Workflow Orchestration — Assessment

Superseded by: docs/plans/phase-0-investigation/kh-sdlc-workflow.md (S47, 2026-05-15). The adopt/adapt/drop verdicts here were ratified and consolidated into the canonical SDLC workflow doc. Read that first; use this only for the underlying analysis (skill inventory, duplicate analysis, Warp comparison) that informed the decisions.

Sibling to kh-workflow-orchestration.md. Source-of-truth review of the proposed orchestrator / sub-agent / skill matrix, with concrete adopt / adapt / drop calls. Target: usable starting point for canonical-pipeline implementation work (S46+) and beyond.

Status: provisional. All “ADOPT” / “DROP” verdicts ready for ratification.

---

1. Summary (one-pager)

Roles. Three roles in the proposal — Orchestrator, Auditor, Evaluator — are sound. Orchestrator is the only one with hard MVP requirements; Auditor and Evaluator can ship later.

Skills. ~40 skills proposed across SDLC + AI-features + integrations. ~30 already exist on disk; the rest are either Warp-only (need porting), missing (need authoring), or duplicated (need de-duplication). Frontmatter inventory + verdict per skill in §3 / §4.

Meta-skill. Adopt using-agent-skills as the orchestrator’s skill-router meta-skill — but rewrite the decision tree to point at KH-specific skills (current tree references skills we don’t have: frontend-ui-engineering, context-engineering, debugging-and-error-recovery, shipping-and-launch, browser-testing-with-devtools, security-and-hardening, performance-optimization).

session-driver-cmux. Found at ~/.claude/session-driver-cmux/ — works, partial port from superpowers session-driver-tmux. Suitable for orchestrator role but currently a personal-config artefact, not project-scoped. Needs a thin SKILL.md wrapper + project-local install path before it’s usable as a workflow primitive.

Warp .warp/workflows/. Ten files, all Rust/Warp-internal shell shortcuts. Zero of them are agentic. Do not port verbatim. Cherry-pick one or two patterns (cherrypick-into-release; start-new-task) into existing KH bash helpers if there’s a gap.

GitBook (docubot). Pattern is .github/actions/docubot/action.yml + prompt.txt (envsubst-templated) + .github/workflows/*.yml (workflow_dispatch / on-comment trigger). Warp uses a separate warpdotdev/gitbook repo as the docs sink — we should follow the same pattern (separate knowledge-hub-gitbook repo) to keep our docs/ in-repo as the working copy and have the bot maintain the published GitBook mirror. Concrete next-steps in §7.

5 additional skills. All five (test-driven-development, spec-driven-development, incremental-implementation, planning-and-task-breakdown, git-workflow-and-versioning) ADOPT as core. They are explicit prereqs in using-agent-skills’ lifecycle sequence — omitting any of them creates a gap in the workflow.

Graph tools. Three overlap heavily. Consolidate to two:

• ccc (cocoindex-code) as the everyday semantic code-search tool (replaces ad-hoc grep for “find code related to X”)
• GitNexus as the framework-aware structural graph (Route/HANDLES_ROUTE/QUERIES/FETCHES — the only one that maps Next.js routes + Supabase call sites)
• DROP Graphify from dev-workflow. Already resolved at S232 CX.32: Cocoindex is the substrate for the user-facing “Knowledge Map”, not Graphify. Graphify’s structural call-graph is a strict subset of GitNexus’s schema, so its dev-workflow role is redundant.
• DW.11 (AST data-flow): ccc does NOT close the gap. Cocoindex-code is semantic search over chunks, not SSA def/use. Gap remains; ts-morph + LSP, or paid Sourcegraph. Recommendation: keep DW.11 open; revisit only if the data-flow gap actually bites the canonical-pipeline test-audit work.

Redundancy of 6 KH skills. Verdicts in §11 — short version: kpf-reference-doc-refresher and gsd-codebase-mapper are superseded by graph tools + docubot; caveman stays (token-saver, no equivalent); start-session, update-docs, handoff stay (they are project-specific orchestration glue with no replacement in the imported skill set).

---

2. Roles

Role	Function	MVP / phased
Workflow Orchestrator	Drives SDLC: skill routing, sub-agent dispatch, verification-gate enforcement, wave merging. Main session role.	MVP
Workflow Auditor	Inspects completed sessions for alignment with the workflow; identifies refinement opportunities. Skills: claude-md-management (plugin), create-skill (warp), update-skill (warp).	Phase 2 — value scales with #sessions
Workflow Evaluator	”Isaac?” in source. External evaluator role (rubric-driven).	Phase 3 — defer until orchestrator + auditor stable

Recommendation: ship Orchestrator first with the meta-skill + sub-agent dispatch primitives below. Auditor + Evaluator come after we have ~10 sessions of trace data to evaluate against.

---

3. SDLC Skill Workflow (frontmatter inventory, grouped by phase)

Skill discovery on disk (paths are SKILL.md locations). Frontmatter description field, paraphrased to one line. bold = already installed; italic = exists but not in current harness skill list; strike = listed in proposal but missing on disk.

3.1 Planning

Skill	Path	Description
brainstorming	~/.agents/skills/brainstorming/SKILL.md	Pre-implementation user-intent / requirements / design exploration. Mandatory before creative work.
idea-refine	~/.agents/skills/idea-refine/SKILL.md	Iterative divergent/convergent refinement of an idea. Trigger: “ideate”.
planning-and-task-breakdown	~/.agents/skills/planning-and-task-breakdown/SKILL.md	Decompose a spec into ordered, implementable tasks.

3.2 Design

Skill	Path	Description
supabase-postgres-best-practices	.claude/skills/supabase-postgres-best-practices/SKILL.md	Postgres performance / schema / config best practices.
api-and-interface-design	~/.agents/skills/api-and-interface-design/SKILL.md	Stable API / module-boundary / public-interface design.
vercel-react-best-practices	~/.agents/skills/vercel-react-best-practices/SKILL.md	React + Next.js performance + data-fetching patterns.
web-design-guidelines	~/.agents/skills/web-design-guidelines/SKILL.md	UI review against Web Interface Guidelines.
interaction-design	~/.agents/skills/interaction-design/SKILL.md	Microinteractions / motion / transitions / loading states.
mobile-design	~/.agents/skills/mobile-design/SKILL.md	Mobile-first iOS/Android engineering doctrine.

3.3 Implementation

Skill	Path	Description
spec-driven-development	~/.agents/skills/spec-driven-development/SKILL.md	Spec → code. Use when starting a new feature / significant change and no spec exists.
spec-driven-implementation	~/.agents/skills/spec-driven-implementation/SKILL.md (Warp-ported, in KH per DW.10 §3)	Orchestrator skill: decides if specs are warranted, chains write-product → write-tech → implement-specs.
write-product-spec	.claude/skills/write-product-spec/SKILL.md	PRODUCT.md for user-facing features.
write-tech-spec	.claude/skills/write-tech-spec/SKILL.md	TECH.md for significant features.
implement-specs	~/.agents/skills/implement-specs/SKILL.md (Warp-ported)	Leaf executor: reads approved PRODUCT.md + TECH.md, builds, keeps specs in-sync.
incremental-implementation	~/.agents/skills/incremental-implementation/SKILL.md	Thin vertical slices; test each before expanding.
test-driven-development	~/.agents/skills/test-driven-development/SKILL.md	Failing test first; prove behaviour.

3.4 QA / Review

Skill	Path	Description
code-review-and-quality	~/.agents/skills/code-review-and-quality/SKILL.md	Multi-axis review before merge.
code-simplification	~/.agents/skills/code-simplification/SKILL.md	Refactor for clarity.
codebase-review	NOT FOUND	Proposal text — point-in-time codebase-wide bug audit. Author if needed; otherwise drop.
commit-commands (plugin)	~/.claude/plugins/.../commit-commands/	/commit, /commit-push-pr, /clean_gone. No discrete SKILL.md — plugin exposes slash commands.

3.5 Testing

Skill	Path	Description
playwright-best-practices	.claude/skills/playwright-best-practices/SKILL.md	Comprehensive Playwright + TS guidance.
agent-browser	~/.agents/skills/agent-browser/SKILL.md	Browser automation: testing, form-fill, screenshot, extraction.
studio-e2e-tests	~/.agents/skills/studio-e2e-tests/SKILL.md	Supabase-Studio-specific Playwright recipe. Possibly drop — KH-irrelevant unless we work on Studio.
webapp-testing	~/.agents/skills/webapp-testing/SKILL.md	Playwright interactions for local web apps. Overlaps with agent-browser; pick one.
web-quality-audit	~/.agents/skills/web-quality-audit/SKILL.md	Perf / a11y / SEO Lighthouse audit.
chrome-cdp	~/.agents/skills/chrome-cdp/SKILL.md	Local Chrome CDP inspection. Explicit-approval-only.
warp-integration-test	/development/warp/.agents/skills/warp-integration-test/SKILL.md	Warp-specific. Drop.
fix-errors	/development/warp/.agents/skills/fix-errors/SKILL.md	Warp-Rust-specific. Drop or rewrite as KH-generic fix-test-failures if needed.

3.6 Documentation

Skill	Path	Description
documentation-and-adrs	~/.agents/skills/documentation-and-adrs/SKILL.md	Records decisions + ADRs.
mermaid-diagrams	~/.agents/skills/mermaid-diagrams/SKILL.md	Class / sequence / flowchart diagrams.

3.7 Deployment / Git

Skill	Path	Description
git-workflow-and-versioning	~/.agents/skills/git-workflow-and-versioning/SKILL.md	Atomic commits, branch hygiene, conflict resolution.
resolve-merge-conflicts	/development/warp/.agents/skills/resolve-merge-conflicts/SKILL.md	Warp-authored but language-agnostic — port.
create-pr	/development/warp/.agents/skills/create-pr/SKILL.md	Warp-repo-specific. Overlapping with commit-commands plugin + KH gh pr create discipline. Port only if we want skill-form (vs plugin-form).
review-pr	/development/warp/.agents/skills/review-pr/SKILL.md	Local-artifact PR diff review. Generic enough to port.
pr-review-toolkit (plugin)	plugin	Existing — overlaps with review-pr. Pick one.
diagnose-ci-failures	/development/warp/.agents/skills/diagnose-ci-failures/SKILL.md	Triage CI / pull issues / test failures from a PR. Generic; port.
github-actions-templates	NOT FOUND on disk	Probably aspirational. Drop unless we want to author.
ci-cd-and-automation	NOT FOUND	In using-agent-skills reference but no concrete file. Author if needed.

3.8 AI feature-specific development

Skill	Path	Description
context-engineering-collection	~/.agents/skills/context-engineering-collection/SKILL.md	Comprehensive collection for building/optimizing/debugging agent systems.
context-engineering	~/.agents/skills/context-engineering/SKILL.md	Per-session context setup; trigger when output quality degrades.
prompt-engineering-patterns	~/.agents/skills/prompt-engineering-patterns/SKILL.md	Production prompt-template patterns.
mcp-builder	~/.agents/skills/mcp-builder/SKILL.md	High-quality MCP server scaffolding.
create-skill (warp)	/development/warp/resources/bundled/skills/create-skill/SKILL.md	Author / edit / optimise SKILL.md.
update-skill (warp)	/development/warp/.agents/skills/update-skill/SKILL.md	Update existing skill.
create-mcp-app	/development/.claude/skills/create-mcp-app/SKILL.md	Build interactive MCP-App UIs.
plugin-dev (plugin)	plugin	No SKILL.md; plugin meta-tooling.

3.9 Integrations / Tooling

Skill	Path	Description
gitbook	/development/knowledge-hub/.claude/skills/gitbook/SKILL.md	Authoring guide for GitBook docs via Git-sync or local Markdown.
ccc	~/.agents/skills/ccc/SKILL.md	Semantic code search + indexing via cocoindex-code CLI.
cocoindex	/development/knowledge-hub/.claude/skills/cocoindex/SKILL.md	Build incremental data-processing pipelines (the library). Different from ccc — this is for authoring pipelines, not searching.
graphify	~/.claude/skills/graphify/SKILL.md	Files → knowledge graph (HTML / JSON / GRAPH_REPORT.md). Overlaps with GitNexus.
gitnexus	MCP server + 6 skill files at /development/knowledge-hub/.claude/skills/gitnexus/{gitnexus-cli,gitnexus-debugging,gitnexus-exploring,gitnexus-guide,gitnexus-impact-analysis,gitnexus-refactoring}	Tree-sitter AST → typed-node knowledge graph with Route/Process/FETCHES/QUERIES schema.
plannotator- (5 skills)*	~/.claude/skills/plannotator-*/SKILL.md	Browser-based annotation: code review, message annotate, file annotate, goal-setup, visual-explainer.
mempalace (plugin)	plugin	Canonical memory system (replaced auto-memory). MCP server.

3.10 Meta / orchestration

Skill	Path	Description
using-agent-skills	~/.agents/skills/using-agent-skills/SKILL.md	Skill-router meta-skill. Decision tree + lifecycle sequence + operating behaviours.
claude-md-management (plugin)	plugin	CLAUDE.md auditor / updater.
start-session	.claude/skills/start-session/SKILL.md	KH-specific session bootstrap.
update-docs	.claude/skills/update-docs/SKILL.md	KH-specific end-of-session docs refresh; auto-chains to handoff.
handoff	.claude/skills/handoff/SKILL.md	KH continuation-prompt generator.
caveman (plugin)	plugin	Token-compression communication mode.

3.11 Listed-but-missing (need author or drop)

CORRECTION (post-feedback): Initial subagent survey under-reported. Re-verified directly. See workflow-orchestration-feedback-response.md §1 for full correction. Updated below.

Confirmed on disk:

• ci-cd-and-automation — EXISTS at ~/.agents/skills/ci-cd-and-automation/SKILL.md.
• github-actions-templates — EXISTS at ~/.agents/skills/github-actions-templates/SKILL.md.
• context-engineering — EXISTS at ~/.agents/skills/context-engineering/SKILL.md (in addition to context-engineering-collection).
• web-design-guidelines — EXISTS at ~/.agents/skills/web-design-guidelines/SKILL.md.
• gitnexus skill files — EXIST at /development/knowledge-hub/.claude/skills/gitnexus/ (6 sub-skills: gitnexus-cli, gitnexus-debugging, gitnexus-exploring, gitnexus-guide, gitnexus-impact-analysis, gitnexus-refactoring). MCP server + skills.

Still missing (genuinely not on disk):

• frontend-ui-engineering — covered by split (vercel-react-best-practices + web-design-guidelines + interaction-design). No author.
• debugging-and-error-recovery — gap. Either fold into KH-rewrite of fix-errors or defer.
• shipping-and-launch — gap. Defer until concrete need.
• security-and-hardening — gap. Partially covered by /security-review slash command. Defer.
• performance-optimization — gap. Adjacent to existing perf skills. Defer.
• browser-testing-with-devtools — gap. Partially covered by chrome-cdp. Treat as equivalent.
• codebase-review — gap. Author if needed, otherwise drop.

Net adopt-now: context-engineering (already on disk). All five “defer” items can be authored later if concrete gaps surface; until then, the orchestrator-routing meta-skill’s decision tree will point at KH equivalents or omit the slots.

---

4. Meta-skill: adopt using-agent-skills as orchestrator router?

Verdict: ADOPT with modifications. The skill provides exactly the abstraction the proposal needs — decision tree mapping task type → skill, plus six non-negotiable operating behaviours (surface assumptions; manage confusion; push back; enforce simplicity; maintain scope; verify don’t assume). These behaviours align with KH’s existing implementation-workflow discipline (verification gates, agent work limits) and with the failure modes called out in CLAUDE.md (silent failures, build-thing-forget-to-turn-it-on, etc.).

Required modifications before adoption:

1. Rewrite the decision tree. Remove references to skills we don’t have (frontend-ui-engineering / debugging-and-error-recovery / shipping-and-launch / etc.). Replace UI branch with vercel-react-best-practices; replace debugging branch with code-review-and-quality + fix-errors (KH-ported, not Warp-Rust); replace shipping branch with commit-commands + git-workflow-and-versioning.

2. Add KH lifecycle prologue. Pre-step: start-session (existing). Post-step: update-docs → handoff (existing). Both already chain.

3. Add verification-gate primitive. using-agent-skills §“6. Verify, Don’t Assume” is good but doesn’t formalise the multi-agent verification cadence we use (impl agent → verifier agent → fix agent → merge). Add a §“Verification gates” subsection making that explicit, referencing CLAUDE.md “Implementation Workflow” rules.

4. Add sub-agent dispatch primitive. using-agent-skills assumes one agent runs the whole sequence. KH workflow uses parallel worktree sub-agents. Add a §“Wave dispatch” subsection that points at Agent(isolation: "worktree") + (eventually) session-driver-cmux for sustained-context worker sessions.

5. Add caveman + token-budget guidance. When orchestrator is dispatching, the savings compound; recommend caveman for sub-agent prompts where appropriate.

Implementation: copy using-agent-skills to .claude/skills/orchestrator-routing/SKILL.md with the above modifications; keep the original at ~/.agents/skills/ untouched as the upstream reference.

---

5. Duplications + adjustments

Duplicate / overlap	Recommendation
agent-browser vs webapp-testing vs chrome-cdp	Three browser-automation skills with overlapping scope. Keep agent-browser as the default; drop webapp-testing (less feature-complete); keep chrome-cdp for explicit-approval debug use.
create-pr (Warp) vs commit-commands (plugin) vs gh pr create direct usage	Three ways to open PRs. Keep commit-commands plugin (already installed, /commit-push-pr is well-formed). Drop need to port create-pr.
review-pr (Warp) vs pr-review-toolkit (plugin) vs /review command vs /ultrareview	Four review paths. Keep pr-review-toolkit (plugin) + /ultrareview (multi-agent cloud review). Don’t port Warp’s review-pr.
graphify vs gitnexus vs ccc (semantic search) vs cocoindex (library)	See §10. Drop graphify; keep ccc + gitnexus + cocoindex (different surface areas).
context-engineering-collection vs context-engineering	One is a collection-of-skills; the other is a per-session skill. Keep both. Disambiguate at adoption time.
spec-driven-development vs spec-driven-implementation (Warp-ported) vs write-product-spec + write-tech-spec + implement-specs	Five-skill spec stack. Per DW.10 §2: spec-driven-implementation is the umbrella, write-product-spec → write-tech-spec → implement-specs are the leaves; spec-driven-development is the upstream skill that decided specs are worth it. Keep all five — each is a discrete step. Adjustment: standardise specs/<id>/ vs docs/specs/<id>/ (DW.10 follow-up #1). Recommendation: docs/specs/<id>/ (existing convention).
caveman + caveman-commit + caveman-review	One mode + two specialised outputs. Keep all. Specialised forms are token-savings on PR comments / commit messages — independent of the conversation-level mode.

---

6. session-driver-cmux — viability for Workflow Orchestrator

Found at: /Users/liamj/.claude/session-driver-cmux/. Four executable scripts (launch-worker.sh, send-prompt.sh, converse.sh, stop-worker.sh) + four symlinks to the upstream superpowers plugin (approve-tool.sh, read-events.sh, read-turn.sh, wait-for-event.sh). The local scripts are a clean port of the tmux versions to cmux (Claude-managed multiplexer): launch-worker creates a cmux workspace, sends a claude --session-id … --plugin-dir … --dangerously-skip-permissions command, waits for session_start. send-prompt is cmux send + Enter. converse chains send + wait-for-stop-event + read last assistant message. stop-worker sends /exit + closes workspace.

Suitability for Workflow Orchestrator: HIGH. Exactly the primitive needed for orchestrator → worker dispatch where the worker is a full Claude session (not a one-shot Agent tool invocation). Use cases:

1. Long-running worker with own context window — e.g. impl agent that needs the full repo context, not the orchestrator’s already-filled context.
2. Reusable workers across multiple sub-tasks — orchestrator sends prompt 1, waits, sends prompt 2 to the same worker (preserves cache hits + local state).
3. Parallel worker fleet — orchestrator can launch-worker N times for N work-packages, fan-out, then converse to each independently.

Gaps before it’s a workflow primitive:

1. Personal-config artefact, not project-scoped. Lives in ~/.claude/, not in this repo. Other developers (Claude on a different machine, agents in worktrees) can’t see it. Fix: copy the four local scripts + a thin wrapper SKILL.md to .claude/skills/session-driver-cmux/ in the project repo; reference the upstream plugin symlinks as documentation only.
2. No SKILL.md. Currently invoked by direct path. Fix: author a SKILL.md with frontmatter name: session-driver-cmux describing the four operations + when to use.
3. cmux binary dependency. Worker dispatch requires cmux on PATH. Fix: document install (likely via the superpowers plugin) in the SKILL.md prereqs.
4. No isolation guarantees. Workers run in cmux workspaces but share the host filesystem. Fix: combine with git worktree discipline — orchestrator creates worktree, launches worker in worktree dir.
5. No event-batching. converse reads one stop event at a time. For wave-dispatch (4 parallel workers), orchestrator needs a multi-worker wait. Fix: add a wait-for-fleet.sh that takes N session IDs and waits for all to emit stop.

Verdict: ADOPT as the orchestrator’s worker-dispatch primitive once project-scoped + SKILL.md authored. Until then, continue using Agent(isolation: "worktree") for parallel sub-agent work — the trade-off is that Agent runs in a single sub-conversation whereas cmux workers are independent Claude sessions with their own context windows.

---

7. Warp .warp/workflows/ — port recommendations

Ten YAML files inspected. All are Warp/Rust shell-shortcut wrappers, not agentic skills. Each is a parameterised shell command (Warp’s “Workflows” feature in the terminal UI).

File	Subject	KH applicability
build_image_and_start_container_for_ssh_testing.yaml	Docker SSH test container	Drop — Warp infra.
cherrypick_into_release.yaml	Cherry-pick commit → release branch + push + PR-URL output	Partial port idea: we have analogous wave-merge cherry-pick discipline (CLAUDE.md “Cherry-pick (not merge) parallel agent branches”). The Warp yaml’s output of the compare-URL is a tiny ergonomic win. Optional: add a cherry-pick-to-main bash helper if we automate wave-merge further.
copy_keychain_to_warp_local.yaml	Warp dev keychain copy	Drop — Warp infra.
create_feature_release_pr.yaml	Opens templated GitHub compare URL	Drop — commit-commands plugin covers this.
run_integration_test.yaml	cargo test --package integration	Drop — Rust.
run_unit_test.yaml	cargo test --lib	Drop — Rust.
run_warp_with_shell.yaml	Warp dev runner	Drop.
run_warp_with_version_and_channel.yaml	Warp dev runner	Drop.
script_bundle_temp.yaml	Warp packaging	Drop.
start_new_task.yaml	git checkout -b new-branch off master	Drop — we use worktree isolation; start-session handles branch hygiene.

Verdict: zero direct ports. The .warp/workflows/ directory is a terminal-shortcut feature, not an agentic-workflow feature. The valuable patterns from the Warp repo are in .agents/skills/ (already mostly imported) and .github/actions/docubot/ (next section).

---

8. GitBook (docubot) — replication next steps

Source files:

• /development/warp/.github/actions/docubot/action.yml — composite action: setup-warp-cli, clone-gitbook-repo (warpdotdev/gitbook), envsubst-template the prompt, run warp-cli agent run --prompt …, upload logs + prompt as artifacts.
• /development/warp/.github/actions/docubot/prompt.txt — system prompt for docubot persona: read PR, edit docs in $GITBOOK_PATH, open docs-PR, comment back on source-PR with @author tag.
• /development/warp/.github/workflows/docubot_reply_to_comment.yml — workflow_dispatch only (auto issue_comment triggers commented out as noisy). Inputs: PR number, prompt, channel, profile-id.

KH replication plan (concrete next steps):

Phase 1 — minimum viable docubot (1–2 sessions):

1. Decide docs repo strategy. Two options:

   • Same-repo (docs/ directory) — agent opens follow-up docs-only PR on the same knowledge-hub repo.
   • Separate-repo (knowledge-hub-gitbook) — mirrors Warp pattern; agent clones, edits, opens PR on the sink repo, comments back on source PR.

2. Author .github/workflows/docubot.yml. Triggers: workflow_dispatch (manual) + pull_request.types: [closed] filtered to merged == true. Skip auto issue_comment (Warp’s lesson).

3. Author .github/actions/docubot/action.yml. Composite action that:

   • Checks out source repo at the merged PR’s SHA.
   • (Same-repo:) checks out docs branch in a fresh worktree.
   • Renders prompt.txt via envsubst with GitHub event context.
   • Invokes Claude Code (or Claude Agent SDK) headless with the prompt.

4. Author .github/actions/docubot/prompt.txt. Adapted from Warp version. Replace Warp-specific language (warpdotdev/gitbook → knowledge-hub docs; Warp persona → KH-docubot persona). Reuse Warp’s commit-conventions, PR-conventions, and final-comment template.

5. Author KH skill keep-docs-in-sync (or extend update-docs). Loaded by the agent automatically. Mirrors what docubot’s prompt embeds — KH conventions for docs/ structure, the doc-inventory at docs/reference/documentation-inventory.md, the SCHEMA-QUICK-REFERENCE rules, etc. Per DW.10 §3 follow-up.

Phase 2 — productionise (post-canonical-pipeline):

1. Migrate to separate knowledge-hub-gitbook repo if GitBook hosting requires it.
2. Wire to Astro+Starlight (Warp’s choice) or Mintlify (alt) if richer hosting needed; or keep raw Markdown if GitBook’s git-sync works directly.
3. Add the docubot’s siblings from Warp’s open-sourced docs repo: review-docs-pr, update-changelog, sync-error-docs, missing_docs, check_for_broken_links, docs-seo-audit. Each is a scheduled or PR-triggered skill that runs unsupervised.

Authentication: docubot needs a token with contents:write + pull-requests:write + issues:write on the docs target. Same-repo: use ${{ secrets.GITHUB_TOKEN }}. Separate-repo: PAT or GH App.

Claude integration: Warp uses warp-cli agent run --prompt …. We have three options:

• Claude Code headless — install in CI, invoke claude with --prompt flag (CI variant of claude --headless).
• Claude Agent SDK (@anthropic-ai/claude-agent-sdk) — script-driven; better for parameterised prompts.
• Anthropic API direct — most control, most code.

Recommendation: Claude Agent SDK. Cleanest balance between scripting + control.

---

9. Warp blog takeaways

Block model post. Three orchestration-relevant insights:

1. Typed blocks in a SumTree → O(log n) lookups across thousands of blocks. For KH this maps to “treat each sub-agent run as a typed block” — verification block, impl block, fix block, etc. Useful conceptually for thinking about how an orchestrator presents waves of work without flattening detail. Practical implication: the orchestrator’s end-of-wave summary should be a summary block with drill-down to underlying agent outputs.

2. View-layer filtering separate from underlying data. Rich content stays in the model but is hidden via zero-height entries. Translation for KH: sub-agent transcripts should be retained (durable) but only the orchestrator-relevant excerpts surface in the main thread. This is what Agent tool already does — but the principle suggests we should also persist the full sub-agent transcript somewhere (e.g. mempalace) rather than letting it evaporate.

3. Block types are extensible. “BlockList doesn’t care what’s inside a block.” Translation: as we add SDLC stages (test-result block, coverage-report block, deploy block), we don’t need to retro-fit infrastructure — same orchestrator handles new block types. Lightly aspirational for our setup but a sensible north-star.

Open-sourcing docs post. Two orchestration-relevant insights:

1. Supervised long-running agents scale sub-linearly. Warp shipped 285 cloud-agent tasks during a hackathon. The marginal cost of task N+1 approaches zero once templates / skills / supervision tooling exists. For KH: the upfront cost of setting up docubot + auditor + evaluator pays off only above a threshold (~50 sessions?), so we should be patient about ROI but committed to the investment.

2. Skills + GitHub Actions = the maintenance surface. Their skills review-docs-pr, update-changelog, sync-error-docs, missing_docs, check_for_broken_links, docs-seo-audit all run unsupervised on triggers. We should plan for at least review-docs-pr + sync-error-docs + check_for_broken_links once the docubot foundation is in place — each is a small skill that closes a specific drift gap.

---

10. graphify / gitnexus / ccc / cocoindex — consolidation

Surface-area difference (one-line each):

• ccc (cocoindex-code, CLI). Semantic code search + per-file/dir summaries. Replaces ad-hoc grep for “find code related to X”. Built on cocoindex library; embedding-based.
• graphify (CLI/MCP). Files → knowledge graph with Leiden clustering + GRAPH_REPORT.md + multi-format export (HTML / Cypher / GraphML / Obsidian). Tree-sitter AST + doc semantic extraction.
• gitnexus (MCP server + UI at :4747). Tree-sitter AST → typed-node graph. Richer framework-aware schema than graphify: Route/HANDLES_ROUTE/Process/STEP_IN_PROCESS/FETCHES/QUERIES/ENTRY_POINT_OF. Browser-side LadybugDB. KH corpus already indexed (40,988 nodes / 58,754 edges per DW.11 eval).
• cocoindex (Python library). Pipeline-authoring framework: incremental data processing with declarative target state. Different surface from ccc — ccc is “use the index”; cocoindex is “build pipelines”.

Overlap analysis (graphify vs gitnexus): Both Tree-sitter AST → structural graph. Per DW.11 eval: gitnexus has framework-aware extras graphify lacks; graphify has Leiden + GRAPH_REPORT.md + multi-format export. Neither does data-flow.

Verdict:

• ccc — ADOPT as everyday tool. Replaces grep-based exploration. Particularly valuable in long sessions where grepping the same area repeatedly burns context. SKILL.md already encodes the lifecycle (init + index-on-stale + search).
• gitnexus — KEEP as structural graph backbone. Used selectively for: route-mapping (api impact assessment), call-graph (impact analysis pre-refactor), shape-check (verifying TypeScript shape conformance). Already exposed via MCP tools mcp__gitnexus__*.
• graphify — DROP from dev-workflow. Per S232 CX.32: Knowledge Map = Cocoindex, not Graphify. Per DW.11 eval: gitnexus schema is a superset of graphify for KH purposes. Graphify’s Leiden / GRAPH_REPORT.md is genuinely nice but redundant given gitnexus + ccc. Caveat: keep /graphify available globally (it’s a personal ~/.claude/skills/ skill) — drop it from the KH workflow proposal, not from your toolbox.
• cocoindex (library) — KEEP separately. It’s the pipeline-authoring substrate, not a search tool. Used to build ccc + (future) Knowledge Map.

DW.11 — AST data-flow tracing — does ccc close the gap?

No. ccc is semantic search over chunks (embedding-based). It can answer “where is X computed?” by similarity, but it does not trace def → use → return → callee-parameter → ... chains. The DW.11 verdict from the dw-subagent eval is unchanged: no third-party tool we’ve evaluated covers AST data-flow. Options remain:

1. ts-morph + LSP — author a KH-specific data-flow extractor (medium effort). Best for “which functions read/write content_items.summary” type queries.
2. Sourcegraph (paid) — has graph-level def/ref but pricing + setup overhead.
3. Defer. DW.11 was flagged as “needs separate investigation if it matters for production-readiness test audit.” Test-audit work has shipped (S43–S44 waves) without it. Recommendation: defer DW.11 until a concrete need surfaces (e.g. extracting the canonical pipeline’s data dependencies for spec-vs-code reconciliation).

---

11. 6 redundancy-candidate skills — survival assessment

Skill	Current role	After GitBook + ccc + gitnexus consolidation	Verdict
kpf-reference-doc-refresher	Refreshes the 11 tracked KH reference docs (schema / AI-classification / data-flow / runbooks) — diffs claimed facts against live codebase, applies edits, bumps Last verified headers.	Largely replaced by docubot. Docubot’s job is exactly “PR causes doc updates” — but kpf operates on a different cadence (scheduled refresh, not PR-triggered) and over a known doc set. Docubot + scheduled review-docs-pr cron + sync-error-docs collectively cover kpf’s surface area.	DROP after Phase 2 docubot ships. Keep for now — replacing it would create a coverage gap. Mark for retirement post-docubot+scheduled-skills.
gsd-codebase-mapper	Parallel mapper agents → .planning/codebase/ documents (STRUCTURE.md etc).	Largely replaced by ccc. .planning/codebase/STRUCTURE.md exists for AI consumption; ccc’s index gives the same access via search. But: STRUCTURE.md is human-readable; ccc index is machine-only. Retain STRUCTURE.md as a generated artefact (a thin script that walks the repo + ccc index could produce it).	DROP gsd-codebase-mapper agent. Replace with a periodic refresh of .planning/codebase/ from a bun run codebase:remap script (using ccc).
caveman	Token-compression communication mode (~75% token reduction). Plugin.	No equivalent in the imported skill set. Independent of doc / graph tooling.	KEEP. Pure-win token saver.
start-session	KH-specific session bootstrap: git hygiene, read CLAUDE.md, read continuation prompt, present session plan.	No equivalent. using-agent-skills is task-routing, not session-bootstrap.	KEEP. Project-specific glue.
update-docs	End-of-session: refresh roadmap JSON, state-of-the-product, generated stats, product backlog; auto-chain to handoff.	Partial overlap with docubot for PR-triggered doc updates, but update-docs runs end-of-session and handles roadmap / SoTP / generated-stats / backlog — none of which docubot touches.	KEEP. Project-specific glue. Possibly extend with a keep-docs-in-sync invocation that asks “what needs docubot to pick up?“
handoff	Continuation-prompt generator for next session.	No equivalent. Project-specific.	KEEP. Project-specific glue.

Summary of redundancy: Only 2 of 6 are genuinely redundant after consolidation — kpf-reference-doc-refresher and gsd-codebase-mapper — and both are conditionally redundant (kpf after docubot+scheduled-skills land; gsd after a codebase:remap script lands). The other 4 survive.

---

12. Open questions for ratification

1. Auditor + Evaluator scope — phased deferral OK, or are they MVP?
2. Same-repo vs separate-repo for docubot docs sink — recommendation §7 is same-repo for Phase 1; confirm?
3. docs/specs/<id>/ vs specs/<id>/ — per DW.10 §3 follow-up #1, the spec skills want specs/<id>/ but KH convention is docs/specs/. Pick one + align all five spec skills.
4. session-driver-cmux project-scoping — author SKILL.md + project-local copy now (S46-ish) or defer until the orchestrator is more concrete?
5. Graphify retirement — agreed to drop from dev-workflow per §10? (Still keeps the global /graphify skill for personal use.)
6. kpf + gsd retirement — agreed conditional retirement per §11? (kpf after docubot Phase 2; gsd after codebase-remap script.)
7. DW.11 (AST data-flow) status change — agreed to defer per §10 (“until concrete need surfaces”)? Currently OPEN; can move to DEFERRED-POST-CANONICAL-PIPELINE.

---

13. Suggested sequencing for canonical-pipeline implementation

Tight version of what needs to land before the orchestrator drives the new canonical pipeline work:

Sprint A (orchestrator MVP — 2–3 sessions):

1. Copy using-agent-skills to .claude/skills/orchestrator-routing/SKILL.md with modifications per §4.
2. Standardise spec path (docs/specs/<id>/ vs specs/<id>/) + update all five spec skills.
3. Author .claude/skills/session-driver-cmux/SKILL.md + copy the four scripts project-local. Verify cmux binary install.
4. Add wait-for-fleet.sh helper to session-driver-cmux for multi-worker wave dispatch.

Sprint B (docubot Phase 1 — 1–2 sessions):

1. Author .github/workflows/docubot.yml + .github/actions/docubot/action.yml + prompt.txt.
2. Decide same-repo vs separate-repo (recommend same-repo).
3. Author or extend update-docs → keep-docs-in-sync skill.
4. Pilot on one merged PR end-to-end.

Sprint C (graph-tool consolidation — 1 session):

1. Drop graphify references from kh-workflow-orchestration.md.
2. Confirm ccc init + ccc index runs cleanly on KH repo; document ccc usage in CLAUDE.md.
3. Author bun run codebase:remap script (uses ccc) to regenerate .planning/codebase/STRUCTURE.md.
4. Mark gsd-codebase-mapper for retirement; remove from agent list.

Sprint D (orchestrator-routed canonical-pipeline kickoff):

1. Orchestrator runs start-session → using-agent-skills (orchestrator-routing) → identifies spec phase → routes to spec-driven-implementation → fan-out via session-driver-cmux workers → verification gates → wave merge.
2. End-of-session: update-docs → docubot picks up PR-merge → handoff.

---

End of assessment.