container-superposition 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/README.md +72 -1014
  2. package/dist/scripts/init.js +512 -238
  3. package/dist/scripts/init.js.map +1 -1
  4. package/dist/tool/commands/adopt.d.ts +62 -0
  5. package/dist/tool/commands/adopt.d.ts.map +1 -0
  6. package/dist/tool/commands/adopt.js +767 -0
  7. package/dist/tool/commands/adopt.js.map +1 -0
  8. package/dist/tool/commands/doctor.js +2 -2
  9. package/dist/tool/commands/explain.d.ts.map +1 -1
  10. package/dist/tool/commands/explain.js +88 -0
  11. package/dist/tool/commands/explain.js.map +1 -1
  12. package/dist/tool/commands/hash.d.ts +36 -0
  13. package/dist/tool/commands/hash.d.ts.map +1 -0
  14. package/dist/tool/commands/hash.js +242 -0
  15. package/dist/tool/commands/hash.js.map +1 -0
  16. package/dist/tool/commands/plan.d.ts +53 -0
  17. package/dist/tool/commands/plan.d.ts.map +1 -1
  18. package/dist/tool/commands/plan.js +784 -42
  19. package/dist/tool/commands/plan.js.map +1 -1
  20. package/dist/tool/questionnaire/composer.d.ts +12 -3
  21. package/dist/tool/questionnaire/composer.d.ts.map +1 -1
  22. package/dist/tool/questionnaire/composer.js +133 -20
  23. package/dist/tool/questionnaire/composer.js.map +1 -1
  24. package/dist/tool/schema/project-config.d.ts +15 -0
  25. package/dist/tool/schema/project-config.d.ts.map +1 -0
  26. package/dist/tool/schema/project-config.js +359 -0
  27. package/dist/tool/schema/project-config.js.map +1 -0
  28. package/dist/tool/schema/types.d.ts +57 -1
  29. package/dist/tool/schema/types.d.ts.map +1 -1
  30. package/dist/tool/utils/backup.d.ts +23 -0
  31. package/dist/tool/utils/backup.d.ts.map +1 -0
  32. package/dist/tool/utils/backup.js +123 -0
  33. package/dist/tool/utils/backup.js.map +1 -0
  34. package/dist/tool/utils/gitignore.d.ts +15 -0
  35. package/dist/tool/utils/gitignore.d.ts.map +1 -0
  36. package/dist/tool/utils/gitignore.js +41 -0
  37. package/dist/tool/utils/gitignore.js.map +1 -0
  38. package/dist/tool/utils/services-export.d.ts +14 -0
  39. package/dist/tool/utils/services-export.d.ts.map +1 -0
  40. package/dist/tool/utils/services-export.js +478 -0
  41. package/dist/tool/utils/services-export.js.map +1 -0
  42. package/dist/tool/utils/summary.d.ts +69 -0
  43. package/dist/tool/utils/summary.d.ts.map +1 -0
  44. package/dist/tool/utils/summary.js +260 -0
  45. package/dist/tool/utils/summary.js.map +1 -0
  46. package/docs/README.md +12 -2
  47. package/docs/adopt.md +196 -0
  48. package/docs/custom-patches.md +1 -1
  49. package/docs/discovery-commands.md +55 -3
  50. package/docs/examples.md +40 -6
  51. package/docs/filesystem-contract.md +58 -0
  52. package/docs/hash.md +183 -0
  53. package/docs/minimal-and-editor.md +1 -1
  54. package/docs/overlays.md +108 -5
  55. package/docs/presets-architecture.md +1 -1
  56. package/docs/presets.md +1 -1
  57. package/docs/publishing.md +36 -23
  58. package/docs/security.md +43 -0
  59. package/docs/specs/001-verbose-plan-graph/checklists/requirements.md +36 -0
  60. package/docs/specs/001-verbose-plan-graph/contracts/plan-verbose-output.md +96 -0
  61. package/docs/specs/001-verbose-plan-graph/data-model.md +111 -0
  62. package/docs/specs/001-verbose-plan-graph/plan.md +127 -0
  63. package/docs/specs/001-verbose-plan-graph/quickstart.md +106 -0
  64. package/docs/specs/001-verbose-plan-graph/research.md +100 -0
  65. package/docs/specs/001-verbose-plan-graph/spec.md +128 -0
  66. package/docs/specs/001-verbose-plan-graph/tasks.md +223 -0
  67. package/docs/specs/002-superposition-config-file/checklists/requirements.md +36 -0
  68. package/docs/specs/002-superposition-config-file/contracts/init-project-config.md +98 -0
  69. package/docs/specs/002-superposition-config-file/data-model.md +126 -0
  70. package/docs/specs/002-superposition-config-file/plan.md +208 -0
  71. package/docs/specs/002-superposition-config-file/quickstart.md +140 -0
  72. package/docs/specs/002-superposition-config-file/research.md +144 -0
  73. package/docs/specs/002-superposition-config-file/spec.md +130 -0
  74. package/docs/specs/002-superposition-config-file/tasks.md +213 -0
  75. package/docs/team-workflow.md +27 -1
  76. package/docs/workflows.md +136 -0
  77. package/overlays/.presets/microservice.yml +32 -6
  78. package/overlays/.presets/sdd.yml +84 -0
  79. package/overlays/.presets/web-api.yml +76 -56
  80. package/overlays/README.md +7 -1
  81. package/overlays/amp/README.md +70 -0
  82. package/overlays/amp/devcontainer.patch.json +3 -0
  83. package/overlays/amp/overlay.yml +15 -0
  84. package/overlays/amp/setup.sh +21 -0
  85. package/overlays/amp/verify.sh +21 -0
  86. package/overlays/claude-code/README.md +83 -0
  87. package/overlays/claude-code/devcontainer.patch.json +3 -0
  88. package/overlays/claude-code/overlay.yml +15 -0
  89. package/overlays/claude-code/setup.sh +21 -0
  90. package/overlays/claude-code/verify.sh +21 -0
  91. package/overlays/cloudflared/README.md +190 -0
  92. package/overlays/cloudflared/devcontainer.patch.json +3 -0
  93. package/overlays/cloudflared/overlay.yml +15 -0
  94. package/overlays/cloudflared/setup.sh +49 -0
  95. package/overlays/cloudflared/verify.sh +21 -0
  96. package/overlays/direnv/README.md +6 -4
  97. package/overlays/direnv/setup.sh +0 -12
  98. package/overlays/gemini-cli/README.md +77 -0
  99. package/overlays/gemini-cli/devcontainer.patch.json +3 -0
  100. package/overlays/gemini-cli/overlay.yml +15 -0
  101. package/overlays/gemini-cli/setup.sh +21 -0
  102. package/overlays/gemini-cli/verify.sh +21 -0
  103. package/overlays/grpc-tools/README.md +242 -0
  104. package/overlays/grpc-tools/devcontainer.patch.json +14 -0
  105. package/overlays/grpc-tools/overlay.yml +14 -0
  106. package/overlays/grpc-tools/setup.sh +57 -0
  107. package/overlays/grpc-tools/verify.sh +47 -0
  108. package/overlays/keycloak/.env.example +5 -0
  109. package/overlays/keycloak/README.md +238 -0
  110. package/overlays/keycloak/devcontainer.patch.json +17 -0
  111. package/overlays/keycloak/docker-compose.yml +32 -0
  112. package/overlays/keycloak/overlay.yml +23 -0
  113. package/overlays/keycloak/verify.sh +54 -0
  114. package/overlays/mailpit/.env.example +4 -0
  115. package/overlays/mailpit/README.md +191 -0
  116. package/overlays/mailpit/devcontainer.patch.json +20 -0
  117. package/overlays/mailpit/docker-compose.yml +17 -0
  118. package/overlays/mailpit/overlay.yml +26 -0
  119. package/overlays/mailpit/verify.sh +52 -0
  120. package/overlays/ngrok/overlay.yml +2 -1
  121. package/overlays/opencode/README.md +76 -0
  122. package/overlays/opencode/devcontainer.patch.json +3 -0
  123. package/overlays/opencode/overlay.yml +14 -0
  124. package/overlays/opencode/setup.sh +21 -0
  125. package/overlays/opencode/verify.sh +21 -0
  126. package/overlays/python/README.md +51 -35
  127. package/overlays/python/devcontainer.patch.json +7 -4
  128. package/overlays/python/setup.sh +50 -23
  129. package/overlays/python/verify.sh +29 -1
  130. package/overlays/spec-kit/README.md +181 -0
  131. package/overlays/spec-kit/devcontainer.patch.json +6 -0
  132. package/overlays/spec-kit/overlay.yml +19 -0
  133. package/overlays/spec-kit/setup.sh +45 -0
  134. package/overlays/spec-kit/verify.sh +33 -0
  135. package/overlays/windsurf-cli/README.md +69 -0
  136. package/overlays/windsurf-cli/devcontainer.patch.json +3 -0
  137. package/overlays/windsurf-cli/overlay.yml +15 -0
  138. package/overlays/windsurf-cli/setup.sh +21 -0
  139. package/overlays/windsurf-cli/verify.sh +21 -0
  140. package/package.json +1 -1
  141. package/tool/schema/config.schema.json +138 -9
