π« 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.jsonnew file mode 100644index 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.shnew file mode 100755index 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.mdindex 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 Agentsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 locall1. 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]