DevEnv is an AI-native software-development workflow engine with a canonical local runtime, CLI/operator surfaces, and a live WebSocket bridge.

• Knowledge vault: Vault/
• Agent entry point: Vault/Atlas/Agent Start Here.md
• Current state: SOURCE_OF_TRUTH.md
• Implementation history: Vault/Operations/RUN_BOOK.md
• Continuation guide: Vault/Operations/CONTINUE_DEVELOPMENT.md

• devenv run, devenv resume, the CLI operator commands, and the live server all sit on the canonical runtime facade in src/workflow/run.py.
• The runtime already supports review gates, resumable permission interrupts, MCP resource/prompt/root access, plugin and project-tool governance, memory review, CI execution/gating, artifact redaction, and bridge-backed live session control.
• The live bridge now supports JSON-RPC, reconnectable sessions, durable owner-token-protected recovery/control, explicit owner rotation, replay, ack cursors, auth handshake, JWT/shared-token auth, backgrounding, takeover arbitration, post-crash recovery start for eligible persisted runs, in-flight checkpoint-aware recovery diagnostics, worker-level parallel recovery metadata, and explicit recovery-risk warnings plus acknowledgement requirements when replay may discard in-flight work.
• The VS Code extension now consumes session recovery metadata plus live trust/guardrail governance data and run-artifact/audit-log operator views, can explicitly resume or recover eligible persisted sessions with acknowledgement prompts for replay risk, and now includes a live-session operator panel for bridge-backed session inspection/control, though broader product UX work is still ongoing.
• The repo now uses one compact source-of-truth file plus RUN_BOOK.md; older drifting status docs were removed.
• The latest full-suite verification recorded in-repo passed with 1706 passed, 2 warnings.

pip install -e .

devenv run "Add email validation to UserRegistration"
devenv resume <run_id>
devenv live

# Main workflow
devenv run "Add tests for the auth flow"
devenv resume <run_id>

# Operator surfaces
devenv sessions
devenv live
devenv permissions
devenv memory
devenv mcp
devenv tools
devenv integrations
devenv plugins
devenv project-tools
devenv bridge
devenv ci

• Canonical runtime: src/workflow/run.py
• Control plane: src/engine/control_plane.py
• CLI/operator entry: src/cli.py
• Server/operator entry: src/server/handlers.py
• Live bridge: src/server/ws_server.py
• Tests: tests/

Compatibility modules may still exist for older callers, but new work should prefer the canonical runtime path.

Use pytest against the real suite in tests/.

python -m pytest tests -q

For the latest focused and broader commands that were actually run, see Vault/Operations/RUN_BOOK.md.

Read in this order (faster and cheaper than reading SOURCE_OF_TRUTH.md in full):

1. Vault/Atlas/Agent Start Here.md — pick the minimal route for the area you’re touching
2. Vault/Knowledgebase/AGENT_PROTOCOL.md — operating rules
3. The matching Vault/Atlas/Routes/... note — minimal area-specific reads
4. Vault/Operations/RUN_BOOK.md (last 2-3 entries) — recent history
5. Only then read the docs named by that route
6. SOURCE_OF_TRUTH.md — only if the route-linked docs look stale

Vault/ is the canonical documentation root for project knowledge. Repo-root RUN_BOOK.md is a compatibility mirror of Vault/Operations/RUN_BOOK.md.

Core rule: do not stop between tasks. Work continuously, commit after each slice, update the KB. See Vault/Knowledgebase/AGENT_PROTOCOL.md for the full protocol. Token rule: use one route, not every route. VS Code, orchestration, implementation, research, and vault-maintenance work should begin from different minimal read sets.

Avoid recreating separate status files. SOURCE_OF_TRUTH.md is the canonical product state; Vault/Knowledgebase/ is the distilled, fast-read working set for agents.