Kh Sdlc Workflow Feedback

kh-sdlc-workflow Section Feedback

• Below is feedback on specific sections of the kh-sdlc-workflow document, but how the workflow elvoves from this feedback will of course impact all sections.

2. Roles

DRAFT - to be updated after next workflow review.

Five canonical roles. Auditor + Evaluator are deferred — see §10.

Role	Model	Operational file	What it does	What it never does
Workflow Orchestrator	opus-4-7 (max)	.claude/agents/workflow-orchestrator.md	To be updated after feedback review	TBD
Task Planner	opus-4-7 (max)	.claude/agents/task-planner.md (required)	To be updated after feedback review	TBD
Task Executor	sonnet-4-6	.claude/agents/task-executor.md (rename)	To be updated after feedback review	TBD
Task Checker	sonnet-4-6	.claude/agents/task-checker.md (rename)	To be updated after feedback review	TBD
Workflow Curator	sonnet-4-6	.claude/agents/workflow-curator.md	To be updated after feedback review	TBD

“Verification gates are not optional” sub-section

User Clarification - Orchestrator wouldn’t directly fix findings. Based on feedback from the Checker (and/or other agents), they would either deploy a new Executor to fix the issues directly, or deploy the Curator who would assess the findings to determine the approach required - add new subtask(s), impact to current task’s remaining subtasks/parallel implementation work/next task(s), update product backlog, escalate for decision on backlog versus roadmap/wider decision.

3. Lifecycle

User Clarifications - We need to re-think and re-work the lifecycle to be task-driven. Task’s provide the “why”, plus they add observability and traceability.

• 3.1 - Shift to task-driven will also include collapsing the top-level worktrees to just main, and utilising feature branches + isolated worktree agents. /start-session skill will need to be updated - continuation prompt will be reviewed, but the session’s tasks will be available in taskmaster.
• 3.2 (and WP3) - Continuation prompt will inform the Orchestrator on what is required for the session. This will either be continuing with taskmaster task/subtask implementation, or updating taskmaster by adding new subtasks to an in-flight task, or adding a new task(s) and expanding to subtasks. ALL work needs to be task-driven, as this enables autonomy in our workflow, e.g., previous session identifies non-trivial work, Curator adds to product backlog, continuation prompt reflects this, Orchestrator in the new session adds subtask(s)/task as relevant, which may be, for example, {N}.1 - Research/Investigate XYZ (likely includes using domain-specific skills/agents, specific to the identified work), {N}.2 - Write Product spec [Written by Workflow Executor using writing-product-spec and then Orchestrator deploys Workflow Checker - Orchestrator deploys Executor to apply ALL findings or moves to next task], {N}.3 - Write Technical Spec [Written by Workflow Executor using writing-tech-spec and then Orchestrator deploys Workflow Checker - Orchestrator deploys Executor to apply ALL findings or moves to next task] - [Orchestrator then determines whether ratified product and tech specs are ‘implementation-ready’, and can therefore be added as a new taskmaster task and expanded to subtasks, or if further decomposition is required, a new ‘{N}.4 - {feature/functionality} task breakdown’ task would be required first, with the Orchestrator following the same pattern, deploying an Executor to use planning-and-task-breakdown, and a Checker to verify, then back to Executor to apply ALL findings. Once ratified, if the plan is determined to be ‘implementation-ready’, it can be added as a new taskmaster task and expanded to subtasks.]
• 3.4 - Orchestrator’s role here is to understand which subtasks can be executed sequential versus parallel. All research/investigate/planning/design work should have been completed by this point, the Orchestrator is focused on dispatching Executor agents to complete ‘implementation-ready’ subtasks - the ‘dispatch brief’ shouldn’t need to vary here, this should ideally be pure execution of a pre-defined sub-task.
• 3.5 - As noted, Checkers aren’t ‘per wave’, they are ‘per subtask/per stage’. This could be “does the implementation meet the spec and project conventions?”, or “Does the implementation meet code quality standards?” or “Is this the most elegant implementation and has the simplest approach been used?” - this is an audit phase, and the Orchestrator’s role is to then determine if these are quick fixes which new Executors can resolve, or if the Curator assessment workflow is required.

4. Per-phase skill routing

User Clarifications: - As above, it looks like the best approach would be using baseline Executor and Checker agents, who’s role is ‘task-execution & verification’ - it’s the research/planning/design/verification/debugging phases where agents require domain or phase-specific skills, rather than the implementation phase, and introducing a task-planner may be a suitable option here.

My view on how the workflow and agents should be structured

• From a taskmaster perspective (or any task-management tool):
  • Top-level Tasks need to be defined and then split into subtasks.
    • Define how this should differ between different types of tasks - what does planning-and-task-breakdown do? Is it a 1:1 match for some types?
  • Sub-tasks are either executed or checked - skill-agnostic Executors and Checkers complete these actions.