@@ -0,0 +1,76 @@
1
+ # opencode Overlay
2
+
3
+ Adds the `opencode` AI coding agent for terminal-based development assistance.
4
+
5
+ ## Features
6
+
7
+ - **opencode CLI** — Multi-provider AI coding agent for the terminal
8
+ - **Provider flexibility** — Supports multiple AI providers (OpenAI, Anthropic, Google, and more)
9
+
10
+ ## What is opencode?
11
+
12
+ opencode is an open-source, terminal-based AI coding agent that supports multiple AI providers:
13
+
14
+ - **Multi-provider** — Choose from OpenAI, Anthropic, Google Gemini, and other providers
15
+ - **Code generation** — Generate new code from natural language descriptions
16
+ - **Codebase context** — Understands your project structure
17
+ - **Agentic tasks** — Execute multi-step coding tasks autonomously
18
+
19
+ ## How It Works
20
+
21
+ This overlay installs `opencode-ai` globally via npm, making the `opencode` command available in your devcontainer.
22
+
23
+ ## Common Commands
24
+
25
+ ```bash
26
+ # Start an interactive session
27
+ opencode
28
+
29
+ # Check version
30
+ opencode --version
31
+ ```
32
+
33
+ ## Use Cases
34
+
35
+ - **Flexible AI assistant** — Switch between AI providers as needed
36
+ - **Open-source first** — Works with self-hosted models via compatible APIs
37
+ - **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai opencode`
38
+
39
+ **Integrates well with:**
40
+
41
+ - `spec-kit` — Use opencode with the SDD workflow
42
+ - `nodejs` — Required for installation
43
+ - `git-helpers` — Git integration for AI-generated code
44
+
45
+ ## Configuration
46
+
47
+ Configure your AI provider API key:
48
+
49
+ ```bash
50
+ # For OpenAI
51
+ export OPENAI_API_KEY=your-key
52
+
53
+ # For Anthropic
54
+ export ANTHROPIC_API_KEY=your-key
55
+
56
+ # For Google Gemini
57
+ export GEMINI_API_KEY=your-key
58
+ ```
59
+
60
+ ## Verification
61
+
62
+ ```bash
63
+ bash .devcontainer/scripts/verify-opencode.sh
64
+ ```
65
+
66
+ ## References
67
+
68
+ - [opencode Website](https://opencode.ai)
69
+ - [opencode GitHub](https://github.com/sst/opencode)
70
+
71
+ **Related Overlays:**
72
+
73
+ - `spec-kit` — Spec-Driven Development with opencode as the AI agent
74
+ - `codex` — OpenAI Codex CLI (alternative AI assistant)
75
+ - `claude-code` — Anthropic Claude Code (alternative AI assistant)
76
+ - `nodejs` — Required for npm-based installation
@@ -0,0 +1,3 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
3
+ }
@@ -0,0 +1,14 @@
1
+ id: opencode
2
+ name: opencode
3
+ description: opencode AI coding agent for terminal-based development assistance
4
+ category: dev
5
+ supports: []
6
+ requires:
7
+ - nodejs
8
+ suggests: []
9
+ conflicts: []
10
+ tags:
11
+ - dev
12
+ - ai
13
+ - opencode
14
+ ports: []
@@ -0,0 +1,21 @@
1
+ #!/bin/bash
2
+ # opencode setup script - Install opencode AI coding agent
3
+
4
+ set -e
5
+
6
+ echo "📦 Installing opencode AI coding agent..."
7
+
8
+ # Install opencode-ai globally
9
+ npm install -g opencode-ai
10
+
11
+ # Verify installation
12
+ if command -v opencode &>/dev/null; then
13
+ echo "✓ opencode installed successfully: $(opencode --version 2>/dev/null || echo 'installed')"
14
+ else
15
+ echo "✗ opencode installation failed"
16
+ exit 1
17
+ fi
18
+
19
+ echo "✓ opencode setup complete"
20
+ echo "ℹ️ opencode: https://opencode.ai"
21
+ echo "ℹ️ Run 'opencode --help' to get started"
@@ -0,0 +1,21 @@
1
+ #!/bin/bash
2
+ # opencode overlay verification script
3
+
4
+ set -e
5
+
6
+ echo "🔍 Verifying opencode overlay setup..."
7
+
8
+ # Check if opencode is installed
9
+ if ! command -v opencode &>/dev/null; then
10
+ echo "✗ opencode is not installed or not in PATH"
11
+ exit 1
12
+ fi
13
+
14
+ echo "✓ opencode is installed: $(opencode --version 2>/dev/null || echo 'installed')"
15
+
16
+ echo ""
17
+ echo "✅ opencode overlay verification complete!"
18
+ echo ""
19
+ echo "💡 Tips:"
20
+ echo " - Run 'opencode --help' to see available commands"
21
+ echo " - Configure your AI provider API key"
@@ -5,67 +5,84 @@ Adds Python 3.12 with development tools, linting, and formatting.
5
5
  ## Features
6
6
 
7
7
  - **Python 3.12** with pip, setuptools, and wheel
8
+ - **Virtual environment** (`.venv`) created automatically in the workspace root
8
9
  - **VS Code Extensions:**
9
10
  - Python (ms-python.python)
10
11
  - Pylance (ms-python.vscode-pylance)
11
12
  - Black Formatter (ms-python.black-formatter)
12
13
  - Ruff (charliermarsh.ruff)
13
- - **Automatic dependency installation** from:
14
- - `requirements.txt`
15
- - `requirements-dev.txt`
14
+ - **Automatic dependency installation** into `.venv` from:
15
+ - `requirements.txt` (project production dependencies)
16
+ - `requirements-dev.txt` (project development dependencies)
16
17
  - `pyproject.toml` (editable install)
17
18
  - `setup.py` (legacy support)
18
19
  - **Pre-configured settings:**
20
+ - VS Code interpreter pointed at `.venv/bin/python`
19
21
  - Black as default formatter
20
22
  - Format on save enabled
21
23
  - Auto-organize imports
22
- - PYTHONPATH set to workspace root
24
+ - `PYTHONPATH`, `VIRTUAL_ENV`, and `PATH` set for the venv
25
+ - **`.gitignore`** — `.venv/`, `__pycache__/`, `*.pyc`, `.pytest_cache/`, and build artefacts added to the project root `.gitignore` automatically
23
26
 
24
- ## Virtual Environment Philosophy
27
+ ## Virtual Environment
25
28
 
26
- This overlay uses **user-level pip installations** (`pip install --user`) instead of virtual environments inside the container for these reasons:
29
+ This overlay automatically creates a `.venv` virtual environment in the workspace root on container creation and installs all dependencies into it.
27
30
 
28
- ### Why Not venv in Container?
31
+ ### Why venv?
29
32
 
30
- 1. **Container IS the environment** - The devcontainer already provides isolation
31
- 2. **Simpler workflow** - No need to activate/deactivate venv
32
- 3. **Better VS Code integration** - Python extension finds packages automatically
33
- 4. **Fewer moving parts** - Less to go wrong
33
+ 1. **Clean isolation** Dependencies are scoped to the project, not the system Python
34
+ 2. **Production parity** Matches how the app runs in CI/CD and production
35
+ 3. **Tool compatibility** Works seamlessly with pytest, mypy, ruff, and other dev tools
36
+ 4. **VS Code integration** — The Python extension is pre-configured to use `.venv/bin/python`
34
37
 
35
- ### When to Use venv
38
+ ### How It Works
36
39
 
37
- Use a virtual environment if you need:
40
+ On container creation, the setup script:
38
41
 
39
- - Multiple Python versions in the same container
40
- - Strict dependency isolation for testing
41
- - Exact production parity (though containers already provide this)
42
+ 1. Creates `.venv` at `${workspaceFolder}/.venv` using `python -m venv`
43
+ 2. Upgrades `pip`, `setuptools`, and `wheel` inside the venv
44
+ 3. Installs overlay default packages from `.devcontainer/requirements-overlay-python.txt`
45
+ 4. Installs project dependencies from `requirements.txt` (if present)
46
+ 5. Installs dev dependencies from `requirements-dev.txt` (if present)
47
+ 6. Installs project in editable mode if `pyproject.toml` or `setup.py` is present
42
48
 
43
- To create a venv manually:
49
+ ### Activating the Virtual Environment
50
+
51
+ The `.venv/bin` directory is prepended to `PATH` automatically in the devcontainer, so tools like `python`, `pip`, `pytest`, and `ruff` resolve to the venv by default. You can also activate explicitly:
44
52
 
45
53
  ```bash
