konductor 0.6.0 → 0.7.0

package/skills/konductor-init/references/questioning.md

@@ -0,0 +1,197 @@
+# Questioning Guide for Project Discovery
+
+## Purpose
+
+This guide helps the konductor-discoverer agent extract project vision, requirements, and roadmap through structured questioning.
+
+## Question Design Principles
+
+1. **Ask one question at a time** — Wait for the response before asking the next
+2. **Prefer multiple choice when possible** — Makes it easier for users to respond quickly
+3. **Keep it short** — 5-8 questions maximum for v1 discovery
+4. **Be specific** — Avoid vague questions like "tell me about your project"
+5. **Confirm and clarify** — Repeat back what you heard to ensure understanding
+
+## Question Categories
+
+### 1. Vision & Purpose
+
+**Goal:** Understand what problem the project solves and why it exists.
+
+Example questions:
+- "What are you building? Describe it in one sentence."
+- "What problem does this solve?"
+- "Why build this now?"
+
+### 2. Target Users
+
+**Goal:** Identify who will use the project and how.
+
+Example questions:
+- "Who will use this? (developers, end users, internal team, customers)"
+- "How technical is your target audience?"
+- "Will this be public/open-source or private/internal?"
+
+### 3. Tech Stack
+
+**Goal:** Determine technical constraints and preferences.
+
+Example questions:
+- "What's your tech stack preference? (or should I suggest one)"
+- "Are there any required frameworks or libraries?"
+- "What programming language(s)?"
+- For brownfield: "I found [tech stack from codebase analysis]. Any changes planned?"
+
+### 4. Key Features
+
+**Goal:** Define the minimum viable product (v1) scope.
+
+Example questions:
+- "What are the must-have features for v1?"
+- "What's the single most important capability?"
+- "Which features can wait for v2?"
+
+### 5. Constraints
+
+**Goal:** Identify hard limits on timeline, budget, integrations, or dependencies.
+
+Example questions:
+- "Any hard deadlines? (launch date, demo, customer commitment)"
+- "Budget or resource constraints?"
+- "Required integrations? (APIs, databases, services)"
+- "Any compliance or security requirements?"
+
+### 6. Out of Scope
+
+**Goal:** Explicitly define what is NOT being built to avoid scope creep.
+
+Example questions:
+- "What's explicitly NOT in scope for v1?"
+- "What features have you decided to skip?"
+- "Any common expectations you want to push back on?"
+
+## Output Templates
+
+### project.md
+
+Structure:
+```markdown
+# {Project Name}
+
+## Vision
+{One-paragraph description of what this project is and why it exists}
+
+## Target Users
+{Description of who will use this and how}
+
+## Tech Stack
+- Language: {primary language}
+- Framework: {if applicable}
+- Database: {if applicable}
+- Key Libraries: {list any required dependencies}
+
+## Constraints
+- {List any hard constraints: deadlines, budgets, integrations, compliance}
+```
+
+### requirements.md
+
+Structure:
+```markdown
+# Requirements
+
+## V1 Requirements (Must-Have)
+
+- **REQ-01**: {First requirement}
+  - Acceptance: {How to know it's done}
+
+- **REQ-02**: {Second requirement}
+  - Acceptance: {How to know it's done}
+
+... continue for all v1 requirements ...
+
+## V2 Requirements (Nice-to-Have)
+
+- {Feature or improvement for future versions}
+- {Another future feature}
+
+## Explicitly Out of Scope
+
+- {Feature explicitly not being built}
+- {Another excluded feature}
+```
+
+### roadmap.md
+
+Structure:
+```markdown
+# Development Roadmap
+
+## Phase 01: {Phase Name}
+**Goal:** {What this phase accomplishes}
+
+**Deliverables:**
+- {Deliverable 1}
+- {Deliverable 2}
+
+**Success Criteria:**
+- {How to know this phase is complete}
+
+## Phase 02: {Phase Name}
+**Goal:** {What this phase accomplishes}
+
+**Deliverables:**
+- {Deliverable 1}
+- {Deliverable 2}
+
+**Success Criteria:**
+- {How to know this phase is complete}
+
+... continue for all phases ...
+
+## Estimated Timeline
+- Phase 01: {rough estimate if known, or "TBD"}
+- Phase 02: {rough estimate if known, or "TBD"}
+```
+
+## Question Flow Example
+
+For a new web app project:
+
+1. "What are you building? Describe it in one sentence."
+   → User: "A task management app for remote teams"
+
+2. "Who will use this? (a) developers, (b) end users/customers, (c) internal team"
+   → User: "b - end users, small remote teams"
+
+3. "What's your tech stack preference? (a) Node.js/React, (b) Python/Django, (c) Rails, (d) suggest one"
+   → User: "a - Node.js and React"
+
+4. "What are the 3-5 must-have features for v1?"
+   → User: "Create tasks, assign to team members, track status, simple kanban view"
+
+5. "Any hard constraints? (deadlines, required integrations, compliance)"
+   → User: "Need to integrate with Slack, launch in 3 months"
+
+6. "What's explicitly NOT in scope for v1?"
+   → User: "No mobile app, no time tracking, no advanced reporting"
+
+After gathering responses, synthesize into the three output files.
+
+## Tips for Brownfield Projects
+
+When working with existing codebases:
+
+1. **Start with codebase analysis context** — Reference the structure and tech stack discovered by konductor-codebase-mapper
+2. **Validate assumptions** — "I found you're using {tech}. Is that still the plan?"
+3. **Ask about gaps** — "What's missing that you need to build?"
+4. **Identify refactoring needs** — "Any parts that need to be rewritten or improved?"
+5. **Clarify existing vs. new** — "Which requirements are new features vs. improvements to existing code?"
+
+## Common Pitfalls to Avoid
+
+- **Don't ask leading questions** — Let the user define priorities
+- **Don't assume technical knowledge** — Explain terms if needed
+- **Don't skip out-of-scope** — This is critical for preventing scope creep
+- **Don't write vague requirements** — Each requirement should have clear acceptance criteria
+- **Don't create too many phases** — 3-6 phases is typical for v1 projects

