konductor 0.6.0 → 0.7.0

package/agents/konductor-codebase-mapper.json

@@ -0,0 +1,8 @@
+{
+    "name": "konductor-codebase-mapper",
+    "description": "Analyzes existing codebases for brownfield projects. Maps file structure, tech stack, patterns, conventions, testing, and integrations.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [],
+    "prompt": ""
+}

package/agents/konductor-discoverer.json

@@ -0,0 +1,8 @@
+{
+    "name": "konductor-discoverer",
+    "description": "Interactive project discovery. Asks questions about vision, users, tech stack, and constraints. Generates project.md, requirements.md, and roadmap.md.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [],
+    "prompt": ""
+}

package/agents/konductor-executor.json

@@ -0,0 +1,13 @@
+{
+    "name": "konductor-executor",
+    "description": "Executes a single implementation plan. Writes code, runs tests, commits atomically per task. Follows deviation rules for auto-fixing bugs.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [
+        "file://.konductor/project.md",
+        "file://.konductor/requirements.md",
+        "file://.konductor/phases/*/plans/*.md",
+        "file://.kiro/steering/**/*.md"
+    ],
+    "prompt": ""
+}

package/agents/konductor-plan-checker.json

@@ -0,0 +1,11 @@
+{
+    "name": "konductor-plan-checker",
+    "description": "Validates execution plans for coverage, sizing, dependencies, and completeness. Fixes issues in-place.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [
+        "file://.konductor/requirements.md",
+        "file://.konductor/phases/*/plans/*.md"
+    ],
+    "prompt": ""
+}

package/agents/konductor-planner.json

@@ -0,0 +1,13 @@
+{
+    "name": "konductor-planner",
+    "description": "Decomposes phases into wave-ordered execution plans with task breakdowns, dependency graphs, and requirement tracing.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [
+        "file://.konductor/project.md",
+        "file://.konductor/requirements.md",
+        "file://.konductor/roadmap.md",
+        "file://.kiro/steering/**/*.md"
+    ],
+    "prompt": ""
+}

package/agents/konductor-researcher.json

@@ -0,0 +1,12 @@
+{
+    "name": "konductor-researcher",
+    "description": "Phase ecosystem research. Investigates libraries, patterns, risks, and best practices for a given phase.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [
+        "file://.konductor/project.md",
+        "file://.konductor/requirements.md",
+        "file://.kiro/steering/**/*.md"
+    ],
+    "prompt": ""
+}

package/agents/konductor-verifier.json

@@ -0,0 +1,12 @@
+{
+    "name": "konductor-verifier",
+    "description": "Post-execution verification. Performs 3-level check (exists, substantive, wired) on all artifacts and key links.",
+    "tools": ["read", "write", "shell", "code"],
+    "allowedTools": ["read", "write", "shell", "code"],
+    "resources": [
+        "file://.konductor/requirements.md",
+        "file://.konductor/phases/*/plans/*.md",
+        "file://.kiro/steering/**/*.md"
+    ],
+    "prompt": ""
+}

package/agents/konductor.json

@@ -0,0 +1,25 @@
+{
+    "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.",
+    "tools": ["read", "write", "shell", "code", "@konductor"],
+    "allowedTools": ["read", "write", "shell", "code", "@konductor"],
+    "resources": [
+        "skill://.kiro/skills/konductor-*/SKILL.md",
+        "file://.kiro/steering/**/*.md",
+        "file://.konductor/config.toml",
+        "file://.konductor/roadmap.md"
+    ],
+    "toolsSettings": {
+        "subagent": {
+            "availableAgents": ["konductor-*"],
+            "trustedAgents": ["konductor-*"]
+        }
+    },
+    "mcpServers": {
+        "konductor": {
+            "command": "konductor",
+            "args": ["mcp"]
+        }
+    },
+    "prompt": "Use the konductor MCP tools (state_init, state_get, state_transition, state_add_blocker, state_resolve_blocker, plans_list, status) for all state management instead of reading/writing state.toml directly."
+}

package/hooks/konductor-hooks.json

@@ -0,0 +1,16 @@
+{
+    "hooks": [
+        {
+            "event": "PostToolUse",
+            "matcher": "write",
+            "command": "konductor hook",
+            "timeout_ms": 2000
+        },
+        {
+            "event": "PreToolUse",
+            "matcher": "shell",
+            "command": "konductor hook",
+            "timeout_ms": 1000
+        }
+    ]
+}

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "konductor",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Spec-driven development orchestrator for Kiro CLI — MCP server and hook processor",
   "bin": {
     "konductor": "bin/konductor"
   },
