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.
- package/README.md +72 -1014
- package/dist/scripts/init.js +512 -238
- package/dist/scripts/init.js.map +1 -1
- package/dist/tool/commands/adopt.d.ts +62 -0
- package/dist/tool/commands/adopt.d.ts.map +1 -0
- package/dist/tool/commands/adopt.js +767 -0
- package/dist/tool/commands/adopt.js.map +1 -0
- package/dist/tool/commands/doctor.js +2 -2
- package/dist/tool/commands/explain.d.ts.map +1 -1
- package/dist/tool/commands/explain.js +88 -0
- package/dist/tool/commands/explain.js.map +1 -1
- package/dist/tool/commands/hash.d.ts +36 -0
- package/dist/tool/commands/hash.d.ts.map +1 -0
- package/dist/tool/commands/hash.js +242 -0
- package/dist/tool/commands/hash.js.map +1 -0
- package/dist/tool/commands/plan.d.ts +53 -0
- package/dist/tool/commands/plan.d.ts.map +1 -1
- package/dist/tool/commands/plan.js +784 -42
- package/dist/tool/commands/plan.js.map +1 -1
- package/dist/tool/questionnaire/composer.d.ts +12 -3
- package/dist/tool/questionnaire/composer.d.ts.map +1 -1
- package/dist/tool/questionnaire/composer.js +133 -20
- package/dist/tool/questionnaire/composer.js.map +1 -1
- package/dist/tool/schema/project-config.d.ts +15 -0
- package/dist/tool/schema/project-config.d.ts.map +1 -0
- package/dist/tool/schema/project-config.js +359 -0
- package/dist/tool/schema/project-config.js.map +1 -0
- package/dist/tool/schema/types.d.ts +57 -1
- package/dist/tool/schema/types.d.ts.map +1 -1
- package/dist/tool/utils/backup.d.ts +23 -0
- package/dist/tool/utils/backup.d.ts.map +1 -0
- package/dist/tool/utils/backup.js +123 -0
- package/dist/tool/utils/backup.js.map +1 -0
- package/dist/tool/utils/gitignore.d.ts +15 -0
- package/dist/tool/utils/gitignore.d.ts.map +1 -0
- package/dist/tool/utils/gitignore.js +41 -0
- package/dist/tool/utils/gitignore.js.map +1 -0
- package/dist/tool/utils/services-export.d.ts +14 -0
- package/dist/tool/utils/services-export.d.ts.map +1 -0
- package/dist/tool/utils/services-export.js +478 -0
- package/dist/tool/utils/services-export.js.map +1 -0
- package/dist/tool/utils/summary.d.ts +69 -0
- package/dist/tool/utils/summary.d.ts.map +1 -0
- package/dist/tool/utils/summary.js +260 -0
- package/dist/tool/utils/summary.js.map +1 -0
- package/docs/README.md +12 -2
- package/docs/adopt.md +196 -0
- package/docs/custom-patches.md +1 -1
- package/docs/discovery-commands.md +55 -3
- package/docs/examples.md +40 -6
- package/docs/filesystem-contract.md +58 -0
- package/docs/hash.md +183 -0
- package/docs/minimal-and-editor.md +1 -1
- package/docs/overlays.md +108 -5
- package/docs/presets-architecture.md +1 -1
- package/docs/presets.md +1 -1
- package/docs/publishing.md +36 -23
- package/docs/security.md +43 -0
- package/docs/specs/001-verbose-plan-graph/checklists/requirements.md +36 -0
- package/docs/specs/001-verbose-plan-graph/contracts/plan-verbose-output.md +96 -0
- package/docs/specs/001-verbose-plan-graph/data-model.md +111 -0
- package/docs/specs/001-verbose-plan-graph/plan.md +127 -0
- package/docs/specs/001-verbose-plan-graph/quickstart.md +106 -0
- package/docs/specs/001-verbose-plan-graph/research.md +100 -0
- package/docs/specs/001-verbose-plan-graph/spec.md +128 -0
- package/docs/specs/001-verbose-plan-graph/tasks.md +223 -0
- package/docs/specs/002-superposition-config-file/checklists/requirements.md +36 -0
- package/docs/specs/002-superposition-config-file/contracts/init-project-config.md +98 -0
- package/docs/specs/002-superposition-config-file/data-model.md +126 -0
- package/docs/specs/002-superposition-config-file/plan.md +208 -0
- package/docs/specs/002-superposition-config-file/quickstart.md +140 -0
- package/docs/specs/002-superposition-config-file/research.md +144 -0
- package/docs/specs/002-superposition-config-file/spec.md +130 -0
- package/docs/specs/002-superposition-config-file/tasks.md +213 -0
- package/docs/team-workflow.md +27 -1
- package/docs/workflows.md +136 -0
- package/overlays/.presets/microservice.yml +32 -6
- package/overlays/.presets/sdd.yml +84 -0
- package/overlays/.presets/web-api.yml +76 -56
- package/overlays/README.md +7 -1
- package/overlays/amp/README.md +70 -0
- package/overlays/amp/devcontainer.patch.json +3 -0
- package/overlays/amp/overlay.yml +15 -0
- package/overlays/amp/setup.sh +21 -0
- package/overlays/amp/verify.sh +21 -0
- package/overlays/claude-code/README.md +83 -0
- package/overlays/claude-code/devcontainer.patch.json +3 -0
- package/overlays/claude-code/overlay.yml +15 -0
- package/overlays/claude-code/setup.sh +21 -0
- package/overlays/claude-code/verify.sh +21 -0
- package/overlays/cloudflared/README.md +190 -0
- package/overlays/cloudflared/devcontainer.patch.json +3 -0
- package/overlays/cloudflared/overlay.yml +15 -0
- package/overlays/cloudflared/setup.sh +49 -0
- package/overlays/cloudflared/verify.sh +21 -0
- package/overlays/direnv/README.md +6 -4
- package/overlays/direnv/setup.sh +0 -12
- package/overlays/gemini-cli/README.md +77 -0
- package/overlays/gemini-cli/devcontainer.patch.json +3 -0
- package/overlays/gemini-cli/overlay.yml +15 -0
- package/overlays/gemini-cli/setup.sh +21 -0
- package/overlays/gemini-cli/verify.sh +21 -0
- package/overlays/grpc-tools/README.md +242 -0
- package/overlays/grpc-tools/devcontainer.patch.json +14 -0
- package/overlays/grpc-tools/overlay.yml +14 -0
- package/overlays/grpc-tools/setup.sh +57 -0
- package/overlays/grpc-tools/verify.sh +47 -0
- package/overlays/keycloak/.env.example +5 -0
- package/overlays/keycloak/README.md +238 -0
- package/overlays/keycloak/devcontainer.patch.json +17 -0
- package/overlays/keycloak/docker-compose.yml +32 -0
- package/overlays/keycloak/overlay.yml +23 -0
- package/overlays/keycloak/verify.sh +54 -0
- package/overlays/mailpit/.env.example +4 -0
- package/overlays/mailpit/README.md +191 -0
- package/overlays/mailpit/devcontainer.patch.json +20 -0
- package/overlays/mailpit/docker-compose.yml +17 -0
- package/overlays/mailpit/overlay.yml +26 -0
- package/overlays/mailpit/verify.sh +52 -0
- package/overlays/ngrok/overlay.yml +2 -1
- package/overlays/opencode/README.md +76 -0
- package/overlays/opencode/devcontainer.patch.json +3 -0
- package/overlays/opencode/overlay.yml +14 -0
- package/overlays/opencode/setup.sh +21 -0
- package/overlays/opencode/verify.sh +21 -0
- package/overlays/python/README.md +51 -35
- package/overlays/python/devcontainer.patch.json +7 -4
- package/overlays/python/setup.sh +50 -23
- package/overlays/python/verify.sh +29 -1
- package/overlays/spec-kit/README.md +181 -0
- package/overlays/spec-kit/devcontainer.patch.json +6 -0
- package/overlays/spec-kit/overlay.yml +19 -0
- package/overlays/spec-kit/setup.sh +45 -0
- package/overlays/spec-kit/verify.sh +33 -0
- package/overlays/windsurf-cli/README.md +69 -0
- package/overlays/windsurf-cli/devcontainer.patch.json +3 -0
- package/overlays/windsurf-cli/overlay.yml +15 -0
- package/overlays/windsurf-cli/setup.sh +21 -0
- package/overlays/windsurf-cli/verify.sh +21 -0
- package/package.json +1 -1
- 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,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
|
|
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
|
|
27
|
+
## Virtual Environment
|
|
25
28
|
|
|
26
|
-
This overlay
|
|
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
|
|
31
|
+
### Why venv?
|
|
29
32
|
|
|
30
|
-
1. **
|
|
31
|
-
2. **
|
|
32
|
-
3. **
|
|
33
|
-
4. **
|
|
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
|
-
###
|
|
38
|
+
### How It Works
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
On container creation, the setup script:
|
|
38
41
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
57
|
+
### Gitignore
|
|
52
58
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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. ✅
|
|
64
|
-
2. ✅
|
|
65
|
-
3. ✅
|
|
66
|
-
4. ✅ Checks for `
|
|
67
|
-
5. ✅ Checks for `
|
|
68
|
-
6. ✅
|
|
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`**
|
|
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
|
-
###
|
|
220
|
+
### Customizing the Interpreter Path
|
|
204
221
|
|
|
205
|
-
|
|
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}
|
|
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": "/
|
|
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
|
}
|
package/overlays/python/setup.sh
CHANGED
|
@@ -1,47 +1,74 @@
|
|
|
1
1
|
#!/bin/bash
|
|
2
|
-
# Python setup script -
|
|
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
|
|
40
|
+
pip install -r ".devcontainer/requirements-overlay-${OVERLAY_NAME}.txt"
|
|
15
41
|
echo "✓ Overlay packages installed"
|
|
16
42
|
fi
|
|
17
43
|
|
|
18
|
-
#
|
|
44
|
+
# Install from root requirements.txt (project production dependencies)
|
|
19
45
|
if [ -f "requirements.txt" ]; then
|
|
20
|
-
echo "📦
|
|
21
|
-
pip install
|
|
46
|
+
echo "📦 Installing dependencies from requirements.txt..."
|
|
47
|
+
pip install -r requirements.txt
|
|
22
48
|
echo "✓ Dependencies installed from requirements.txt"
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
#
|
|
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
|
|
60
|
+
echo "📦 Found pyproject.toml, installing project in editable mode..."
|
|
61
|
+
pip install -e .
|
|
33
62
|
echo "✓ Project installed in editable mode"
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
44
|
-
echo "
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
echo "
|
|
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
|
|
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,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
|