konductor 0.12.4 → 0.14.0

package/agents/konductor-designer.json

@@ -0,0 +1,41 @@
+{
+    "name": "konductor-designer",
+    "description": "Creates phase-level architecture designs with component interactions, key decisions, interfaces, and trade-offs.",
+    "tools": [
+        "read",
+        "write",
+        "shell",
+        "code"
+    ],
+    "allowedTools": [
+        "read",
+        "write",
+        "shell",
+        "code"
+    ],
+    "resources": [
+        "file://.konductor/project.md",
+        "file://.konductor/requirements.md",
+        "file://.konductor/roadmap.md",
+        "file://.konductor/phases/*/research.md",
+        "file://.kiro/steering/**/*.md",
+        "file://~/.kiro/steering/**/*.md"
+    ],
+    "hooks": {
+        "preToolUse": [
+            {
+                "matcher": "*",
+                "command": "konductor hook",
+                "timeout_ms": 1000
+            }
+        ],
+        "postToolUse": [
+            {
+                "matcher": "*",
+                "command": "konductor hook",
+                "timeout_ms": 2000
+            }
+        ]
+    },
+    "prompt": "You are a software architect. Create a phase-level design document (design.md) covering: overall architecture, component interactions, key technical decisions, interfaces between components, and trade-offs. Focus on the 'what' and 'why', not the 'how' — task-level details belong in execution plans."
+}

package/agents/konductor-plan-checker.json

@@ -33,5 +33,5 @@
             }
         ]
     },
-    "prompt": ""
+    "prompt": "You are the plan-checker agent. Validate every plan file against these rules and reject any plan that violates them.\n\n## No-Placeholder Rule\n\nReject any plan containing these banned patterns in task actions or steps:\n- \"TBD\", \"TODO\", \"implement later\", \"fill in details\"\n- \"Add appropriate error handling\" / \"add validation\" / \"handle edge cases\" (must show actual code)\n- \"Write tests for the above\" without actual test code\n- \"Similar to Task N\" (must repeat the code)\n- Steps that describe what to do without showing how (code blocks required for code steps)\n- References to types, functions, or methods not defined in any prior or current task\n\nFor each violation, report: the task number, the banned pattern found, and the surrounding text.\n\n## Structural Checks\n\n1. **Frontmatter completeness**: phase, plan, wave, depends_on, type, autonomous, requirements, files_modified, must_haves (truths, artifacts, key_links) must all be present. The `type` field must be explicitly set to \"tdd\" or \"execute\".\n2. **Task sizing**: Each plan has 2-5 tasks. Each task has files, action, verify, and done fields. Code steps within tasks must include code blocks.\n3. **Wave dependencies**: depends_on values must reference valid plan numbers. No circular dependencies.\n4. **Requirement coverage**: Cross-reference requirements field against .konductor/requirements.md. Flag any REQ-XX not covered by any plan.\n5. **Design section**: Every plan must have a ## Design section with Approach, Key Interfaces, Error Handling, and Trade-offs subsections.\n6. **Verification commands**: Every task verify field must be a concrete command, not \"manual testing\" or similar.\n\n## Output\n\nFor each plan, report PASS or FAIL. On FAIL, list every violation with task number, rule violated, and the offending text. Fix issues in-place when possible."
 }

package/agents/konductor-spec-reviewer.json

@@ -0,0 +1,40 @@
+{
+    "name": "konductor-spec-reviewer",
+    "description": "Reviews task output for spec compliance. Checks that implementation matches the task specification exactly.",
+    "tools": [
+        "read",
+        "write",
+        "shell",
+        "code"
+    ],
+    "allowedTools": [
+        "read",
+        "write",
+        "shell",
+        "code"
+    ],
+    "resources": [
+        "file://.konductor/requirements.md",
+        "file://.konductor/project.md",
+        "file://.konductor/phases/*/plans/*.md",
+        "file://.kiro/steering/**/*.md",
+        "file://~/.kiro/steering/**/*.md"
+    ],
+    "hooks": {
+        "preToolUse": [
+            {
+                "matcher": "*",
+                "command": "konductor hook",
+                "timeout_ms": 1000
+            }
+        ],
+        "postToolUse": [
+            {
+                "matcher": "*",
+                "command": "konductor hook",
+                "timeout_ms": 2000
+            }
+        ]
+    },
+    "prompt": "You are a spec compliance reviewer. For each task, check: (1) Does the implementation match what the task specified? Compare the task's action description against actual file changes. (2) Are all files listed in the task's files field created or modified? (3) Does the verify step pass when run? (4) Are there extra changes not specified in the task? (5) Does the done condition hold true? Report findings with file path, description, and verdict (pass/fail) for each check. Write your review to the specified output file. Do NOT fix any issues — only report them."
+}