46
- python -m venv .venv
47
54
  source .venv/bin/activate
48
- pip install -r requirements.txt
49
55
  ```
50
56
 
51
- Then update VS Code settings:
57
+ ### Gitignore
52
58
 
53
- ```json
54
- {
55
- "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
56
- }
59
+ When the Python overlay is selected, the composer automatically adds Python-specific entries to the **project root** `.gitignore` (creating the file if it doesn’t exist, and never duplicating existing entries):
60
+
61
+ ```gitignore
62
+ # python (container-superposition)
63
+ .venv/
64
+ __pycache__/
65
+ *.pyc
66
+ *.pyo
67
+ .pytest_cache/
68
+ *.egg-info/
69
+ dist/
70
+ build/
57
71
  ```
58
72
 
73
+ This happens at generation time — no container startup required.
74
+
59
75
  ## Automatic Setup
60
76
 
61
77
  The overlay automatically runs on container creation:
62
78
 
63
- 1. ✅ Installs overlay packages from `.devcontainer/requirements-overlay.txt`
64
- 2. ✅ Checks for `requirements.txt` installs with pip
65
- 3. ✅ Checks for `requirements-dev.txt` → installs dev dependencies
66
- 4. ✅ Checks for `pyproject.toml` → installs project in editable mode
67
- 5. ✅ Checks for `setup.py` → installs legacy projects
68
- 6. ✅ Upgrades pip, setuptools, and wheel to latest
79
+ 1. ✅ Creates `.venv` virtual environment in the workspace root
80
+ 2. ✅ Upgrades pip, setuptools, and wheel inside the venv
81
+ 3. ✅ Installs overlay packages from `.devcontainer/requirements-overlay-python.txt`
82
+ 4. ✅ Checks for `requirements.txt` → installs into venv
83
+ 5. ✅ Checks for `requirements-dev.txt` → installs dev dependencies into venv
84
+ 6. ✅ Checks for `pyproject.toml` installs project in editable mode
85
+ 7. ✅ Checks for `setup.py` → installs legacy projects in editable mode
69
86
 
