Add OpenSpec workflow infrastructure and Apple container extension design

[tomasz]

Summary

This PR establishes the foundational infrastructure for an OpenSpec-based development workflow and introduces a comprehensive design for a Dev Containers IDE extension targeting Apple's container runtime.

Key Changes

OpenSpec Workflow Infrastructure

• Skills (Claude & Cursor): Added reusable skill definitions for the experimental workflow:

  • openspec-explore: Thinking partner mode for investigating problems and clarifying requirements
  • openspec-propose: One-step change proposal with artifacts (proposal, design, tasks)
  • openspec-apply-change: Implementation guidance for executing change tasks
  • openspec-sync-specs: Delta spec synchronization to main specs
  • openspec-archive-change: Change finalization and archiving

• Commands (Claude & Cursor): Added command definitions for the experimental workflow:

  • /opsx:explore: Enter exploration mode
  • /opsx:propose: Create a new change proposal
  • /opsx:apply: Implement tasks from a change
  • /opsx:sync: Sync delta specs to main specs
  • /opsx:archive: Archive completed changes

Apple Container Dev Containers Extension Design

• Proposal (proposal.md): Rationale for building a Dev Containers extension on Apple container instead of Docker, addressing the closed nature of Microsoft's remote containers extension

• Design (design.md): Comprehensive technical architecture covering:

  • Constraint analysis (Microsoft's closed API, SSH as universal attach surface, Apple container's CLI-only interface)
  • Architecture decisions (SSH bridge pattern, static agent injection, devcontainer spec compliance)
  • Integration points with VS Code, Cursor, VSCodium, and Windsurf
  • Reference implementation patterns from DevPod and devcontainers/cli

• Delta Specs (8 capability specs):

  • devcontainer-config: Configuration discovery and precedence
  • devcontainer-lifecycle: Container creation, reuse, and lifecycle management
  • devcontainer-features: Feature reference resolution (OCI, HTTPS, local)
  • container-runtime-adapter: Runtime detection and version gating
  • ssh-attach-bridge: In-container SSH provisioning without image requirements
  • ide-attach: IDE detection and attachment targeting
  • extension-ux: Core extension commands and UI
  • port-forwarding: Port forwarding via create-time publish and SSH tunnels
  • clone-repo-in-volume: Repository cloning into named volumes

• Tasks (tasks.md): 7-milestone implementation roadmap (M0–M7) with acceptance criteria, from repository scaffolding through production-ready extension

Project Configuration

• OpenSpec config (openspec/config.yaml): Project context and schema definition for spec-driven workflow
• README (updated): High-level project description and feature overview
• References (docs/references.md): Curated research notes on Dev Containers spec, Apple container, and related tooling

Notable Implementation Details

• Multi-IDE support: Design accounts for VS Code, Cursor, VSCodium, and Windsurf with IDE-specific server download paths
• SSH-based architecture: Avoids proprietary APIs by using SSH as the universal remote attachment surface, following the DevPod pattern
• Static agent injection: Enables SSH access in minimal container images without requiring sshd in the base image
• Spec compliance: All delta specs reference the official Dev Containers specification schema and implementor documentation
• Dual-platform skills/commands: Infrastructure duplicated for both Claude and Cursor to ensure consistency across AI assistants

https://claude.ai/code/session_017gvu6ymwP46QkpALqTwfDE