konductor 0.12.4 → 0.14.0

package/skills/konductor-plan/references/planning-guide.md

@@ -39,26 +39,80 @@ Plans execute in waves. Wave dependencies must form a DAG (directed acyclic grap
 
 ## Task Sizing
 
-Each plan contains 2-5 tasks. Each task should take 15-60 minutes of execution time.
+Each plan contains 2-5 tasks. Each task is broken into **bite-sized steps that take 2-5 minutes each**. Every step that involves code must include the actual code block — no prose descriptions of what to write.
 
 **If a plan would need more than 5 tasks:** Split it into multiple plans in the same wave.
 
 **Task structure:**
 - **files:** Which files to modify/create
-- **action:** What to do (be specific)
+- **action:** What to do — broken into numbered steps, each 2-5 minutes
 - **verify:** How to check success (command to run)
 - **done:** What "done" looks like (observable outcome)
 
-**Example task:**
+**Each step within a task must:**
+1. Be completable in 2-5 minutes
+2. Include the exact code to write (for code steps)
+3. Include the command to run (for verification steps)
+4. Be independently verifiable
+
+**Example task with bite-sized steps (TDD):**
 ```markdown
 ### Task 2: Add password hashing to User model
 
 - **files:** `src/models/user.rs`
-- **action:** Import bcrypt crate, add `hash_password` method to User impl, call it in `new` constructor
-- **verify:** `cargo test user::test_password_hashing`
-- **done:** Passwords are hashed with bcrypt before storage
+- **action:**
+  1. Write failing test:
+     ```rust
+     #[cfg(test)]
+     mod tests {
+         use super::*;
+
+         #[test]
+         fn test_password_is_hashed() {
+             let user = User::new("test@example.com".into(), "Secret123!".into()).unwrap();
+             assert_ne!(user.password_hash(), "Secret123!");
+             assert!(user.verify_password("Secret123!"));
+         }
+     }
+     ```
+  2. Run `cargo test user::tests::test_password_is_hashed` — confirm it fails (method not found)
+  3. Implement:
+     ```rust
+     use bcrypt::{hash, verify, DEFAULT_COST};
+
+     impl User {
+         pub fn new(email: String, password: String) -> Result<Self, AuthError> {
+             let password_hash = hash(&password, DEFAULT_COST)
+                 .map_err(|_| AuthError::HashError)?;
+             Ok(Self { id: Uuid::new_v4(), email, password_hash, created_at: Utc::now() })
+         }
+
+         pub fn password_hash(&self) -> &str { &self.password_hash }
+
+         pub fn verify_password(&self, password: &str) -> bool {
+             verify(password, &self.password_hash).unwrap_or(false)
+         }
+     }
+     ```
+  4. Run `cargo test user::tests::test_password_is_hashed` — confirm it passes
+- **verify:** `cargo test user::tests::test_password_is_hashed`
+- **done:** Passwords are hashed with bcrypt before storage, verified by test
 ```
 
+## No Placeholders
+
+Every step must contain the actual content an engineer needs to execute it. The **konductor-plan-checker** agent enforces this rule and will reject plans that violate it.
+
+**Banned patterns:**
+- `"TBD"`, `"TODO"`, `"implement later"`, `"fill in details"`
+- `"Add appropriate error handling"` / `"add validation"` / `"handle edge cases"` (show the actual error handling, validation, or edge case code)
+- `"Write tests for the above"` without actual test code (include the test code)
+- `"Similar to Task N"` (repeat the code — the engineer may be reading tasks out of order)
+- Steps that describe what to do without showing how (code blocks required for code steps)
+- References to types, functions, or methods not defined in any prior or current task
+
+**Rule:** If a step involves writing code, the step must include the code block. If a step involves running a command, the step must include the command. No exceptions.
+
 ## Plan File Format
 
 Each plan is a markdown file with TOML frontmatter and a structured body.
@@ -68,7 +122,7 @@ Each plan is a markdown file with TOML frontmatter and a structured body.
 - `plan`: Plan number within the phase (1, 2, 3...)
 - `wave`: Execution wave (1, 2, 3...)
 - `depends_on`: List of plan numbers this plan depends on (e.g., `[1, 2]`)
-- `type`: Either "execute" (standard implementation) or "tdd" (test-driven)
+- `type`: Either "tdd" (test-driven, default) or "execute" (standard implementation). Use `type = "execute"` to opt out of TDD for infrastructure, configuration, or documentation tasks. The planner must always emit an explicit `type` field.
 - `autonomous`: Boolean, true if executor can proceed without human input
 - `requirements`: List of REQ-XX identifiers this plan addresses
 - `files_modified`: List of files this plan will touch (helps with merge conflict prediction)
@@ -93,7 +147,7 @@ phase = "01-auth-system"
 plan = 1
 wave = 1
 depends_on = []
-type = "execute"
+type = "tdd"
 autonomous = true
 requirements = ["REQ-01", "REQ-02"]
 files_modified = ["src/models/user.rs", "src/db/migrations/001_users.sql"]
@@ -138,33 +192,120 @@ impl User {
 
 ## Tasks
 
-### Task 1: Create User struct
+### Task 1: Create User struct with tests
 
 - **files:** `src/models/user.rs`
-- **action:** Define User struct with fields: id (UUID), email (String), password_hash (String), created_at (DateTime)
-- **verify:** `cargo check` passes
-- **done:** User struct compiles
+- **action:**
+  1. Write failing test:
+     ```rust
+     #[cfg(test)]
+     mod tests {
+         use super::*;
+
+         #[test]
+         fn test_new_user_has_correct_email() {
+             let user = User::new("test@example.com".into(), "Secret123!".into()).unwrap();
+             assert_eq!(user.email, "test@example.com");
+         }
+
+         #[test]
+         fn test_new_user_has_uuid() {
+             let user = User::new("test@example.com".into(), "Secret123!".into()).unwrap();
+             assert!(!user.id.is_nil());
+         }
+     }
+     ```
+  2. Run `cargo test models::user::tests` — confirm it fails (User not defined)
+  3. Implement:
+     ```rust
+     use chrono::{DateTime, Utc};
+     use uuid::Uuid;
+
+     pub struct User {
+         pub id: Uuid,
+         pub email: String,
+         password_hash: String,
+         pub created_at: DateTime<Utc>,
+     }
+
+     impl User {
+         pub fn new(email: String, password: String) -> Result<Self, AuthError> {
+             Ok(Self {
+                 id: Uuid::new_v4(),
+                 email,
+                 password_hash: password, // placeholder — next task adds hashing
+                 created_at: Utc::now(),
+             })
+         }
+     }
+     ```
+  4. Run `cargo test models::user::tests` — confirm both tests pass
+- **verify:** `cargo test models::user::tests`
+- **done:** User struct compiles and passes basic tests
 
 ### Task 2: Add password hashing
 
 - **files:** `src/models/user.rs`
-- **action:** Import bcrypt, add `hash_password` method, call in constructor
-- **verify:** `cargo test user::test_password_hashing`
-- **done:** Passwords are hashed before storage
+- **action:**
+  1. Add failing test:
+     ```rust
+     #[test]
+     fn test_password_is_hashed_not_plaintext() {
+         let user = User::new("test@example.com".into(), "Secret123!".into()).unwrap();
+         assert_ne!(user.password_hash, "Secret123!");
+     }
+
+     #[test]
+     fn test_verify_correct_password() {
+         let user = User::new("test@example.com".into(), "Secret123!".into()).unwrap();
+         assert!(user.verify_password("Secret123!"));
+     }
+
+     #[test]
+     fn test_verify_wrong_password() {
+         let user = User::new("test@example.com".into(), "Secret123!".into()).unwrap();
+         assert!(!user.verify_password("WrongPass1!"));
+     }
+     ```
+  2. Run `cargo test models::user::tests` — confirm new tests fail
+  3. Update `User::new` and add `verify_password`:
+     ```rust
+     use bcrypt::{hash, verify, DEFAULT_COST};
+
+     impl User {
+         pub fn new(email: String, password: String) -> Result<Self, AuthError> {
+             let password_hash = hash(&password, DEFAULT_COST)
+                 .map_err(|_| AuthError::HashError)?;
+             Ok(Self { id: Uuid::new_v4(), email, password_hash, created_at: Utc::now() })
+         }
+
+         pub fn verify_password(&self, password: &str) -> bool {
+             verify(password, &self.password_hash).unwrap_or(false)
+         }
+     }
+     ```
+  4. Run `cargo test models::user::tests` — confirm all 5 tests pass
+- **verify:** `cargo test models::user::tests`
+- **done:** Passwords are hashed with bcrypt, verified by 3 new tests
 
 ### Task 3: Create migration
 
 - **files:** `src/db/migrations/001_users.sql`
-- **action:** Write CREATE TABLE users with columns matching User struct
-- **verify:** `sqlx migrate run` succeeds
-- **done:** users table exists in database
-
-### Task 4: Wire User model to auth routes
-
-- **files:** `src/routes/auth.rs`
-- **action:** Import User model, use it in registration handler
-- **verify:** Compilation succeeds, User is referenced
-- **done:** Registration route can create User instances
+- **action:**
+  1. Write the migration:
+     ```sql
+     CREATE TABLE users (
+         id UUID PRIMARY KEY,
+         email VARCHAR(255) NOT NULL UNIQUE,
+         password_hash VARCHAR(255) NOT NULL,
+         created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+     );
+
+     CREATE INDEX idx_users_email ON users (email);
+     ```
+  2. Run `sqlx migrate run` — confirm it succeeds
+- **verify:** `sqlx migrate run`
+- **done:** users table exists in database with email unique constraint
 ```
 
 ## Phase-Level Design Document
@@ -245,37 +386,71 @@ A requirement can span multiple plans. Example: "REQ-05: Users can manage their
 - Plan 3: View profile (requirements = ["REQ-05"])
 - Plan 4: Edit profile (requirements = ["REQ-05"])
 
-## TDD Detection
+## TDD as Default
+
+TDD is the default execution mode for all plans. The planner must always emit `type = "tdd"` unless the plan explicitly opts out.
 
-If a task can be expressed as "expect(fn(input)).toBe(output)", make it a TDD plan.
+**Backward compatibility:** Existing plans without an explicit `type` field are treated as `"execute"`. The planner must always emit an explicit `type` field going forward, making the default moot for well-formed plans.
 
-**Indicators:**
-- Pure functions (no I/O)
-- Clear input/output contract
-- Algorithmic logic (sorting, parsing, validation)
-- Data transformations
+**Opt-out with `type = "execute"`:** Use `type = "execute"` for tasks where TDD doesn't apply:
+- Infrastructure plans (SAM templates, Terraform, CI/CD configs)
+- Configuration files (TOML, YAML, JSON configs)
+- Documentation-only plans (README, guides, specs)
+- Refactoring plans where existing tests already cover the behavior
 
-**TDD plan differences:**
-- `type = "tdd"` in frontmatter
-- First task writes tests
-- Remaining tasks implement to pass tests
-- Verification is `cargo test` or equivalent
+**TDD task structure (RED → GREEN → REFACTOR):**
+1. **RED:** Write a failing test with the exact test code
+2. **Verify RED:** Run the test command — confirm it fails
+3. **GREEN:** Write the minimal implementation to pass the test
+4. **Verify GREEN:** Run the test command — confirm it passes
+5. **REFACTOR** (optional): Clean up while keeping tests green
 
 **Example TDD task:**
 ```markdown
-### Task 1: Write password validation tests
-
-- **files:** `src/validation/password_test.rs`
-- **action:** Write tests for: min 8 chars, has uppercase, has number, has special char
-- **verify:** Tests exist and fail
-- **done:** 4 test cases written
-
-### Task 2: Implement password validation
-
-- **files:** `src/validation/password.rs`
-- **action:** Write validate_password function to satisfy tests
-- **verify:** `cargo test validation::password` passes
-- **done:** All password validation tests pass
+### Task 1: Write password validation tests and implement
+
+- **files:** `src/validation/password.rs`, `src/validation/password_test.rs`
+- **action:**
+  1. Write failing tests:
+     ```rust
+     #[cfg(test)]
+     mod tests {
+         use super::validate_password;
+
+         #[test]
+         fn rejects_short_password() {
+             assert!(validate_password("Ab1!").is_err());
+         }
+
+         #[test]
+         fn rejects_no_uppercase() {
+             assert!(validate_password("abcdefg1!").is_err());
+         }
+
+         #[test]
+         fn rejects_no_number() {
+             assert!(validate_password("Abcdefgh!").is_err());
+         }
+
+         #[test]
+         fn accepts_valid_password() {
+             assert!(validate_password("Secret123!").is_ok());
+         }
+     }
+     ```
+  2. Run `cargo test validation::password` — confirm all 4 tests fail
+  3. Implement:
+     ```rust
+     pub fn validate_password(password: &str) -> Result<(), &'static str> {
+         if password.len() < 8 { return Err("too short"); }
+         if !password.chars().any(|c| c.is_uppercase()) { return Err("no uppercase"); }
+         if !password.chars().any(|c| c.is_numeric()) { return Err("no number"); }
+         Ok(())
+     }
+     ```
+  4. Run `cargo test validation::password` — confirm all 4 tests pass
+- **verify:** `cargo test validation::password`
+- **done:** Password validation passes all 4 test cases
 ```
 
 ## Interface Context
@@ -330,9 +505,13 @@ Before finalizing plans, verify:
 
 - [ ] Phase-level `design.md` exists with overview, components, interactions, key decisions, and shared interfaces
 - [ ] Every plan has valid TOML frontmatter
+- [ ] Every plan has an explicit `type` field (`"tdd"` or `"execute"`)
+- [ ] Plans default to TDD unless explicitly opted out (infra, config, docs)
 - [ ] Every plan has a `## Design` section with Approach, Key Interfaces, Error Handling, and Trade-offs
 - [ ] Wave numbers form a valid DAG (no cycles)
 - [ ] Each plan has 2-5 tasks
+- [ ] Each task has bite-sized steps (2-5 minutes each) with code blocks for code steps
+- [ ] No placeholder patterns (TBD, TODO, implement later, etc.)
 - [ ] Each task has files, action, verify, and done
 - [ ] Every requirement from requirements.md is covered
 - [ ] `must_haves` section is complete and observable

package/skills/konductor-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: konductor-review
+description: Review design and plans before execution. Use when the user says review, check design, review plans, or approve.
+---
+
+# Konductor Review — Design & Plan Review
+
+You are the Konductor orchestrator. Review the design and plans for a phase before execution.
+
+## Critical Rules
+
+1. **Only YOU manage state transitions** — use the MCP tools (`state_get`, `state_add_blocker`) instead of writing `state.toml` directly.
+2. **Read config via MCP** — call `config_get` to get feature flags (design_review).
+3. **Accept a phase argument** — the user may say "review phase 01". Resolve short form by scanning `.konductor/phases/` directories.
+
+## Step 1: Validate State
+
+Call the `state_get` MCP tool to read current state.
+
+Validate that `current.step` is `"planned"`. If not, tell the user:
+> "Phase {phase} is not ready for review. Current step: {step}. Run 'plan' first."
+Then stop.
+
+## Step 2: Design Review (if enabled)
+
+If `config.toml` `features.design_review = true`:
+
+Use the **konductor-design-reviewer** agent to review the technical design. Provide it with:
+- `.konductor/phases/{phase}/design.md`
+- All plan files in `.konductor/phases/{phase}/plans/`
+- `.konductor/requirements.md`
+- `.konductor/roadmap.md` (phase goal and success criteria)
+- `.konductor/project.md` (tech stack and constraints)
+- Instructions: analyze the phase design and per-plan Design sections, then write a structured review to `.konductor/phases/{phase}/review.md`
+
+**Review criteria the agent must evaluate:**
+1. Architectural soundness of design.md — do the components and interactions make sense?
+2. Feasibility of per-plan Design sections — are the proposed interfaces and approaches realistic?
+3. Cross-plan consistency — do shared interfaces match across plans that depend on each other?
+4. Requirement coverage — every REQ-XX for this phase is addressed
+5. Risk identification — missing error handling, security concerns, dependency issues
+
+**Review output format** (written to `.konductor/phases/{phase}/review.md`):
+```markdown
+# Design Review: Phase {phase}
+
+## Summary
+{one paragraph overall assessment}
+
+## Verdict: {pass | revise | reject}
+
+## Issues
+
+### Issue 1: {title}
+- **Severity:** critical | warning | info
+- **Affected plan:** {plan number or "design.md"}
+- **Description:** {what's wrong}
+- **Suggestion:** {how to fix}
+
+## Strengths
+{what the design does well}
+```
+
+Wait for the reviewer to complete. Verify `review.md` was created.
+
+**If verdict is "pass":** Proceed to Step 3.
+
+**If verdict is "revise"** (has critical or warning issues):
+1. Spawn a new **konductor-planner** agent with the review feedback as additional context
+2. Instruct it to revise `design.md` and the affected plans in-place
+3. Re-run the **konductor-design-reviewer**
+4. Maximum 2 review-revise iterations. If still "revise" after 2 iterations, proceed to user approval with warnings noted.
+
+**If verdict is "reject":** Stop. Tell the user:
+> "Design rejected by reviewer. See `.konductor/phases/{phase}/review.md` for details. Fix the fundamental issues and re-run design."
+
+## Step 3: User Approval
+
+Present the review summary to the user. Ask:
+> "Approve plans for execution? (approve / reject)"
+
+- **On approve:** Tell the user: "Plans approved. Say 'next' to execute, or 'exec' to start execution."
+- **On reject:** Tell the user: "Plans not approved. Edit the plans in `.konductor/phases/{phase}/plans/` or re-run design."
+
+If `features.design_review = false`: skip the automated review and go straight to user approval, presenting a summary of the plans instead.
+
+## Error Handling
+
+If the reviewer subagent fails:
+1. Call `state_add_blocker` MCP tool with the phase and reason for the failure
+2. Report failure to user with actionable context

package/skills/{konductor-init → konductor-spec}/SKILL.md

@@ -1,20 +1,20 @@
 ---
-name: konductor-init
-description: Initialize a new Konductor project with spec-driven development. Use when the user says init, initialize, new project, start project, set up konductor, or bootstrap.
+name: konductor-spec
+description: Define project requirements and generate spec documents. Use when the user says spec, define requirements, new project, start project, set up konductor, or bootstrap.
 ---
 
-# Konductor Init — Project Initialization
+# Konductor Spec — Project Requirements
 
-You are the Konductor orchestrator. Initialize a new spec-driven development project.
+You are the Konductor orchestrator. Define project requirements and generate spec documents.
 
 ## Step 1: Check Existing State
 
 Check if `.konductor/` directory already exists.
 - If it exists, call the `state_get` MCP tool. If it returns valid state:
-  - If `current.step` is `"shipped"`: ask the user: "Project is shipped. Do you want to (a) add a new phase to the existing project, or (b) reinitialize from scratch?"
+  - If `current.step` is `"shipped"`: ask the user: "Project is shipped. Do you want to (a) add a new phase to the existing project, or (b) re-spec from scratch?"
     - If (a): ask for the new phase name. Read `.konductor/roadmap.md` to determine the updated `phases_total`. Call the `state_advance_phase` MCP tool with the new phase identifier and updated phases_total. Skip to Step 8 (report success).
-    - If (b): proceed with normal reinitialization below.
-  - Otherwise: warn the user: "A Konductor project already exists here. Reinitializing will overwrite project.md, requirements.md, and roadmap.md. Proceed? (y/n)"
+    - If (b): proceed with normal re-spec below.
+  - Otherwise: warn the user: "A Konductor project already exists here. Re-speccing will overwrite project.md, requirements.md, and roadmap.md. Proceed? (y/n)"
 - If user declines, stop.
 
 ## Step 2: Create Directory Structure
@@ -64,7 +64,7 @@ Call the `state_init` MCP tool with:
 - `phase`: the first phase identifier from the roadmap
 - `phases_total`: the total number of phases from the roadmap
 
-This creates `.konductor/state.toml` with the correct initial structure.
+This creates `.konductor/state.toml` with step `specced`.
 
 Call the `config_init` MCP tool to create `.konductor/config.toml` with defaults.
 
@@ -80,4 +80,4 @@ Create/update `.kiro/steering/` files:
 Tell the user:
 - How many phases were identified in the roadmap
 - List the phase names
-- Suggest: "Say 'next' to start planning phase 1, or 'discuss phase 01' to set preferences first."
+- Suggest: "Say 'next' to start designing phase 1, or 'discuss phase 01' to set preferences first."

package/skills/konductor-status/SKILL.md

@@ -19,7 +19,7 @@ Call the `status` MCP tool. This returns a structured JSON report with:
 - `next_suggestion`
 
 If the tool returns a `STATE_NOT_FOUND` error, tell the user:
-> "No Konductor project found. Run 'init' to initialize a project."
+> "No Konductor project found. Run 'spec' to initialize a project."
 
 Then stop.
 
@@ -90,13 +90,14 @@ Last activity: {last_activity_relative} ({last_activity_absolute})
 - · = pending
 
 **Next step suggestions by current step:**
-- `initialized` → "Say 'next' to start planning, or 'discuss phase {n}' to set preferences first."
-- `discussed` → "Say 'next' to begin planning phase {n}."
+- `specced` → "Say 'next' to start design, or 'discuss phase {n}' to set preferences first."
+- `discussed` → "Say 'next' to begin designing phase {n}."
+- `designed` → "Say 'next' to create execution plans."
 - `planned` → "Say 'exec' to execute the plans."
 - `executing` → "Execution in progress. Wait for completion or check logs."
 - `executed` → "Say 'next' to verify the phase."
 - `complete` → "Phase {n} complete. Say 'next' to move to phase {n+1}."
-- `shipped` → "All phases shipped. Add new phases to roadmap.md or say 'init' to start a new project."
+- `shipped` → "All phases shipped. Add new phases to roadmap.md or say 'spec' to start a new project."
 - `blocked` → "Resolve the blocker with `state_resolve_blocker`, then say 'next'."
 
 ## Error Handling
@@ -104,7 +105,7 @@ Last activity: {last_activity_relative} ({last_activity_absolute})
 **Missing state files:**
 If the `status` tool returns an error:
 1. Report the error
-2. Suggest running `init` to reinitialize (warn about overwriting)
+2. Suggest running `spec` to re-spec (warn about overwriting)
 
 **Empty results directory:**
 If `.konductor/.results/` is empty, that's normal for newly initialized projects — simply report no activity yet.