70
87
  ## Customizing Overlay Packages
71
88
 
@@ -176,7 +193,7 @@ mytool = "mytool.cli:main"
176
193
  1. **Pin versions** in requirements.txt for reproducibility
177
194
  2. **Separate dev dependencies** in requirements-dev.txt
178
195
  3. **Use pyproject.toml** for modern Python projects
179
- 4. **Add `.gitignore`** for `__pycache__`, `.pytest_cache`, etc.
196
+ 4. **Add `.gitignore`** handled automatically by the overlay
180
197
 
181
198
  ## Troubleshooting
182
199
 
@@ -200,17 +217,16 @@ Update `devcontainer.patch.json`:
200
217
  }
201
218
  ```
202
219
 
203
- ### Want to use venv anyway?
220
+ ### Customizing the Interpreter Path
204
221
 
205
- Add to your project's `.devcontainer/devcontainer.json`:
222
+ The overlay pre-configures VS Code to use `${workspaceFolder}/.venv/bin/python`. If your venv is elsewhere, update `python.defaultInterpreterPath` in your workspace settings or `.devcontainer/custom/devcontainer.patch.json`:
206
223
 
207
224
  ```json
208
225
  {
209
- "postCreateCommand": "python -m venv .venv && .venv/bin/pip install -r requirements.txt",
210
226
  "customizations": {
211
227
  "vscode": {
212
228
  "settings": {
213
- "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
229
+ "python.defaultInterpreterPath": "${workspaceFolder}/my-custom-venv/bin/python"
214
230
  }
215
231
  }
216
232
  }
@@ -26,16 +26,19 @@
26
26
  "source.organizeImports": "explicit"
27
27
  }
