Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

chore: add `devcontainer` support to ease developer workstation setup

Tine Kondo900bc2ed68e3
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 000000000..2b57f67e9
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,58 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+ "name": "SpecKitDevContainer",
+ // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+ "image": "mcr.microsoft.com/devcontainers/python:3.13-trixie", // based on Debian "Trixie" (13)
+ "features": {
+ "ghcr.io/devcontainers/features/common-utils:2": {
+ "installZsh": true,
+ "installOhMyZsh": true,
+ "installOhMyZshConfig": true,
+ "upgradePackages": true,
+ "username": "devcontainer",
+ "userUid": "automatic",
+ "userGid": "automatic"
+ },
+ "ghcr.io/devcontainers/features/dotnet:2": {
+ "version": "lts"
+ },
+ "ghcr.io/devcontainers/features/git:1": {
+ "ppa": true,
+ "version": "latest"
+ }
+ },
+
+ // Use 'forwardPorts' to make a list of ports inside the container available locally.
+ "forwardPorts": [
+ 8080 // for Spec-Kit documentation site
+ ],
+ "containerUser": "devcontainer",
+ "updateRemoteUserUID": true,
+ "postCreateCommand": "chmod +x ./.devcontainer/post-create.sh && ./.devcontainer/post-create.sh",
+ "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
+ "customizations": {
+ "vscode": {
+ "extensions": [
+ "mhutchie.git-graph",
+ "eamodio.gitlens",
+ "anweber.reveal-button",
+ "chrisdias.promptboost",
+ // Github Copilot
+ "GitHub.copilot",
+ "GitHub.copilot-chat",
+ // Codex
+ "openai.chatgpt",
+ // Kilo Code
+ "kilocode.Kilo-Code",
+ // Roo Code
+ "RooVeterinaryInc.roo-cline",
+ // Amazon Developer Q
+ "AmazonWebServices.amazon-q-vscode"
+ ],
+ "settings": {
+ "debug.javascript.autoAttachFilter": "disabled" // fix running commands in integrated terminal
+ }
+ }
+ }
+}
diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh
new file mode 100755
index 000000000..797fd831b
--- /dev/null
+++ b/.devcontainer/post-create.sh
@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# Exit immediately on error, treat unset variables as an error, and fail if any command in a pipeline fails.
+set -euo pipefail
+
+# Function to run a command and show logs only on error
+run_command() {
+ local command_to_run="$*"
+ local output
+ local exit_code
+
+ # Capture all output (stdout and stderr)
+ output=$(eval "$command_to_run" 2>&1) || exit_code=$?
+ exit_code=${exit_code:-0}
+
+ if [ $exit_code -ne 0 ]; then
+ echo -e "\033[0;31m[ERROR] Command failed (Exit Code $exit_code): $command_to_run\033[0m" >&2
+ echo -e "\033[0;31m$output\033[0m" >&2
+
+ return $exit_code
+ fi
+}
+
+# Note: We use Bun (instead of npm) as our package manager for its speed and overall efficiency
+# It is a drop-in replacement for Node.js, so we can install npm packages through it without issues
+echo "πŸ“¦ Installing Bun Package Manager..."
+run_command "curl -fsSL https://bun.sh/install | bash"
+run_command "source ~/.bashrc"
+echo "βœ… Done"
+
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+
+# Installing CLI-based AI Agents
+
+echo -e "\nπŸ€– Installing Copilot CLI..."
+run_command "bun add --global @github/copilot@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing Claude CLI..."
+run_command "bun add --global @anthropic-ai/claude-code@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing Codex CLI..."
+run_command "bun add --global @openai/codex@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing Gemini CLI..."
+run_command "bun add --global @google/gemini-cli@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing Augie CLI..."
+run_command "bun add --global @augmentcode/auggie@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing Qwen Code CLI..."
+run_command "bun add --global @qwen-code/qwen-code@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing OpenCode CLI..."
+run_command "bun add --global opencode-ai@latest"
+echo "βœ… Done"
+
+echo -e "\nπŸ€– Installing Amazon Developer Q CLI..."
+run_command "curl --proto '=https' --tlsv1.2 -sSf \"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip\" -o \"q.zip\""
+run_command "unzip q.zip && rm q.zip"
+run_command "./q/install.sh --no-confirm"
+run_command "rm -rf ./q"
+echo "βœ… Done"
+
+# Installing UV (Python package manager)
+echo -e "\n🐍 Installing UV - Python Package Manager..."
+run_command "pipx install uv"
+echo "βœ… Done"
+
+# Installing DocFx (for documentation site)
+echo -e "\nπŸ“š Installing DocFx..."
+run_command "dotnet tool update -g docfx"
+echo "βœ… Done"
+
+echo -e "\n🧹 Cleaning cache..."
+run_command "sudo apt-get autoclean"
+run_command "sudo apt-get clean"
+
+echo "βœ… Setup completed. Happy coding! πŸš€"
diff --git a/AGENTS.md b/AGENTS.md
index 62bbe1e0e..40c187ac0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -239,6 +239,51 @@ AGENT_CONFIG = {
- Reduces the chance of bugs when adding new agents
- Tool checking "just works" without additional mappings
+#### 7. Update Devcontainer files (Optional)
+
+For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files:
+
+##### VS Code Extension-based Agents
+
+For agents available as VS Code extensions, add them to `.devcontainer/devcontainer.json`:
+
+```json
+{
+ "customizations": {
+ "vscode": {
+ "extensions": [
+ // ... existing extensions ...
+ // [New Agent Name]
+ "[New Agent Extension ID]"
+ ]
+ }
+ }
+}
+```
+
+##### CLI-based Agents
+
+For agents that require CLI tools, add installation commands to `.devcontainer/post-create.sh`:
+
+```bash
+#!/bin/bash
+
+# Existing installations...
+
+echo -e "\nπŸ€– Installing [New Agent Name] CLI..."
+# run_command "bun add --global [agent-cli-package]@latest" # Example for node-based CLI
+# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)...
+echo "βœ… Done"
+
+```
+
+**Quick Tips:**
+
+- **Extension-based agents**: Add to the `extensions` array in `devcontainer.json`
+- **CLI-based agents**: Add installation scripts to `post-create.sh`
+- **Hybrid agents**: May require both extension and CLI installation
+- **Test thoroughly**: Ensure installations work in the devcontainer environment
+
## Agent Categories
### CLI-Based Agents
@@ -249,6 +294,7 @@ Require a command-line tool to be installed:
- **Cursor**: `cursor-agent` CLI
- **Qwen Code**: `qwen` CLI
- **opencode**: `opencode` CLI
+- **Amazon Q Developer CLI**: `q` CLI
- **CodeBuddy CLI**: `codebuddy` CLI
### IDE-Based Agents
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 947480d03..39ba07b95 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,6 +13,23 @@ These are one time installations required to be able to test your changes locall
1. Install [Git](https://git-scm.com/downloads)
1. Have an [AI coding agent available](README.md#-supported-ai-agents)
+<details>
+<summary><b>πŸ’‘ Hint if you are using <code>VSCode</code> or <code>Github Codespaces</code> as your IDE</b></summary>
+
+<br>
+
+Provided you have [Docker](https://docker.com) installed on your machine, you can leverage [Dev Containers](https://containers.dev) through this [VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), to easily set up your development environment, with aforementioned tools already installed and configured, thanks to the `.devcontainer/devcontainer.json` file (located at the root of the project).
+
+To do so, simply:
+
+- Checkout the repo
+- Open it with VSCode
+- Open the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and select "Dev Containers: Open Folder in Container..."
+
+On [Github Codespaces](https://github.com/features/codespaces) it's even simpler, as it leverages the `.devcontainer/devcontainer.json` automatically upon opening the codespace.
+
+</details>
+
## Submitting a pull request
>[!NOTE]