Skip to content

Latest commit

 

History

History
89 lines (70 loc) · 4.32 KB

README.md

File metadata and controls

89 lines (70 loc) · 4.32 KB

Karl Implementation Plans

Generated by the improve advisor workflow on 2026-07-11 at commit 1ab5a69. These plans turn Karl's product-direction discussion into durable, executor-ready work. Execute in dependency order. Every executor must read its plan fully, honor STOP conditions, run all verification gates, and update its status row.

The issue tracker should become the authoritative status surface after Plan 001 is implemented. Until then, this index is the durable local queue.

Execution order and status

Plan Title Priority Effort Depends on Status
001 Establish durable product and work governance P1 M — DONE
002 Add a crash-safe, inspectable run journal P1 L 001 DONE
003 Execute one validated evidence-led run recipe P1 L 001, 002 DONE
004 Make context packs inspectable and reproducible P2 M 001, 002 DONE
005 Add progressive-disclosure run inspection P2 M 002 DONE
006 Add explicit, reproducible model comparisons P3 L 002, 004 DONE

Status values: TODO, IN PROGRESS, DONE, BLOCKED: <reason>, or REJECTED: <reason>.

Dependency notes

  • 001 establishes stable product/non-goal language, tracker states, and the repository-owned workflow contract used by every later plan.
  • 002 is the operational foundation. Recipes, context linkage, UX, and comparisons must consume one event journal rather than create parallel logs.
  • 003 is the first execution tracer bullet. Do not add more recipes until its worktree, gate, verification, and handoff behavior has been reviewed in use.
  • 004 can proceed alongside 003 after 002. It resolves the current split between Karl metadata and Ivo context content.
  • 005 deliberately follows 002 because terminal output is a projection of the journal, not a second source of truth.
  • 006 follows 004 so comparisons can prove they used identical context.

Suggested issue mapping

After Plan 001 installs the issue template and lifecycle, create one issue per plan. Copy the plan's Why, Scope, Done criteria, dependencies, and STOP conditions into the issue; link back to the plan file. Do not duplicate changing status in roadmap Markdown.

Symphony concepts adopted

The plans selectively borrow from the OpenAI Symphony service specification:

  • repository-owned workflow policy;
  • explicit work item, attempt, workspace, and live-session concepts;
  • isolated persistent workspaces;
  • one authority for lifecycle transitions;
  • typed failure/terminal reasons, bounded retries, and reconciliation;
  • structured, operator-visible observability;
  • successful execution may hand off to human review rather than imply Done.

Reference: https://github.com/openai/symphony/blob/main/SPEC.md

Considered and rejected for this sequence

  • Long-running polling daemon: premature; first prove one manually invoked, recoverable recipe and its operating contract.
  • General DAG/workflow engine: conflicts with Karl's slim product thesis; one typed recipe is enough to test the architecture.
  • Automatic workspace cleanup: rejected after the 2026-07-11 recovery incident; failed and completed scratch worktrees remain until explicit cleanup.
  • Full split-pane TUI / Ink dependency: most value should come from concise live summaries plus durable inspection first.
  • Skill marketplace, ratings, and team registry: ecosystem work before the runtime is trustworthy would multiply compatibility and support obligations.
  • Automatic model learning or global capability rankings: opaque and hard to reproduce; explicit comparisons are the smaller, inspectable primitive.
  • Enterprise policy suite, editor integrations, KFL, and daemon context watching: interesting later, but not part of the current product-defining sequence.

Global verification baseline

All plans inherit these repository gates:

bun run check
bun run --cwd packages/karl test-skills
git diff --check

At planning time, bun run check covered typecheck, 41 tests, and a compiled build. Executors must accept higher test counts but never fewer passing tests.