28
28
  },
29
- "python.defaultInterpreterPath": "/usr/local/bin/python",
29
+ "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
30
+ "python.terminal.activateEnvironment": true,
30
31
  "files.exclude": {
31
32
  "**/__pycache__": true,
32
- "**/.pytest_cache": true
33
+ "**/.pytest_cache": true,
34
+ "**/.venv": true
33
35
  }
34
36
  }
35
37
  }
36
38
  },
37
39
  "remoteEnv": {
38
- "PATH": "${containerEnv:HOME}/.local/bin:${containerEnv:PATH}",
39
- "PYTHONPATH": "${containerWorkspaceFolder}"
40
+ "PATH": "${containerWorkspaceFolder}/.venv/bin:${containerEnv:HOME}/.local/bin:${containerEnv:PATH}",
41
+ "PYTHONPATH": "${containerWorkspaceFolder}",
42
+ "VIRTUAL_ENV": "${containerWorkspaceFolder}/.venv"
40
43
  }
41
44
  }
@@ -1,47 +1,74 @@
1
1
  #!/bin/bash
2
- # Python setup script - Install Python packages
2
+ # Python setup script - Create virtual environment and install dependencies
3
3
 
4
4
  set -e
5
5
 
6
6
  # Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
7
7
  OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
8
8
 
9
- echo "🐍 Setting up Python environment..."
9
+ echo "🐍 Setting up Python virtual environment..."
10
+
11
+ # Determine workspace root (script is run from workspace root via postCreateCommand)
12
+ WORKSPACE_ROOT="${PWD}"
13
+ VENV_DIR="${WORKSPACE_ROOT}/.venv"
14
+
15
+ # Create virtual environment if it doesn't exist
16
+ if [ ! -d "${VENV_DIR}" ]; then
17
+ echo "📦 Creating virtual environment at .venv..."
18
+ if ! command -v python3 >/dev/null 2>&1; then
19
+ echo "❌ python3 is not available on PATH. Please ensure python3 is installed."
20
+ exit 1
21
+ fi
22
+ python3 -m venv "${VENV_DIR}"
23
+ echo "✓ Virtual environment created"
24
+ else
25
+ echo "✓ Virtual environment already exists at .venv"
26
+ fi
27
+
28
+ # Activate virtual environment
29
+ # shellcheck source=/dev/null
30
+ source "${VENV_DIR}/bin/activate"
31
+
32
+ # Upgrade pip, setuptools, and wheel inside the venv
33
+ echo "⬆️ Upgrading pip, setuptools, and wheel..."
34
+ pip install --upgrade pip setuptools wheel
35
+ echo "✓ pip, setuptools, and wheel upgraded"
10
36
 
