feat(#138): Reorganise .devcontainer/ into autonomous/, scripts/, and a real VS Code devcontainer

[leecampbell-codeagent]

Issue #138: Reorganise .devcontainer/ into autonomous/, scripts/, and a real VS Code devcontainer

Summary

The .devcontainer/ directory currently contains autonomous-agent Docker infrastructure (Dockerfile, agent-loop.sh, firewall scripts, prompt files) rather than a real VS Code / GitHub Codespaces devcontainer.
This misuses the well-known devcontainer convention and was already flagged as confusing in CONTRIBUTING.md (line 54).

The directory also mixes two concerns: host-side orchestration entry points (run.sh, fleet.sh) and Docker build internals (Dockerfile, entrypoint.sh, init-firewall.sh, prompts/).

The goal is to split these cleanly and provide a genuine VS Code devcontainer for human contributors.

What Needs to Change and Why

Why

• devcontainer.json is absent — VS Code and GitHub Codespaces users who open the repo get nothing useful.
• Agent infrastructure mixed with expected devcontainer convention causes contributor confusion (acknowledged in CONTRIBUTING.md).
• run.sh and fleet.sh are host-side scripts that belong with the other orchestration scripts in scripts/.

What

1. Create ./autonomous/ — move all agent Docker build internals here:

   • Dockerfile
   • entrypoint.sh
   • agent-loop.sh
   • init-firewall.sh
   • .env.example
   • prompts/ (all five markdown prompt files)

2. Move run.sh and fleet.sh → ./scripts/ — host-side entry points live alongside plan.sh, execute-issue.sh, execute-milestone.sh.

3. Update run.sh and fleet.sh — fix Docker build context and .env paths:

   • Build context: "$REPO_ROOT/autonomous/" (was "$SCRIPT_DIR/")
   • Dockerfile flag: -f "$REPO_ROOT/autonomous/Dockerfile"
   • .env source/env-file: "$REPO_ROOT/autonomous/.env" (was "$SCRIPT_DIR/.env")
   • Both scripts must derive REPO_ROOT from SCRIPT_DIR (e.g., REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" — but note cd is disallowed in agent contexts; use $(dirname "$SCRIPT_DIR") or realpath "$SCRIPT_DIR/.." instead).

4. Create .devcontainer/devcontainer.json — a proper interactive devcontainer for human contributors:

   • Base image: mcr.microsoft.com/devcontainers/dotnet:8.0
   • Features: Node.js 20, GitHub CLI
   • Post-create command: dotnet restore && npm install -g @anthropic-ai/claude-code
   • VS Code extensions: C# Dev Kit (ms-dotnettools.csdevkit), EditorConfig (editorconfig.editorconfig)
   • No firewall, no agent-loop, no fork cloning

5. Update CONTRIBUTING.md — line 54 references .devcontainer/; update to reference autonomous/ and note scripts/run.sh / scripts/fleet.sh as the entry points.

Files Affected (Confirmed by Exploration)

Files to move (git mv)

Source	Destination
.devcontainer/Dockerfile	autonomous/Dockerfile
.devcontainer/entrypoint.sh	autonomous/entrypoint.sh
.devcontainer/agent-loop.sh	autonomous/agent-loop.sh
.devcontainer/init-firewall.sh	autonomous/init-firewall.sh
.devcontainer/.env.example	autonomous/.env.example
.devcontainer/prompts/	autonomous/prompts/
.devcontainer/run.sh	scripts/run.sh
.devcontainer/fleet.sh	scripts/fleet.sh

Files to create

File	Description
.devcontainer/devcontainer.json	VS Code devcontainer for human contributors

Files to edit

File	Change
scripts/run.sh	Fix build context, Dockerfile path, and .env path to use $REPO_ROOT/autonomous/
scripts/fleet.sh	Fix build context, Dockerfile path, and .env path to use $REPO_ROOT/autonomous/
CONTRIBUTING.md	Update reference from .devcontainer/ to autonomous/; mention scripts/run.sh and scripts/fleet.sh

Files confirmed unchanged

File	Reason
autonomous/Dockerfile	COPY paths are build-context-relative — no changes needed
.gitignore	Already covers autonomous/.env via bare .env pattern on line 122
.claude/settings.json	Already permits Bash(./scripts/*)

Acceptance Criteria

• .devcontainer/ contains only devcontainer.json (no Dockerfile, no shell scripts, no prompts)
• ./autonomous/ contains: Dockerfile, entrypoint.sh, agent-loop.sh, init-firewall.sh, .env.example, prompts/
• ./scripts/ contains: run.sh, fleet.sh, plan.sh, execute-issue.sh, execute-milestone.sh
• scripts/run.sh builds Docker image with $REPO_ROOT/autonomous/ as build context and reads .env from $REPO_ROOT/autonomous/.env
• scripts/fleet.sh builds Docker image with $REPO_ROOT/autonomous/ as build context and reads .env from $REPO_ROOT/autonomous/.env
• .devcontainer/devcontainer.json is valid JSON with base image mcr.microsoft.com/devcontainers/dotnet:8.0, Node.js 20 feature, GitHub CLI feature, post-create dotnet restore && npm install -g @anthropic-ai/claude-code, C# Dev Kit and EditorConfig extensions
• CONTRIBUTING.md no longer references .devcontainer/ for agent infrastructure; references autonomous/ and scripts/run.sh / scripts/fleet.sh
• autonomous/.env.example exists (moved from .devcontainer/.env.example)

Test Strategy

There are no automated tests for shell scripts or Docker infrastructure in this repository (it uses xUnit for .NET code only).
Verification is manual / structural:

1. File presence checks — confirm each file exists at its new path and is absent from its old path.
2. Path correctness in scripts — read scripts/run.sh and scripts/fleet.sh and confirm all references to the build context, Dockerfile, and .env resolve to autonomous/ relative to the repo root.
3. JSON validity — validate .devcontainer/devcontainer.json with jq empty .devcontainer/devcontainer.json.
4. CONTRIBUTING.md review — confirm line 54 (and surrounding context) now references autonomous/ and no longer says .devcontainer/ for agent infrastructure.
5. dotnet build still passes — the .NET solution must not be broken by the reorganisation (it has no dependency on these files).

No new xUnit tests are required — the changed artefacts are infrastructure files, not library code.

Risks and Open Questions

Item	Detail
REPO_ROOT derivation in scripts	run.sh and fleet.sh currently set SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")". After moving to scripts/, SCRIPT_DIR will be <repo>/scripts/. Deriving REPO_ROOT via "$(dirname "$SCRIPT_DIR")" or realpath "$SCRIPT_DIR/.." is fine in bash outside the agent context; cd is forbidden inside agent tool calls but these scripts run as host commands, not via the agent's Bash tool. Use REPO_ROOT="$(realpath "$SCRIPT_DIR/..")" for clarity.
Issue body template artefact	The issue body contains {{ISSUE_BODY}}{{ISSUE_BODY}} in the post-create command — this is a template rendering artefact. The intended command is dotnet restore && npm install -g @anthropic-ai/claude-code.
.env.example move	The .env.example file needs to be moved (not just copied) so contributors know the canonical location is autonomous/.env.example. Update any inline comments or docs that reference its old path.
CONTRIBUTING.md scope	Only the agent-infrastructure paragraph (around line 54) needs updating. The build/test instructions for human contributors remain unchanged.
No devcontainer Dockerfile needed	The issue says "optionally a lightweight Dockerfile" — a plain devcontainer.json using the Microsoft base image is sufficient and simpler.

Task breakdown

Task List — Issue #138: Reorganise .devcontainer/ into autonomous/, scripts/, and a real VS Code devcontainer

Current State (Confirmed by Exploration)

• .devcontainer/ contains: Dockerfile, entrypoint.sh, agent-loop.sh, init-firewall.sh, .env.example, run.sh, fleet.sh, prompts/ (5 files) — no devcontainer.json
• scripts/ contains: plan.sh, execute-issue.sh, execute-milestone.sh — no run.sh or fleet.sh
• autonomous/ directory does not exist
• .devcontainer/devcontainer.json does not exist
• CONTRIBUTING.md line 54 says .devcontainer/ is for agent automation only

---

Tasks

Phase 1 — Move agent infrastructure files to autonomous/

• T1 git mv .devcontainer/Dockerfile autonomous/Dockerfile
  — Moves the agent Docker build file out of the misused devcontainer dir.
  Verify: git status shows renamed: .devcontainer/Dockerfile -> autonomous/Dockerfile; file absent from .devcontainer/.

• T2 git mv .devcontainer/entrypoint.sh autonomous/entrypoint.sh
  — Moves the container entrypoint script.
  Verify: git status shows rename; file absent from .devcontainer/.

• T3 git mv .devcontainer/agent-loop.sh autonomous/agent-loop.sh
  — Moves the agent state-machine loop.
  Verify: git status shows rename; file absent from .devcontainer/.

• T4 git mv .devcontainer/init-firewall.sh autonomous/init-firewall.sh
  — Moves the firewall initialisation script.
  Verify: git status shows rename; file absent from .devcontainer/.

• T5 git mv .devcontainer/.env.example autonomous/.env.example
  — Moves the environment variable template. .gitignore already covers autonomous/.env via the bare .env pattern (line 122).
  Verify: autonomous/.env.example exists; .devcontainer/.env.example absent.

• T6 git mv .devcontainer/prompts autonomous/prompts
  — Moves the entire prompts directory (5 markdown files: execute-tasks.md, pick-issue.md, apply-review.md, create-tasks.md, review-brief.md).
  Verify: autonomous/prompts/ contains all 5 files; .devcontainer/prompts/ absent.

Phase 2 — Move host-side entry points to scripts/

• T7 git mv .devcontainer/run.sh scripts/run.sh
  — Moves the single-agent launch script alongside the other host-side orchestration scripts.
  Verify: scripts/run.sh exists; .devcontainer/run.sh absent.

• T8 git mv .devcontainer/fleet.sh scripts/fleet.sh
  — Moves the multi-agent fleet orchestration script.
  Verify: scripts/fleet.sh exists; .devcontainer/fleet.sh absent.

Phase 3 — Update path references in moved scripts

• T9 Update scripts/run.sh — add REPO_ROOT derivation and fix all paths.
  After the existing SCRIPT_DIR line, add:
  REPO_ROOT="$(realpath "$SCRIPT_DIR/..")"
  Then replace:

  • "$SCRIPT_DIR/.env" (source) → "$REPO_ROOT/autonomous/.env"
  • "$SCRIPT_DIR/Dockerfile" → "$REPO_ROOT/autonomous/Dockerfile"
  • "$SCRIPT_DIR/" (build context) → "$REPO_ROOT/autonomous/"
  • "$SCRIPT_DIR/.env" (env-file) → "$REPO_ROOT/autonomous/.env"
    Verify: Read scripts/run.sh; confirm no remaining $SCRIPT_DIR references to .env or Dockerfile; all four path occurrences use $REPO_ROOT/autonomous/.

• T10 Update scripts/fleet.sh — add REPO_ROOT derivation and fix all paths.
  After the existing SCRIPT_DIR line, add:
  REPO_ROOT="$(realpath "$SCRIPT_DIR/..")"
  Then replace:

  • "$SCRIPT_DIR/.env" (source) → "$REPO_ROOT/autonomous/.env"
  • "$SCRIPT_DIR/Dockerfile" → "$REPO_ROOT/autonomous/Dockerfile"
  • "$SCRIPT_DIR/" (build context) → "$REPO_ROOT/autonomous/"
  • "$SCRIPT_DIR/.env" (env-file) → "$REPO_ROOT/autonomous/.env"
    Verify: Read scripts/fleet.sh; confirm no remaining $SCRIPT_DIR references to .env or Dockerfile; all four path occurrences use $REPO_ROOT/autonomous/.

Phase 4 — Create the real VS Code devcontainer

• T11 Create .devcontainer/devcontainer.json with the following content:
  • name: "HdrHistogram.NET"
  • image: "mcr.microsoft.com/devcontainers/dotnet:8.0"
  • features: Node.js 20 (ghcr.io/devcontainers/features/node:1 with version: "20") and GitHub CLI (ghcr.io/devcontainers/features/github-cli:1)
  • postCreateCommand: "dotnet restore && npm install -g @anthropic-ai/claude-code"
  • customizations.vscode.extensions: ["ms-dotnettools.csdevkit", "editorconfig.editorconfig"]
    Verify: jq empty .devcontainer/devcontainer.json exits 0 (valid JSON); jq '.image' .devcontainer/devcontainer.json outputs "mcr.microsoft.com/devcontainers/dotnet:8.0".

Phase 5 — Update CONTRIBUTING.md

• T12 Update CONTRIBUTING.md around line 54 — replace the paragraph that references .devcontainer/ as agent-only infrastructure.
  New text should:
  • State that autonomous/ contains the agent Docker infrastructure
  • Name scripts/run.sh and scripts/fleet.sh as the host-side entry points
  • No longer describe .devcontainer/ as agent-only (it is now a proper VS Code devcontainer)
    Verify: Read CONTRIBUTING.md; confirm the word ".devcontainer/" does not appear in the context of agent infrastructure; autonomous/ is mentioned; scripts/run.sh and scripts/fleet.sh are named.

Phase 6 — Verification

• T13 Confirm .devcontainer/ contains only devcontainer.json and nothing else.
  Run: ls .devcontainer/ and confirm only devcontainer.json is listed.

• T14 Confirm autonomous/ contains all six expected items.
  Run: ls autonomous/ and confirm Dockerfile, entrypoint.sh, agent-loop.sh, init-firewall.sh, .env.example, prompts/ are present.

• T15 Confirm scripts/ contains all five expected scripts.
  Run: ls scripts/ and confirm run.sh, fleet.sh, plan.sh, execute-issue.sh, execute-milestone.sh are present.

• T16 Validate devcontainer.json is well-formed JSON.
  Run: jq empty .devcontainer/devcontainer.json — must exit 0 with no output.

• T17 Verify dotnet build still passes (the .NET solution has no dependency on infrastructure files).
  Run: dotnet build from repo root — must exit 0 with no errors.

---

Acceptance Criteria Cross-Reference

Acceptance Criterion	Covered By
.devcontainer/ contains only devcontainer.json	T1–T8 (moves), T13 (verify)
./autonomous/ contains Dockerfile, entrypoint.sh, agent-loop.sh, init-firewall.sh, .env.example, prompts/	T1–T6, T14 (verify)
./scripts/ contains run.sh, fleet.sh, plan.sh, execute-issue.sh, execute-milestone.sh	T7–T8, T15 (verify)
scripts/run.sh uses $REPO_ROOT/autonomous/ for build context and .env	T9
scripts/fleet.sh uses $REPO_ROOT/autonomous/ for build context and .env	T10
.devcontainer/devcontainer.json is valid JSON with correct base image, features, post-create command, extensions	T11, T16 (verify)
CONTRIBUTING.md references autonomous/ and scripts/run.sh / scripts/fleet.sh; no .devcontainer/ for agent infra	T12
autonomous/.env.example exists	T5, T14 (verify)

Closes #138

[LeeCampbell]

Let's give it a go. Could also open the repo up to working nicely on codespaces?
WOuld make it nice when jumping between my PCs and MacBook