[Feature]: Export AIDLC workflow assets for local development

[jeromevdl]

Description

Allow a user to export an intent's current workflow and generated assets into a self-contained bundle that can be placed in a local repository and resumed with the native AI-DLC workflow from an IDE or CLI.

The export should:

1. Use the native harness for the intent's configured agent CLI by default.
2. Preserve the effective workflow composition used by the intent.
3. Include the current generated Markdown artifacts in native AI-DLC paths.
4. Reconstruct enough native state to continue at the first unfinished stage.
5. Exclude source code, credentials, session data, and secret values.

The export is a point-in-time, one-way handoff. Changes made locally are not synchronized back to the collaborative run.

Use case

Users may want to run the workflow locally, especially developers during construction phase (code-generation), because they are used to work in an IDE or with a CLI.

Fast path / first step of #324.

Area

Backend (Lambda)

Additional context

Current State

The data needed for an export exists, but it is split across several stores:

• DynamoDB stores workflow and block metadata.
• S3 stores content-addressed block bodies and scripts under blocks/bodies/sha256/ and blocks/scripts/sha256/.
• S3 stores the collaborative runtime machinery under aidlc-runtime/<ref>/, but this is not a complete native harness distribution.
• DynamoDB stores intent process state, stages, attempts, gates, effective workflow information, and the selected agentCli.
• Neptune stores the current generated artifact heads, including Markdown content and the stage or unit that produced each artifact.
• S3 stores project custom rules and intent attachments.

The collaborative runtime does not persist a native AI-DLC workspace. It clones source repositories and writes transient .aidlc prompt and CLI configuration files, while authoritative execution state remains in DynamoDB and Neptune. In particular, it does not create:

• aidlc-state.md
• Native audit shards
• Native phase and stage artifact directories
• A complete .claude, .codex, .kiro, or opencode harness

An export therefore cannot copy an existing S3 prefix. It must project the collaborative data model into a native AI-DLC workspace.

Native AI-DLC State Version 7 stores an intent under:

aidlc/spaces/<space>/intents/<date-label>/

Normal artifacts live under phase and producer-stage paths. Construction artifacts may also be scoped by unit, while reverse-engineering artifacts live in the space-level codekb/<repository>/ tree. Native state supports per-stage EXECUTE and SKIP suffix overrides. The exporter emits every stage from the harness stage graph and marks every non-selected stage [S], so the stock scope grid cannot re-enable a stage omitted by the collaborative composition.

Version Fidelity

Workflow planning and AgentCore now resolve each placed stage through its recorded tenant and pinned version. This closes the stage-version drift that previously allowed a workflow snapshot to execute against LATEST.

The native distribution still owns its methodology stage, agent, sensor, rule, and knowledge files. Phase one accepts custom compositions of the stock native methodology and project-uploaded Markdown rules, but rejects an intent that resolves an edited methodology block. The rejection lists the incompatible block IDs. A later version may add a validated native overlay format.

Proposed Behavior

Export Request

Add an authenticated endpoint:

POST /projects/{projectId}/intents/{intentId}/export

Request:

{
  "harness": "codex"
}

harness is optional and supports:

• claude
• codex
• kiro
• kiro-ide
• opencode

When omitted, it defaults to the intent's stored agentCli. The existing kiro agent value maps to Kiro CLI; Kiro IDE is an explicit override.

The response is:

{
  "downloadUrl": "<short-lived presigned URL>",
  "filename": "aidlc-<intent-label>-<export-id>.zip",
  "expiresAt": "<timestamp>",
  "warnings": []
}

The service creates the archive under:

workflow-exports/<intentId>/<exportId>.zip

The presigned download URL should be short-lived, and an S3 lifecycle rule should delete generated exports after one day.

Snapshot Semantics

Version 1 supports intents in stable states:

• DRAFT
• WAITING
• FAILED
• CANCELLED
• SUCCEEDED

A changing RUNNING intent is rejected with 409 Conflict because DynamoDB stage state and Neptune artifact heads cannot be read atomically. A later version can support an explicit pause-and-export operation if required.

