feat(migration): migrate out agentic to golang or rust

[soulcodex]

Goal

In order to make more easier, readable and evolvable not needing alwaus AI usage we aim to migrate out the agentic CLI to golang to make more easier its mainteinance, evolution and more open to become multiplatform.

Key aspects

1. Use cobra framework to build the tool
2. Start publishing versions with the proper binaries attached to it per architecture (x86, arm64, amd64, and so on), therefore multiple architecture must be taken into account
3. Research if right now it´s possible to do doogfooding by using agentic to build / evolve agentic, if so use the profile ´golang-hexagonal-cobra-cli´, ´--link´ mode and take the current AGENTS.md content
4. Do not remove the bash test suite until we´re able to reproduce the same behavior and test suite coverage in the destination language (Go)
5. Planify surgical PR´s little by little against branch v2 and only running the validation CI jobs per PR, if possible do a chained approach step by step and mention this issue on each one to keep traceability about changes made driven by this issue
6. Public API stills the same only changes the language, that´s it
7. Remove any reference to just commands from user facing docs

[soulcodex]

Reviewed Implementation Plan

Implementation Plan for Issue #99 - feat(migration): migrate out agentic to golang or rust

Source

• Issue: feat(migration): migrate out agentic to golang or rust #99
• URL: feat(migration): migrate out agentic to golang or rust #99
• Labels: none
• Author: soulcodex
• Assignees: none
• Milestone: none
• Created: 2026-04-25T23:08:27Z
• Updated: 2026-04-25T23:22:30Z

Problem summary

