How AI-DLC Handles Session Continuity When Resuming a Project

AI-DLC maintains seamless session continuity by persisting project state in aidlc-docs/aidlc-state.md and automatically reloading context through a tiered artifact loading strategy when users return to existing workflows.

When working with the awslabs/aidlc-workflows repository, developers can pause AI-DLC projects and resume them later without losing context. The system implements a robust state management mechanism that detects existing projects, renders personalized welcome-back prompts, and intelligently loads only the necessary artifacts for the current phase.

State Detection via aidlc-state.md

At the start of every session, the Workspace Detection stage defined in aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md checks for the presence of aidlc-docs/aidlc-state.md.

If this state file exists, AI-DLC interprets the request as a resume operation rather than a green-field start. The logic follows this detection pattern:

def detect_resume(state_path: Path) -> bool:
    if state_path.is_file():
        state = yaml.safe_load(state_path.read_text())
        # Load artifacts based on stored phase

        load_artifacts(state['current_phase'])
        # Render welcome back prompt

        render_welcome_back(state)
        return True
    return False

When detected, the workflow skips initial green-field steps and proceeds directly to context restoration as defined in aidlc-rules/aws-aidlc-rules/core-workflow.md.

The Welcome-Back Prompt Template

The Session Continuity rule in aidlc-rules/aws-aidlc-rule-details/common/session-continuity.md defines a templated prompt that renders using data from aidlc-state.md. This interface displays the project name, current phase, last completed step, and the next recommended action.

The markdown template appears as follows:

**Welcome back! I can see you have an existing AI‑DLC project in progress.**

Based on your aidlc-state.md, here's your current status:
- **Project**: [project-name]
- **Current Phase**: [INCEPTION/CONSTRUCTION/OPERATIONS]
- **Current Stage**: [Stage Name]
- **Last Completed**: [Last completed step]
- **Next Step**: [Next step to work on]

**What would you like to work on today?**
A) Continue where you left off ([Next step description])
B) Review a previous stage ([Show available stages])
[Answer]:

This prompt gives users immediate visibility into their project status and offers options to continue or review previous stages.

Smart Context Loading by Phase

AI-DLC implements tiered artifact loading that varies by project phase to optimize token usage. The loading matrix defined in session-continuity.md specifies different artifact sets for each development stage:

• Early stages (Workspace Detection, Reverse Engineering): Load only workspace analysis artifacts.
• Requirements/Stories phases: Load reverse engineering artifacts plus any existing requirements.
• Design stages: Load requirements, stories, architecture, and design documents.
• Code stages: Load all artifacts and existing code files.

The implementation follows this phase-aware pattern:

def load_artifacts(phase):
    if phase == "INCEPTION":
        load_reverse_engineering()
        load_requirements()
    elif phase == "CONSTRUCTION":
        load_requirements()
        load_user_stories()
        load_design()
    elif phase == "CODE":
        load_all_previous_artifacts()
        load_code_files()

This strategy ensures the model receives sufficient context without exceeding token limits with irrelevant historical data.

Audit Logging and Error Recovery

Every continuity action is recorded for traceability. According to the Audit Log section of aidlc-rules/aws-aidlc-rules/core-workflow.md, every reload prompt and context-loading action is appended to aidlc-docs/audit.md with timestamps.

If required artifacts are missing or corrupted during resumption, AI-DLC invokes the recovery protocol from aidlc-rules/aws-aidlc-rule-details/common/error-handling.md. The system requests clarification or retries loading specific artifacts before proceeding, preventing workflow execution with incomplete context.

Summary

• AI-DLC detects resume scenarios by checking for aidlc-docs/aidlc-state.md at session start via the Workspace Detection stage in inception/workspace-detection.md.
• The Session Continuity rule generates personalized welcome-back prompts showing project status, current phase, and next steps.
• Tiered loading optimizes context injection by loading only phase-relevant artifacts rather than the entire project history.
• All continuity actions are immutably logged to aidlc-docs/audit.md for complete traceability.
• Robust error handling in common/error-handling.md ensures the workflow never proceeds with corrupted or missing artifacts.

Frequently Asked Questions

Where does AI-DLC store session state for project resumption?

AI-DLC persists session state in aidlc-docs/aidlc-state.md, a JSON/YAML file that records the current phase, stage, checkpoints, and project metadata. This file is checked at the start of every session by the Workspace Detection logic to determine whether to initiate a resume sequence or start fresh.

What happens if artifacts are missing when resuming a project?

If required artifacts are missing or corrupted during resumption, AI-DLC follows the recovery protocol defined in aidlc-rules/aws-aidlc-rule-details/common/error-handling.md. The system halts the workflow, requests clarification from the user, or attempts to reload the specific artifacts before allowing the session to continue.

How does AI-DLC determine which artifacts to load during a resume?

The system uses a tiered loading strategy defined in session-continuity.md that maps project phases to specific artifact sets. Early phases load minimal workspace data and reverse engineering artifacts, while later code-generation phases load all previous artifacts including requirements, design documents, stories, and existing code files.

Can AI-DLC resume a project from any development phase?

Yes, AI-DLC supports resumption from any phase (INCEPTION, CONSTRUCTION, or CODE/OPERATIONS) recorded in aidlc-state.md. The load_artifacts() function dynamically adjusts the context window based on the stored phase value, ensuring the model receives appropriate historical data regardless of when the user pauses or returns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}