11
37
  # Install overlay-specific packages (if requirements-overlay.txt exists)
12
38
  if [ -f ".devcontainer/requirements-overlay-${OVERLAY_NAME}.txt" ]; then
13
39
  echo "📦 Installing overlay packages from requirements-overlay-${OVERLAY_NAME}.txt..."
14
- pip install --user -r .devcontainer/requirements-overlay-${OVERLAY_NAME}.txt
40
+ pip install -r ".devcontainer/requirements-overlay-${OVERLAY_NAME}.txt"
15
41
  echo "✓ Overlay packages installed"
16
42
  fi
17
43
 
18
- # Check if requirements.txt exists (project dependencies)
44
+ # Install from root requirements.txt (project production dependencies)
19
45
  if [ -f "requirements.txt" ]; then
20
- echo "📦 Found requirements.txt, installing dependencies..."
21
- pip install --user -r requirements.txt
46
+ echo "📦 Installing dependencies from requirements.txt..."
47
+ pip install -r requirements.txt
22
48
  echo "✓ Dependencies installed from requirements.txt"
23
- elif [ -f "requirements-dev.txt" ]; then
24
- echo "📦 Found requirements-dev.txt, installing dev dependencies..."
25
- pip install --user -r requirements-dev.txt
49
+ fi
50
+
51
+ # Install from requirements-dev.txt (project development dependencies)
52
+ if [ -f "requirements-dev.txt" ]; then
53
+ echo "📦 Installing dev dependencies from requirements-dev.txt..."
54
+ pip install -r requirements-dev.txt
26
55
  echo "✓ Dev dependencies installed from requirements-dev.txt"
27
56
  fi
28
57
 
29
- # Check if pyproject.toml exists (modern Python projects)
58
+ # Install project in editable mode if pyproject.toml exists (modern Python projects)
30
59
  if [ -f "pyproject.toml" ]; then
31
- echo "📦 Found pyproject.toml, installing project..."
32
- pip install --user -e .
60
+ echo "📦 Found pyproject.toml, installing project in editable mode..."
61
+ pip install -e .
33
62
  echo "✓ Project installed in editable mode"
34
- fi
35
-
36
- # Check if setup.py exists (legacy Python projects)
37
- if [ -f "setup.py" ] && [ ! -f "pyproject.toml" ]; then
38
- echo "📦 Found setup.py, installing project..."
39
- pip install --user -e .
63
+ elif [ -f "setup.py" ]; then
64
+ # Fallback for legacy Python projects
65
+ echo "📦 Found setup.py, installing project in editable mode..."
66
+ pip install -e .
40
67
  echo "✓ Project installed in editable mode"
41
68
  fi
42
69
 
43
- # Upgrade pip, setuptools, and wheel
44
- echo "⬆️ Upgrading pip, setuptools, and wheel..."
45
- pip install --user --upgrade pip setuptools wheel
46
-
47
- echo " Python setup complete"
70
+ echo ""
71
+ echo " Python virtual environment setup complete"
72
+ echo " Virtual environment: ${VENV_DIR}"
73
+ echo " Python interpreter: ${VENV_DIR}/bin/python"
74
+ echo " Activate manually: source .venv/bin/activate"
@@ -1,6 +1,6 @@
1
1
  #!/bin/bash
2
2
  # Verification script for Python overlay
3
- # Confirms Python and pip are installed
3
+ # Confirms Python, pip, and virtual environment are installed and functional
4
4
 
5
5
  set -e
6
6
 
@@ -28,5 +28,33 @@ else
28
28
  exit 1
29
29
  fi
30
30
 
