Work Packages: Mission DSL Foundation

Inputs: Design documents from /kitty-specs/037-mission-dsl-foundation/ Prerequisites: plan.md (required), spec.md (user stories)

Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable and testable.

Prompt Files: Each work package references a matching prompt file in /tasks/ generated by /spec-kitty.tasks.

Work Package WP01: transitions Dependency + JSON Schema (Priority: P0)

Goal: Add transitions library as a dependency and define the JSON Schema for v1 mission YAML validation. Independent Test: import transitions succeeds, JSON Schema validates a sample v1 mission YAML dict. Prompt: /tasks/WP01-transitions-dep-and-schema.md

Included Subtasks

  • ✅ T001 Add transitions>=0.9.2 to pyproject.toml dependencies
  • ✅ T002 Add jsonschema to pyproject.toml dependencies (if not already present)
  • ✅ T003 Create src/specify_cli/mission_v1/__init__.py subpackage
  • ✅ T004 Create src/specify_cli/mission_v1/schema.py with JSON Schema definition
  • ✅ T005 Create tests/unit/mission_v1/test_schema.py with validation tests

Implementation Notes

  • The JSON Schema must cover: mission (name, version, description), initial, states, transitions, inputs, outputs, guards
  • Guard expression patterns: artifact_exists("..."), gate_passed("..."), etc.
  • Schema should validate guard expression syntax (known function names only)

Dependencies

  • None (starting package).

Risks & Mitigations

  • transitions version compatibility: Pin >=0.9.2 to ensure MarkupMachine support.

Work Package WP02: MissionRunner + MarkupMachine Wrapper (Priority: P0)

Goal: Create the core MissionRunner class that wraps transitions.MarkupMachine to load and execute v1 state machines. Independent Test: Load a v1 mission config dict, construct a MarkupMachine, verify state transitions work. Prompt: /tasks/WP02-mission-runner.md

Included Subtasks

  • ✅ T006 Create src/specify_cli/mission_v1/runner.py with MissionRunner class
  • ✅ T007 Create MissionModel class with callback method stubs
  • ✅ T008 Implement MarkupMachine construction from validated config
  • ✅ T009 [P] Create tests/unit/mission_v1/test_runner.py with runner tests

Implementation Notes

  • MarkupMachine(model=model, auto_transitions=False, send_event=True, **config)
  • MissionModel holds feature_dir, event_log_path, inputs as context
  • All callbacks on the model receive EventData (due to send_event=True)

Dependencies

  • Depends on WP01 (schema validation runs before machine construction).

Risks & Mitigations

  • MarkupMachine dict format quirks: Test with minimal configs first, then full missions.

Work Package WP03: Guard Expression Compiler (Priority: P0)

Goal: Implement the guard expression compiler that parses declarative guard strings into callable methods. Independent Test: Compile artifact_exists("spec.md") → callable that checks file existence, returns True/False. Prompt: /tasks/WP03-guard-compiler.md

Included Subtasks

  • ✅ T010 Create src/specify_cli/mission_v1/guards.py with expression parser
  • ✅ T011 Implement 6 guard primitives: artifact_exists, gate_passed, all_wp_status, any_wp_status, input_provided, event_count
  • ✅ T012 Implement guard compilation: string → bound method on model
  • ✅ T013 Add unknown guard rejection at load time
  • ✅ T014 [P] Create tests/unit/mission_v1/test_guards.py with guard tests

Implementation Notes

  • Guard expressions are strings like artifact_exists("spec.md") parsed via regex
  • Registry maps function names → factory callables that return guard methods
  • Each guard method receives EventData and returns bool
  • Guards access feature context through the model (feature_dir, event_log, etc.)

Parallel Opportunities

  • Can be developed in parallel with WP02 (runner) since guards are composed into the machine later.

Dependencies

  • Depends on WP01 (subpackage structure).

Risks & Mitigations

  • Guard expression parsing edge cases: Test with quoted paths, integers, nested quotes.

Work Package WP04: PhaseMission v0 Compatibility Wrapper (Priority: P1)

Goal: Create PhaseMission adapter that wraps v0 phase-list missions as linear state machines. Independent Test: Load existing software-dev mission.yaml (v0), wrap in PhaseMission, advance through phases linearly. Prompt: /tasks/WP04-phase-mission-compat.md

Included Subtasks

  • ✅ T015 Create src/specify_cli/mission_v1/compat.py with PhaseMission class
  • ✅ T016 Generate synthetic linear state machine from phase list
  • ✅ T017 Implement API compatibility with StateMachineMission
  • ✅ T018 [P] Create tests/unit/mission_v1/test_compat.py with v0 wrapper tests

Implementation Notes

  • PhaseMission reads workflow.phases from existing v0 config
  • Generates states: [phase1, phase2, ..., phaseN, done] with linear transitions
  • No guards on v0 transitions
  • Must expose same API surface as StateMachineMission (state, trigger, get_triggers, etc.)

Parallel Opportunities

  • Independent of WP02/WP03 (uses Machine directly, not MarkupMachine).

