konductor 0.5.0 → 0.7.0

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

@@ -0,0 +1,265 @@
+# Planning Guide — Decomposing Phases into Execution Plans
+
+This guide helps you transform a phase goal into concrete, executable plans.
+
+## Core Philosophy: Vertical Slices
+
+**Prefer vertical slices over horizontal layers.**
+
+- **Bad (horizontal):** Plan 1 = data models, Plan 2 = API endpoints, Plan 3 = UI components
+- **Good (vertical):** Plan 1 = user registration (model + API + UI), Plan 2 = user login (model + API + UI)
+
+**Why vertical?**
+- Each plan delivers a working feature end-to-end
+- Plans can be executed in parallel (fewer dependencies)
+- Users can test functionality incrementally
+- Rollback is easier (one feature vs. broken layer)
+
+**When to use horizontal:**
+- Foundation work that everything depends on (database setup, auth middleware)
+- Cross-cutting concerns (logging, error handling)
+- Infrastructure (deployment, CI/CD)
+
+## Wave Assignment
+
+Plans execute in waves. Wave dependencies must form a DAG (directed acyclic graph).
+
+**Rules:**
+1. Plans with no dependencies → Wave 1
+2. Plans depending only on Wave 1 outputs → Wave 2
+3. Plans depending on Wave N outputs → Wave N+1
+4. A plan can depend on multiple waves; use the max wave number + 1
+
+**Goal:** Minimize wave count. More parallelism = faster execution.
+
+**Example:**
+- Wave 1: User model + migrations, Product model + migrations (parallel)
+- Wave 2: Auth middleware (depends on User), Shopping cart (depends on User + Product)
+- Wave 3: Checkout flow (depends on Shopping cart)
+
+## Task Sizing
+
+Each plan contains 2-5 tasks. Each task should take 15-60 minutes of execution time.
+
+**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)
+- **verify:** How to check success (command to run)
+- **done:** What "done" looks like (observable outcome)
+
+**Example task:**
+```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
+```
+
+## Plan File Format
+
+Each plan is a markdown file with TOML frontmatter and a structured body.
+
+**Frontmatter fields:**
+- `phase`: Phase identifier (e.g., "01-auth-system")
+- `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)
+- `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)
+- `must_haves.truths`: Observable truths that must be true when done
+- `must_haves.artifacts`: Files that must exist
+- `must_haves.key_links`: Wiring checks (A imports B, C calls D)
+
+**Complete example:**
+```markdown
++++
+phase = "01-auth-system"
+plan = 1
+wave = 1
+depends_on = []
+type = "execute"
+autonomous = true
+requirements = ["REQ-01", "REQ-02"]
+files_modified = ["src/models/user.rs", "src/db/migrations/001_users.sql"]
+
+[must_haves]
+truths = ["Users can register with email and password", "Passwords are hashed with bcrypt"]
+artifacts = ["src/models/user.rs", "src/db/migrations/001_users.sql"]
+key_links = ["User model imported by auth routes", "bcrypt used in user.rs"]
++++
+
+# Plan 01: User Model and Migrations
+
+## Goal
+Create the User data model and database schema to support user registration.
+
+## Tasks
+
+### Task 1: Create User struct
+
+- **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
+
+### 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
+
+### 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
+```
+
+## Goal-Backward Methodology
+
+Work backward from the phase goal to derive concrete requirements.
+
+**Steps:**
+1. **State the goal:** "Users can register with email and password"
+2. **Derive observable truths:**
+   - A user record exists in the database
+   - The password is hashed, not plaintext
+   - The registration endpoint returns success
+3. **Derive required artifacts:**
+   - `src/models/user.rs` (User struct)
+   - `src/db/migrations/001_users.sql` (users table)
+   - `src/routes/auth.rs` (registration endpoint)
+4. **Derive required wiring:**
+   - User model imported by auth routes
+   - bcrypt library used in User model
+   - Registration route calls User::new
+5. **Identify key links:**
+   - "User model imported by auth routes"
+   - "bcrypt used in user.rs"
+   - "POST /auth/register returns 201"
+
+Use these to populate the `must_haves` section of the plan frontmatter.
+
+## Requirement Coverage
+
+Every requirement from `.konductor/requirements.md` must appear in at least one plan's `requirements` field.
+
+**Check coverage:**
+1. List all REQ-XX identifiers from requirements.md
+2. Collect all `requirements` arrays from plan frontmatter
+3. Ensure every REQ-XX appears at least once
+4. If a requirement is missing, add a plan or extend an existing plan
+
+**Multi-plan requirements:**
+A requirement can span multiple plans. Example: "REQ-05: Users can manage their profile" might be split into:
+- Plan 3: View profile (requirements = ["REQ-05"])
+- Plan 4: Edit profile (requirements = ["REQ-05"])
+
+## TDD Detection
+
+If a task can be expressed as "expect(fn(input)).toBe(output)", make it a TDD plan.
+
+**Indicators:**
+- Pure functions (no I/O)
+- Clear input/output contract
+- Algorithmic logic (sorting, parsing, validation)
+- Data transformations
+
+**TDD plan differences:**
+- `type = "tdd"` in frontmatter
+- First task writes tests
+- Remaining tasks implement to pass tests
+- Verification is `cargo test` or equivalent
+
+**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
+```
+
+## Interface Context
+
+When plans depend on each other, include interface definitions so executors don't need to explore the codebase.
+
+**Include in dependent plans:**
+- Type signatures
+- Function signatures
+- API contracts (request/response shapes)
+- Event names and payloads
+
+**Example:**
+```markdown
+## Dependencies
+
+This plan depends on Plan 1 (User model). Expected interface:
+
+```rust
+pub struct User {
+    pub id: Uuid,
+    pub email: String,
+    // password_hash is private
+}
+
+impl User {
+    pub fn new(email: String, password: String) -> Result<Self, Error>;
+    pub fn verify_password(&self, password: &str) -> bool;
+}
+```
+
+Use this interface in Task 2 when implementing the login handler.
+```
+
+## Anti-Patterns to Avoid
+
+**1. God plans:** A plan that touches 20+ files or has 10+ tasks. Split it.
+
+**2. Circular dependencies:** Plan A depends on Plan B, Plan B depends on Plan A. Use waves to break cycles.
+
+**3. Vague tasks:** "Set up authentication" is too vague. Be specific: "Add bcrypt to Cargo.toml", "Create User model", etc.
+
+**4. Missing verification:** Every task needs a `verify` command. "Manual testing" is not sufficient.
+
+**5. Underspecified must_haves:** "The feature works" is not an observable truth. Be concrete: "POST /auth/register returns 201 with user JSON".
+
+**6. Ignoring research:** If research.md exists, use it. Don't re-discover libraries or patterns.
+
+## Checklist for Completed Plans
+
+Before finalizing plans, verify:
+
+- [ ] Every plan has valid TOML frontmatter
+- [ ] Wave numbers form a valid DAG (no cycles)
+- [ ] Each plan has 2-5 tasks
+- [ ] Each task has files, action, verify, and done
+- [ ] Every requirement from requirements.md is covered
+- [ ] `must_haves` section is complete and observable
+- [ ] Dependent plans include interface context
+- [ ] File paths in `files_modified` are realistic
+- [ ] Verification commands are concrete (not "manual testing")
+- [ ] Plans prefer vertical slices over horizontal layers

package/skills/konductor-plan/references/verification-patterns.md

@@ -0,0 +1,400 @@
+# Verification Patterns — 3-Level Verification Framework
+
+This guide defines how to verify that phase execution actually achieved its goals, not just created files.
+
+## The Three Levels
+
+Verification proceeds in three increasingly rigorous levels:
+
+### Level 1: Exists
+**Question:** Is the artifact present?
+
+**Checks:**
+- File exists at expected path
+- Directory structure is correct
+- Database tables exist
+- API endpoints are defined
+
+**Commands:**
+```bash
+# File existence
+[ -f src/models/user.rs ] && echo "OK" || echo "MISSING"
+
+# Directory structure
+[ -d src/routes ] && [ -d src/models ] && echo "OK"
+
+# Database table (PostgreSQL)
+psql -d mydb -c "\dt users" | grep -q users && echo "OK"
+
+# API endpoint defined (grep for route definition)
+grep -r "POST.*auth/register" src/routes/ && echo "OK"
+```
+
+**When Level 1 fails:** The most basic requirement is unmet. Execution did not complete.
+
+### Level 2: Substantive
+**Question:** Is the artifact a real implementation, not a stub?
+
+**Checks:**
+- File has meaningful content (>minimum line count)
+- Not just comments or placeholders
+- No TODO/FIXME/PLACEHOLDER patterns
+- Contains expected code structures (functions, classes, exports)
+
+**Thresholds:**
+- Model files: >20 lines
+- Route handlers: >15 lines
+- Component files: >25 lines
+- Test files: >30 lines
+- Migration files: >10 lines
+
+**Anti-patterns to detect:**
+```rust
+// STUB: Not substantive
+pub struct User {
+    // TODO: implement fields
+}
+
+// REAL: Substantive
+pub struct User {
+    pub id: Uuid,
+    pub email: String,
+    password_hash: String,
+    created_at: DateTime<Utc>,
+}
+```
+
+**Commands:**
+```bash
+# Line count check (exclude comments)
+lines=$(grep -v '^[[:space:]]*#' src/models/user.rs | grep -v '^[[:space:]]*$' | wc -l)
+[ "$lines" -gt 20 ] && echo "OK" || echo "STUB"
+
+# TODO/FIXME detection
+grep -i 'TODO\|FIXME\|PLACEHOLDER\|STUB' src/models/user.rs && echo "INCOMPLETE"
+
+# Meaningful structure (has at least one pub fn)
+grep -q 'pub fn' src/models/user.rs && echo "OK"
+```
+
+**When Level 2 fails:** Execution created files but didn't implement them properly. This is common with autonomous executors that hit errors.
+
+### Level 3: Wired
+**Question:** Is the artifact connected to the rest of the system?
+
+**Checks:**
+- Imported by other files
+- Actually used (not just imported)
+- Part of the call graph
+- No orphaned code
+
+**Common wiring patterns:**
+
+**Component → API fetch:**
+```javascript
+// In component file
+import { fetchUsers } from '../api/users'
+// And uses it
+const users = await fetchUsers()
+```
+
+**API → Database query:**
+```python
+# In API handler
+from models.user import User
+# And uses it
+user = User.query.filter_by(email=email).first()
+```
+
+**Form → Handler:**
+```rust
+// In form component
+<form action="/auth/register" method="POST">
+// And in routes
+pub async fn register(form: Form<RegisterData>) -> Response
+```
+
+**State → Render:**
+```jsx
+// In state file
+export const userSlice = createSlice({ ... })
+// And in component
+import { selectUser } from '../store/userSlice'
+const user = useSelector(selectUser)
+```
+
+**Commands:**
+```bash
+# Check if User model is imported anywhere
+grep -r "use.*models::user" src/ --exclude-dir=models | wc -l
+
+# Check if User is actually used (not just imported)
+# Look for User:: or User.new or similar
+grep -r "User::\|User\.new\|User\.find" src/ | wc -l
+
+# Check bidirectional wiring (component imports API, API returns component data)
+grep -q "fetchUsers" src/components/UserList.tsx && \
+grep -q "export.*fetchUsers" src/api/users.ts && echo "WIRED"
+```
+
+**When Level 3 fails:** Execution implemented features but they're isolated. Integration work is missing.
+
+## Must-Haves Derivation
+
+Every plan should have a `must_haves` section in its frontmatter:
+
+```toml
+[must_haves]
+truths = [...]
+artifacts = [...]
+key_links = [...]
+```
+
+Verification uses these to determine what to check.
+
+### Option A: From Plan Frontmatter
+
+If the plan has a `must_haves` section, use it directly.
+
+**Example plan frontmatter:**
+```toml
+[must_haves]
+truths = ["Users can register with email", "Passwords are hashed"]
+artifacts = ["src/models/user.rs", "src/routes/auth.rs"]
+key_links = ["User imported by auth routes", "bcrypt used in user.rs"]
+```
+
+**Verification:**
+1. For each truth, derive a test (manual or automated)
+2. For each artifact, check Levels 1-3
+3. For each key_link, verify the connection exists
+
+### Option B: From Roadmap Success Criteria
+
+If the plan doesn't have `must_haves`, fall back to the phase's success criteria from `roadmap.md`.
+
+**Example roadmap:**
+```markdown
+## Phase 01: Authentication System
+
+Success criteria:
+- Users can register with email and password
+- Users can log in and receive a session token
+- Passwords are securely hashed
+```
+
+**Derive must_haves:**
+- **truths:** Each success criterion becomes a truth
+- **artifacts:** Infer from common patterns (User model, auth routes, migrations)
+- **key_links:** Infer from dependencies (auth routes use User model)
+
+### Option C: Goal-Backward Derivation
+
+If neither plan frontmatter nor roadmap success criteria are available, work backward from the phase goal.
+
+**Steps:**
+1. Read the phase goal from roadmap.md
+2. Ask: "What must be true for this goal to be achieved?"
+3. Ask: "What files must exist?"
+4. Ask: "How must those files be connected?"
+
+**Example:**
+- **Goal:** "Implement user authentication"
+- **Truths:** Users can register, Users can log in, Sessions are managed
+- **Artifacts:** User model, auth routes, session middleware
+- **Key links:** Auth routes import User, Middleware validates sessions
+
+## Gap Structuring
+
+When verification finds issues, structure them as "gaps" for the next planning cycle.
+
+**Gap format:**
+```toml
+[[gaps]]
+truth = "Users can register with email"
+status = "failed"
+reason = "Registration endpoint returns 500"
+artifacts = ["src/routes/auth.rs"]
+missing = ["Error handling", "Email validation"]
+```
+
+**Fields:**
+- `truth`: Which must_have truth failed
+- `status`: "failed" or "partial" or "incomplete"
+- `reason`: Specific error or issue
+- `artifacts`: Which files are involved
+- `missing`: What needs to be added/fixed
+
+**Write gaps to:** `.konductor/phases/{phase}/gaps.toml`
+
+The next planning cycle can read this file and create gap-closure plans.
+
+## Verification Commands by Language
+
+### Rust
+```bash
+# Compilation check
+cargo check
+
+# Test execution
+cargo test
+
+# Import check
+grep -r "use crate::models::User" src/
+
+# Usage check
+grep -r "User::" src/ | grep -v "^src/models/user.rs"
+```
+
+### Python
+```bash
+# Import check
+python -c "from models.user import User; print('OK')"
+
+# Test execution
+pytest tests/
+
+# Import usage
+grep -r "from models.user import" src/ | wc -l
+
+# Usage check
+grep -r "User(" src/ | grep -v "models/user.py"
+```
+
+### JavaScript/TypeScript
+```bash
+# Compilation check (TypeScript)
+npx tsc --noEmit
+
+# Test execution
+npm test
+
+# Import check
+grep -r "import.*from.*models/user" src/
+
+# Usage check
+grep -r "new User\|User\.find\|User\.create" src/
+```
+
+### Go
+```bash
+# Compilation check
+go build ./...
+
+# Test execution
+go test ./...
+
+# Import check
+grep -r "\"myapp/models\"" . | wc -l
+
+# Usage check
+grep -r "models\.User" . | grep -v "models/user.go"
+```
+
+## Example Verification Report
+
+A verification report should follow this structure:
+
+```markdown
+# Verification Report: Phase 01 — Authentication System
+
+**Status:** Issues Found
+**Date:** 2026-03-19
+**Plans Verified:** 3
+
+## Level 1: Exists ✓
+
+All expected artifacts are present:
+- ✓ src/models/user.rs
+- ✓ src/routes/auth.rs
+- ✓ src/db/migrations/001_users.sql
+- ✓ tests/auth_test.rs
+
+## Level 2: Substantive ✓
+
+All files contain real implementations:
+- ✓ User model has 45 lines, includes fields and methods
+- ✓ Auth routes have 67 lines, no TODOs
+- ✓ Migration file creates users table with all columns
+- ✓ Tests have 52 lines with 6 test cases
+
+## Level 3: Wired ⚠
+
+Issues found:
+- ⚠ User model is imported by auth routes (OK)
+- ⚠ Auth routes use User::new (OK)
+- ✗ Registration endpoint returns 500 error
+- ✗ No middleware validates session tokens
+
+## Gaps
+
+```toml
+[[gaps]]
+truth = "Users can register with email"
+status = "failed"
+reason = "POST /auth/register returns 500: database connection error"
+artifacts = ["src/routes/auth.rs", "src/db/connection.rs"]
+missing = ["Database connection pool initialization", "Error handling"]
+
+[[gaps]]
+truth = "Sessions are validated on protected routes"
+status = "incomplete"
+reason = "Session middleware exists but is not applied to routes"
+artifacts = ["src/middleware/session.rs", "src/main.rs"]
+missing = ["Apply middleware to protected routes"]
+```
+
+## Next Steps
+
+1. Run `konductor plan phase 01 --gaps` to create gap-closure plans
+2. Or manually fix: Initialize DB connection pool in main.rs
+3. Re-run verification after fixes
+```
+
+## Verification Automation
+
+Verification should be automated where possible.
+
+**Pattern: Verification script per plan**
+
+Create `.konductor/phases/{phase}/verify-plan-{n}.sh`:
+```bash
+#!/bin/bash
+set -e
+
+# Level 1: Exists
+[ -f src/models/user.rs ] || { echo "FAIL: user.rs missing"; exit 1; }
+
+# Level 2: Substantive
+lines=$(grep -v '^[[:space:]]*//' src/models/user.rs | grep -v '^[[:space:]]*$' | wc -l)
+[ "$lines" -gt 20 ] || { echo "FAIL: user.rs is stub"; exit 1; }
+
+# Level 3: Wired
+grep -q "User::" src/routes/auth.rs || { echo "FAIL: User not used in auth"; exit 1; }
+
+# Truth verification
+cargo test auth::test_register || { echo "FAIL: registration test failed"; exit 1; }
+
+echo "PASS: Plan 1 verified"
+```
+
+Then run: `bash .konductor/phases/{phase}/verify-plan-{n}.sh`
+
+## Verification vs. Testing
+
+**Testing** checks that code is correct (unit tests, integration tests).
+**Verification** checks that execution achieved the phase goal (end-to-end validation).
+
+**Testing:**
+- Runs during execution (per task)
+- Checks individual functions
+- Passes/fails per test case
+- Developer-focused
+
+**Verification:**
+- Runs after all plans execute
+- Checks the entire phase
+- Validates against must_haves
+- User-focused (does it deliver the feature?)
+
+**Both are necessary.** Tests catch bugs. Verification catches gaps.