• The scope of the subtask determines which skill(s) the Planner, Executor, Checker, or Orchestrator invokes, determined by which SDLC phase the subtask is part of.

  • Planner: These cover tasks up to the implementation phase.

    • Skills invoked by phase:
      • Research & Design
        • Current state research and understanding
          • Context management - context-engineering
          • Codebase understanding - ccc
          • Data flow understanding - ast-dataflow (new skill currently being created on ast-dataflow top-level worktree)
          • Database - Supabase MCP
          • Canonical-pipeline-related - cocoindex
          • Impact Analysis - - gitnexus-impact-analysis
          • Refactoring - gitnexus-refactoring
        • Target State Design
          • Context management - context-engineering
          • Latest package versions & documented patterns - context7 MCP
          • Database/schema-related - supabase-postgres-best-practices
          • Canonical-pipeline-related - cocoindex
          • API - api-and-interface-design, claude-api
          • UI/UX - vercel-react-best-practices, web-design-guidelines, interaction-design
          • Mobile - mobile-design
          • CI/CD - ci-cd-and-automation, github-actions-templates
          • AI (Prompt-related) - context-engineering-collection, prompt-engineering-patterns
          • AI (Skills) - create-skill, update-skill
          • AI (Agent-related) - agent-development
          • AI (MCP-specific) - mcp-builder, create-mcp-app
          • E2E testing - playwright-best-practices
          • Documentation - documentation-and-adrs, astro, mermaid-diagrams
      • Spec-authoring
        • write-product-spec
        • test-driven-development, write-tech-spec
        • mermaid-diagrams
      • Task Breakdown
        • test-driven-development, planning-and-task-breakdown, mermaid-diagrams

  • Executor: These are the do-ers, even if the work they are completing is technically a verification-type task e.g., using the code-simplification and code-review-and-quality skills.

    • Skills invoked by phase:

      • Implementation
        • context-engineering
        • implement-specs (or is this too broad when using our task-driven approach?)
        • commit-commands, git-workflow-and-versioning (or should this just be for the Orchestrator?)
        • fix-errors (?)
      • QA
        • code-simplification
        • code-review-and-quality
      • Testing
        • browser-testing-with-devtools + agent-browser
      • Debugging
        • gitnexus-debugging
        • browser-testing-with-devtools + chrome-cdp
        • browser-testing-with-devtools + chrome-devtools MCP
      • Documentation Updates
        • documentation-and-adrs, astro, mermaid-diagrams

    • There are two exceptions when Executor agents aren’t used for implementing a task:

      • When reviewing skills, use the skill-reviewer agent.
      • When creating agents, use the agent-creator agent.

    • Why don’t we use domain-specific skills for implementation tasks?

      • This is because once we are at the stage where something is ready to be implemented, we fully understand the code base and implications, we’ve researched the latest technical information and patterns, we’re following best practice, everything has been documented, and so the task/subtask has therefore already been carefully curated and verified, and is ready to be executed.

  • Checker: These are not ‘do-ers’, they are verifiers - Has a task/sub-task been executed to spec (where one exists), or does it meet it’s acceptance criteria.

    • Checkers also provide structured feedback for the Orchestrator, so that the Orchestrator can make informed decisions on next workflow actions.

  • Orchestrator:

    • Session orchestration - context-engineering, session-driver-cmux, workflow-orchestration, handoff
    • Phase-specific:
      • Workflow/project context - claude-md-management
      • When new tasks are required - spec-driven-implementation
      • Requirements gathering - for example, prior to Research/Design Phase when implementing something which isn’t fully understood from a product-perspective. - brainstorming, idea-refine
      • Deployment - git-workflow-and-versioning, resolve-merge-conflicts, diagnose-ci-failures

  • Curator:

    • Finding triage - triage-finding
    • Roadmap/backlog promotion - update-roadmap-backlog

  • Evaluator:

    • Workflow performance improvement - claude-md-management, create-skill, update-skill

  • Auditor:

    • TBD

5. Dispatch primitives

These will be adapted after finalising the wider workflow based on this round of feedback.

Role and Workflow Feedback/Questions not specific to kh-sdlc-workflow sections

• In terms of starting sessions:

  • Does the Orchestrator need dispatching-parallel-agents and/or using-git-worktrees, or would it make sense to create an amalgamated skill, covering the aspects which will be specific to our workflow?
  • My current understanding is that the first step in a session would be to invoke the /start-session skill (a re-worked version, once we finalise our approach) - this would include reviewing the previous session’s mempalace diary entry, and reviewing taskmaster to identify the next task or sub-tasks that require execution. After this, what is the intention?

    • Are you (Claude), going to be the workflow orchestrator, from the main session, or are you ‘deploying’ a workflow-orchestrator, perhaps to their own cmux terminal, which you would then be able to monitor, along with any additional terminals which they create during the session. If so, then my guess would be that workflow-orchestrator.md would remain an agent file, but I’d need to understand how session-driver-cmux then fits into the workflow, as well as dispatching-parallel-agents and/or using-git-worktrees.

      For example, which of the below is the more practical approach, considering our intended workflow?

      • (i) Main Session: Invokes /start-session, chains to /session-driver-cmux, deploys workflow-orchestrator agent who begins the Executor + Checker workflow. Main session monitors orchestration agent’s cmux terminal, and communicates with the workflow orchestrator, or intervenes, if there are any issues spotted.
      • (ii) Main Session: Invokes /start-session, chains to workflow-orchestration (skill-version, rather than agent file), chains to /session-driver-cmux skill, chains to amalgamated dispatching-parallel-agents + using-git-worktrees (unless workflow-orchestration covers this), begins the Executor + Checker workflow.