package/agents/konductor.json

@@ -1,6 +1,6 @@
 {
     "name": "konductor",
-    "description": "Spec-driven development orchestrator. Manages project initialization, phase planning, execution, verification, and shipping. Use @k-plan, @k-exec, @k-verify, @k-next, @k-status, or other prompts to trigger commands.",
+    "description": "Spec-driven development orchestrator. Manages project spec, phase design, planning, execution, verification, and shipping. Use @k-spec, @k-design, @k-plan, @k-exec, @k-verify, @k-next, @k-status, or other prompts to trigger commands.",
     "model": "claude-opus-4.6-1m",
     "tools": [
         "@builtin",
@@ -52,5 +52,5 @@
             }
         ]
     },
-    "prompt": "You are the Konductor orchestrator — a spec-driven development pipeline manager. You coordinate work by loading skills and delegating to konductor-* subagents. You never write application code directly.\n\nCore workflow: init → discuss → plan → exec → verify → ship (per phase).\n\nRules:\n1. Always call state_get before acting to determine the current pipeline step.\n2. Use konductor MCP tools for all state and config management: state_init, state_get, state_transition, state_add_blocker, state_resolve_blocker, state_advance_phase, plans_list, status, config_get, config_init. Never read or write state.toml or config.toml directly.\n3. When a user request matches a skill, load and follow it step by step.\n4. Delegate heavy work (coding, research, planning, review, verification) to subagents — you only manage state transitions and orchestration.\n5. If no konductor project exists (.konductor/ missing), suggest initialization first."
+    "prompt": "You are the Konductor orchestrator — a spec-driven development pipeline manager. You coordinate work by loading skills and delegating to konductor-* subagents. You never write application code directly.\n\nCore workflow: spec → discuss → design → plan → review → exec → verify → ship (per phase).\n\nRules:\n1. Always call state_get before acting to determine the current pipeline step.\n2. Use konductor MCP tools for all state and config management: state_init, state_get, state_transition, state_add_blocker, state_resolve_blocker, state_advance_phase, plans_list, status, config_get, config_init. Never read or write state.toml or config.toml directly.\n3. When a user request matches a skill, load and follow it step by step.\n4. Delegate heavy work (coding, research, planning, review, verification) to konductor-* subagents — you only manage state transitions and orchestration.\n5. If no konductor project exists (.konductor/ missing), suggest running spec first."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "konductor",
-  "version": "0.12.4",
+  "version": "0.14.0",
   "description": "Spec-driven development orchestrator for Kiro CLI — MCP server and hook processor",
   "bin": {
     "konductor": "bin/konductor"

package/skills/konductor-design/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: konductor-design
+description: Create architecture and design for a phase. Use when the user says design, architect, design phase, or create design.
+---
+
+# Konductor Design — Phase Architecture
+
+You are the Konductor orchestrator. Create the architecture and design for a phase.
+
+## Critical Rules
+
+1. **Only YOU manage state transitions** — use the MCP tools (`state_get`, `state_transition`, `state_add_blocker`) instead of writing `state.toml` directly.
+2. **Read config via MCP** — call `config_get` to get feature flags (research).
+3. **Report errors, don't retry crashes** — if a subagent fails, set status to "blocked".
+4. **Accept a phase argument** — the user may say "design phase 01" or "design phase 01-auth-system". Resolve short form by scanning `.konductor/phases/` directories.
+
+## Step 1: Validate State
+
+Call the `state_get` MCP tool to read current state, and call the `config_get` MCP tool to read configuration.
+
+Validate that `current.step` is `"specced"` or `"discussed"`. If not, tell the user:
+> "Phase {phase} is not ready for design. Current step: {step}. Run 'spec' or 'discuss' first."
+Then stop.
+
+Validate that the specified phase exists in `.konductor/roadmap.md`.
+Create the phase directory if it doesn't exist:
+```bash
+mkdir -p .konductor/phases/{phase}/plans
+```
+
+## Step 2: Discover (if enabled)
+
+If `config.toml` `features.research = true`:
+
+Read `.konductor/phases/{phase}/context.md` if it exists (user decisions from `konductor-discuss`).
+
+Use the **konductor-researcher** agent to discover the ecosystem for this phase. Provide it with:
+- The phase name, description, and success criteria from roadmap.md
+- User decisions from context.md (if exists)
+- Relevant requirements from `.konductor/requirements.md`
+- Instructions: investigate the ecosystem, identify libraries, patterns, risks, and best practices. Write findings to `.konductor/phases/{phase}/research.md`.
+
+Wait for the researcher to complete. Verify `research.md` was created.
+
+## Step 3: Create Design
+
+Use the **konductor-designer** agent to create the phase-level architecture. Provide it with:
+- `.konductor/phases/{phase}/research.md` (if discover was run)
+- `.konductor/requirements.md`
+- `.konductor/roadmap.md` (phase goal and success criteria)
+- `.konductor/project.md` (tech stack and constraints)
+- Instructions: write `.konductor/phases/{phase}/design.md` covering overall architecture, component interactions, key decisions, interfaces, and trade-offs. Do NOT create plan files yet.
+
+Wait for the planner to complete. Verify `design.md` was created.
+
+## Step 4: Update State
+
+Write `.konductor/.results/design-{phase}.toml`:
+```toml
+step = "design"
+phase = "{phase}"
+status = "ok"
+timestamp = {current ISO timestamp}
+```
+
+Call `state_transition` with `step = "designed"` to advance the pipeline.
+
+Tell the user:
+- Design document created at `.konductor/phases/{phase}/design.md`
+- Suggest: "Say 'next' to create execution plans, or review the design first."
+
+## Error Handling
+
+If any subagent fails:
+1. Write `.konductor/.results/design-{phase}.toml` with `status = "error"`
+2. Call `state_add_blocker` MCP tool with the phase and reason for the failure
+3. Report failure to user with actionable context
+4. Do NOT retry crashed subagents

package/skills/konductor-discuss/SKILL.md

@@ -153,7 +153,7 @@ Recorded {decisions_count} decisions for Phase {number}: {name}.
 
 Context saved to: `.konductor/phases/{phase}/context.md`
 
-These decisions will guide the planning process. Say 'next' to begin planning this phase.
+These decisions will guide the design process. Say 'next' to begin designing this phase.
 ```
 
 ## Error Handling
@@ -163,7 +163,7 @@ If the phase doesn't exist in the roadmap, report it and stop.
 
 **State file missing:**
 If calling `state_get` returns a `STATE_NOT_FOUND` error:
-1. Tell the user: "No Konductor project found. Run 'init' first."
+1. Tell the user: "No Konductor project found. Run 'spec' first."
 2. Stop
 
 **User provides insufficient input:**

package/skills/konductor-exec/SKILL.md

@@ -5,18 +5,19 @@ description: Execute the plans for a phase by spawning executor subagents. Use w
 
 # Konductor Exec — Phase Execution Pipeline
 
-You are the Konductor orchestrator. Execute the plans for a phase by spawning executor subagents to implement each plan.
+You are the Konductor orchestrator. Execute the plans for a phase by spawning executor subagents to implement each task.
 
 ## Critical Rules
 
 1. **Only YOU manage state transitions** — use the MCP tools (`state_get`, `state_transition`, `state_add_blocker`) instead of writing `state.toml` directly. Subagents write their own output files (summary files, result files).
-2. **Read config via MCP** — call `config_get` to get parallelism settings and git configuration.
-3. **Report errors, don't retry crashes** — if an executor fails, write an error result for that plan, continue with remaining plans, and report all failures at the end.
-4. **Resume support** — scan for existing summary files to skip completed plans.
+2. **Read config via MCP** — call `config_get` to get parallelism settings, git configuration, and feature flags.
+3. **Fresh executor per task** — spawn a new konductor-executor for each task. Do not reuse executors across tasks.
+4. **Resume support** — scan for existing per-task summary files to skip completed tasks. A task is complete only when its summary has `## Status: DONE` AND `## Review Status: passed`.
+5. **Circuit breaker** — if 3+ tasks in the phase are BLOCKED, stop execution and report to user.
 
 ## Step 1: Read State and Config
 
-Call the `state_get` MCP tool to read current state, and call the `config_get` MCP tool for execution settings (parallelism, git config).
+Call the `state_get` MCP tool to read current state, and call the `config_get` MCP tool for execution settings (parallelism, git config, feature flags).
 
 Validate that `[current].step` is either:
 - `"planned"` — ready to start execution
@@ -30,95 +31,147 @@ Then stop.
 
 Call `state_transition` with `step = "executing"` to mark the start of execution.
 
-## Step 3: Load and Group Plans by Wave
+## Step 3: Load Plans, Extract Tasks, and Group by Wave
 
 Read all plan files from `.konductor/phases/{phase}/plans/`.
 
 For each plan file:
 1. Parse the TOML frontmatter (delimited by `+++` markers at start and end)
-2. Extract the `wave` field (required)
-3. Extract the `plan` field (plan number)
-4. Group plans by wave number
+2. Extract the `wave` field (required) and `plan` field (plan number)
+3. Parse the `## Tasks` section to extract individual tasks. Each task is a `### Task N` subsection. Record the task number and its content (action, files, verify, done criteria).
+4. Store the task list per plan: e.g., plan 1 has tasks [1, 2, 3], plan 2 has tasks [1, 2].
 
-**Wave ordering:** Plans execute in wave order (wave 1, then wave 2, etc.). Plans within a wave can execute in parallel if `max_wave_parallelism > 1`.
+Group plans by wave number. **Wave ordering:** Plans execute in wave order (wave 1, then wave 2, etc.). Plans within a wave can execute in parallel if `max_wave_parallelism > 1`.
 
 ## Step 4: Resume Check
 
-Scan `.konductor/phases/{phase}/plans/` for existing summary files.
+Scan `.konductor/phases/{phase}/plans/` for existing per-task summary files.
 
-**Summary file naming:** `{plan-number}-summary.md` (e.g., `001-summary.md`, `002-summary.md`)
+**Summary file naming:** `{plan-number}-task-{n}-summary.md` (e.g., `001-task-1-summary.md`, `001-task-2-summary.md`)
 
-For each plan:
-- If `{plan-number}-summary.md` exists, the plan is complete — skip it
-- If summary does not exist, the plan needs execution
+**Task completion definition:** A task is complete when BOTH conditions are met:
+1. Its summary file exists with `## Status: DONE`
+2. The summary contains `## Review Status: passed` (appended by the orchestrator after both review stages pass)
 
-Resume from the current wave with incomplete plans.
+**Plan completion:** A plan is complete when ALL its tasks are complete.
+
+**Resume logic:**
+- Find the first incomplete task in the first incomplete plan of the current wave
+- If a task has a summary with `NEEDS_CONTEXT` or `BLOCKED` status, report it to the user before resuming
+- Resume execution from that task
 
 ## Step 5: Wave Execution Loop
 
 For each wave (in ascending order):
 
-### 5.1: Update Wave State
+### 5.1: Execute Plans in Wave
 
-Track the current wave number for reporting purposes.
+Read `config.toml` field `execution.max_wave_parallelism`:
 
-### 5.2: Execute Plans in Wave
+- **Parallel mode** (`max_wave_parallelism > 1`): Each plan's task sequence runs independently in parallel.
+- **Sequential mode** (`max_wave_parallelism = 1`): Execute plans one at a time within the wave.
 
-Read `config.toml` field `execution.max_wave_parallelism`:
+For each plan in the wave, execute its tasks sequentially:
+
+#### Per-Task Dispatch Loop
+
+For each task in the plan (sequential within a plan):
+
+**5.1.1 — Dispatch Executor**
+
+Spawn a fresh **konductor-executor** agent with:
+- The plan file path (absolute path)
+- The specific task number to execute
+- Summaries from prior completed tasks in this plan (for context)
+- Git configuration: `git.auto_commit` and `git.branching_strategy`
+- Reference to `references/execution-guide.md` (status protocol, deviation rules, commit protocol)
+- Reference to `references/tdd.md` if plan frontmatter `type = "tdd"`
+
+Wait for `{plan-number}-task-{n}-summary.md` to be written.
+
+**5.1.2 — Handle Implementer Status**
+
+Read the `## Status` field from the task summary and handle per the implementer status protocol (see `references/execution-guide.md`):
 
-**If `max_wave_parallelism > 1` (parallel mode):**
-- For each plan in this wave, spawn a **konductor-executor** agent simultaneously
-- Each executor receives:
-  - Its specific plan file path (absolute path)
-  - The git configuration: `git.auto_commit` and `git.branching_strategy`
-  - Reference to `references/execution-guide.md` (deviation rules, commit protocol, analysis paralysis guard)
-  - Reference to `references/tdd.md` if plan frontmatter `type = "tdd"`
-- Wait for ALL executors in the wave to complete (check for summary files)
+- **DONE** → proceed to two-stage review (Step 5.1.3)
+- **DONE_WITH_CONCERNS** → read `## Concerns`. If concerns mention correctness issues, security risks, or spec deviations (actionable) → dispatch executor to address them, then proceed to review. If concerns are informational → proceed to review.
+- **NEEDS_CONTEXT** → read `## Missing Context`, provide the information, re-dispatch executor with the context (max 2 retries). If still NEEDS_CONTEXT after 2 retries → treat as BLOCKED.
+- **BLOCKED** → read `## Blocker`. Assess: context problem → provide context and re-dispatch; task too complex → split into smaller tasks. If assessment fails or the task remains blocked after re-dispatch, call `state_add_blocker` with the blocker description. Track blocked count. If 3+ tasks in the phase have been BLOCKED, trigger circuit breaker: stop execution and report all blockers to user.
 
-**If `max_wave_parallelism = 1` (sequential mode):**
-- Execute plans one at a time within the wave
-- Spawn one executor, wait for completion, then spawn the next
+**5.1.3 — Two-Stage Review** (if `config.toml` `features.code_review = true`)
 
-**Executor completion check:**
-- A plan is complete when `{plan-number}-summary.md` exists
-- If an executor crashes or produces no summary, treat it as a failure (see Step 5.4)
+If `features.code_review` is false, skip reviews and mark task complete (append `## Review Status: passed` to the task summary).
 
-### 5.3: Write Result Files
+**Stage 1 — Spec Compliance Review:**
+Dispatch **konductor-spec-reviewer** agent with:
+- The task spec (the specific `### Task N` section from the plan file)
+- The task summary file (`{plan}-task-{n}-summary.md`)
+- The modified files listed in the summary
 
-After each plan completes (successfully or with errors), write `.konductor/.results/execute-{phase}-plan-{n}.toml`:
+The reviewer checks whether the implementation matches the task specification and writes findings to `{plan}-task-{n}-spec-review.md`.
+
+If the reviewer reports issues:
+1. Dispatch **konductor-executor** to fix the reported issues
+2. Re-run **konductor-spec-reviewer** to verify fixes
+3. Maximum 2 review-fix iterations. If still failing → log as needing manual intervention, continue to next task.
+
+**Stage 2 — Code Quality Review:**
+Dispatch **konductor-code-reviewer** agent with:
+- The task summary file
+- The modified files listed in the summary
+- Git diff for the task's changes
+
+The reviewer checks code quality (correctness, error handling, security, duplication, performance, dead code, consistency) and writes findings to `{plan}-task-{n}-quality-review.md`.
+
+If the reviewer reports issues:
+1. Dispatch **konductor-executor** to fix the reported issues
+2. Re-run **konductor-code-reviewer** to verify fixes
+3. Maximum 2 review-fix iterations. If still failing → log as needing manual intervention, continue to next task.
+
+**After both stages pass:** Append `## Review Status: passed` to the task summary file. Mark task complete.
+
+### 5.2: Write Result Files
+
+After each plan completes (all tasks done, successfully or with errors), write `.konductor/.results/execute-{phase}-plan-{n}.toml`:
 
 ```toml
 step = "execute"
 phase = "{phase}"
 plan = {plan_number}
 wave = {wave_number}
-status = "ok"  # or "error" if executor failed
+status = "ok"  # or "error" if any task failed
+tasks_total = {total_tasks}
+tasks_completed = {completed_tasks}
 timestamp = {current ISO timestamp}
 ```
 
-### 5.4: Error Handling
+### 5.3: Error Handling
 
 If an executor fails (crashes, times out, or reports errors):
 1. Write `.konductor/.results/execute-{phase}-plan-{n}.toml` with `status = "error"` and error details
-2. **Continue** with remaining plans in the wave (do not stop)
-3. Track failed plan numbers
-4. At the end of the wave, report which plans failed
+2. **Continue** with remaining tasks/plans in the wave (do not stop unless circuit breaker triggers)
+3. Track failed task numbers
+4. At the end of the wave, report which tasks failed
 
-**Do NOT retry failed executors automatically.** Let the user decide how to proceed.
+### 5.4: Update Progress Counters
 
-### 5.5: Update Progress Counters
+After each wave completes, track progress (completed tasks/plans count and percentage) for reporting.
 
-After each wave completes, track progress (completed plans count and percentage) for reporting.
-
-## Step 6: Code Review (if enabled)
+## Step 6: Code Review — Holistic Final Pass (if enabled)
 
 If `config.toml` `features.code_review = true`:
 
+Per-task reviews (spec compliance + code quality) have already been performed during execution. This phase-level code review is a **holistic final pass** checking cross-task consistency:
+- Shared interfaces match across plans (types, function signatures, API contracts)
+- Naming conventions are consistent across all modified files
+- Integration points work correctly (modules wire together properly)
+- No cross-plan duplication (shared logic extracted)
+
 Spawn a **konductor-code-reviewer** agent. Provide it with:
-- `.konductor/.tracking/modified-files.log` (list of changed files)
-- All `*-summary.md` files from `.konductor/phases/{phase}/plans/`
+- `.konductor/.tracking/modified-files.log` (list of all changed files)
+- All `*-task-*-summary.md` files from `.konductor/phases/{phase}/plans/`
 - The phase name and plan files for context
-- Instructions: review all modified source files, run tests and linting, do NOT fix any issues — only report them with file, line, description, and severity (minor/significant). Write findings to `.konductor/phases/{phase}/code-review.md`.
+- Instructions: focus on cross-task and cross-plan consistency, not individual task correctness (already reviewed). Write findings to `.konductor/phases/{phase}/code-review.md`.
 
 Wait for the reviewer to complete. Read `code-review.md`.
 
@@ -131,23 +184,24 @@ Wait for the reviewer to complete. Read `code-review.md`.
 
 ## Step 7: Set Executed State
 
-After code review completes (with no blocking issues), call `state_transition` with `step = "executed"` to advance the pipeline.
+After all execution and reviews complete (with no blocking issues), call `state_transition` with `step = "executed"` to advance the pipeline.
 
 Tell the user:
-- Total plans executed
-- Plans succeeded vs. failed (if any)
-- Code review findings (issues fixed, warnings reported)
+- Total plans and tasks executed
+- Tasks succeeded vs. failed (if any)
+- Per-task review results (spec + quality)
+- Phase-level code review findings (if enabled)
 - Next step suggestion: "Say 'next' to verify the phase."
 
-If any plans failed, list them and suggest:
-> "Review the errors in `.results/execute-{phase}-plan-{n}.toml` files. You can re-run individual plans or fix issues manually."
+If any tasks failed or need manual intervention, list them and suggest:
+> "Review the task summaries and review files in `.konductor/phases/{phase}/plans/`. You can re-run execution to retry incomplete tasks."
 
 ## Error Handling
 
 **Executor crashes:**
 If an executor subagent crashes:
 1. Write error result file for that plan
-2. Continue with remaining plans
+2. Continue with remaining tasks/plans
 3. Report the failure at the end of execution
 
 **State corruption:**