How jasgujral/mokata-oss works
1. Repository shape: a Python core with multiple integration surfaces
- The main product is the src/mokata Python package, exposed as a CLI and also embedded into Claude Code via plugin/MCP/hook surfaces.
- Surrounding it are docs, templates for slash commands, reusable “skills,” a VS Code extension, hook scripts, packaging assets, and a large test suite.
2. Core execution boundary: deterministic engine vs AI-facing surfaces
- The cli.py, __main__.py, pipeline.py, engine/, execmode/, modes/, and related modules implement the deterministic orchestration layer.
- The AI tools themselves are outside the core; mokata provides guarded workflows, context selection, gates, and audit rather than being an LLM runtime.
3. Primary product flow: spec-driven pipeline
- The central flow is brainstorm → spec → test → develop → review, with gating between phases.
- engine/ contains phase/gate logic such as completeness, compliance, premortem, preview, and ship; this is the “no code before spec passes” boundary emphasized in the README.
4. Governance subsystem: writes are mediated and audited
- govern/ is the safety/control plane: rules, secrets, token budgeting, trust, hooks, lifecycle, ledger, revert, and gate enforcement.
- Durable actions like writing code, memory, or config are human-gated and recorded; the audit ledger is a key cross-cutting data store for decision traceability.
5. Knowledge subsystem: structural codebase awareness
- knowledge/ provides codebase lookup and graph-style navigation through backends like grep and graph adapters, with Neo4j support present as an optional backend.
- The repo explicitly treats the knowledge graph as “adopted” with a grep fallback, so architecture diagrams should show knowledge as a pluggable read layer feeding context selection and routing.
6. Memory subsystem: persistent, local-first, self-healing state
- memory/ handles episodic/decision memory, consolidation, embedding/vector retrieval, tiered storage, and backend abstraction.
- The README indicates SQLite as the default local store and Postgres for shared/team setups; memory is a first-class durable subsystem, not an add-on.
7. Execution modes: sequential vs parallel subagent orchestration
- execmode/ contains routing, selection, decomposition, estimation, review, and task orchestration for different run styles.
- The architecture supports a lowest-cost sequential path and a parallel fan-out model with isolated subagents and review, so the diagram should show execution mode as a strategy layer above the engine.
8. Session and portability layer
- session_bundle.py, session_transport.py, resume.py, and share.py support packaging, transferring, and resuming work across machines or teammates.
- This creates a portable session artifact boundary: checkpoints, brainstorm state, and relevant memory can be bundled, scanned, and reloaded.
9. Team and shared-backend capabilities
- team.py, team_audit.py, vault.py, stacks.py, and share.py support team onboarding, shared memory/backends, stack distribution, and vault-backed sharing.
- The architecture is explicitly multi-project and project-scoped when using shared storage, so shared services must be drawn with project-key partitioning.
10. Editor and agent integrations
- editors/vscode/ is a separate VS Code extension surface, and mcp_server.py plus adapters/mcp.py expose Model Context Protocol integration.
- The repo also has plugin metadata under .claude-plugin/ and shell/Python hooks under hooks/, showing multiple integration paths into external agent runtimes.
11. Profiles, manifests, and command surfaces
- manifest.py, profiles.py, config.py, schema.py, stacks/, and templates/ define the configurable command/runtime surface and packaged command templates.
- Profiles control which layers are active: minimal, standard, or full, with optional backends and tools degrading safely when unavailable.
12. Operational and supply-chain boundary
- .github/workflows/, release assets, packaging files, and scripts show a strong release/CI layer: reproducible builds, SBOM/provenance, security checks, docs publication, and cross-platform validation.
- The project is local-first and telemetry-free by design; external services are optional and only present when explicitly configured.
13. Testing strategy mirrors the architecture
- Tests cover CLI wiring, engine phases, governance, memory, knowledge, sessions, MCP, VS Code integration, platform support, and release behavior.
- The test layout indicates the repo is organized around subsystem contracts and end-to-end pipeline behavior, which is useful for diagramming boundaries and data flow confidence.
Main entry points: govern Governance · pipeline.py Pipeline · engine Engine · execmode Exec modes
Components 20
Core engine
Deterministic orchestration, governance, knowledge, memory, and execution modes.
- CLI · Main command entry and top-level wiring.
src/mokata/cli.py - Module main · Python module execution entrypoint.
src/mokata/__main__.py - Pipeline · Spec-driven run pipeline and phase coordination.
src/mokata/pipeline.py - Engine · Phase, completeness, compliance, premortem, preview, and ship gates.
src/mokata/engine - Exec modes · Sequential and parallel execution strategies for subagent orchestration.
src/mokata/execmode - Governance · Rules, budgets, hooks, trust, ledger, revert, and gate enforcement.
src/mokata/govern - Knowledge · Codebase awareness and context lookup with pluggable backends.
src/mokata/knowledge - Profiles · Activation profiles for minimal, standard, and full runtime sets.
src/mokata/profiles.py - Manifest · Packaged command/runtime manifest definitions.
src/mokata/manifest.py
Surfaces
CLI, MCP, editor, hooks, and command templates exposed to users and agents.
- MCP server · Model Context Protocol server surface.
src/mokata/mcp_server.py - Adapters · Contract and MCP adapter wiring for external runtimes.
src/mokata/adapters - Hooks · Launch and secret-guard hook entrypoints.
hooks - VS Code · Separate editor extension surface for chat and MCP integration.
editors/vscode - Templates · Reusable slash-command and skill templates.
templates
State and sharing
Portable session artifacts, shared team storage, and vault-backed coordination.
- Memory · Local-first episodic, consolidated, and vector memory.
src/mokata/memory - Sessions · Bundle, transport, resume, and sharing boundary for portable work state.
src/mokata/session_bundle.py - Team · Shared-backend onboarding, audit, stacks, and vault coordination.
src/mokata/team.py - Share · Portable sharing and project-scoped distribution of state.
src/mokata/share.py
Packaging
Docs, plugin metadata, release assets, and CI supply-chain plumbing.
- Docs · Concepts, how-tos, reference docs, and tutorials.
docs - CI & release · Workflows, packaging, and reproducible release tooling.
.github/workflows/ci.yml
Connections 21
- CLI → Pipeline: runs · CLI commands drive the deterministic product pipeline.
- Module main → CLI: dispatches · Module execution delegates to CLI wiring.
- Pipeline → Engine: gates · Pipeline uses engine phase gates before code change execution.
- Pipeline → Exec modes: selects · Pipeline chooses sequential or parallel execution strategy.
- Engine → Knowledge: requests context · Gates and phases consult codebase awareness for grounding.
- Engine → Governance: enforces · Governance mediates writes, trust, budgets, and audit.
- Exec modes → Knowledge: routes context · Execution modes use knowledge-backed routing and decomposition.
- Exec modes → Memory: reads/writes · Subagent execution can persist and retrieve state from memory.
- Governance → Memory: records · Governance persists decisions, lifecycle events, and durable traces.
- Governance → Sessions: protects · Session resume and portable artifacts pass through safety controls.
- Knowledge → Memory: augments · Knowledge lookup is informed by remembered context when available.
- Profiles → Manifest: configures · Profiles shape which command and runtime surfaces are active.
- Manifest → Templates: renders · Manifested command surfaces are packaged as templates.
- MCP server → Adapters: exposes · MCP server uses adapter contracts for external tool integration.
- Hooks → Governance: guarded by · Hook scripts trigger governed lifecycle and secret checks.
- VS Code → MCP server: connects · Editor extension talks through MCP integration paths.
- Sessions → Share: bundles · Portable sessions are packaged for transfer and resume.
- Share → Team: enables · Shared distribution supports team-scoped collaboration and backends.
- Docs → Templates: documents · Docs explain the command and skill template surface.
- CI & release → CLI: validates · CI and release workflows validate CLI and packaging behavior.
- CI & release → VS Code: checks · Supply-chain and release checks cover editor extension builds.