Summary

Configure GitHub Codespaces prebuilds for the main and develop branches to eliminate the 2-3 minute container build wait when creating new codespaces, and restructure devcontainer lifecycle commands to maximize prebuild cache effectiveness.

Acceptance Criteria

• Codespaces prebuild configuration enabled for main and develop branches
• Prebuild region set to US West (or appropriate primary region)
• postCreateCommand logic moved to updateContentCommand so that dependency installation and tool setup are captured in the prebuild snapshot
• postCreateCommand reserved for user-session-specific operations only (or removed if empty)
• New codespace creation time reduced to under 30 seconds for prebuild-eligible branches
• Local devcontainer builds (VS Code Remote-Containers) continue to work without regression
• Prebuild template retention configured to keep at most 2 versions

Technical Details

Lifecycle Command Restructure

The devcontainer spec defines the following execution order:

1. initializeCommand — runs on host before container starts
2. onCreateCommand — runs once when container is first created
3. updateContentCommand — runs after onCreateCommand and after any content update; included in prebuild snapshot
4. postCreateCommand — runs after updateContentCommand; NOT included in prebuild snapshot
5. postStartCommand — runs every time the container starts
6. postAttachCommand — runs every time a client attaches

Moving dependency installation (npm install, pip install, PowerShell module installs) from postCreateCommand to updateContentCommand ensures these operations are cached in the prebuild image rather than running on every codespace creation.

Impact on Local Development

For local VS Code Remote-Containers usage (non-Codespaces), both updateContentCommand and postCreateCommand execute sequentially on first creation. Moving logic between them changes only the execution order relative to content updates — there is no functional difference for local users.

Prebuild Configuration

Repository Settings → Codespaces → Prebuilds:

• Branches: main, develop
• Region: US West
• Triggers: Push to configured branches, configuration file changes
• Template retention: 2 versions

Dependencies

• chore(devcontainer): pin base image version and align Node.js to v20 #513 — Pin base image version (recommended before enabling prebuilds for deterministic builds)
• fix(devcontainer): resolve tool parity gaps between devcontainer and copilot-setup-steps #514 — Resolve tool parity gaps (ensures prebuild installs the correct tool set)

How to Build This

This is a devcontainer configuration task using the task-implementor workflow.

Workflow: /task-research → /task-plan → /task-implement → /task-review

Phase 1: Research

Source Material

• This issue body
• #file:.devcontainer/devcontainer.json (current lifecycle commands)
• #file:.devcontainer/scripts/on-create.sh (container creation script)
• #file:.devcontainer/scripts/post-create.sh (post-creation setup)
• #file:.github/workflows/copilot-setup-steps.yml (tool parity reference)

Steps

1. Type /clear to start a fresh context.
2. Attach or open the files listed above.
3. Copy and run this prompt:

/task-research topic="GitHub Codespaces prebuild configuration and lifecycle command restructure"

Research how to configure Codespaces prebuilds and restructure lifecycle commands for
maximum prebuild cache effectiveness. Investigate:

1. The current devcontainer.json lifecycle commands and what each script installs
2. The devcontainer specification for lifecycle command execution order and which
   commands are included in prebuild snapshots
3. What operations should move from postCreateCommand to updateContentCommand
   (dependency installs, tool setup) vs what should stay (user-specific config)
4. GitHub Codespaces prebuild configuration options (branches, regions, triggers, retention)
5. How copilot-setup-steps.yml mirrors the devcontainer tool setup and whether
   restructuring affects the setup workflow
6. Impact on local VS Code Remote-Containers builds (both commands execute sequentially)
7. Dependencies on #513 (base image pinning) and #514 (tool parity)

Output: Research document at .copilot-tracking/research/{{YYYY-MM-DD}}-codespaces-prebuilds-research.md

Phase 2: Plan

Source Material

• Research document from Phase 1

Steps

1. Type /clear to start a fresh context.
2. Open the research document from Phase 1.
3. Copy and run this prompt:

/task-plan

Create an implementation plan for Codespaces prebuild configuration and lifecycle
command restructure. The plan should specify which operations move to updateContentCommand,
what remains in postCreateCommand, the repository settings changes for prebuilds,
and verification steps for both Codespaces and local devcontainer builds.

Output: Plan at .copilot-tracking/plans/ and details at .copilot-tracking/details/

Phase 3: Implement

Source Material

• Plan from Phase 2

Steps

1. Type /clear to start a fresh context.
2. Open the plan document from Phase 2.
3. Copy and run this prompt:

/task-implement

Implement the Codespaces prebuild configuration. Restructure devcontainer.json
lifecycle commands, create or modify scripts to split prebuild-eligible operations
from user-session operations, and document the prebuild configuration steps for
repository settings.

Output: Modified devcontainer files, changes log at .copilot-tracking/changes/

Phase 4: Review

Source Material

• Plan from Phase 2
• Changes log from Phase 3

Steps

1. Type /clear to start a fresh context.
2. Open the plan and changes log.
3. Copy and run this prompt:

/task-review

Review the Codespaces prebuild implementation. Verify:
- devcontainer.json lifecycle commands are correctly restructured
- Local devcontainer rebuilds still work (test with "Rebuild Container" command)
- updateContentCommand captures all dependency installation steps
- postCreateCommand contains only user-session operations (or is removed if empty)
- New codespace creation time target is achievable with the restructured commands

Output: Review log at .copilot-tracking/reviews/

After Review

• Pass: All criteria met. Create a PR referencing this issue. Note: repository Settings changes for prebuild configuration require manual setup by a maintainer.
• Iterate: Review found issues. Run /clear, return to Phase 3 with the review feedback.
• Escalate: Fundamental design issue discovered. Run /clear, return to Phase 1 to research the gap.

Authoring Standards

• devcontainer.json follows the devcontainer specification schema
• Shell scripts maintain compatibility with both Codespaces and local VS Code Remote-Containers
• Tool installation mirrors copilot-setup-steps.yml for parity

Success Criteria

• updateContentCommand captures dependency installation and tool setup
• postCreateCommand reserved for user-session operations only
• Local devcontainer builds work without regression
• Prebuild configuration documented for repository settings
• Template retention set to 2 versions