31
+ # Check venv module is available
32
+ echo ""
33
+ echo "3️⃣ Checking venv module..."
34
+ if python3 -m venv --help &> /dev/null; then
35
+ echo " ✅ venv module available"
36
+ else
37
+ echo " ❌ venv module not available"
38
+ exit 1
39
+ fi
40
+
41
+ # Check virtual environment was created (only if we are inside a devcontainer)
42
+ echo ""
43
+ echo "4️⃣ Checking virtual environment..."
44
+ VENV_DIR="${PWD}/.venv"
45
+ if [ -d "${VENV_DIR}" ]; then
46
+ if [ -f "${VENV_DIR}/bin/python" ]; then
47
+ VENV_PYTHON_VERSION=$("${VENV_DIR}/bin/python" --version 2>&1)
48
+ echo " Virtual environment: ${VENV_DIR}"
49
+ echo " Python version: ${VENV_PYTHON_VERSION}"
50
+ echo " ✅ Virtual environment is functional"
51
+ else
52
+ echo " ⚠️ Virtual environment directory exists but python not found"
53
+ echo " ℹ️ Run setup script to create it: bash .devcontainer/scripts/setup-python.sh"
54
+ fi
55
+ else
56
+ echo " ℹ️ No .venv found — will be created on container start by setup-python.sh"
57
+ fi
58
+
31
59
  echo ""
32
60
  echo "✅ Python overlay verification complete"
