Files
ai-engineering/docs/roadmap.md
T
Nilton Constantino bd2c9133da feat: add agent coordination and automatic work completion
Add portable topics and surveys, decision approval history, execution plans, local Codex and Claude adapters, and general agent routing. Consolidate Plan and EPIC results through deterministic completion receipts, reviewed cancellation scope and recoverable reconciliation.

Track the completed WRK-0001 and WRK-0002 records, protocol documentation, source manifests and delivery evidence.

Validation: 117 tests including Modulith; GraalVM 25 native compilation, standalone smoke and ZIP/TAR verification on macOS ARM64; identical persisted context across JVM and native executions.
2026-11-14 01:12:21 +00:00

144 lines
8.5 KiB
Markdown

# Roadmap
## Milestone 0 — Bootstrap
Implemented: Java 25, Spring Boot 4, non-web Picocli entry point, one Gradle Kotlin DSL
project with Wrapper, Modulith boundaries, help/version smoke tests, Spring AOT,
Native Image configuration and native archive tasks. Acceptance: clean tests and JAR
build pass, CLI terminates and errors are meaningful. Native results are tracked in
the experiment log, separately from configuration claims.
## Milestone 1 — Portable engineering protocol
Implemented: project discovery/init, schema 1 configuration, linked Git/submodule
registry and default read-only policy, stable Work IDs, local artifact workspaces,
discussion history, draft DECs, evidence integrity, structural validation and stable
Markdown/JSON context. Temporary-fixture tests cover continuity, independent Works,
multiple repositories and malformed/missing/unsafe state.
Simple projects are supported directly: initialize in an existing source folder
without Git, or register a single existing Git repository using `repo add app --path .`.
No enclosing workspace or additional repositories are required. Regression coverage
includes fresh processes without Git on PATH and single-repository root discovery.
Pilot usability improvements include explicit `work update` refinement and UTF-8
`discussion add --text-file` input. Scope fields can now be maintained through the CLI,
and long proposals can be authored as ordinary Markdown files before persistence.
Acceptance demonstration: initialize a project with two independent Git repositories,
create a Work referencing both, append discussion, persist a draft decision and
evidence, export context, then reconstruct the same context in independent processes
using only files. No framework state or model history may be required.
Platform release targets: Linux x86_64, macOS ARM64, macOS x86_64 and Windows x86_64.
The workflow builds the three available GraalVM 25 platforms. **macOS x86_64 is blocked
by upstream GraalVM 25 support removal**, documented in the
[official release notes](https://www.graalvm.org/release-notes/JDK_25/).
Do not substitute an older Java target or label an ARM binary as Intel. A future
distribution experiment must identify and validate a maintained compatible toolchain
before enabling that native release target. CI configuration is not evidence that CI
has run; see actual local results in experiments.
## Operational replacement baseline — expanded scope
Implemented after the initial milestones at the user's request: provider-neutral
discovery instructions and manifest, root `AGENTS.md` integration, explicit DEC
approval/rejection/revision with history, lightweight plans and dependent steps,
status/next-actions, mechanical completion checks, criterion evidence mappings,
canonical knowledge integration snapshots, retained archives and reversible reopening.
No old Agenda/Lesson entity or automatic housekeeping deletion is introduced.
Acceptance: a fresh process reads the entry contract and reconstructs an approved,
planned, evidenced, completed and archived Work; another execution reopens it with
prior conclusions and delivery history intact. Invalid approval, dependency, evidence
and revision-history states are diagnosed. No agent/provider service is required.
The test suite verifies mechanics, not an arbitrary external AI's compliance.
Continue piloting the installed entry files and CLI in an existing real project,
with an external agent continuing a Work through human-reviewed closure. The first
Discussion refinement slice is described below. A separate future importer must
preserve origins/history for open agendas and valuable legacy Lessons, integrating
knowledge into canonical docs instead of requiring Lesson artifacts.
## Milestone 2 — Discussion refinement (first contract slice)
PLN-0001 implements the explicitly approved first slice: topics, surveys with options
and free text, append-only answer revisions, reversible proposal dispositions, a small
AgentAdapter API, general fallback/specialized routing and two deterministic fixtures.
Run provenance, idempotent completed requests and source-staleness diagnostics remain
portable. The framework applies validated proposals; human approval stays explicit.
Acceptance experiment: one fake organizes two topics and a survey; fixture answers
are revised, evidence attached, and another fake continues from a fresh process with
an investigation, reversible archive and DEC draft. Unchanged context matches across
executions. This verifies the contract, not real semantic intelligence. Actual build
and native outcomes are recorded in [experiments](experiments.md).
The subsequent local CLI slice below implements the selected real transports;
fixtures remain the default acceptance-test baseline without external accounts.
## EPIC coordination — second approved slice
PLN-0002 implements DEC-0003: Works can coordinate derived Works through versioned
EPIC policies. Children are important by default, with explicit optional subsets,
decomposition-only delivery, cycle/multiple-parent rejection and nested coordination.
Important cancellation remains pending until scope/importance review. Automatic
completion requires explicit policy delegation, local readiness and valid important
deliveries; receipts distinguish system results from human delivery approvals.
Lifecycle commands propagate outcomes/reopenings and return a deterministic report.
Reconciliation recovers missed propagation from files without an LLM. Acceptance
covers independent processes, repeated notification, policy/scope changes, history,
important/optional/cancelled children and native standalone execution. Actual observed
results are recorded in [experiments](experiments.md).
The EPIC slice itself does not choose providers or execute child repository changes.
Agent-generated decomposition and the agenda/Lesson importer remain separate work.
## Local Codex/Claude adapters — third approved slice
PLN-0003 follows SVY-0001: both installed CLIs, for Discussion/synthesis proposals
validated by AIE. Implements fixed process arguments, private workspaces, schemas,
timeout/output/cleanup limits, safe diagnostics, general classification/routing,
RUN provenance, local doctor and guided init for general/activity executors.
Credentials remain with the provider. No provider is activated automatically in the
AIE source project. Native distribution and ordinary protocol use still need no JVM,
Node or model service; optional real runs require the chosen CLI/authentication.
Acceptance uses deterministic JDK subprocess fixtures, including failure, invalid
output, ownership, timeout/descendants, cleanup and fresh-process reconstruction.
Bounded real-provider checks and native outcomes are reported separately in
[experiments](experiments.md). Provider-native config profiles, direct APIs, source
editing/execution and a generic orchestration engine are outside this slice.
## Plan consolidation — approved execution-state slice
WRK-0002/DEC-0001 adds a separately approved execution-state slice before further
OODA work: deterministic Step → Plan → Work consolidation, reviewed cancellation
scope, pending commitments, system receipts, idempotent recovery and EPIC propagation.
Acceptance requires offline multi-Plan/no-model tests, legacy/fresh-process continuity,
Modulith and actual local native/distribution verification. This is protocol state
management, not an autonomous OODA engine. Results are recorded in experiments.md.
## Milestone 3 — Adaptive OODA (design only)
Add observations, orientation, operational decisions and Attempts using the conceptual
contracts in protocol.md. Acceptance: experiment evidence changes the next action;
history prevents repeating an invalidated attempt without a stated new hypothesis.
No rigid Observe→Orient→Decide→Act pipeline or autonomous engine is implemented now.
## Milestone 4 — Coordinated repositories (design only)
Add per-Work permissions, independent worktrees, exact source revisions, coordinated
validation and separate commit outcomes. Acceptance: partial success in one repository
remains visible; destructive actions, push and merge require explicit authorization.
Never assume atomic commit across repositories.
## Milestone 5 — Extended knowledge integration and conformance (design only)
Extend the operational baseline's explicit human-reviewed mappings with richer
checks against evidence; identify impacted canonical specs, tests,
code and documentation; expose conformance checks to agents and CI. Acceptance: a Work
can demonstrate its outcome and preserve actionable knowledge without a mandatory
Lesson model or redundant documentation trail.