+  "files": [
+    "bin/",
+    "scripts/",
+    "agents/",
+    "skills/",
+    "hooks/",
+    "README.md"
+  ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js"
   },

package/scripts/postinstall.js

@@ -71,6 +71,44 @@ async function main() {
   fs.writeFileSync(dest, binary);
   fs.chmodSync(dest, 0o755);
   console.log("konductor binary installed.");
+
+  // Install agents, skills, and hooks to ~/.kiro/
+  installKiroAssets();
+}
+
+function copyDirSync(src, dest, force) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath, force);
+    } else if (force || !fs.existsSync(destPath)) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function installKiroAssets() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) return;
+  const kiroDir = path.join(home, ".kiro");
+  const pkgRoot = path.join(__dirname, "..");
+
+  const assets = [
+    { src: "agents", dest: "agents" },
+    { src: "skills", dest: "skills" },
+    { src: "hooks", dest: "hooks" },
+  ];
+
+  for (const { src, dest } of assets) {
+    const srcDir = path.join(pkgRoot, src);
+    if (fs.existsSync(srcDir)) {
+      copyDirSync(srcDir, path.join(kiroDir, dest), false);
+      console.log(`Installed ${src} to ${path.join(kiroDir, dest)}`);
+    }
+  }
 }
 
 main().catch((err) => {

package/skills/konductor-discuss/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: konductor-discuss
+description: Discuss and set context for a phase before planning. Use when the user says discuss phase, talk about phase, set phase context, phase preferences, or discuss decisions.
+---
+
+# Konductor Discuss — Phase Context and Decision Setting
+
+You are the Konductor orchestrator. Have a conversation with the user to establish context, preferences, and decisions for a specific phase before planning begins.
+
+## Step 1: Parse Phase Argument
+
+The user will provide a phase identifier (e.g., "discuss phase 01", "discuss phase 2", "talk about authentication").
+
+Extract the phase number or name from the request.
+
+If no phase is specified, ask the user:
+> "Which phase would you like to discuss? (Provide a phase number or name)"
+
+Wait for their response.
+
+## Step 2: Read Phase Information
+
+Read `.konductor/roadmap.md` to find the specified phase.
+
+For the target phase, extract:
+- Phase number
+- Phase name
+- Goal/purpose
+- Scope description
+- Success criteria (if defined)
+
+If the phase is not found in the roadmap, tell the user:
+> "Phase '{phase}' not found in roadmap. Say 'status' to see all phases."
+
+Then stop.
+
+## Step 3: Present Phase Context
+
+Display the phase information to the user:
+
+```
+# Discussing Phase {number}: {name}
+
+## Goal
+{goal from roadmap}
+
+## Scope
+{scope from roadmap}
+
+{if success criteria exist}
+## Success Criteria
+{criteria from roadmap}
+{/if}
+
+Let's discuss how we should approach this phase.
+```
+
+## Step 4: Interactive Discussion
+
+Ask the user a series of questions to gather context and preferences. Adapt questions to the phase goal, but generally cover:
+
+1. **Approach preferences:**
+   - "What approach would you prefer for {phase goal}? (e.g., incremental vs. all-at-once, TDD vs. implementation-first)"
+
+2. **Library and tool choices:**
+   - "Are there specific libraries, frameworks, or tools you want to use for this phase?"
+   - "Any libraries or approaches you want to avoid?"
+
+3. **Architectural trade-offs:**
+   - "What's more important for this phase: performance, simplicity, maintainability, or something else?"
+
+4. **Known constraints:**
+   - "Are there any constraints we should keep in mind? (e.g., existing APIs to integrate with, backward compatibility, deployment limitations)"
+
+5. **Scope boundaries:**
+   - "Is there anything explicitly out of scope for this phase that we should defer to later?"
+
+**Conversation style:**
+- Ask questions one at a time or in small groups
+- Wait for user responses
+- Ask follow-up questions if answers are vague
+- Acknowledge their input and summarize understanding
+- Keep the conversation focused on decisions that will affect planning
+
+This is a natural conversation — not a rigid questionnaire. Adapt based on the user's responses.
+
+## Step 5: Write Decisions to Context File
+
+After gathering sufficient context, write the decisions to `.konductor/phases/{phase}/context.md`.
+
+**File structure:**
+
+```markdown
+# Phase {number}: {name} — Context
+
+Discussed: {current date}
+
+## Phase Goal
+{goal from roadmap}
+
+## Decisions
+
+### Decision 1: {title}
+**Choice:** {what was decided}
+**Rationale:** {why this choice was made}
+
+### Decision 2: {title}
+**Choice:** {what was decided}
+**Rationale:** {why this choice was made}
+
+{repeat for all decisions}
+
+## Constraints
+{list any constraints mentioned by the user}
+
+## Out of Scope
+{list anything explicitly deferred or excluded from this phase}
+
+## Preferred Libraries/Tools
+{list specific libraries or tools to use}
+
+## Avoid
+{list anything the user wants to avoid}
+```
+
+Create the phase directory if it doesn't exist:
+```bash
+mkdir -p .konductor/phases/{phase}
+```
+
+## Step 6: Update State
+
+Call the `state_transition` MCP tool with `step = "discussed"` to advance the pipeline state.
+If the transition fails (e.g., the current phase doesn't match), the tool will return an error — report it to the user.
+
+Write a result file at `.konductor/.results/discuss-{phase}.toml`:
+
+```toml
+step = "discuss"
+phase = "{phase}"
+timestamp = {current ISO timestamp}
+decisions_count = {number of decisions recorded}
+```
+
+## Step 7: Confirm with User
+
+Tell the user:
+
+```
+# Phase Context Set
+
+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.
+```
+
+## Error Handling
+
+**Phase not found:**
+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."
+2. Stop
+
+**User provides insufficient input:**
+If the user gives very brief or unclear answers:
+- Ask clarifying follow-up questions
+- Offer examples or options to help them decide
+- Don't proceed until you have enough context to write meaningful decisions
+
+**No decisions made:**
+If the conversation ends without any concrete decisions:
+- Summarize what was discussed
+- Ask if the user wants to proceed with default approaches
+- If yes, write a minimal context file noting "default approach" for key decisions

package/skills/konductor-exec/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: konductor-exec
+description: Execute the plans for a phase by spawning executor subagents. Use when the user says execute phase, exec, run phase, build phase, or implement.
+---
+
+# Konductor Exec — Phase Execution Pipeline
+
+You are the Konductor orchestrator. Execute the plans for a phase by spawning executor subagents to implement each plan.
+
+## 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.toml` first** — respect 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.
+
+## Step 1: Read State and Config
+
+Call the `state_get` MCP tool to read current state, and read `.konductor/config.toml` for execution settings (parallelism, git config).
+
+Validate that `[current].step` is either:
+- `"planned"` — ready to start execution
+- `"executing"` — resuming interrupted execution
+
+If the phase is not in one of these states, tell the user:
+> "Phase {phase} is not ready for execution. Current step: {step}. Run 'plan phase {phase}' first."
+Then stop.
+
+## Step 2: Set Executing State
+
+Call `state_transition` with `step = "executing"` to mark the start of execution.
+
+## Step 3: Load and Group Plans 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
+
+**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.
+
+**Summary file naming:** `{plan-number}-summary.md` (e.g., `001-summary.md`, `002-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
+
+Resume from the current wave with incomplete plans.
+
+## Step 5: Wave Execution Loop
+
+For each wave (in ascending order):
+
+### 5.1: Update Wave State
+
+Track the current wave number for reporting purposes.
+
+### 5.2: Execute Plans in Wave
+
+Read `config.toml` field `execution.max_wave_parallelism`:
+
+**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)
+
+**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
+
+**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)
+
+### 5.3: Write Result Files
+
+After each plan completes (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
+timestamp = {current ISO timestamp}
+```
+
+### 5.4: 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
+
+**Do NOT retry failed executors automatically.** Let the user decide how to proceed.
+
+### 5.5: Update Progress Counters
+
+After each wave completes, track progress (completed plans count and percentage) for reporting.
+
+## Step 6: Set Executed State
+
+After all waves complete, call `state_transition` with `step = "executed"` to advance the pipeline.
+
+Tell the user:
+- Total plans executed
+- Plans succeeded vs. failed (if any)
+- 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."
+
+## Error Handling
+
+**Executor crashes:**
+If an executor subagent crashes:
+1. Write error result file for that plan
+2. Continue with remaining plans
+3. Report the failure at the end of execution
+
+**State corruption:**
+If `state_get` returns malformed data or plan files are malformed:
+1. Report the specific parsing error
+2. Stop execution
+3. Do NOT attempt to fix state automatically
+
+**Missing plan files:**
+If a plan referenced in the state doesn't exist:
+1. Report the missing plan number
+2. Skip that plan
+3. Continue with remaining plans