Dependencies

  • Depends on WP01 (subpackage structure).

Risks & Mitigations

  • API surface mismatch: Define a Protocol/ABC that both classes implement.

Work Package WP05: Provisional emit_event Interface (Priority: P1)

Goal: Create the thin emit_event(type, payload) boundary for event emission, logging to JSONL. Independent Test: Call emit_event("phase_entered", {...}), verify JSONL line written to file. Prompt: /tasks/WP05-emit-event.md

Included Subtasks

  • ✅ T019 Create src/specify_cli/mission_v1/events.py with emit_event function
  • ✅ T020 Implement JSONL file writer with atomic append
  • ✅ T021 Wire emit_event into MissionModel callbacks (on_enter, on_exit, guard failures)
  • ✅ T022 [P] Create tests/unit/mission_v1/test_events.py with event emission tests

Implementation Notes

  • Event format: {"type": str, "timestamp": str, "mission": str, "payload": dict}
  • JSONL file at <feature_dir>/mission-events.jsonl (distinct from status events.jsonl)
  • emit_event failures log warning but never block state transitions
  • This is a Phase 2 boundary — keep it simple, no event store

Parallel Opportunities

  • Can be developed in parallel with WP03 (guards) and WP04 (compat).

Dependencies

  • Depends on WP02 (MissionRunner model for callback wiring).

Risks & Mitigations

  • File locking: Use append mode, no locking needed for single-process CLI.

Work Package WP06: Software-Dev v1 Mission YAML (Priority: P1)

Goal: Define the software-dev mission in v1 format with states, transitions, rollback support, and guards. Independent Test: Load software-dev v1 YAML, verify state graph has rollback transitions, guards on key transitions. Prompt: /tasks/WP06-software-dev-mission.md

Included Subtasks

  • ✅ T023 Write v1 software-dev mission.yaml with states and transitions
  • ✅ T024 Define guards for key transitions (artifact_exists for spec.md, plan.md, tasks.md)
  • ✅ T025 Define rollback transitions (review → implement rework)
  • ✅ T026 Define typed inputs and outputs
  • ✅ T027 [P] Create integration test for software-dev mission loading

Implementation Notes

  • States: discovery, specify, plan, implement, review, done
  • Forward transitions: advance trigger for each step
  • Rollback: rework trigger from review → implement
  • Guards: artifact_exists("spec.md") for specify → plan, artifact_exists("plan.md") for plan → implement
  • Keep existing v0 fields (workflow, artifacts, paths, etc.) for backward compat

Dependencies

  • Depends on WP01 (schema), WP02 (runner), WP03 (guards).

Risks & Mitigations

  • Schema validation strictness: Ensure v1 fields coexist with v0 fields in same YAML.

Work Package WP07: Research + Plan v1 Mission YAMLs (Priority: P2)

Goal: Define research and plan missions in v1 format with domain-specific state machines and guards. Independent Test: Load each v1 YAML, verify unique state graphs and domain-specific guards. Prompt: /tasks/WP07-research-plan-missions.md

Included Subtasks

  • ✅ T028 Write v1 research mission.yaml with evidence-gated transitions
  • ✅ T029 Write v1 plan mission.yaml with rollback transitions
  • ✅ T030 Create plan mission directory structure (new mission)
  • ✅ T031 Define domain-specific guards for each mission
  • ✅ T032 [P] Create integration tests for research and plan mission loading

Implementation Notes

  • Research: scoping → gathering → synthesis → output → done, with event_count("source_documented", 3) guard
  • Plan: goals → research → structure → draft → review → done, with rollback from draft → structure
  • Plan is a NEW mission — create src/specify_cli/missions/plan/ directory

Parallel Opportunities

  • Can be developed in parallel with WP06 (different YAML files).

Dependencies

  • Depends on WP01 (schema), WP02 (runner), WP03 (guards).

Risks & Mitigations

  • New plan mission needs command-templates and templates directories.

Work Package WP08: load_mission() Dispatch + Integration (Priority: P1)

Goal: Create the load_mission() entry point that auto-detects v0/v1 format and returns the appropriate mission type. Independent Test: load_mission(path) returns StateMachineMission for v1 YAML, PhaseMission for v0 YAML. Prompt: /tasks/WP08-load-mission-dispatch.md

Included Subtasks

  • ✅ T033 Implement load_mission() in mission_v1/__init__.py with v0/v1 dispatch
  • ✅ T034 Define Mission Protocol/ABC that both types satisfy
  • ✅ T035 Wire load_mission into existing get_mission_by_name() call path
  • ✅ T036 Handle hybrid YAML (v1 fields + v0 legacy fields coexisting)
  • ✅ T037 [P] Create tests/integration/test_mission_loading.py

Implementation Notes

  • Detection: if states AND transitions keys present → v1, else v0
  • v1: validate schema → construct MarkupMachine → return StateMachineMission
  • v0: wrap existing Mission in PhaseMission → return
  • Must not break existing Mission class consumers

