How loudiman/mission-forge works
1. What this repo is
MissionForge is a Python 3.11+ toolchain centered on a deterministic mission workspace stored on disk. The core product is a Typer-based CLI, with a separate FastAPI backend for API access, plus documentation, static landing-page assets, and CI/CD automation.
2. Primary runtime boundary: CLI vs backend
The CLI lives under src/missionforge/cli/ and is the main user entrypoint for mission lifecycle commands. The backend lives under src/missionforge/backend/ and appears to expose mission data and related operations over HTTP. These are separate surfaces sharing the same core models and validation logic rather than duplicating business rules.
3. Workspace and filesystem as the system of record
MissionForge is file-centric. Mission state is persisted in .missionforge/missions/<MISSION_ID>/ with mission.yaml, generated plan.yaml, report.md, and sub-missions/ artifacts. The core/workspace.py module and the repository layer act as the main boundary between logic and the on-disk workspace layout.
4. Mission lifecycle pipeline
The repository is organized around a workflow: initialize a workspace, define a parent mission, decompose into sub-missions, validate sub-missions, generate an execution plan, choose the next task, capture baselines, and produce a final report. The CLI command modules map directly to these stages: workspace, mission, decompose, plan, next, baseline, validate, and report.
5. Validation and schema enforcement layer
src/missionforge/models/schemas.py and src/missionforge/schemas/ define the structured mission and sub-mission contracts using Pydantic v2 and JSON/schema validators. core/mission_validator.py, core/validation_service.py, and core/parent_validation_service.py perform cross-field and cross-file checks such as ID format, parent-child linkage, allowed/forbidden path constraints, and dependency consistency.
6. Planning and dependency resolution
The planning subsystem resolves sub-mission dependencies into a deterministic execution order. The README states it uses topological sorting and detects cycles; this logic is implemented in the planning command and supporting core services, then written back to plan.yaml for later consumption by next and reporting flows.
7. Baseline and validation evidence
core/baseline_service.py and core/report_generator.py support the evidence-gathering stages around implementation. Baselines and validation artifacts are captured per sub-mission and then folded into a PR-ready Markdown report through a Jinja2 template in src/missionforge/templates/mission_report.md.j2.
8. Git and subprocess are deliberately constrained
src/missionforge/git/operations.py wraps system git commands, and src/missionforge/utils/subprocess_utils.py centralizes safe subprocess execution. This is a clear security boundary: external commands are used for deterministic operations, but the code avoids shell expansion and keeps command execution auditable.
9. Extensibility via plugins
src/missionforge/plugins/ defines a plugin system for commands, validators, formatters, and metrics. The registry and base classes indicate the architecture expects future extension without changing the core mission workflow, which is important for architecture diagrams that need to show optional extension points.
10. Backend API structure
The backend has its own main app, routers, response models, cache, config, and CORS middleware. The cache layer uses file-backed storage (backend/cache/file_cache.py), suggesting the API is still anchored in workspace artifacts rather than an independent database. In diagrams, this should be shown as an API façade over the same mission files and core validation logic.
11. Supporting utilities and safeguards
Utilities in src/missionforge/utils/ handle path matching and subprocess concerns, which are critical because the repo enforces scoped file access for sub-missions. These utilities support the repo’s boundary checks around allowed_paths, forbidden_paths, and workspace-safe output generation.
12. Testing architecture
The test suite is broad and maps well to the layered design: unit tests cover models, validators, workspace logic, subprocess wrappers, and git operations; integration tests cover CLI workflows and backend API behavior; manual tests exist for edge cases and parent-validation scenarios. For a diagram, this means most architectural seams are already explicitly tested.
13. Operational and delivery surface
GitHub Actions workflows handle CI, issue numbering, and landing-page deployment. The landing-page/ directory is a separate static site surface, likely used for product/documentation presentation rather than core mission execution.
14. Overall architectural shape
The repo is best understood as a deterministic workflow engine around mission files: CLI and backend are thin orchestration layers, core services enforce rules, schemas define contracts, git/subprocess utilities interact with the environment, and outputs are persisted back into the mission workspace. The main diagram boundaries should be: user interface, core business rules, filesystem workspace, external command execution, and optional HTTP backend.
Main entry points: workspace.py Workspace · app.py CLI app · validation_service.py Validation core · missions.py Mission routes
Components 27
User surfaces
Primary command-line and HTTP entrypoints.
- CLI app · Main command-line surface for mission lifecycle operations.
src/missionforge/cli/app.py - Workspace cmd · Initializes and manages the mission workspace.
src/missionforge/cli/commands/workspace.py - Mission cmd · Creates and updates mission definitions.
src/missionforge/cli/commands/mission.py - Decompose cmd · Splits a parent mission into scoped sub-missions.
src/missionforge/cli/commands/decompose.py - Plan cmd · Builds deterministic execution order for sub-missions.
src/missionforge/cli/commands/plan.py - Next cmd · Selects the next executable sub-mission.
src/missionforge/cli/commands/next.py - Validate cmd · Checks mission and sub-mission correctness.
src/missionforge/cli/commands/validate.py - Baseline cmd · Captures implementation evidence for sub-missions.
src/missionforge/cli/commands/baseline.py - Report cmd · Generates the final mission report artifact.
src/missionforge/cli/commands/report.py - API app · HTTP façade over mission workspace data.
src/missionforge/backend/main.py - Mission routes · Mission endpoints exposed by the backend.
src/missionforge/backend/routers/missions.py
Workflow engine
Mission lifecycle, validation, planning, reporting, and workspace orchestration.
- Validation core · Cross-field and cross-file mission validation.
src/missionforge/core/validation_service.py - Parent checks · Validates parent-child relationships and path scoping.
src/missionforge/core/parent_validation_service.py - Mission validator · Enforces mission identity, path, and dependency rules.
src/missionforge/core/mission_validator.py - Baseline service · Captures per-sub-mission baseline artifacts.
src/missionforge/core/baseline_service.py - Report generator · Assembles the final report from mission evidence and template data.
src/missionforge/core/report_generator.py - Report template · Markdown template for PR-ready mission reporting.
src/missionforge/templates/mission_report.md.j2 - Plan logic · Topological ordering and cycle detection for sub-missions.
src/missionforge/cli/commands/plan.py - Next selection · Chooses the next task from the persisted execution plan.
src/missionforge/cli/commands/next.py
Contracts and storage
Shared schemas and the on-disk mission workspace.
- Workspace · Deterministic on-disk mission store under .missionforge/missions.
src/missionforge/core/workspace.py - Mission artifacts · Mission.yaml, plan.yaml, report.md, and sub-mission evidence files.
.missionforge/missions - Schemas · Structured mission and sub-mission contracts.
src/missionforge/models/schemas.py - Schema validators · JSON-schema and structural validators for mission contracts.
src/missionforge/schemas/validators.py
Execution boundary
Controlled git, subprocess, and API persistence layers.
- Git ops · Restricted wrapper around git commands.
src/missionforge/git/operations.py - Subprocess utils · Centralized non-shell subprocess execution boundary.
src/missionforge/utils/subprocess_utils.py - File cache · File-backed cache used by the API layer.
src/missionforge/backend/cache/file_cache.py
Extensions
Optional plugin hooks for the core workflow.
- Plugin registry · Registers optional commands, validators, formatters, and metrics.
src/missionforge/plugins/registry.py
Connections 42
- CLI app → Workspace cmd: dispatches · The CLI app exposes workspace lifecycle commands.
- CLI app → Mission cmd: dispatches · The CLI app exposes mission creation and update commands.
- CLI app → Decompose cmd: dispatches · The CLI app exposes decomposition commands.
- CLI app → Plan cmd: dispatches · The CLI app exposes planning commands.
- CLI app → Next cmd: dispatches · The CLI app exposes task-selection commands.
- CLI app → Validate cmd: dispatches · The CLI app exposes validation commands.
- CLI app → Baseline cmd: dispatches · The CLI app exposes baseline-capture commands.
- CLI app → Report cmd: dispatches · The CLI app exposes report-generation commands.
- Workspace cmd → Workspace: initializes · Workspace commands create and manage the on-disk mission root.
- Mission cmd → Schemas: writes · Mission commands serialize validated mission contracts.
- Mission cmd → Schema validators: checks · Mission commands validate structured inputs before persisting.
- Decompose cmd → Validation core: checks · Decomposition is constrained by validation and scoping rules.
- Decompose cmd → Workspace: reads/writes · Decomposition operates on workspace mission artifacts.
- Plan cmd → Plan logic: drives · Planning command builds deterministic execution order.
- Plan cmd → Workspace: persists · Planning writes plan.yaml back into the workspace.
- Next cmd → Next selection: uses · Next command selects the next actionable sub-mission.
- Next cmd → Workspace: reads · Next command reads the persisted plan and mission state.
- Validate cmd → Validation core: runs · Validation command invokes the core validation pipeline.
- Baseline cmd → Baseline service: captures · Baseline command records implementation evidence.
- Baseline cmd → Workspace: writes · Baseline artifacts are written into the mission workspace.
- Report cmd → Report generator: renders · Report command produces the final mission report.
- Report generator → Report template: uses · Report generation uses the Markdown Jinja2 template.
- Report generator → Workspace: reads · Report generation consumes mission artifacts and evidence.
- Validation core → Mission validator: includes · Core validation aggregates mission-level rules.
- Validation core → Parent checks: includes · Core validation aggregates parent-child checks.
- Validation core → Schemas: relies on · Validation is anchored in the shared mission schema contracts.
- Mission validator → Schema validators: enforces · Mission validator applies structural schema rules.
- Mission validator → Workspace: scopes · Validator checks workspace paths, IDs, and dependencies.
- Parent checks → Workspace: scopes · Parent validation checks allowed and forbidden paths in the workspace.
- Plan logic → Workspace: reads/writes · Planning resolves dependencies from mission files and persists plan data.
- Next selection → Workspace: reads · Next selection consumes the stored plan and mission artifacts.
- Baseline service → Workspace: reads · Baseline capture consumes per-mission artifacts.
- Report generator → Git ops: references · Reporting can summarize git-backed implementation state.
- Git ops → Subprocess utils: executes through · Git commands are run through the safe subprocess boundary.
- API app → Mission routes: mounts · The FastAPI app assembles mission routes.
- Mission routes → Workspace: serves · API responses are derived from workspace mission artifacts.
- Mission routes → File cache: uses · Routes leverage file-backed caching for API data.
- Mission routes → Schemas: serializes · API response models align with shared mission schemas.
- Mission routes → Validation core: shares rules · Backend relies on the same validation logic as the CLI.
- Plugin registry → CLI app: extends · Plugins can add or alter command surface behavior.
- Plugin registry → Validation core: extends · Plugins can contribute validators and formatters.
- Plugin registry → API app: extends · Plugins can contribute backend-facing metrics or behaviors.