[RFC]: External construction from user IDEs

# RFC: External construction from developer IDEs

## Summary

Collaborative AI-DLC keeps full control of the workflow.
When a construction unit reaches `code-generation`, users can let the autonomous workflow continue (like today) or a developer can claim it, prepare and validate its `code-generation-plan` in Collaborative AI-DLC, then develop the code on an assigned Git branch in their own IDE, alone or with a local agent.
When finished, they submit the commit SHA from that branch.
Collaborative AI-DLC verifies that exact commit, creates and validates the `code-summary` online, runs the existing server-side checks and review, then resumes its normal lane reconciliation and merge flow.
Local development changes source code only; it never writes canonical graph artifacts.

## Motivation

Construction currently runs in hosted AgentCore workspaces. This preserves workflow control and validation, but prevents users (developers) from using their own IDE, debugger, local tools, and coding agents.

Some developers and organizations are also not ready to let an agent implement code autonomously. They may need to retain direct control for security, compliance, code-quality, adoption, or accountability reasons. They should be able to use Collaborative AI-DLC's planning, context, validation, and traceability while choosing whether the source code is written manually, reviewed continuously, or assisted by a local agent.

The goal is to let a developer implement an assigned unit locally without creating a second workflow engine on their machine. Collaborative AI-DLC must remain the authority for:

- which unit is ready;
- who owns it and for how long;
- the plan, questions, summary, and other graph artifacts;
- validation, review, merge, retry, rewind, and cancellation.

## Detailed design

### The simple flow

This is the intended user experience:

```mermaid
sequenceDiagram
participant W as Collaborative AI-DLC workflow
participant D as Developer in Collaborative AI-DLC
participant I as Developer IDE or local agent
participant V as Collaborative AI-DLC validation

W->>D: Unit reaches code-generation and becomes claimable
D->>W: Claim the unit
Note over W,D: The unit is locked to this developer
D->>W: Prepare and validate the code-generation plan online
W->>D: Give branch, task, graph context, and development bundle
D->>I: Clone or open repository on assigned branch
D->>I: Code, test, commit, and push
D->>W: Submit the final commit SHA
W->>V: Verify the SHA and freeze the submitted revision
V->>D: Create the code summary online for review or enrichment
D->>V: Validate the summary
V->>W: Run checks and review, then reconcile and merge normally
```

In prose:

1. **The workflow makes a unit claimable.** It has reached `code-generation` and its dependencies are already satisfied. The current walking-skeleton and dependency-wave scheduling stay unchanged.
2. **A developer claims the unit in Collaborative AI-DLC.** The claim locks that unit to that developer. Nobody else can claim it, submit code for it, or advance it. The rest of the workflow can still progress on independent units.
3. **The developer prepares the plan online.** Collaborative AI-DLC shows the task, its graph context, and any required questions. The developer produces and validates the canonical `code-generation-plan` there.
4. **Collaborative AI-DLC gives access to local development.** Only after plan validation does it create/assign the unit branch and show the developer the branch name, base commit, task, context, rules, expected source-code outcome, and validation expectations.
5. **The developer develops locally.** They clone or open the repository, checkout the assigned branch, then code, test, commit, and push normally. They may use a local coding agent.
6. **The developer submits one commit SHA.** This means “validate this exact revision.” The SHA is necessary because a Git branch can move after it is pushed.
7. **Collaborative AI-DLC takes control again.** It verifies that the submitted SHA is the head of the assigned branch and descends from the expected base, then freezes that revision while it finalizes the unit. The unit is not claimable again at this point.
8. **The summary and review happen online.** Collaborative AI-DLC creates the canonical `code-summary` from the accepted diff, the plan, test evidence, and comments. The developer can review or enrich it. The platform then runs sensors, reviewer checks, lane reconciliation, and the existing merge or PR flow.

### What the claim locks

The claim is one temporary lease for one exact unit and one workflow attempt. It is not a lock on the whole intent or project.

While claimed:

- another developer cannot claim the same unit;
- the workflow cannot skip the developer's work and advance that unit;
- the developer cannot act on another unit through this claim;
- independent ready units may still be claimed and developed in parallel.

The lock has a heartbeat and expiry. The claimant can release it. An authorized user can revoke it. Cancellation, rewind, and retry revoke it automatically. In all of these cases, work held by the old client cannot later be submitted into the new attempt.

### What is online and what is local

| Concern | Collaborative AI-DLC | Local IDE or agent |
| --- | --- | --- |
| Workflow state, gates, and ownership | Owns | Cannot change |
| `code-generation-plan` | Created and validated online before development | Reads |
| Source code | Verifies and integrates Git revision | Writes, tests, commits, pushes |
| Graph context | Provides canonical data | Reads only |
| Questions and comments | Stores and shows them | Can ask/add |
| `code-summary` | Creates and validates online after SHA submission | Can provide comments/evidence |
| Validation, review, merge | Runs and decides | May run local tests as non-authoritative evidence |