The public agentic CLI is still implemented as Bash: bin/agentic sources tooling/lib/cli.sh, which then shells out to the rest of tooling/lib/*.sh. This keeps the command surface tied to shell-specific parsing, install-time path embedding, and POSIX behavior. The issue asks to move the CLI to Go with Cobra, publish architecture-specific binaries, keep the public command API stable, preserve the existing Bash test suite until Go reaches comparable behavior and coverage, remove just command references from user-facing docs, and sequence the migration as small PRs against v2.

The migration should be treated as a staged CLI-front-end replacement, not a wholesale rewrite of the library internals. The repository still depends on Bash backends, just, shell-based installers, and POSIX link-mode behavior.

Current behavior / context

The current CLI is a shell wrapper:

• bin/agentic resolves the library path and sources tooling/lib/cli.sh.
• tooling/lib/cli.sh defines the public commands and help text through main, cmd_deploy, cmd_compose, cmd_init, cmd_switch, cmd_sync, cmd_list, and cmd_uninstall.
• Shared discovery and config behavior lives in tooling/lib/common.sh, especially discover_library, discover_target, find_target_config_deep, read_active_vendors, and AGENTIC_VENDORS.

The CLI currently delegates all real work to Bash backends:

• tooling/lib/compose.sh
• tooling/lib/vendor-gen.sh
• tooling/lib/deploy-skills.sh
• tooling/lib/vendor-switch.sh
• tooling/lib/sync.sh
• tooling/lib/init.sh
• tooling/lib/validate.sh
• tooling/lib/index.sh
• tooling/lib/install.sh for local install/uninstall
• install.sh for remote installation

Behavior already covered by the Bash test suite includes:

• Global CLI help/version/list/discovery/uninstall flows in tooling/lib/test.sh, especially T44-T57.
• Link-mode behavior in T60-T66.
• init flows in T99-T101.
• MCP precedence/compatibility in T102-T103.

Important current constraints and drift:

• profiles/golang-hexagonal-cobra-cli.yaml already exists and is the obvious self-hosting profile target for this migration.
• The repo has a root AGENTS.md that should be the reference instructions set for any dogfooding experiment.
• The current CLI contract is not fully settled:
  • docs/commands.md documents --link for agentic deploy and agentic compose
  • tooling/lib/cli.sh does not currently parse --link
  • only the backend shell scripts support it
• The current installer story is still shell-and-just-centric:
  • tooling/lib/install.sh installs a generated shell wrapper that embeds LIBRARY_ROOT
  • remote install.sh clones the repo and then runs just install
  • removing just from docs without changing installer behavior would create a documentation/behavior mismatch
• There is no existing Go module, Go source tree, or release workflow for compiled binaries.
• The local checkout does not contain a v2 branch, so the requested chained-PR target branch is currently a real blocker, not just a minor unknown.

Relevant code paths

• CLI entrypoint and command parsing
  • bin/agentic
  • tooling/lib/cli.sh
  • tooling/lib/common.sh
• Core Bash backends that the Go CLI can initially delegate to
  • tooling/lib/compose.sh
  • tooling/lib/vendor-gen.sh
  • tooling/lib/deploy-skills.sh
  • tooling/lib/vendor-switch.sh
  • tooling/lib/sync.sh
  • tooling/lib/init.sh
  • tooling/lib/validate.sh
  • tooling/lib/index.sh
  • tooling/lib/sync-links.sh
  • tooling/lib/mcp.sh
• Install/distribution paths
  • tooling/lib/install.sh
  • install.sh
  • VERSION
• Public documentation that will need CLI-language and installer updates
  • README.md
  • docs/commands.md
  • docs/getting-started/installation.md
  • docs/getting-started/quickstart.md
  • docs/customization.md
  • docs/vendors.md
  • vendors/codex/README.md
• CI/workflows affected by adding Go and release publishing
  • .github/workflows/validate.yml
  • .github/workflows/docs-build in the same file
  • new release workflow(s) under .github/workflows/
• Existing profile and dogfooding inputs
  • profiles/golang-hexagonal-cobra-cli.yaml
  • AGENTS.md
• Existing tests that define the current contract
  • tooling/lib/test.sh

Proposed implementation

Implement the migration in explicit phases, with the CLI contract frozen before the Go rewrite starts.

1. Add a contract-freeze phase before any Go code lands.

   • Capture the current user-visible CLI behavior from:
     • tooling/lib/cli.sh
     • tooling/lib/test.sh
     • docs/commands.md
   • Resolve the --link mismatch up front:
     • either fix the Bash CLI first and add test coverage
     • or explicitly declare the documented --link behavior as the target contract and codify it in new tests before the Go port
   • Do not start the Go rewrite against an ambiguous command surface.

2. Treat v2 branch confirmation as a start gate, not a later footnote.

   • Confirm whether v2 exists and is the intended target for the PR chain before implementation starts.
   • If v2 is absent, the worker should stop and document the branch-strategy blocker instead of silently targeting main.

3. Replace the public CLI front-end first, not the full engine.

   • Create a Go module at repo root with:
     • go.mod
     • go.sum
     • cmd/agentic/main.go
     • one Cobra command file per command under internal/cli/
   • Keep main() as the only exit point via cobra.CheckErr.
   • Match current command names, positional argument rules, exit codes, and help text as closely as possible after the contract-freeze decision.
   • Initially delegate mutating work to the existing Bash scripts instead of porting all library behavior at once.

4. Introduce narrow Go abstractions around the current shell responsibilities.

   • Add testable discovery and execution abstractions such as:
     • internal/application/discovery/library_locator.go
     • internal/application/discovery/target_locator.go
     • internal/application/runtime/script_runner.go
     • internal/infrastructure/fs/...
     • internal/infrastructure/shell/...
   • Re-implement the precedence from discover_library and discover_target in Go so the shell entrypoint can eventually be retired without changing user-facing semantics.
   • Keep interfaces narrow, for example:
     • LibraryLocator.Discover(cwd, env)
     • TargetLocator.Discover(cwd)
     • ScriptRunner.Run(ctx, script, args, stdout, stderr)

5. Preserve Bash backends during the first migration milestone.

   • deploy, compose, switch, sync, init, and uninstall should continue invoking the existing shell backends in the early PRs.
   • Do not remove tooling/lib/test.sh or any tooling/lib/*.sh implementation until Go has parity coverage for the affected command surface.
   • Treat “Go CLI, Bash engine” as the first stable milestone.

6. Keep repo-local developer entrypoints and installed entrypoints separate during transition.

   • The installed CLI path and the repo-local bin/agentic wrapper do not have to migrate in the same PR.
   • Recommended sequence:
     • first, add the Go CLI and test/build it in-repo
     • second, teach tooling/lib/install.sh how to install the built Go binary instead of generating a shell wrapper
     • third, update install.sh after binary distribution exists
   • Do not force the remote installer to keep cloning the repo and calling just install once the Go binary path is available.

7. Separate “Go CLI” from “binary distribution and installer rewrite”.

   • Release automation should be a later milestone than the first Go CLI front-end.
   • After the Go front-end is stable, add release workflow(s) to build agentic for at least:
     • darwin/amd64
     • darwin/arm64
     • linux/amd64
     • linux/arm64
   • Leave Windows out of the first binary release unless link-mode and symlink semantics are explicitly supported and tested.
   • Keep GoReleaser optional. A hand-written GitHub Actions matrix is acceptable if it is simpler and easier to verify.

8. Do not remove just from user-facing docs until installers and usage flows no longer require it.

   • The docs-cleanup step must be gated by actual installer behavior.
   • Today the remote installer still installs dependencies including just and then runs just install.
   • Therefore, “remove just from user-facing docs” is not a docs-only task; it depends on:
     • tooling/lib/install.sh
     • install.sh
     • release/binary distribution path
   • Keep contributor just workflows unless a separate decision is made.

9. Make dogfooding a deliberate validation slice, not an assumption.

   • Add a spike or dedicated validation PR that tests whether this repo can self-host the migration using:
     • profiles/golang-hexagonal-cobra-cli.yaml
     • current link mode semantics once the --link contract is resolved
     • the root AGENTS.md
   • Compare the generated .agentic/profile.yaml, AGENTS.md, vendor outputs, and CLI behavior with current expectations.
   • If self-hosting reveals blockers, record them explicitly rather than broadening the implementation silently.

10. Sequence the work as surgical PRs.

• Recommended chain:
  • PR0: confirm target branch and freeze CLI contract, including the --link decision
  • PR1: bootstrap Go module, Cobra root, version, help, list, discovery logic, and Go unit tests
  • PR2: add compose, deploy, switch, sync, init, and uninstall as Go commands delegating to Bash scripts
  • PR3: update CI to build/test the Go CLI on PRs
  • PR4: add release automation and migrate installer paths to binaries
  • PR5: remove stale user-facing just references once the binary install flow is real
  • PR6+: port selected Bash backends to Go only after parity tests exist for each migrated behavior

Files likely affected

• New Go sources
  • go.mod
  • go.sum
  • cmd/agentic/main.go
  • internal/cli/root.go
  • internal/cli/deploy.go
  • internal/cli/compose.go
  • internal/cli/init.go
  • internal/cli/switch.go
  • internal/cli/sync.go
  • internal/cli/list.go
  • internal/cli/uninstall.go
  • internal/cli/version.go
  • internal/application/discovery/*.go
  • internal/application/runtime/*.go
  • internal/infrastructure/fs/*.go
  • internal/infrastructure/shell/*.go
• Existing CLI/install entrypoints
  • bin/agentic
  • tooling/lib/install.sh
  • install.sh
  • VERSION
• CI and release automation
  • .github/workflows/validate.yml
  • new .github/workflows/release*.yml
  • optional .goreleaser.yaml
• Documentation
  • README.md
  • docs/commands.md
  • docs/getting-started/installation.md
  • docs/getting-started/quickstart.md
  • docs/customization.md
  • docs/vendors.md
  • vendors/codex/README.md
• Existing Bash tests and new Go tests
  • tooling/lib/test.sh
  • internal/.../*_test.go
  • optional test/e2e/...

Tests to add or update

• Add a pre-port contract gate:
  • extend Bash-side tests first if needed to lock in the chosen --link behavior for deploy and compose
  • do not let the Go rewrite define behavior that the Bash CLI never tested
• Add Go unit tests for command parsing and help output.
  • Cover root, deploy, compose, init, switch, sync, list, uninstall, and version
  • Assert argument arity, error text, and help routing behavior currently covered by T44-T57
• Add Go unit tests for discovery precedence.
  • Cover AGENTIC_REPO_ROOT, AGENTIC_ROOT, .agentic/config.yaml agentic_root, target auto-detection from nested directories, and the missing-library error path
• Add Go integration tests around shell delegation.
  • Cover compose --full
  • cover the chosen --link behavior once frozen
  • cover deploy --skills ...
  • cover init --sync
  • cover init --no-sync
  • cover switch list
  • cover sync preserving active vendors
• Keep and continue running the Bash suite in tooling/lib/test.sh.
  • Do not delete or weaken T44-T57, T60-T66, or T99-T103 during early PRs
  • If any backend behavior is ported from Bash to Go later, add equivalent Go coverage before removing the corresponding shell-path dependency
• Add CI build verification for the Go binary before adding release automation.
  • The PR workflow should at least compile the Go CLI and run Go tests once Go code lands
• Add release/build verification when release workflows arrive.
  • Verify asset names, architecture mapping, and install-script expectations explicitly
• Update doc-related validation once installer or command examples change.
  • docs-build must still pass after any user-facing command-installation edits

Risks and unknowns

• Public API baseline is currently ambiguous because docs/commands.md documents --link while tooling/lib/cli.sh does not parse it. Migrating without resolving that first would codify the wrong contract.
• The local checkout does not contain v2, so the requested PR-target strategy is currently unresolved.
• The binary likely cannot be fully standalone in this issue without a much larger scope increase because the repository still contains profiles, fragments, skills, schemas, vendor templates, and Bash backends.
• The current remote installer fundamentally depends on cloning the repo and invoking just install. Removing just from docs without replacing that behavior would be a regression in clarity.
• Windows support is unclear because current link mode is explicitly POSIX-oriented and symlink behavior plus installer expectations may make Windows a separate follow-up.
• Output compatibility matters because existing users may depend on help text, exit codes, discovery precedence, installer messages, and auto-detection behavior even if those behaviors are not formally versioned.

Dependencies or blockers

• Confirm the v2 branch strategy for the chained PR series before implementation starts.
• Decide the --link contract before porting command parsing.
• Decide the first binary distribution milestone:
  • compile in CI only
  • or compile and publish release assets
• Decide whether bin/agentic remains as a repo-local wrapper during transition or is replaced later after install/release work lands.
• Confirm that the first Go milestone is allowed to keep delegating to Bash backends.
• Add Go toolchain setup to CI once Go code lands.

Execution checklist

1. Confirm whether v2 exists and is the intended PR target; stop and document the blocker if not.
2. Capture the current CLI contract from tooling/lib/cli.sh, tooling/lib/test.sh, and docs/commands.md.
3. Resolve the --link parity decision and codify it in tests before the Go port.
4. Bootstrap the Go module and Cobra root command using the repo’s Go/Cobra conventions.
5. Implement Go versions of library discovery and target discovery with unit tests.
6. Port read-only commands first: version, help, and list.
7. Add Go command wrappers for compose, deploy, switch, sync, init, and uninstall that delegate to existing Bash scripts.
8. Update CI so PRs build the Go binary and run Go tests alongside the existing Bash suite.
9. Run the dogfooding spike with golang-hexagonal-cobra-cli and the root AGENTS.md once the chosen link-mode contract is available.
10. Add release automation and migrate installer paths to built binaries.
11. Remove stale user-facing just references only after installer/runtime behavior no longer depends on them.
12. Only begin porting Bash backends into Go after the CLI front-end, CI, tests, installer, and release assets are stable.

Suggested worker prompt

Implement Issue #99 in small, reviewable steps on top of the existing repository without breaking the current Bash tooling contract.

Constraints:

• Keep the public agentic command surface stable after a deliberate contract-freeze decision.
• Use Cobra for the new CLI.
• Do not remove the Bash backends or tooling/lib/test.sh yet.
• Prefer a first milestone of “Go CLI delegating to Bash backends”.
• Do not remove user-facing just references until installer behavior truly no longer depends on just.
• Do not start coding until the v2 branch strategy is confirmed.

Concrete requirements:

• Add a Go module and a Cobra-based binary under cmd/agentic/.
• Add separate command files for deploy, compose, init, switch, sync, list, uninstall, and version.
• Re-implement library and target discovery from tooling/lib/common.sh in Go, preserving precedence and error behavior.
• Add a shell runner abstraction so Go commands can invoke existing scripts in tooling/lib/*.sh.
• Keep compose, deploy, switch, sync, init, and uninstall delegating to the current shell scripts for the first implementation pass.
• Before the Go port, decide how to handle the current --link docs/implementation mismatch and codify that decision in tests.
• Add Go tests covering CLI help/version/list/discovery and the main argument-validation paths already exercised by T44-T57 and T99-T103 in tooling/lib/test.sh.
• Preserve the Bash suite and make sure it still passes.
• Add Go build/test steps to CI once Go code lands.
• Migrate installer and release behavior in a later PR after the Go front-end is stable.
• Update end-user docs only when the new binary-based install flow is real.

Definition of done for the first stable milestone:

• agentic command parsing and dispatch are backed by Go/Cobra.
• Current shell backends still perform the substantive work.
• Existing Bash tests still run.
• New Go tests cover the new front-end behavior.
• CI builds and tests the Go CLI.
• Installer and binary-release work can land in the next milestone without reopening the command contract.

[soulcodex]

Reviewed Implementation Plan (Refreshed)

Issue #99 — feat(migration): migrate out agentic to golang or rust

Plan refreshed against latest main state:

• Base commit reviewed: e20e844998d9ac63ddd0236690e376a4ef8e5428
• Context includes latest merged orchestration work from PR feat(tooling): add opt-in portable agents sync #134.

Why this refresh

The migration should avoid a big-bang rewrite and keep agentic stable while moving to Go/Cobra.
This plan slices work into small PRs, adds explicit dogfooding checkpoints, introduces periodic update checks, and defines release/versioning rollout via release-please starting at v1.0.0 once the Go rewrite is published.

Guardrails

1. Public CLI contract remains stable (agentic <command> behavior parity first).
2. Bash backend stays until Go parity tests exist for migrated paths.
3. No large rewrite PRs; every PR is independently reviewable and releasable.
4. Dogfooding is required: use agentic to evolve agentic.
5. User-facing docs must stop prescribing just for end-user CLI flows once binary flow is live.

PR Slices (no big-bang)

PR1 — Contract Freeze + Branching + Migration Scaffolding

Scope:

• Freeze CLI UX contract from current shell CLI/help/errors.
• Capture argument/exit-code behavior in tests.
• Add migration ADR and branch strategy (v2 chain if required).

Deliverables:

• Contract test matrix (command-by-command parity target).
• ADR for “Go CLI front-end, Bash backend first”.
• CI sanity remains green.

PR2 — Go Bootstrap (Cobra shell only)

Scope:

• Add go.mod, Cobra root command, version/help/list first.
• Keep operational commands delegated to existing Bash scripts.

Deliverables:

• cmd/agentic/main.go
• internal/cli/* for root/version/help/list
• Go unit tests for parsing/help/version
• CI: Go build + Go tests added (without removing Bash tests)

PR3 — Command Delegation Parity (compose/deploy/sync/switch/init/uninstall)

Scope:

• Implement full command tree in Go.
• Delegate execution to existing shell scripts.
• Preserve discovery precedence and target detection behavior.

Deliverables:

• Parity tests for command args/errors/exit-codes.
• Shared runner abstraction in Go.
• No behavior regressions versus existing CLI suite.

PR4 — Dogfooding Phase 1 (Build agentic with agentic)

Scope:

• Use profile golang-hexagonal-cobra-cli and --link mode against this repo.
• Compose/sync the project using the new CLI path.
• Keep current AGENTS instructions as source of truth.

Deliverables:

• Dogfooding report in issue comment.
• Gaps/bugs opened as linked follow-up issues.

PR5 — Incremental Backend Porting to Go (selected low-risk paths)

Scope:

• Port smallest backend components first (read-only/low side effects).
• Keep shell scripts for non-ported paths.
• Add parity tests before switching each command path.

Deliverables:

• One or two command internals fully native Go.
• Shell fallback retained for remaining commands.

PR6 — Periodic Update Check (every 48h)

Scope:

• Add non-blocking version check on CLI invocation (Oh-My-Zsh style cadence).
• Check at most once every 48h per user/machine.

Behavior:

• Cache file in user cache dir (e.g. ~/.cache/agentic/update-check.json).
• If last check < 48h: skip network call.
• If newer release exists: print concise opt-in upgrade hint.
• Never fail command execution if check fails.

Controls:

• AGENTIC_NO_UPDATE_CHECK=1 to disable.
• Optional agentic config flag later if needed.

PR7 — Distribution + Installer Migration (binary-first)

Scope:

• Publish multi-arch binaries.
• Move installer flow away from repo-clone + just dependency for end users.

Targets (minimum):

• linux/amd64, linux/arm64, darwin/amd64, darwin/arm64

Deliverables:

• Updated install scripts consuming release binaries.
• User docs updated for binary install flow.
• Remove end-user references that require just.

PR8 — Release Please + v1.0.0 Cutover

Scope:

• Add release-please workflow to manage semantic version PRs/tags/changelog.
• Start versioning from v1.0.0 after rewrite is complete and publish-ready.

Deliverables:

• .github/workflows/release-please.yml
• release-please config/manifest files
• release flow connected to binary publish job
• first release PR/tag pipeline validated

PR9 — Bash Decommission (only after parity)

Scope:

• Remove shell paths only after Go parity is demonstrated by tests/coverage.
• Keep backward-safe wrappers where needed for transition.

Deliverables:

• Removal checklist completed.
• CI no longer depends on legacy shell runtime for migrated commands.

Dogfooding Acceptance Criteria

• agentic compose, agentic sync, agentic switch, agentic deploy operate on this repo via Go CLI path.
• golang-hexagonal-cobra-cli profile is used in at least one documented dogfooding pass.
• Defects found during dogfooding are linked and triaged before release cut.

CI/Versioning End State

After rewrite completion:

1. PR CI: Bash suite + Go unit/integration + lint.
2. Release-please: automated release PR/version management.
3. Release publish: multi-arch binaries attached to GitHub Releases.
4. Runtime update check: every 48h, non-blocking, user-overridable.

Dependencies / Blockers

• Confirm v2 chained-PR target policy (if enforced).
• Decide first backend slice to port natively in PR5.
• Confirm whether Windows is in or out for first binary release wave.

Execution order recommendation

PR1 -> PR2 -> PR3 -> PR4 -> PR5 -> PR6 -> PR7 -> PR8 -> PR9

This keeps risk low, preserves continuity, and gives a clean path to v1.0.0 with release automation.

[soulcodex]

Alternative Deep Plan — Rust Migration Track for Issue #99

This is an alternative to the Go path: same migration intent, but using Rust as the CLI implementation language.

Research Baseline (current repo)

Validated against origin/main (e20e844):

• Public CLI today is shell-based (bin/agentic + tooling/lib/cli.sh).
• Backends are shell scripts under tooling/lib/*.sh.
• Test surface is broad (tooling/lib/test.sh has 150+ named tests, currently 500+ assertions in CI runs).
• Current critical contracts include:
  • command parsing and discovery (discover_library, discover_target)
  • active vendor state (active_vendors)
  • orchestration switching paths (.codex/agents, .opencode/agents)
  • MCP source-of-truth now fixed to .agentic/mcp.yaml
  • installer and sync behavior

Conclusion: a safe migration should start as a Rust front-end that preserves backend behavior before backend rewrites.

Why Rust can be a strong fit here

• Predictable single-binary distribution for multi-arch releases.
• Strong CLI ecosystem (clap, anstyle, anyhow/thiserror).
• Good structured config parsing (serde, serde_yaml, serde_json).
• Strong test ergonomics (cargo test, integration tests under tests/).

Trade-off:

• Higher initial implementation complexity than shell.
• Must avoid big-bang rewrites to keep parity and contributor confidence.

Migration Principles

1. Preserve current CLI contract first; implementation language changes, behavior doesn’t.
2. Rust CLI delegates to shell backends initially.
3. Backend rewrites happen command-by-command, only after parity tests exist.
4. Dogfooding is mandatory before v1.0.0 cut.
5. Keep PRs surgical and chain-linked to this issue.

Proposed PR Slices (Rust)

PR1 — Contract Freeze + Rust Workspace Bootstrap

Scope:

• Freeze public command contract from current CLI/help/errors.
• Add Rust workspace skeleton.
• Add architecture docs and migration ADR.

Deliverables:

• Cargo.toml, src/main.rs (or crates/agentic-cli).
• ADR: “Rust front-end first, shell backends retained initially”.
• Contract test inventory mapped from existing shell tests.

PR2 — Rust Read-only Commands (no mutations)

Scope:

• Implement version, help, list in Rust.
• Reproduce output shape and exit codes.

Deliverables:

• clap command tree for read-only commands.
• Rust unit/integration tests.
• Keep shell CLI as fallback for remaining commands.

PR3 — Discovery & Target Resolution Parity

Scope:

• Port discover_library and discover_target logic to Rust.
• Preserve precedence semantics and error messages.

Deliverables:

• Rust module for discovery.
• Parity tests for env/config/directory traversal behavior.

PR4 — Delegating Rust Commands (compose/deploy/sync/switch/init/uninstall)

Scope:

• Implement full command surface in Rust.
• Delegate execution to current shell scripts via std::process::Command.

Deliverables:

• Stable command UX in Rust.
• Backend behavior unchanged (still shell).
• CI runs shell tests + rust tests together.

PR5 — Dogfooding Phase 1 (agentic builds agentic)

Scope:

• Use agentic to manage this repository with Rust CLI path.
• Use profile golang-hexagonal-cobra-cli and --link flow for comparative migration discipline.

Deliverables:

• Dogfooding report posted in issue.
• Found gaps converted to linked issues/PR tasks.

PR6 — 48h Update Check (Oh-My-Zsh-like cadence)

Scope:

• Add periodic update check when agentic is invoked.
• Check at most once every 48h.

Behavior:

• Cache file in user cache dir (e.g. ~/.cache/agentic/update-check.json).
• If cached check < 48h, skip remote call.
• If newer version exists, print concise upgrade notice.
• Must be non-blocking and non-fatal.

Controls:

• AGENTIC_NO_UPDATE_CHECK=1 disables check.
• Future config knob can be added later.

PR7 — First Native Rust Backend Slice (low-risk)

Scope:

• Port a low-risk backend path first (recommended: validation/discovery-adjacent, not full compose).
• Keep shell fallback for non-ported operations.

Deliverables:

• Clear parity tests before switch-over.
• No regressions in existing shell suite.

PR8 — Incremental Backend Porting (high-impact paths)

Scope:

• Port command internals one by one (compose, switch, sync, etc.).
• Maintain equivalent outputs/filesystem behavior.

Deliverables:

• Per-command parity gates.
• Shell fallback removal only after parity pass.

PR9 — Release Automation with release-please (start at v1.0.0)

Scope:

• Add release-please config and workflow.
• Configure semantic release PRs/tags.
• Coordinate artifact publication (multi-arch binaries).

Deliverables:

• .github/workflows/release-please.yml
• release-please config/manifest
• initial version baseline at v1.0.0 after rewrite publish readiness

PR10 — Installer Migration + Docs Cleanup

Scope:

• Move install flow to binary-first (no repo clone requirement for end users).
• Remove end-user references to just where no longer needed.

Deliverables:

• Installer path consumes release artifacts.
• Docs updated (docs/commands.md, installation docs, vendor docs).

PR11 — Bash Decommission Gate

Scope:

• Remove legacy shell command paths only after parity metrics are met.

Exit criteria:

• Rust integration tests cover migrated behavior.
• CI green without shell dependency for migrated commands.

Dogfooding Protocol (explicit)

• Run Rust CLI against this repo as daily driver during migration.
• Use agentic-managed workflows (compose/sync/switch/deploy) on this repository itself.
• Track “dogfood incidents” as linked issues with severity.
• Require zero high-severity open dogfood incidents before v1.0.0 publish.

CI/Quality Strategy

• Keep existing shell validation in place until parity cutover.
• Add Rust lint/test/build jobs incrementally:
  • cargo fmt --check
  • cargo clippy -- -D warnings
  • cargo test
• Keep release jobs separate from PR validation jobs.

Risks / Unknowns

• Exact parity of CLI output/error messages can be tricky across languages.
• File/symlink semantics and platform differences need strict integration tests.
• Releasing binaries changes operational expectations; installer migration must be explicit.

Recommended Execution Order

PR1 -> PR2 -> PR3 -> PR4 -> PR5 -> PR6 -> PR7 -> PR8 -> PR9 -> PR10 -> PR11

This keeps migration controlled, auditable, and releasable with minimal disruption.