Exporting does not pause, cancel, or otherwise mutate the intent.

The bundle contains current artifact heads only. Archived artifact revisions, agent transcripts, CLI session stores, and source repositories are excluded. For a multi-repository intent, the user extracts the bundle into an empty workspace directory and uses native AI-DLC's repos.json and aidlc-workspace-sync support to clone the recorded branches as sibling repositories.

Bundle Contents

The archive contains:

• The selected native AI-DLC harness distribution.
• State-file EXECUTE/SKIP overrides representing the intent's effective composition over the complete native stage graph.
• The commit-pinned stock native methodology and applicable project custom rules.
• State Version 7 files for the exported intent.
• Generated Markdown artifacts in canonical native paths.
• Native intents.json repository metadata.
• A native repos.json for multi-repository workspace reproduction.
• export-manifest.json with provenance and checksums.

The exporter does not introduce handoff-specific Markdown documents. Workflow context must be represented through existing native state, audit, artifact, memory, knowledge, and rule structures. Transport-only information belongs in export-manifest.json and is not a methodology artifact.

The manifest includes:

• Source project and intent IDs
• Intent title and source branch
• Workflow ID and version
• Native upstream ref and distribution version
• Selected harness
• Effective composition grid and skip overlay
• Repository clone URLs, branches, and expected base revisions
• Export timestamp
• File checksums
• Compatibility warnings

State Projection

The exporter aggregates stage instances and attempts into native stage state:

• A fully successful stage is [x].
• A stage excluded by the effective workflow is [S].
• The first unfinished stage is [-].
• Later unfinished stages are [ ].

Failed or partially completed stages are rerun locally. An open cloud human gate is not transplanted as a live callback; its stage becomes the first unfinished stage and is rerun using the native workflow.

For per-unit construction stages, the exporter aggregates attempts by unit and only marks the stage complete when every required unit completed successfully. The generated audit records explain any aggregation or rerun decision.

Artifact Projection

Use the artifact's canonical artifactType, not an agent-selected display ID, to determine its filename.

Write mapped artifact heads to:

# Normal artifact
<intent-record>/<phase>/<producer-stage>/<artifact-type>.md

# Per-unit construction artifact
<intent-record>/construction/<unit>/<producer-stage>/<artifact-type>.md

# Reverse-engineering artifact
aidlc/spaces/<space>/codekb/<repository>/<artifact-type>.md

An artifact that cannot be mapped to a declared native path is a compatibility failure. Return 409 Conflict with the artifact identity and mapping reason. The exporter must neither drop it nor invent a non-native Markdown location.

Multi-Repository Workspace

For intents with multiple repositories, export one native workspace root:

<workspace>/
|-- <harness-directory>/
|-- aidlc/
`-- repos.json

The native intent registry records the repository directory names. The generated repos.json records each clone URL and the intent branch that should be checked out for a new clone. Source repositories are not placed in the archive.

After extraction, the user runs the selected harness's existing aidlc-workspace-sync tool. It clones missing repositories as siblings and generates aidlc.code-workspace. The developer's own Git credentials are used.

The export UI, rather than a generated Markdown README, presents the extraction, workspace-sync, doctor, and resume instructions.

Compatibility Validation

Before creating an archive, validate that the effective collaborative workflow can be represented by native AI-DLC:

• Supported native phases
• Supported stage execution modes
• Valid stage dependencies and ordering
• Known artifact definitions
• Resolvable pinned block versions
• A compatible native distribution for the selected harness
• Safe, collision-free native paths

Return 409 Conflict with structured incompatibility details when the workflow cannot be projected. A best-effort executable bundle is more dangerous than an explicit rejection because it can resume with different
instructions from the cloud run.

Security and Privacy

• Require project membership for every export.
• Do not include OAuth tokens, API keys, MCP secret values, environment secret values, CLI credentials, session stores, or Git credentials.
• Include project rules only when they are part of the intent's effective workflow context.
• Sanitize user-controlled names before using them as paths or filenames.
• Log export identity and outcome, but not artifact bodies or secret-bearing configuration.
• Apply S3 encryption, short URL expiry, and lifecycle deletion.