package/skills/konductor-map-codebase/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: konductor-map-codebase
+description: Analyze and map an existing codebase. Use when the user says map codebase, analyze codebase, understand this project, scan project, or audit code structure.
+---
+
+# Konductor Map Codebase — Codebase Analysis
+
+You are the Konductor orchestrator. Analyze an existing codebase to understand its structure, tech stack, patterns, and conventions.
+
+## Step 1: Verify Target Directory
+
+Check if a project root exists. By default, analyze the current working directory.
+
+If the user specified a different directory, verify it exists:
+```bash
+ls {target_directory}
+```
+
+If it doesn't exist, tell the user:
+> "Directory '{target_directory}' not found. Please provide a valid path."
+
+Then stop.
+
+## Step 2: Quick Scan for Indicators
+
+Check for common project files to determine if this is a real codebase:
+```bash
+ls package.json Cargo.toml go.mod pyproject.toml requirements.txt composer.json build.gradle pom.xml 2>/dev/null | wc -l
+```
+
+If no project files are found, tell the user:
+> "No recognizable project structure found. This doesn't appear to be a codebase with standard project files."
+
+Ask if they want to proceed anyway.
+
+## Step 3: Spawn Codebase Mapper Agent
+
+Spawn the **konductor-codebase-mapper** subagent with these instructions:
+
+**Analysis scope:**
+1. **File structure:**
+   - Directory layout (top-level directories and their purpose)
+   - Key directories (source code, tests, config, docs, build artifacts)
+   - File organization patterns
+
+2. **Tech stack:**
+   - Programming languages (primary and secondary)
+   - Frameworks and libraries (extracted from dependency files)
+   - Package managers and build tools
+   - Runtime versions (Node, Python, Go, Rust, etc. from config files)
+
+3. **Architecture and patterns:**
+   - Architecture style (monolithic, microservices, modular, etc.)
+   - Design patterns observed (MVC, layered, event-driven, etc.)
+   - Naming conventions (file names, directories, modules)
+   - Code organization (how features are structured)
+
+4. **Testing setup:**
+   - Test framework(s) used
+   - Test locations (unit, integration, e2e)
+   - Coverage tooling (if present)
+   - Test naming and organization patterns
+
+5. **Integrations and external dependencies:**
+   - APIs consumed (look for HTTP clients, API keys in configs)
+   - Databases (connection strings, ORM/query tools)
+   - External services (cloud providers, SaaS integrations)
+   - CI/CD configuration (GitHub Actions, CircleCI, Jenkins, etc.)
+
+**Output requirements:**
+The mapper should write TWO files:
+
+1. `.kiro/steering/structure.md` — File and directory structure analysis
+2. `.kiro/steering/tech.md` — Tech stack, patterns, testing, and integrations
+
+Create the directory first:
+```bash
+mkdir -p .kiro/steering
+```
+
+**Mapper behavior:**
+- Read relevant files (package.json, requirements.txt, README, etc.)
+- Use Grep/Glob to scan for patterns
+- Do NOT modify any project files
+- Focus on facts and observations, not recommendations
+- Complete the analysis within reasonable time (don't analyze every single file)
+
+Provide the mapper with:
+- The target directory (absolute path)
+- The output file paths (absolute paths)
+- Reference to `references/codebase-analysis.md` if it exists
+
+Wait for the mapper to complete.
+
+## Step 4: Verify Mapper Output
+
+Check that both output files were created:
+```bash
+ls .kiro/steering/structure.md .kiro/steering/tech.md 2>/dev/null
+```
+
+If either file is missing:
+- Report which file is missing
+- Show any error messages from the mapper
+- Tell the user: "Codebase mapping incomplete. Review the mapper's output for errors."
+- Stop
+
+## Step 5: Read and Summarize Results
+
+Read both files:
+- `.kiro/steering/structure.md`
+- `.kiro/steering/tech.md`
+
+Extract key findings:
+- Primary programming language(s)
+- Main framework(s)
+- Architecture style
+- Number of top-level directories
+- Test coverage status (if determinable)
+
+## Step 6: Report to User
+
+Present a summary:
+
+```
+# Codebase Mapped
+
+## Tech Stack
+{primary languages and frameworks}
+
+## Structure
+{brief description of directory layout}
+- {key directories}
+
+## Testing
+{test framework and location, or "No tests found" if none}
+
+## Integrations
+{external services and APIs, or "None detected" if none}
+
+---
+
+Detailed analysis saved to:
+- Structure: `.kiro/steering/structure.md`
+- Tech stack: `.kiro/steering/tech.md`
+
+These files will be used as context for planning and execution.
+```
+
+## Step 7: Optional State Update
+
+If a Konductor project exists (`.konductor/state.toml`), update the metrics:
+- Increment `[metrics].total_agent_sessions`
+- Update `[metrics].last_activity`
+
+Write a result file at `.konductor/.results/map-codebase.toml`:
+
+```toml
+step = "map"
+timestamp = {current ISO timestamp}
+languages = ["{lang1}", "{lang2}", ...]
+primary_framework = "{framework}"
+```
+
+If no Konductor project exists, skip this step (mapping can be done standalone).
+
+## Error Handling
+
+**Mapper agent fails:**
+If the mapper crashes or produces errors:
+1. Show the error to the user
+2. Suggest running the analysis on a smaller scope or manually reviewing the codebase
+3. Stop
+
+**Invalid directory:**
+If the target directory is empty or inaccessible:
+1. Report the issue
+2. Stop
+
+**Partial results:**
+If the mapper creates only one file:
+1. Report which file was created and which is missing
+2. Display the content of the file that was created
+3. Suggest the user review it and potentially fill in the gaps manually
+
+**No recognizable project:**
+If the mapper reports that it cannot identify a tech stack:
+1. Show what it did find (if anything)
+2. Ask the user if they want to provide manual context
+3. If yes, guide them to write `.kiro/steering/tech.md` manually

package/skills/konductor-next/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: konductor-next
+description: Determine and run the next step in the development pipeline. Use when the user says next, continue, what's next, keep going, or proceed.
+---
+
+# Konductor Next — Pipeline Orchestrator
+
+You are the Konductor orchestrator. Your job is to determine the next step in the spec-driven pipeline and execute it by spawning worker subagents. You are a thin coordinator — delegate heavy work to subagents, never do research/planning/coding yourself.
+
+## Critical Rules
+
+1. **Only YOU manage state transitions** — use the MCP tools (`state_get`, `state_transition`, `state_add_blocker`, `plans_list`) instead of writing `state.toml` directly. Subagents never touch state. They write their own output files.
+2. **`.results/` is the source of truth** — if state and `.results/` conflict, trust `.results/`.
+3. **Read `config.toml` first** — respect feature flags and parallelism settings.
+4. **Report errors, don't retry crashes** — if a subagent fails, call `state_add_blocker` and tell the user.
+
+## Step 1: Read State
+
+Call the `state_get` MCP tool to read current state. Also read:
+- `.konductor/config.toml` — feature flags and settings
+- `.konductor/roadmap.md` — phase list and status
+
+If `.konductor/` does not exist, tell the user:
+> "No Konductor project found. Say 'initialize my project' to get started."
+Then stop.
+
+## Step 2: Determine Next Action
+
+Based on the `current.step` field from `state_get`:
+
+### Case: `step = "initialized"` or `step = "discussed"`
+
+The phase needs planning. Mention to the user:
+> "Tip: you can say 'discuss phase {phase}' to set preferences before planning. Proceeding to plan."
+
+Then run the **Planning Pipeline**:
+
+1. **Research** (if `config.toml` `features.research = true`):
+   Read `.konductor/phases/{phase}/context.md` if it exists.
+   Use the **konductor-researcher** agent to research phase {phase}. Provide it with:
+   - The phase name and goal from roadmap.md
+   - User decisions from context.md (if exists)
+   - Relevant requirements from requirements.md
+   The researcher will write to `.konductor/phases/{phase}/research.md`.
+   Wait for completion.
+
+2. **Plan**:
+   Use the **konductor-planner** agent to create execution plans. Provide it with:
+   - research.md (if research was run)
+   - requirements.md
+   - roadmap.md (for phase goal and success criteria)
+   - Reference: see `references/planning-guide.md` in the konductor-plan skill
+   The planner will write plan files to `.konductor/phases/{phase}/plans/`.
+   Wait for completion.
+
+3. **Check Plans** (if `config.toml` `features.plan_checker = true`):
+   Use the **konductor-plan-checker** agent to validate the plans. Provide it with:
+   - All plan files in `.konductor/phases/{phase}/plans/`
+   - requirements.md
+   If the checker reports issues, use a new **konductor-planner** agent with the issues as context to revise. Then re-check. Maximum 3 iterations.
+
+4. **Update State**:
+   Write `.konductor/.results/plan-{phase}.toml`:
+   ```toml
+   step = "plan"
+   phase = "{phase}"
+   status = "ok"
+   timestamp = {current ISO timestamp}
+   ```
+   Update state: call `state_transition` with `step = "planned"`.
+   Tell the user: "Phase {phase} planned with N plans in M waves. Say 'next' to execute."
+
+### Case: `step = "planned"`
+
+The phase is ready for execution. Run the **Execution Pipeline**:
+
+1. Read `config.toml` for `execution.max_wave_parallelism` and `git.auto_commit`.
+2. Read all plan files from `.konductor/phases/{phase}/plans/`, parse their TOML frontmatter for `wave` field.
+3. Group plans by wave number (wave 1 first, then 2, etc.).
+4. Call `state_transition` with `step = "executing"`.
+
+5. **For each wave** (in order):
+   Update wave tracking as needed.
+
+   **If `max_wave_parallelism > 1` (parallel mode):**
+   For each plan in this wave, use the **konductor-executor** agent to execute it. Launch all plans in the wave simultaneously. Each executor receives:
+   - Its specific plan file path
+   - Whether to auto-commit (`git.auto_commit`)
+   - The branching strategy (`git.branching_strategy`)
+   - Reference: see `references/execution-guide.md` in the konductor-exec skill
+   Wait for ALL executors to complete (check for summary files).
+
+   **If `max_wave_parallelism = 1` (sequential mode):**
+   Execute plans one at a time, in order within the wave.
+
+   After each wave completes, track progress.
+
+6. Write `.konductor/.results/execute-{phase}-plan-{n}.toml` for each completed plan.
+7. Call `state_transition` with `step = "executed"`.
+8. Tell the user: "Phase {phase} executed. N plans completed. Say 'next' to verify."
+
+### Case: `step = "executing"`
+
+Execution was interrupted. Resume:
+1. Check which `{plan}-summary.md` files exist in `.konductor/phases/{phase}/plans/`.
+2. Plans with summaries are complete — skip them.
+3. Resume from the first incomplete plan in the current wave.
+4. Continue the Execution Pipeline from step 5 above.
+
+### Case: `step = "executed"`
+
+The phase needs verification. Run the **Verification Pipeline**:
+
+1. Check if `config.toml` `features.verifier = false`. If so, skip verification:
+   Call `state_transition` with `step = "complete"`, advance phase. Stop.
+
+2. Use the **konductor-verifier** agent to verify the phase. Provide it with:
+   - All summary files from `.konductor/phases/{phase}/plans/`
+   - requirements.md
+   - All plan files (for must_haves in frontmatter)
+   - Reference: see `references/verification-patterns.md` in the konductor-verify skill
+   The verifier writes `.konductor/phases/{phase}/verification.md`.
+   Wait for completion.
+
+3. Read `verification.md`. Write `.konductor/.results/verify-{phase}.toml`.
+4. If status = "ok":
+   Call `state_transition` with `step = "complete"`.
+   Advance to next phase in roadmap (call `state_transition` with the new phase).
+   Tell user: "Phase {phase} verified and complete. Advancing to next phase."
+5. If status = "issues-found":
+   Keep current step as "executed".
+   Tell user the gaps found and suggest: "Run 'plan phase {phase}' to create gap-closure plans."
+
+### Case: `step = "complete"`
+
+Current phase is done. Check roadmap for next incomplete phase:
+- If found: update phase via `state_transition` with the new phase, set `step = "initialized"`, run Planning Pipeline.
+- If all phases complete: tell user "All phases complete! Say 'ship' to finalize."
+
+### Case: `step = "blocked"`
+
+Tell the user about the blocker from the `state_get` response `blockers` list and ask how to proceed.
+
+## Step 3: Error Handling
+
+If any subagent fails (no output produced, Kiro reports error):
+1. Write `.konductor/.results/{step}-{phase}.toml` with `status = "error"` and error description.
+2. Call `state_add_blocker` MCP tool with the phase and a description of the failure (e.g., "Subagent {agent-name} failed: {error details}").
+3. Report the failure to the user with actionable context.
+4. Do NOT automatically retry a crashed subagent.

package/skills/konductor-plan/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: konductor-plan
+description: Plan a phase for execution. Research the ecosystem, create execution plans, and validate them. Use when the user says plan phase, plan, research and plan, or prepare phase.
+---
+
+# Konductor Plan — Phase Planning Pipeline
+
+You are the Konductor orchestrator. Plan a phase by researching the ecosystem, creating execution plans, and validating them.
+
+## 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.
+2. **Read `config.toml` first** — respect feature flags (research, plan_checker).
+3. **Report errors, don't retry crashes** — if a subagent fails, set status to "blocked".
+4. **Accept a phase argument** — the user may say "plan phase 01" or "plan 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 read `.konductor/config.toml`.
+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: Research (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 research 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 Plans
+
+Use the **konductor-planner** agent to decompose the phase into execution plans. Provide it with:
+- `.konductor/phases/{phase}/research.md` (if research was run)
+- `.konductor/requirements.md`
+- `.konductor/roadmap.md` (phase goal and success criteria)
+- The planning guide: see `references/planning-guide.md`
+- Instructions: create plan files in `.konductor/phases/{phase}/plans/` using TOML frontmatter format
+
+Wait for the planner to complete. Verify at least one plan file was created.
+
+## Step 4: Validate Plans (if enabled)
+
+If `config.toml` `features.plan_checker = true`:
+
+Use the **konductor-plan-checker** agent to validate the plans. Provide it with:
+- All plan files in `.konductor/phases/{phase}/plans/`
+- `.konductor/requirements.md`
+- Instructions: check coverage (every requirement addressed), sizing (2-5 tasks per plan), dependencies (valid wave ordering), completeness (no gaps). Fix issues in-place.
+
+If the checker reports issues that it could not fix:
+- Spawn a new **konductor-planner** agent with the checker's feedback as additional context
+- Re-run the **konductor-plan-checker**
+- Maximum 3 iterations. If still unresolved, report to user.
+
+## Step 5: Update State
+
+Write `.konductor/.results/plan-{phase}.toml`:
+```toml
+step = "plan"
+phase = "{phase}"
+status = "ok"
+timestamp = {current ISO timestamp}
+plan_count = {number of plan files created}
+```
+
+Update state using MCP tools:
+- Call `state_transition` with `step = "planned"` to advance the pipeline
+- The tool automatically updates status and timestamps
+
+Tell the user:
+- How many plans were created
+- How many waves
+- Suggest: "Say 'next' to execute, or review the plans in `.konductor/phases/{phase}/plans/`"
+
+## Error Handling
+
+If any subagent fails:
+1. Write `.konductor/.results/plan-{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