• Is the ‘Code self-review’ phase required, or are we duplicating effort? My thinking here is that by this point:

  • Spec(s) would have been created and verified -> converted to a plan & verified OR added to taskmaster as a task and subtasks -> Executor should already have clear instructions for implementation approach -> Checker is then adversarially reviewing the implementation against the spec -> full verification is about to take place.

• We also need to think about and then determine the Checker’s scope, again to avoid duplication, and also to ensure proper coverage. The “6.1 Checker verdict” section suggests the Checker covers 6 axis, which could work for some tasks, but not all. Would it be better to split? We also need to determine whether certain skills/agents are used throughout the implementation of each sub-task, versus at key checkpoints of a task’s completion (thinking in terms of taskmaster flow here, which might take the implementation of a feature and then split it down into various subtasks where the initial subtasks for developing functionality should be bitesize test-driven development implementation, but a taskmaster task will cover all SDLC aspects of implementing functionality - with some being DB-related, others could be infrastructure, others may be frontend, or it could be that a task covers sub-tasks for all aspects, plus triggering documentation-related skills/tasks, when appropriate.

  • Currently we have two core Anthropic agents available as a baseline - code-simplifier and code-reviewer. We then also have the code-review-and-quality skill. We need to determine the correct workflow ordering here:
    • Is the Checker therefore purely “spec and standards compliance”, and a separate agent or agents cover code review, quality, and simplification? What is the correct order here? E.g., Executor implements sub-task(s), Checker completes “spec and standards compliance” and then feeds back to the Orchestrator in terms of whether a sub-task was correctly executed to spec (plus any “standards” issues identified). If it was executed correctly, a code simplification OR code quality review pass (whichever makes more logical sense to deploy first in a dev workflow) could then follow, with the agent reporting back to the Orchestrator once complete, which could include feedback on whether or not whichever agent didn’t run (simplification or review) should then be deployed or if the subtask/task is already complete and meets quality expectations. If the Checker reports back that changes are required, this would of course trigger a new Executor/Checker pass first. Or should it be that code simplification takes place first (prior to the checker), followed by code review and quality checks, and then Checker? Or is it that code simplification runs after each sub-task (or main task), but code quality and review only takes place once a full task is complete? I imagine there’s nuance here and certain tasks won’t require code simplification or quality review at all from a code perspective as they won’t have implemented code. Or another consideration will be how a task is broken down into subtasks and therefore the approach for simplification and code quality and review taking place being altered in terms of the cadence, to reflect the size of the work being implemented. Important here is ensuring that what we’re providing the Orchestrator with is a structured approach for being able to determine what should be happening, based on the information that they are provided with, including of course being able to escalate to me, where the approach isn’t clear, or escalation is required.
    • Should performance-optimization and security-and-hardening be brought in, to be used, when a specific subtask or task would benefit from these?
    • There are also Anthropic baseline agents available for type-design-analyzer (when introducing or refactoring types) and silent-failure-hunter (as a final check at PR time).

• From reading the SDLC workflow document I think the workflow-worker-minimal concept has been misunderstood, which will have been my fault for not providing clear enough direction on this. Rather than there being a separate new agent type, my original question and intention was more to do with whether Anthropic had a mode for more streamlined agents - I actually found what I was trying to reference - “bare mode” (https://code.claude.com/docs/en/headless#start-faster-with-bare-mode).

  • For clarity, we don’t need the concept of a workflow-worker-minimal, the intention was just to ensure that we are managing subagent context windows effectively. It may be that “bare mode” isn’t suitable, as it’s for headless, but the concept behind may still be something we can integrate into our workflow, and also potentially into the KH platform, whenever there is a requirement to utilise agents for platform-specific functionality.

• Now may also be a good time to compare the original Superpowers driving-claude-code-sessions skill (~./claude/plugins/cache/superpowers-marketplace/claude-session-driver/1.01/) with our session-driver-cmux skill, from a functionality perspective. It may be that ours deviates, based on the other feedback I’ve provided here, predominantly in terms of interacting with our other skills, and how our sessions will run.

  • If we update our skill we should use /update-skill and also the /cmux skill, to ensure we follow best practice, and are using the latest cmux patterns.

• We need to evaluate ALL agent and skill files once the workflow is finalised.

  • We’ll then use /update-skill and/or /create-skill, and agent-development.
  • For workflow agents who are using the same skills each time they are deployed, we need to ensure we use the skills field to inject skill content.
    • Agents can of course still be deployed with instructions from the Orchestrator to also invoke subtask/task-specific skills.