Devcontainer Removal Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Remove all devcontainer-related code while preserving user access to personal secrets in Vault

Architecture: Two-phase approach - first migrate Vault policy permissions (critical for MCP credentials), then remove all devcontainer files and references

Tech Stack: Terraform (Vault provider), Git, Bash

---

Phase 1: Vault Policy Migration

Task 1: Create Feature Branch and Update Default Policy

Files: - Modify: tf/vault/policy-default.tf (add user secrets section at end of policy)

Step 1: Create feature branch

git checkout main && git pull origin main
git checkout -b chore/devcontainer-removal

Step 2: Add user secrets access to default policy

Add the following HCL at the end of the policy string in policy-default.tf, before the closing EOT:

# =============================================================================
# Per-User Secret Storage
# =============================================================================

# Allow users to manage their own secrets (MCP server keys, etc.)
path "secret/data/users/{{identity.entity.name}}/*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "secret/metadata/users/{{identity.entity.name}}/*" {
  capabilities = ["list", "delete"]
}

Step 3: Verify the edit

Ensure the policy block ends with:

...
path "secret/metadata/users/{{identity.entity.name}}/*" {
  capabilities = ["list", "delete"]
}

EOT
}

Step 4: Commit

git add tf/vault/policy-default.tf
git commit -m "feat(vault): add user secrets access to default policy

Migrates secret/users/* access from claude-code policy to default policy.
This is a general user capability (MCP server API keys), not devcontainer-specific.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 2: Delete Claude-Code Policy

Files: - Delete: tf/vault/policy-claude-code.tf

Step 1: Remove policy file

rm tf/vault/policy-claude-code.tf

Step 2: Commit

git add -u tf/vault/policy-claude-code.tf
git commit -m "chore(vault): remove claude-code policy

Access to secret/users/* has been migrated to the default policy.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 3: Validate Terraform Changes

Step 1: Initialize and plan

cd tf/vault
terraform init -upgrade
terraform plan

Expected output: - vault_policy.default will be updated (adding user secrets paths) - vault_policy.claude_code will be destroyed - No other resources affected

Step 2: Verify no errors

If plan shows expected changes only, proceed. If errors, investigate before continuing.

---

Phase 2: Devcontainer Removal

Task 4: Delete Devcontainer Directory

Files: - Delete: .devcontainer/ (entire directory)

Step 1: Remove directory

rm -rf .devcontainer

Step 2: Commit

git add -A .devcontainer
git commit -m "chore: remove devcontainer directory

Development workflow has shifted to native macOS + Claude Code CLI.
Configuration preserved in git history for potential future reference.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 5: Delete CI Workflow

Files: - Delete: .github/workflows/devcontainer-ci.yml

Step 1: Remove workflow file

rm .github/workflows/devcontainer-ci.yml

Step 2: Commit

git add -u .github/workflows/devcontainer-ci.yml
git commit -m "ci: remove devcontainer CI workflow

No longer needed as devcontainer configuration has been removed.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 6: Delete Helper Script

Files: - Delete: dev.sh

Step 1: Remove script

rm dev.sh

Step 2: Commit

git add -u dev.sh
git commit -m "chore: remove dev.sh helper script

Script was entirely devcontainer-focused. No longer needed.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 7: Archive Design Document

Files: - Move: docs/plans/2025-12-25-devcontainer-claude-code-design.md → docs/plans/archive/2025-12-25-devcontainer-claude-code-design.md

Step 1: Move file to archive

mv docs/plans/2025-12-25-devcontainer-claude-code-design.md docs/plans/archive/

Step 2: Commit

git add docs/plans/2025-12-25-devcontainer-claude-code-design.md docs/plans/archive/2025-12-25-devcontainer-claude-code-design.md
git commit -m "docs: archive devcontainer design document

Feature has been removed. Preserving design for historical reference.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 8: Update CLAUDE.md

Files: - Modify: CLAUDE.md (remove lines 121-129)

Step 1: Remove devcontainer section

Remove the following section from CLAUDE.md:

### `.devcontainer/CLAUDE.md`
**Read when:** Modifying devcontainer configuration or CI workflow
- Two-config pattern: main (`devcontainer.json`) vs CI (`ci/devcontainer.json`)
- Host bind mounts vs Docker volumes (CI can't use host paths)
- Feature-based tool installation
- **Shell configuration:** zsh default, aliases MUST go to both `.zshrc` AND `.bashrc`
- **Git config:** Programmatic (not mounted), uses `GIT_AUTHOR_*` env vars
- **Homebrew tools:** Adding new tools, alias patterns
- `devcontainer-ci.yml` workflow validation

This section starts after ###argocd/CLAUDE.md` and ends before## Security`.

Step 2: Verify context-specific section ends properly

After edit, the Context-Specific Instructions section should end with:

### `argocd/CLAUDE.md`
**Read when:** Modifying Kubernetes manifests or application configs
- Application directory structure and kustomization patterns
- ExternalSecret integration with Vault ClusterSecretStore
- Naming conventions (kebab-case), RBAC scoping
- GitOps workflow (changes sync via ArgoCD after merge)

## Security

Step 3: Commit

git add CLAUDE.md
git commit -m "docs: remove devcontainer section from CLAUDE.md

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 9: Update .envrc

Files: - Modify: .envrc (remove line 22)

Step 1: Remove devcontainer comment

Remove this line from .envrc:

# in devcontainers. Run `vault login -method=oidc` on the host first.

The comment block should end with:

# Note: Vault OIDC login requires localhost:8250 callback, which doesn't work
# when running remotely. Run `vault login -method=oidc` locally first.

Wait - let me re-read. The original says:

# Note: Vault OIDC login requires localhost:8250 callback, which doesn't work
# in devcontainers. Run `vault login -method=oidc` on the host first.

The second line references devcontainers. Update to remove devcontainer reference:

Step 2: Update the comment to be accurate

Replace:

# Note: Vault OIDC login requires localhost:8250 callback, which doesn't work
# in devcontainers. Run `vault login -method=oidc` on the host first.

With:

# Note: Vault OIDC login requires localhost:8250 callback. Ensure you're
# running `vault login -method=oidc` from a local terminal with browser access.

Step 3: Commit

git add .envrc
git commit -m "chore: remove devcontainer reference from .envrc

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 10: Update .gitignore

Files: - Modify: .gitignore (remove lines 195-196)

Step 1: Remove devcontainer entry

Remove these lines from the end of .gitignore:

# Devcontainer environment file (generated by initializeCommand)
.devcontainer/.env.devcontainer

Step 2: Commit

git add .gitignore
git commit -m "chore: remove devcontainer entry from .gitignore

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Task 11: Update docs/README.md

Files: - Modify: docs/README.md (remove line 13)

Step 1: Remove devcontainer link from table

Remove this row from the Quick Reference table:

| [../.devcontainer/README.md](../.devcontainer/README.md) | Development container setup and usage |

Step 2: Verify table structure

After removal, the Quick Reference table should be:

## Quick Reference

| Document | Purpose |
|----------|---------|
| [windmill.md](windmill.md) | Windmill Terraform GitOps automation |
| [vault.md](vault.md) | HashiCorp Vault secrets management |
| [mcp-servers.md](mcp-servers.md) | MCP server configuration for AI assistants |
| [github-token-setup.md](github-token-setup.md) | GitHub PAT for Actions Runner Controller |

Step 3: Commit

git add docs/README.md
git commit -m "docs: remove devcontainer link from docs README

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

---

Phase 3: Final Steps

Task 12: Create Pull Request

Step 1: Push branch

git push -u origin chore/devcontainer-removal

Step 2: Create PR

gh pr create --title "chore: remove devcontainer infrastructure" --body "$(cat <<'EOF'
## Summary

Removes all devcontainer-related code, configuration, and documentation.

### Motivation

- **Not in use** - Development workflow has shifted to native macOS + Claude Code CLI
- **Maintenance burden** - Keeping devcontainer config current requires ongoing effort
- **Simplification** - Reducing repository complexity

### Changes

**Vault Policy Migration (Critical)**
- Added user secrets access (`secret/users/*`) to default policy
- Removed `policy-claude-code.tf`
- MCP server credentials continue to work seamlessly

**Deleted**
- `.devcontainer/` directory (14 files)
- `.github/workflows/devcontainer-ci.yml`
- `dev.sh` helper script

**Updated**
- `CLAUDE.md` - removed devcontainer section
- `.envrc` - removed devcontainer reference
- `.gitignore` - removed devcontainer entry
- `docs/README.md` - removed devcontainer link

**Archived**
- `docs/plans/2025-12-25-devcontainer-claude-code-design.md`

### Rollback

If needed, restore from git history:
```bash
git checkout HEAD~1 -- .devcontainer/

Test plan

• [ ] Verify Terraform plan shows only policy changes
• [ ] Confirm MCP server credentials still work after merge
• [ ] Verify no broken links in documentation

🤖 Generated with Claude Code EOF )"

---

### Task 13: Apply Terraform (After PR Merge)

**IMPORTANT:** This task runs AFTER the PR is merged to main.

**Step 1: Verify HCP Terraform run**

HCP Terraform will automatically plan/apply after merge. Monitor the run:

```bash
# Check latest run status
gh api repos/fzymgc-house/selfhosted-cluster/actions/runs --jq '.workflow_runs[0] | {status, conclusion, name}'

Or check HCP Terraform UI: https://app.terraform.io/app/fzymgc-house/workspaces/vault/runs

Step 2: Verify MCP credentials still work

After Terraform applies, test that Vault secrets are accessible:

vault kv get secret/users/$(vault_entity_name)/firecrawl

Expected: Should return API key if previously stored.

---

Task 14: Archive This Implementation Plan

Files: - Move: docs/plans/2025-12-28-devcontainer-removal-implementation.md → docs/plans/archive/2025-12-28-devcontainer-removal-implementation.md - Move: docs/plans/2025-12-28-devcontainer-removal-design.md → docs/plans/archive/2025-12-28-devcontainer-removal-design.md

Step 1: Archive plans after successful merge

git checkout main && git pull
mv docs/plans/2025-12-28-devcontainer-removal-implementation.md docs/plans/archive/
mv docs/plans/2025-12-28-devcontainer-removal-design.md docs/plans/archive/
git add docs/plans/
git commit -m "docs: archive devcontainer removal plans

Implementation complete.

🤖 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
git push origin main