v0.1.0 Platform & Migration Decision Record

Decision Statement¶

For v0.1.0 and beyond:

1. Build devflow as an independent open-source repository and release it as a standalone CLI (devflow, alias dwf).

2. Create kroki-rs-nxt as a new repository for next-generation architecture.

3. Keep current kroki-rs as a stable/maintenance line during migration.

4. Start kroki-rs-nxt as a single workspace monorepo (not many repos at first), then split only when ownership and release velocity justify it.

Context¶

Two major tracks are in flight:

• Track A: generic workflow platform (devflow) reusable across stacks.

• Track B: major architecture refactor for Kroki (multi-surface model).

Trying to do both as in-place refactors in the same repository creates high coupling risk and weakens governance clarity for open-source contributors.

Options Evaluated¶

Option A: New kroki-rs-nxt repository + new devflow repository¶

Pros:

• Clean architectural runway; no legacy constraints in the new design.

• Stronger decision hygiene and contributor clarity.

• Easier to enforce canonical workflow graph and plugin boundaries from day one.

Cons:

• Dual-repo overhead (issues, releases, docs, CI).

• Migration complexity and temporary duplication of effort.

• Requires clear compatibility and deprecation policy.

Option B: In-place refactor of current kroki-rs while creating devflow¶

Pros:

• Single repo continuity.

• Lower initial operational overhead.

Cons:

• Higher risk of “hybrid limbo” architecture.

• Slower deep refactor due to compatibility pressure.

• Harder to keep contributor mental model clear.

Rationale for Selected Direction¶

We choose Option A with a strict execution guard:

• devflow and kroki-rs-nxt are separate from day one.

• kroki-rs-nxt stays monorepo workspace initially.

• Multi-repo fragmentation is postponed until evidence shows it is needed.

This gives deterministic architecture evolution with less long-term maintenance debt.

Ruthless Review Outcomes from Brainstorm Docs¶

Key concerns identified in brainstorm artifacts:

• Multi-repo-first design is over-ambitious without concrete release/versioning governance.

• Layer count is high; without strict phase gates it can become abstraction tax.

• Multi-format serialization should be staged, not implemented all at once.

• Plugin/WASM model needs explicit ABI/capability contracts before broad adoption.

Therefore:

• Start with one canonical external contract format and add others only when measured need exists.

• Introduce plugin runtime as a bounded subsystem with explicit compatibility policy.

• Treat architecture documents as directional until backed by executable conformance checks.

Target Repository Structures¶

devflow¶

devflow/
  Cargo.toml
  crates/
    devflow-core/
    devflow-cli/
    devflow-gh/
    devflow-ext-rust/
    devflow-ext-node/
    devflow-ext-react/
    devflow-ext-lit/
    devflow-ext-vscode/
    devflow-ext-tauri/
  examples/
    rust-lib/
    node-ts/
    react/
    tauri/
    vscode-extension/
  docs/

kroki-rs-nxt¶

kroki-rs-nxt/
  Cargo.toml
  crates/
    kroki-core/
    kroki-contracts/
    kroki-plugin-api/
    kroki-plugin-runtime/
    kroki-adapter-http/
    kroki-adapter-cli/
    kroki-observability/
  apps/
    kroki-server/
    kroki-cli/
  plugins/
  tests/
    contract/
    integration/
    conformance/
  schemas/
  devflow.toml

Rollout Plan with Phase Gates¶

Phase 0: Governance and Contracts¶

• Define compatibility/deprecation policy.

• Define versioning strategy for devflow and kroki-rs-nxt.

• Define required quality gates and ownership model.

Exit criteria:

• Published governance docs and contribution model.

• Baseline ADRs approved.

Phase 1: devflow MVP¶

• Implement canonical command graph (setup, fmt, lint, build, test, verify, ci generate).

• Implement Rust extension first, along with Node parity.

• Generate reproducible CI workflow and local container execution.

• Implement Subprocess Extensions for multi-language future-proofing.

Status: COMPLETE

Exit criteria met:

• devflow runs on at least one Rust reference project (Validated via examples/rust-lib).

• Execution architecture supports completely uncoupled external binaries via standard JSON/stdio (Phase 2 constraint validated via examples/python-ext).

• Node, Typescript, and Hybrid stacks evaluate correctly (Validated via examples/node-ts, examples/react, examples/tauri, and examples/vscode-extension).

Phase 2: kroki-rs-nxt Bootstrap¶

• Scaffold workspace structure.

• Port core domain and contracts first.

• Integrate devflow in CI and local workflow from start.

Exit criteria:

• Core + CLI + HTTP adapter compile and pass baseline tests.

Phase 3: Feature Migration by Capability Slice¶

• Migrate providers/plugins in prioritized batches.

• Add contract/conformance tests per slice.

Exit criteria:

• Feature parity target reached for v0.1.0 scope.

Phase 4: Stabilization and Release¶

• Performance/correctness hardening.

• Packaging and release automation via devflow.

• Publish migration guide from kroki-rs to kroki-rs-nxt.

Exit criteria:

• v0.1.0 RC passes all quality gates and release checklist.

Risks and Mitigations¶

• Risk: over-abstraction in early architecture.

  • Mitigation: enforce phase gates and measurable adoption criteria.

• Risk: contributor confusion between repos.

  • Mitigation: publish explicit repo purpose and migration matrix.

• Risk: tool/project coupling (devflow too Kroki-specific).

  • Mitigation: extension API and example projects across stacks.

• Risk: release burden across two active lines.

  • Mitigation: designate kroki-rs as maintenance-only during transition.

Pros/Cons of the Chosen Path¶

Pros:

• High architectural clarity and long-term maintainability.

• Stronger reuse potential through devflow.

• Better open-source governance through explicit boundaries.

Cons:

• Higher short-term setup and coordination cost.

• Requires disciplined phase governance and clear communication.

Reference Learnings¶

The following ecosystems inform this decision:

• Rust workspace model and staged modularization:

  • https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html

• Tauri ecosystem (Rust + frontend integration, monorepo evolution):

  • https://github.com/tauri-apps/tauri

  • https://v2.tauri.app/

• Terraform plugin protocol/versioning discipline:

  • https://developer.hashicorp.com/terraform/plugin/how-terraform-works#provider-plugins

• Nx plugin/extensibility model for reusable developer workflows:

  • https://nx.dev/concepts/plugins/introduction

• GitHub reusable workflow patterns:

  • https://docs.github.com/actions/using-workflows/reusing-workflows

• cargo-nextest as scalable Rust CI test runner:

  • https://nexte.st/docs/

Review Cadence¶

• Revisit this decision at the end of each phase.

• If phase exit criteria fail twice consecutively, open a decision review issue and adjust scope/sequence before continuing.