This is intentional: local work is only source-code work. There is no risk that a local agent leaves half-written methodology documents in the graph or advances workflow state by mistake.

### Commit SHA submission

Pushing does not resume the workflow. A developer can push as often as they need while working.

The workflow resumes only when the claimant explicitly submits a SHA. The submitted SHA is the immutable candidate for this attempt. Before accepting it, Collaborative AI-DLC checks:

- the branch is the branch assigned to this unit;
- the branch head equals the submitted SHA;
- the SHA descends from the base commit assigned at plan validation;
- the active claimant and current attempt submitted it;
- project path and protected-file policies pass.

The server then checks out that exact revision in an isolated workspace. It calculates the changed files itself and does not trust a client-provided diff or test result.

### Local agent and MCP access

A local agent does not run the workflow. It can receive the same development bundle as the human developer: task, plan, relevant graph context, rules, branch details, and validation expectations.

An optional remote MCP gateway lets the agent:

- read the graph context that belongs to its assigned unit;
- ask a question through the existing Collaborative AI-DLC gate flow;
- read answers and steering;
- add a session comment, for example: “the interface now has parameter `foo` because ...”.

The MCP gateway cannot create or edit canonical graph artifacts, choose another unit, advance a stage, submit a SHA, merge code, or access AWS credentials. Questions and comments are session events. They are available to help generate the summary and guide code review, but are not methodology artifacts.

Manual developers do not need an agent or MCP. The UI or CLI provides the same read, question, comment, heartbeat, release, and submit operations.

### Optional IDE and remote workspace integrations

The initial workflow is IDE-neutral: the developer receives a branch and opens it with their existing tooling. A later convenience feature can launch a prepared workspace directly from the claimed unit, for example through VS Code Remote, Dev Containers, GitHub Codespaces, a managed browser workspace, or a JetBrains equivalent.

Such an integration may:

- clone or open the assigned branch;
- install the project’s declared development environment;
- make the read-only development bundle and MCP configuration available;
- show claim status, questions, comments, and SHA submission in the IDE.

It does not change the workflow contract. Collaborative AI-DLC still owns the claim, online plan and summary, graph state, SHA acceptance, validation, review, and merge. This lets the product improve developer ergonomics without tying the core design to VS Code or any specific workspace provider.

### Platform finalization

Hosted AgentCore and external development should share the same server-side finalizer. For an external submission, it:

1. fences the session and freezes the submitted SHA;
2. verifies the Git handoff;
3. prepares the online `code-summary`;
4. runs deterministic sensors and reviewer checks against the accepted revision;
5. records the accepted SHA, changed files, evidence, and outcome;
6. completes the existing stage callback only on success.

Local test results are useful input, but never replace server-side validation.

### Security and failure handling

The local client receives no Collaborative AI-DLC AWS credentials, provider tokens, or direct access to Neptune, DynamoDB, and S3. It uses its own Git-provider credentials to push its assigned branch.

Each session has a short-lived capability and a renewable lease generation. Every question, comment, heartbeat, and SHA submission is checked against the current unit, attempt, claimant, and lease. A stale client is rejected after expiry, release, cancel, rewind, retry, or revocation.

## Alternatives considered

### Run AI-DLC locally

The developer could run AI-DLC locally, including its code-generation plan, summary, workflow state, and agent harnesses. This is not retained because Collaborative AI-DLC and its orchestrator must remain the only source of truth. Running AI-DLC locally would give the checkout its own workflow state and risk disagreement about the current stage, questions, outputs, and completion. The local environment therefore performs source-code work only; the plan and summary remain in Collaborative AI-DLC.

### Generate Markdown artifacts into the repository

Collaborative AI-DLC could export graph artifacts as Markdown files alongside the source code so a local clone contains the task context and methodology documents. This is not retained because those files would duplicate the graph and create two potential sources of truth. The graph remains canonical; any local bundle is an ephemeral, read-only context snapshot outside the tracked repository.

### Expose the current MCP server remotely

The current MCP server could be exposed over HTTP so local AI-DLC clients can interact directly with Collaborative AI-DLC. This is a promising future direction for a native AI-DLC and Collaborative AI-DLC integration, potentially through an extension or plugin. It needs discussion and a joint integration design with the AI-DLC team, so it is not a dependency of the initial local-development flow.

## Breaking changes

This is additive. Hosted AgentCore remains the default and existing executions do not change.

The implementation adds external-session state, claim/lease APIs, online plan and summary screens, branch assignment, SHA submission, and a read-only remote MCP gateway. It also refactors hosted and external completion to share the same server-side finalizer.

## Open questions

1. For multi-repository units, must all repository SHAs be submitted atomically?
2. Which optional workspace integrations should follow the generic workflow: VS Code Remote, Dev Containers, Codespaces, managed browser workspaces, or JetBrains?

No files, tests, or implementation entry points are named in the RFC. Start by resolving the open questions and locating the existing hosted AgentCore finalization, workflow claim, branch, and MCP components; done requires an agreed design and implementation plan for external sessions without changing the hosted default.

Written by the indexing model from the issue text.