harmony/ROADMAP.md

Harmony roadmap

This file is the current priority index. Detailed plans under ROADMAP/ are working documents, not architecture decisions. The status written in an ADR's body is authoritative; fix any mismatch with the ADR index before relying on it.

Current sprint

The sprint goal is a production release of Harmony Fleet with deployment code that meets Harmony's UX/DX standard.

1. Keep the closed PR knowledge available without reviving its implementations. See the July 2026 PR archive.
2. Make harmony-fleet-deploy the clear path for deploying the production Fleet release. Reduce setup friction and remove accidental complexity without redesigning the framework during cleanup.
3. Validate the real production composition from a clean client: explicit target, noninteractive configuration, stable credentials, visible platform prerequisites, and truthful readiness reporting.
4. Cut and validate the next customer release.
5. Add production-equivalent Fleet deployment E2E to CI/CD immediately after that release, using a dedicated test cluster.

Framework direction

Use Fleet deployment as the current UX/DX case for framework changes. Simplify and release harmony-fleet-deploy before applying those changes to harmony_app or another client application.

Work in this area should:

• reuse existing Scores and capabilities before adding layers;
• keep app-specific behavior in deploy crates;
• move logic into Harmony only when it is demonstrably reusable;
• prefer small extractions, such as duplicated Helm/context handling, as separate changes;
• leave unresolved architecture choices to focused design work.

Deployment UX/DX bar

These are evaluation criteria, not settled API decisions.

• A new contributor can find the deploy path from the repository root and run the documented local path from a clean checkout.
• The same declaration drives local, E2E, and production deployment. The context supplies target-specific access and policy.
• Production always has an explicit target. Scripts and agents never encounter a hidden prompt or an implicit fallback.
• Common work is visible in --help and examples. Users should not need branch history, a specific checkout layout, or undocumented platform knowledge.
• Human output is concise and actionable. Automation gets stable exit codes and machine-readable results without scraping terminal decoration.
• Errors identify the failed component, expected state, observed state, and a useful next action. A successful command must not claim more readiness than it verified.
• Deploy code reads as application and platform intent. Kubernetes, Helm, and identity-provider details stay in the owning module unless the application genuinely needs to choose them.
• Humans and LLMs use the same documented interface. Do not build a parallel agent API to compensate for an ambiguous CLI or deployment model.

This follows established CLI practice around discoverability, explicit remote actions, noninteractive execution, stdout/stderr separation, and structured output. See the Command Line Interface Guidelines.

Evidence from a real application

A review of a real client application found useful evidence, but its proposed APIs are not accepted designs.

Verified against current code:

• The short ComposeDeploy example does not yet cover the real application, which still assembles lower-level Scores.
• ComposeDeploy supports one public endpoint. Capability environment wiring applies to every Compose service, PostgreSQL exports one fixed variable, and the current Zitadel capability covers only a simple PKCE application.
• The real deploy still duplicates namespace-derived names and some provider conventions. Those are concrete DRY problems.
• The application layer does not yet prove its full readiness claim; Helm acceptance is not application smoke-test success.
• The current app CLI has human-only, decorated output and no stable machine format. Its agent and CI contract remains design work.
• Several onboarding defects in the original review have since been fixed, including the branch dependency, vault path, OIDC redirect, and unsafe production refresh-key fallback.

Ideas such as a generic environment-wiring API, typed Score outputs, a generic secret loader, a Compose macro, a namespace topology marker, or a broad Zitadel capability need focused design and another real use case. Fleet does not use those application abstractions and does not validate them.

Decisions requiring project-lead review

These remain undecided:

• readiness and idempotency contracts;
• the long-term crate and harmony core boundaries;
• ADR-024 fleet decomposition;
• ADR-026 application CLI contract;
• the final production Fleet composition and context shape.

Active supporting tracks

Track	Document	Status
Fleet production hardening	Fleet v0.3	Needs revalidation against current code and ADR-025
Config consolidation	Config crate, migration	In progress
Application CLI	Unified CLI	Design input; reconcile with ADR-026 before implementation
Core cleanup	April code review	Backlog; verify each item before work
Monitoring	Tenant application monitoring	Design pending
OPNsense and bare metal	OPNsense, HA production	Separate customer track

Deferred plans

The remaining numbered plans are retained as backlog and historical context:

• Assets
• GitHub publication
• Simple E2E
• KVM E2E
• SSO and config hardening
• Firewall pair topology
• Named config instances

Do not infer priority from the phase number. Revalidate a plan against current code and accepted ADRs before implementing it.