F038: AWF Devcontainer Plugin for Worktree-Isolated Development Environments

[pocky]

F038: AWF Devcontainer Plugin for Worktree-Isolated Development Environments

User Stories

US1: Initialize Devcontainer for Worktree (P1 - Must Have)

As a developer working with git worktrees,
I want to initialize an isolated devcontainer environment for each worktree,
So that I can work on multiple branches simultaneously without environment conflicts.

Acceptance Scenarios:

• Given I have a git worktree at ~/project/feature-x, when I run awf devcontainer init, then a .devcontainer/ directory is created with worktree-specific configuration
• Given I already have a devcontainer in the main worktree, when I init in a new worktree, then volumes are configured to be isolated from other worktrees
• Given I run init without a git worktree, when the command executes, then I receive an error "Not inside a git worktree"

Independent Test: Create a worktree, run init, verify .devcontainer/devcontainer.json exists with unique volume names

US2: VS Code Integration (P1 - Must Have)

As a VS Code user,
I want the devcontainer to integrate seamlessly with VS Code Remote - Containers,
So that I can open the worktree in VS Code and have the correct container automatically start.

Acceptance Scenarios:

• Given a devcontainer is initialized, when I run code . in the worktree, then VS Code prompts to reopen in container
• Given the devcontainer.json is generated, when VS Code parses it, then no validation errors occur
• Given I have worktree-specific extensions defined, when the container starts, then those extensions are installed

Independent Test: Generate devcontainer.json, validate with VS Code devcontainer CLI schema validator

US3: Docker Volume Management (P2 - Should Have)

As a developer,
I want to manage Docker volumes per worktree with cleanup capabilities,
So that I can reclaim disk space from abandoned worktrees without affecting active ones.

Acceptance Scenarios:

• Given a devcontainer is running, when I run awf devcontainer volumes list, then I see volumes scoped to current worktree
• Given I have orphaned volumes from deleted worktrees, when I run awf devcontainer volumes prune, then only orphaned volumes are removed
• Given a worktree is active, when I attempt to prune its volumes, then I receive a warning and must confirm

Independent Test: Create worktree, init devcontainer, delete worktree, run prune, verify volumes removed

US4: Configuration Templates (P2 - Should Have)

As a team lead,
I want to define devcontainer templates in the main repository,
So that all team members get consistent development environments across worktrees.

Acceptance Scenarios:

• Given a .awf/devcontainer-template.json exists in repo root, when I init a new worktree, then the template is used as base configuration
• Given the template defines shared volumes, when init runs, then shared volumes use consistent names while worktree-specific volumes are isolated
• Given no template exists, when I init, then a sensible default configuration is generated

Independent Test: Create template, init worktree, verify generated config matches template structure

US5: Rebuild and Sync (P3 - Nice to Have)

As a developer,
I want to rebuild my devcontainer when the base configuration changes,
So that I stay synchronized with team updates without manual intervention.

Acceptance Scenarios:

• Given the template in main branch changes, when I run awf devcontainer sync, then my worktree's devcontainer.json is updated and container is rebuilt
• Given I have local customizations, when sync runs, then my customizations are preserved in a separate layer

Independent Test: Modify template, run sync in worktree, verify new settings applied while local overrides remain

---

Requirements

Functional Requirements

• FR-001: Plugin must detect git worktree context and extract worktree name for volume naming
• FR-002: Generated devcontainer.json must be valid against VS Code devcontainer schema v2.0+
• FR-003: Volume names must follow pattern awf-{repo}-{worktree}-{purpose} for isolation
• FR-004: Plugin must support .awf/devcontainer-template.json for team-wide base configuration
• FR-005: volumes list must display volume name, size, creation date, and associated worktree
• FR-006: volumes prune must only remove volumes for non-existent worktrees after confirmation
• FR-007: Plugin must generate VS Code-compatible devcontainer.json with remoteUser, mounts, and customizations.vscode sections

Non-Functional Requirements

• NFR-001: Init command must complete in < 2 seconds for default configuration
• NFR-002: No credentials or secrets must be written to devcontainer.json
• NFR-003: Volume operations must be atomic - no partial state on interruption
• NFR-004: Plugin must work offline after initial container image pull

---

Success Criteria

• All P1 user stories implemented and tested
• All P2 user stories implemented and tested
• Unit test coverage >= 80%
• No lint errors
• Documentation updated
• VS Code devcontainer schema validation passes for all generated configs
• Integration test with actual Docker daemon succeeds

---

Key Entities

Entity	Description	Attributes
DevcontainerConfig	Generated devcontainer.json content	name, image, mounts, customizations, remoteUser
WorktreeContext	Git worktree metadata	path, name, mainWorktreePath, repoName
VolumeInfo	Docker volume metadata	name, worktree, purpose, size, createdAt, isOrphaned
Template	Base devcontainer configuration	baseImage, sharedVolumes, extensions, settings

---

Metadata

• Status: backlog
• Version: v0.5.0
• Priority: medium
• Estimation: L

Dependencies

• Blocked by: none
• Unblocks: none

Clarifications

Section populated during clarify step with resolved ambiguities.

• Q: Should the plugin support Podman as an alternative to Docker?
• Q: How should conflicts between template and local customizations be resolved during sync?
• Q: Should volume naming include a hash to handle worktree names with special characters?

Notes

• Consider using Docker labels for volume metadata instead of external state file
• VS Code devcontainer schema: https://containers.dev/implementors/json_schema/
• Git worktree detection: git rev-parse --show-toplevel vs git worktree list
• Volume naming collision risk if two repos have same name - may need repo URL hash