@@ -0,0 +1,181 @@
1
+ # Spec Kit (SDD) Overlay
2
+
3
+ Installs the `specify` CLI and its prerequisites (`uv`) for **Spec-Driven Development** — a disciplined workflow that elevates specifications to first-class artifacts driving AI-powered implementation.
4
+
5
+ ## Features
6
+
7
+ - **`specify` CLI** — Interactive SDD workflow commands for any supported AI coding agent
8
+ - **`uv`** — Fast Python package manager used to install and run `specify`
9
+ - **20+ AI agent integrations** — Works with Codex, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Amp, and more
10
+
11
+ ## What is Spec-Driven Development?
12
+
13
+ Spec-Driven Development (SDD) flips the traditional workflow: instead of vibe-coding, you author rich specifications that become executable artifacts driving AI agents through a disciplined multi-step process:
14
+
15
+ | Step | Command | Description |
16
+ | ---- | ----------------------- | ----------------------------------------- |
17
+ | 1 | `/speckit.constitution` | Create project governing principles |
18
+ | 2 | `/speckit.specify` | Define requirements (what & why, not how) |
19
+ | 3 | `/speckit.clarify` | Clarify underspecified areas |
20
+ | 4 | `/speckit.plan` | Create a technical implementation plan |
21
+ | 5 | `/speckit.analyze` | Cross-artifact consistency analysis |
22
+ | 6 | `/speckit.tasks` | Break plan into actionable tasks |
23
+ | 7 | `/speckit.implement` | Execute tasks with an AI agent |
24
+
25
+ ## How It Works
26
+
27
+ This overlay:
28
+
29
+ 1. Installs `uv` (Astral's fast Python package manager) if not already present
30
+ 2. Uses `uv tool install` to install `specify-cli` from the [github/spec-kit](https://github.com/github/spec-kit) repository
31
+ 3. Makes `specify` available on the PATH inside the devcontainer
32
+
33
+ **Why `uv`?** Spec Kit uses `uv` as its package manager for fast, isolated tool installation — it avoids the overhead of creating a full virtual environment while keeping `specify` globally accessible.
34
+
35
+ ## Common Commands
36
+
37
+ ### Initialize a project
38
+
39
+ ```bash
40
+ # Initialize SDD for a project with a specific AI agent
41
+ specify init . --here --ai codex
42
+ specify init . --here --ai claude
43
+ specify init . --here --ai gemini
44
+ specify init . --here --ai copilot
45
+ specify init . --here --ai amp
46
+ ```
47
+
48
+ ### SDD Workflow
49
+
50
+ ```bash
51
+ # After initializing, use the installed slash commands in your AI agent:
52
+ # /speckit.constitution — Define project principles
53
+ # /speckit.specify — Author requirements spec
54
+ # /speckit.clarify — Clarify ambiguities
55
+ # /speckit.plan — Generate implementation plan
56
+ # /speckit.analyze — Check consistency
57
+ # /speckit.tasks — Break into tasks
58
+ # /speckit.implement — Implement with AI
59
+ ```
60
+
61
+ ### Utility Commands
62
+
63
+ ```bash
64
+ # Check specify is available
65
+ specify --version
66
+
67
+ # List supported agents
68
+ specify --help
69
+ ```
70
+
71
+ ## Supported AI Agents
72
+
73
+ The `specify` CLI supports the following agents (pass as `--ai <agent>`):
74
+
75
+ | Agent | `--ai` flag | Notes |
76
+ | --------------------- | -------------- | --------------------------------------- |
77
+ | OpenAI Codex | `codex` | Requires `codex` overlay |
78
+ | Anthropic Claude Code | `claude` | Requires `claude-code` overlay |
79
+ | Google Gemini CLI | `gemini` | Requires `gemini-cli` overlay |
80
+ | GitHub Copilot | `copilot` | IDE-integrated, no extra overlay needed |
81
+ | Cursor Agent | `cursor-agent` | IDE-integrated |
82
+ | Codeium Windsurf | `windsurf` | Requires `windsurf-cli` overlay |
83
+ | Sourcegraph Amp | `amp` | Requires `amp` overlay |
84
+ | opencode | `opencode` | Requires `opencode` overlay |
85
+ | Roo Code | `roo-code` | IDE-integrated |
86
+ | Kiro CLI | `kiro` | Check upstream docs |
87
+ | Generic (BYOA) | `generic` | Bring your own agent |
88
+
89
+ For the full list see the [spec-kit supported agents documentation](https://github.com/github/spec-kit#-supported-ai-agents).
90
+
91
+ ## Use Cases
92
+
93
+ - **Greenfield projects** — Start with a specification before writing any code
94
+ - **Feature development** — Spec out new features before asking AI to implement them
95
+ - **Team alignment** — Share specifications as structured artifacts
96
+ - **AI-assisted refactoring** — Spec the desired end state, let AI plan the migration
97
+ - **Documentation-driven development** — Specifications become living documentation
98
+
99
+ **Integrates well with:**
100
+
101
+ - `codex` — OpenAI Codex CLI (most common with SDD)
102
+ - `claude-code` — Anthropic Claude Code
103
+ - `gemini-cli` — Google Gemini CLI
104
+ - `amp` — Sourcegraph Amp
105
+ - `git-helpers` — Git integration for specification artifacts
106
+ - `pre-commit` — Quality gates for specification files
107
+
108
+ ## Configuration
109
+
110
+ The `specify` tool stores its slash-command templates in your project directory after running `specify init`. These files are committed to your repository.
111
+
112
+ **Environment variable (optional):**
113
+
114
+ ```bash
115
+ # Set a default AI agent to avoid passing --ai on every command
116
+ export SPECIFY_AI_AGENT=codex
117
+ ```
118
+
119
+ ## Verification
120
+
121
+ After setup, run the verification script to ensure proper installation:
122
+
123
+ ```bash
124
+ bash .devcontainer/scripts/verify-spec-kit.sh
125
+ ```
126
+
127
+ This checks:
128
+
129
+ - `uv` is installed
130
+ - `specify` CLI is available on PATH
131
+
132
+ ## Troubleshooting
133
+
134
+ ### `specify` command not found
135
+
136
+ **Solution:**
137
+
138
+ Ensure `$HOME/.local/bin` is on your PATH:
139
+
140
+ ```bash
141
+ export PATH="$HOME/.local/bin:$PATH"
142
+
143
+ # Or add to your shell profile:
144
+ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
145
+ ```
146
+
147
+ ### `uv` not found
148
+
149
+ **Solution:**
150
+
151
+ ```bash
152
+ curl -LsSf https://astral.sh/uv/install.sh | sh
153
+ export PATH="$HOME/.local/bin:$PATH"
154
+ ```
155
+
156
+ ### `specify` fails to install
157
+
158
+ **Solution:**
159
+
160
+ Check internet connectivity and try reinstalling:
161
+
162
+ ```bash
163
+ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git --force
164
+ ```
165
+
166
+ ## References
167
+
168
+ - [Spec Kit GitHub](https://github.com/github/spec-kit)
169
+ - [Spec-Driven Development Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)
170
+ - [Specify CLI Reference](https://github.com/github/spec-kit#-specify-cli-reference)
171
+ - [Supported AI Agents](https://github.com/github/spec-kit#-supported-ai-agents)
172
+ - [uv Documentation](https://docs.astral.sh/uv/)
173
+
174
+ **Related Overlays:**
175
+
176
+ - `codex` — OpenAI Codex CLI
177
+ - `claude-code` — Anthropic Claude Code
178
+ - `gemini-cli` — Google Gemini CLI
179
+ - `amp` — Sourcegraph Amp
180
+ - `opencode` — opencode CLI
181
+ - `windsurf-cli` — Codeium Windsurf CLI
@@ -0,0 +1,6 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
3
+ "remoteEnv": {
4
+ "PATH": "${containerEnv:PATH}:${containerEnv:HOME}/.local/bin"
5
+ }
6
+ }
@@ -0,0 +1,19 @@
1
+ id: spec-kit
2
+ name: Spec Kit (SDD)
3
+ description: Specify CLI for Spec-Driven Development with any AI coding agent
4
+ category: dev
5
+ supports: []
6
+ requires: []
7
+ suggests:
8
+ - python
9
+ - codex
10
+ conflicts: []
11
+ tags:
12
+ - dev
13
+ - ai
14
+ - sdd
15
+ - spec-driven
16
+ - specify
17
+ - spec-kit
18
+ ports: []
19
+ order: 20