Dependencies

  • Depends on WP02 (runner), WP03 (guards), WP04 (compat).

Risks & Mitigations

  • Circular imports: mission_v1 imports from mission.py for v0 wrapping, mission.py calls load_mission for dispatch. Use lazy imports.

Work Package WP09: Integration Tests + Regression Check (Priority: P2)

Goal: Comprehensive integration tests and full regression check against existing test suite. Independent Test: All integration tests pass, no new regressions in 2032+ test suite. Prompt: /tasks/WP09-integration-tests.md

Included Subtasks

  • ✅ T038 Create tests/integration/test_mission_guards.py with guard evaluation tests
  • ✅ T039 E2E test: load v1 mission → trigger transitions → verify guards block/allow
  • ✅ T040 E2E test: load v0 mission → PhaseMission linear progression
  • ✅ T041 E2E test: load all 3 v1 missions + documentation (v0) → verify coexistence
  • ✅ T042 Run full test suite for regressions
  • ✅ T043 Verify existing mission tests still pass

Implementation Notes

  • Guards need feature context (feature_dir, event log) — create temp fixtures
  • Verify documentation mission (v0) loads unchanged alongside v1 missions
  • Known baseline: ~81 failures on 2.x (pre-existing cross-test pollution)

Dependencies

  • Depends on WP06, WP07, WP08 (all missions defined and dispatch working).

Risks & Mitigations

  • Cross-test pollution from new transitions import: Use isolated tmp_path fixtures.

Dependency & Execution Summary

Phase 1 - Foundation:
  WP01 (schema + deps) ──────────────────────────┐
                                                   │
Phase 2 - Core Engine (parallel):                 │
  WP02 (runner) ──────── depends on WP01 ────────┤
  WP03 (guards) ──────── depends on WP01 ────────┤
  WP04 (v0 compat) ───── depends on WP01 ────────┤
  WP05 (emit_event) ──── depends on WP02 ────────┤
                                                   │
Phase 3 - Missions + Integration (parallel):      │
  WP06 (software-dev) ── depends on WP01-03 ─────┤
  WP07 (research+plan) ─ depends on WP01-03 ─────┤
  WP08 (dispatch) ────── depends on WP02-04 ─────┘
                                                   │
Phase 4 - Validation:                              │
  WP09 (integration) ─── depends on WP06-08 ──────┘
  • Sequence: WP01 → {WP02, WP03, WP04} parallel → {WP05, WP06, WP07, WP08} parallel → WP09
  • Parallelization: WP02/WP03/WP04 are fully parallel after WP01. WP06/WP07 are parallel with each other.
  • MVP Scope: WP01 + WP02 + WP03 + WP04 + WP08 (core engine + dispatch + compat)

Subtask Index (Reference)

Subtask IDSummaryWork PackagePriorityParallel?
T001Add transitions dependencyWP01P0No
T002Add jsonschema dependencyWP01P0No
T003Create mission_v1 subpackageWP01P0No
T004Define JSON Schema for v1WP01P0No
T005Schema validation testsWP01P0Yes
T006Create MissionRunner classWP02P0No
T007Create MissionModel classWP02P0No
T008MarkupMachine constructionWP02P0No
T009Runner testsWP02P0Yes
T010Guard expression parserWP03P0No
T0116 guard primitivesWP03P0No
T012Guard compilationWP03P0No
T013Unknown guard rejectionWP03P0No
T014Guard testsWP03P0Yes
T015PhaseMission classWP04P1No
T016Synthetic linear state machineWP04P1No
T017API compatibilityWP04P1No
T018v0 wrapper testsWP04P1Yes
T019emit_event functionWP05P1No
T020JSONL file writerWP05P1No
T021Wire emit_event into callbacksWP05P1No
T022Event emission testsWP05P1Yes
T023Software-dev v1 YAMLWP06P1No
T024Software-dev guardsWP06P1No
T025Software-dev rollback transitionsWP06P1No
T026Software-dev typed I/OWP06P1No
T027Software-dev integration testWP06P1Yes
T028Research v1 YAMLWP07P2No
T029Plan v1 YAMLWP07P2No
T030Plan mission directoryWP07P2No
T031Domain-specific guardsWP07P2No
T032Research/Plan integration testsWP07P2Yes
T033load_mission() dispatchWP08P1No
T034Mission Protocol/ABCWP08P1No
T035Wire into get_mission_by_nameWP08P1No
T036Hybrid YAML handlingWP08P1No
T037Mission loading integration testsWP08P1Yes
T038Guard evaluation integration testsWP09P2No
T039E2E v1 transitions testWP09P2No
T040E2E v0 compat testWP09P2No
T041E2E coexistence testWP09P2No
T042Full test suite regressionWP09P2No
T043Existing mission tests passWP09P2No

<!-- status-model:start -->

Canonical Status (Generated)

<!-- status-model:end -->

  • WP01: done
  • WP02: done
  • WP03: done
  • WP04: done
  • WP05: done
  • WP06: done
  • WP07: done
  • WP08: done
  • WP09: done