refactor: clean up template repo, add ToB devcontainer + firewall setup

- Remove stale files (PDFs, IMPLEMENTATION_PLAN stub, .dockerignore)
- Add --devcontainer trailofbits and --egress-firewall to setup_project.py
- Rewrite README with composition diagram showing 3 external components
- Update CLAUDE.md with correct repo URLs
- Update GETTING_STARTED.md for split architecture
- Update CHANGELOG with split summary

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: stranma

.dockerignore

@@ -59,7 +59,7 @@ jobs:
         run: |
           # Paths managed by the template (synced from upstream)
           # Defined once here; reused in the apply step via GITHUB_OUTPUT
-          TEMPLATE_PATHS=".claude/agents/ .claude/commands/ .claude/hooks/ .claude/rules/ .claude/skills/ .devcontainer/ .github/workflows/ docs/DEVELOPMENT_PROCESS.md"
+          TEMPLATE_PATHS=".github/workflows/ scripts/"
           echo "template_paths=${TEMPLATE_PATHS}" >> "$GITHUB_OUTPUT"
 
           # Get changed files between local and upstream
@@ -156,7 +156,8 @@ jobs:
 
           ### What to review
           - Check if any synced files conflict with project-specific customizations
-          - Template-managed paths: `.claude/`, `.devcontainer/`, `.github/workflows/`, `docs/DEVELOPMENT_PROCESS.md`
+          - Template-managed paths: `.github/workflows/`, `scripts/`
+          - `.claude/` is managed by `pyclaude-forge`, `.devcontainer/` by `claude-code-devcontainer`
           - Project-specific files (`apps/`, `libs/`, `tests/`, `pyproject.toml`, `README.md`) are NOT touched
 
           ### How to resolve conflicts

.github/workflows/template-sync.yml

@@ -32,5 +32,6 @@ All packages maintain synchronized MAJOR.MINOR versions. Patch versions can diff
 ## Optional Integrations
 
 This template can be composed with:
-- **[claude-code-harness](../claude-code-harness)** -- Claude Code workflow (skills, agents, rules, hooks)
-- **[claude-code-devcontainer](../claude-code-devcontainer)** -- secure devcontainer with egress firewall
+- **[pyclaude-forge](https://github.com/stranma/pyclaude-forge)** -- Claude Code workflow (skills, agents, rules, hooks)
+- **[trailofbits/claude-code-devcontainer](https://github.com/trailofbits/claude-code-devcontainer)** -- secure devcontainer with Claude Code
+- **[Egress firewall](https://gist.github.com/stranma/f43d932bedc8335e24404c9784fcf190)** -- iptables whitelist preventing code exfiltration

CLAUDE.md

@@ -8,26 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
-- Security model simplified to 2-layer exfiltration defense: iptables firewall (primary) blocks non-approved network domains; `dangerous-actions-blocker.sh` (narrowed) blocks exfiltration via trusted channels (gh gist, gh issue --body, package publishing, secrets in args) -- local destruction (rm -rf, sudo, etc.) is no longer blocked since devcontainer is disposable
-- CLAUDE.md Security section rewritten to describe the 2-layer defense model instead of listing individual hooks
-- Devcontainer simplified: permission tiers removed, single settings.json baseline for all environments
+- Repository split into 3 independent repos: template (this), [pyclaude-forge](https://github.com/stranma/pyclaude-forge) (workflow), [claude-code-devcontainer](https://github.com/stranma/claude-code-devcontainer) (deprecated, use Trail of Bits)
+- `setup_project.py` gains `--devcontainer trailofbits` and `--egress-firewall` options to compose external components
+- README rewritten with composition diagram showing how the 3 external pieces plug in
+- GETTING_STARTED.md updated for the split architecture
+- `template-sync.yml` paths reduced to `.github/workflows/` and `scripts/` only
 
 ### Removed
-- Permission tier system (`.devcontainer/permissions/tier1-assisted.json`, `tier2-autonomous.json`, `tier3-full-trust.json`) and `PERMISSION_TIER` env var -- single settings.json baseline replaces graduated tiers
-- `devcontainer-policy-blocker.sh` hook -- tier-dependent policy enforcement no longer needed
-- `output-secrets-scanner.sh` hook -- conversation leaks to Anthropic are accepted risk
-- `unicode-injection-scanner.sh` hook -- exotic threat with low practical risk
-- `test-on-change.sh` hook -- informational-only hook that added latency without preventing issues
-- All slash commands (`/cove`, `/cove-isolated`, `/security-audit`) -- niche utilities that added complexity without proportional value
-- 6 agents: `agent-auditor`, `security-auditor`, `output-evaluator`, `acceptance-criteria-validator`, `implementation-tracker`, `refactoring-specialist` -- pruned to the 6 agents directly used by the QSP workflow
-- `/edit-permissions` skill -- permission tier system removed
-- `docs/ARCHITECTURE_GUIDE.md`, `docs/DEVCONTAINER_PERMISSIONS.md`, `docs/community/` -- supporting docs for removed features
-- Local destruction patterns from `dangerous-actions-blocker.sh` (`rm -rf`, `sudo`, `DROP DATABASE`, `git push --force`, etc.) -- devcontainer is disposable, these blocks added friction without security value
-
-### Added
-- Architecture Deep Dive guide (`docs/ARCHITECTURE_GUIDE.md`) explains why each component exists, what it does under the hood, and what happens if you remove or modify it -- covers all hooks, agents, skills, rules, configuration files, devcontainer layers, and CI/CD workflows with a defense-in-depth diagram and customization guide
-- `/landed` skill for post-merge lifecycle -- verifies merge CI, optionally checks deployments (via `.claude/deploy.json`), cleans up feature branches, and identifies the next phase for P-scope work
-- `.claude/deploy.json.example` template for configuring deployment verification in `/landed`
+- All `.claude/` content (moved to [pyclaude-forge](https://github.com/stranma/pyclaude-forge))
+- All `.devcontainer/` content (use [trailofbits/claude-code-devcontainer](https://github.com/trailofbits/claude-code-devcontainer) instead)
+- Permission tiers, security hooks, policy enforcement -- dropped from scope
+- Stale docs: PDF artifacts, IMPLEMENTATION_PLAN.md stub, .dockerignore
+- Broken doc references: ARCHITECTURE_GUIDE.md, DEVCONTAINER_PERMISSIONS.md
 - Chain-of-Verification (CoVe) commands (`/cove`, `/cove-isolated`) for high-stakes accuracy -- 4-step self-verification process based on Meta's CoVe paper, with an isolated variant that runs verification in a separate agent to prevent confirmation bias
 - Template sync workflow (`.github/workflows/template-sync.yml`) for downstream projects to auto-sync upstream template improvements -- runs weekly or on manual trigger, creates PRs with changed template-managed files while preserving project-specific code
 - Python-specific SOLID checklist in `refactoring-specialist` agent -- checks for mutable default arguments, ABC/Protocol misuse, missing dependency injection, god classes, `@property` overuse, and circular imports

README.md

@@ -10,19 +10,13 @@ Before using this template, you should be comfortable with:
 - Opening a terminal (VS Code integrated terminal, Windows Terminal, macOS Terminal)
 - Navigating directories (`cd`, `ls`/`dir`)
 - Running commands and reading their output
-- Understanding file paths
 
 ### Git basics
-- What a repository is
 - `git clone`, `git add`, `git commit`, `git push`
 - What a branch is and how to create one (`git checkout -b`)
-- What a pull request (PR) is -- you don't need to be an expert, but you should understand the concept
+- What a pull request (PR) is
 
-If git is new to you, work through [Git - the simple guide](https://rogerdudler.github.io/git-guide/) first. It takes about 15 minutes.
-
-### GitHub account
-- You need a [GitHub](https://github.com) account to use the template and its CI/CD workflows
-- Install the [GitHub CLI](https://cli.github.com/) (`gh`) -- the template's `/done` command uses it to create PRs and check CI status
+If git is new to you, work through [Git - the simple guide](https://rogerdudler.github.io/git-guide/) first.
 
 ### Python basics
 - You can write and run a Python script
@@ -42,8 +36,6 @@ If you need to install or upgrade: [python.org/downloads](https://www.python.org
 
 ### 2. uv (package manager)
 
-uv replaces pip, virtualenv, and poetry. It's fast and handles everything.
-
 ```bash
 # macOS/Linux:
 curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -62,31 +54,31 @@ npm install -g @anthropic-ai/claude-code
 
 You'll need an Anthropic API key or a Claude subscription. See [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/overview).
 
-### 4. VS Code + Dev Containers (recommended)
+### 4. Devcontainer (optional)
+
+For a secure sandbox where Claude Code runs in isolation:
 
-The template includes a devcontainer that sandboxes Claude Code for safety.
+```bash
+python setup_project.py --name my-project --devcontainer trailofbits --egress-firewall
+```
 
-1. Install [VS Code](https://code.visualstudio.com/)
-2. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
-3. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
-4. Clone your project, open in VS Code, and click "Reopen in Container" when prompted
+This clones [trailofbits/claude-code-devcontainer](https://github.com/trailofbits/claude-code-devcontainer) and adds an egress firewall. You'll need:
 
-The devcontainer comes with Python, uv, ruff, git, and Claude Code pre-installed.
+1. [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+2. VS Code [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
 
 ## Your First Project
 
 ### 1. Create from template
 
-Go to [stranma/claude-code-python-template](https://github.com/stranma/claude-code-python-template) and click **"Use this template"** > **"Create a new repository"**. Clone it locally.
+Go to [stranma/claude-code-python-template](https://github.com/stranma/claude-code-python-template) and click **"Use this template"**. Clone it locally.
 
 ### 2. Run setup
 
 ```bash
 python setup_project.py --name my-first-project --namespace my_first_project --type single
 ```
 
-This renames all placeholder files to match your project name.
-
 ### 3. Install dependencies
 
 ```bash
@@ -101,50 +93,39 @@ uv run ruff check .
 uv run pyright
 ```
 
-All three should pass with no errors.
-
 ### 5. Start Claude Code
 
 ```bash
 claude
 ```
 
-Try these to get a feel for the workflow:
-
+Try:
 ```
 > /sync
 > "Add a function that calculates fibonacci numbers with tests"
 > /done
 ```
 
-Claude Code will write the code, write tests, and `/done` will validate, commit, and create a PR.
-
 ## Key Concepts
 
 ### What is CLAUDE.md?
 
-A file in your project root that tells Claude Code how to behave. It contains project rules, development commands, and workflow references. Think of it as a briefing document for your AI assistant. The template provides one pre-configured for the `/sync` -> `/design` -> `/done` workflow.
+A file in your project root that tells Claude Code how to behave -- project rules, development commands, workflow references. The template provides one pre-configured.
 
 ### What are agents?
 
-Agents are specialized Claude Code sub-processes that handle specific tasks (linting, testing, code review). They run automatically as part of the workflow. You don't invoke them directly -- `/done` orchestrates them.
+Specialized Claude Code sub-processes for specific tasks (linting, testing, code review). They run automatically as part of `/done`.
 
 ### What are hooks?
 
-Shell scripts that run before or after Claude Code actions. For example, the `dangerous-actions-blocker` hook prevents Claude from running `rm -rf` or leaking secrets. They run silently in the background.
-
-### What is TDD?
-
-Test-Driven Development: write the test first, then write the code to make it pass. The template enforces this order. It feels backwards at first, but it produces more reliable code because you're always building toward a defined expectation.
+Shell scripts that run before or after Claude Code actions. For example, `auto-format` runs ruff after edits.
 
 ### What is a devcontainer?
 
-A Docker container configured for development. VS Code opens your project inside the container, so all tools are pre-installed and Claude Code runs in a sandbox. If something goes wrong, your host machine is unaffected.
+A Docker container configured for development. VS Code opens your project inside it, so all tools are pre-installed and Claude Code runs in a sandbox.
 
 ## Next Steps
 
-- Read the [Development Process](DEVELOPMENT_PROCESS.md) to understand the full workflow
-- Read the [Architecture Deep Dive](ARCHITECTURE_GUIDE.md) to understand why each component exists and what happens if you remove it
-- Try the `/design` command to plan a small feature before implementing it
-- Run `/security-audit` to see how the security scanning works
-- Check [Devcontainer Permissions](DEVCONTAINER_PERMISSIONS.md) if you want to adjust Claude Code's autonomy level
+- Install [pyclaude-forge](https://github.com/stranma/pyclaude-forge) for the full Claude Code workflow (`/sync`, `/design`, `/done`, `/landed`)
+- Try the `/design` command to plan a feature before implementing it
+- Read the [CHANGELOG](CHANGELOG.md) for the latest updates

docs/CHANGELOG.md

@@ -18,6 +18,7 @@
 import shutil
 import subprocess
 import sys
+import urllib.request
 from datetime import datetime
 from pathlib import Path
 
@@ -473,6 +474,74 @@ def get_input(prompt: str, default: str = "") -> str:
     return input(f"{prompt}: ").strip()
 
 
+FIREWALL_GIST_URL = (
+    "https://gist.githubusercontent.com/stranma/"
+    "f43d932bedc8335e24404c9784fcf190/raw/init-firewall.sh"
+)
+
+TOB_REPO = "https://github.com/trailofbits/claude-code-devcontainer.git"
+
+
+def setup_devcontainer(root: Path, *, devcontainer: str, egress_firewall: bool) -> list[str]:
+    """Set up devcontainer from Trail of Bits + optional egress firewall.
+
+    :param root: Project root directory.
+    :param devcontainer: Devcontainer type ("trailofbits" or "none").
+    :param egress_firewall: Whether to fetch the egress firewall script.
+    :returns: List of actions taken.
+    """
+    if devcontainer == "none":
+        return []
+
+    actions: list[str] = []
+    dc_dir = root / ".devcontainer"
+
+    if devcontainer == "trailofbits":
+        # Clone Trail of Bits devcontainer and extract template files
+        try:
+            subprocess.run(
+                ["git", "clone", "--depth", "1", TOB_REPO, str(dc_dir)],
+                check=True,
+                capture_output=True,
+                timeout=60,
+            )
+            # Remove .git from the clone (we don't want a submodule)
+            git_dir = dc_dir / ".git"
+            if git_dir.exists():
+                shutil.rmtree(git_dir)
+            actions.append("  Cloned trailofbits/claude-code-devcontainer into .devcontainer/")
+        except subprocess.CalledProcessError as e:
+            actions.append(f"  WARNING: Failed to clone Trail of Bits devcontainer: {e}")
+            return actions
+        except subprocess.TimeoutExpired:
+            actions.append("  WARNING: Clone timed out after 60s")
+            return actions
+
+    if egress_firewall:
+        dc_dir.mkdir(exist_ok=True)
+        firewall_path = dc_dir / "init-firewall.sh"
+        try:
+            urllib.request.urlretrieve(FIREWALL_GIST_URL, firewall_path)
+            firewall_path.chmod(firewall_path.stat().st_mode | 0o755)
+            actions.append("  Fetched egress firewall (init-firewall.sh) from gist")
+
+            # Add postStartCommand to devcontainer.json if it exists
+            dc_json = dc_dir / "devcontainer.json"
+            if dc_json.exists():
+                raw = dc_json.read_text(encoding="utf-8")
+                try:
+                    config = json.loads(raw)
+                    config["postStartCommand"] = "sudo /usr/local/bin/init-firewall.sh"
+                    dc_json.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+                    actions.append("  Added postStartCommand for firewall to devcontainer.json")
+                except json.JSONDecodeError:
+                    actions.append("  WARNING: Could not parse devcontainer.json to add firewall command")
+        except Exception as e:
+            actions.append(f"  WARNING: Failed to fetch firewall script: {e}")
+
+    return actions
+
+
 def interactive_setup() -> dict[str, str]:
     """Collect configuration interactively."""
     print("\n=== Claude Code Python Template Setup ===\n")
@@ -511,6 +580,18 @@ def interactive_setup() -> dict[str, str]:
     svc_map = {"1": "none", "2": "postgres", "3": "postgres-redis", "4": "custom"}
     config["services"] = svc_map.get(svc_choice, "none")
 
+    print("\nDevcontainer setup:")
+    print("  1. None")
+    print("  2. Trail of Bits (recommended -- secure sandbox for Claude Code)")
+    dc_choice = get_input("Choose [1/2]", "1")
+    config["devcontainer"] = "trailofbits" if dc_choice == "2" else "none"
+
+    if config["devcontainer"] != "none":
+        fw_choice = get_input("Include egress firewall? (blocks code exfiltration) [y/n]", "y")
+        config["egress_firewall"] = fw_choice.lower() in ("y", "yes")
+    else:
+        config["egress_firewall"] = False
+
     return config
 
 
@@ -532,6 +613,17 @@ def main() -> None:
         default="none",
         help="Docker Compose services profile for devcontainer (default: none)",
     )
+    parser.add_argument(
+        "--devcontainer",
+        choices=["none", "trailofbits"],
+        default="none",
+        help="Devcontainer setup (default: none)",
+    )
+    parser.add_argument(
+        "--egress-firewall",
+        action="store_true",
+        help="Add egress firewall to devcontainer (blocks code exfiltration)",
+    )
     parser.add_argument("--git-init", action="store_true", help="Initialize git and make initial commit")
     parser.add_argument("--keep-setup", action="store_true", help="Don't delete this setup script after running")
 
@@ -552,6 +644,8 @@ def main() -> None:
             "type": args.type,
             "packages": args.packages,
             "services": args.services,
+            "devcontainer": args.devcontainer,
+            "egress_firewall": args.egress_firewall,
         }
 
     # Validate required fields
@@ -577,6 +671,9 @@ def main() -> None:
     print(f"  Type: {config.get('type', 'mono')}")
     print(f"  Base branch: {config.get('base_branch', 'master')}")
     print(f"  Devcontainer services: {config.get('services', 'none')}")
+    print(f"  Devcontainer: {config.get('devcontainer', 'none')}")
+    if config.get("egress_firewall"):
+        print("  Egress firewall: yes")
 
     # Step 1: Rename {{namespace}} directories
     print("\nRenaming namespace directories...")
@@ -648,6 +745,15 @@ def main() -> None:
         for a in actions:
             print(a)
 
+    # Step 5b: Set up devcontainer
+    dc_type = config.get("devcontainer", "none")
+    if dc_type != "none":
+        print(f"\nSetting up devcontainer ({dc_type})...")
+        fw = config.get("egress_firewall", False)
+        actions = setup_devcontainer(TEMPLATE_DIR, devcontainer=dc_type, egress_firewall=fw)
+        for a in actions:
+            print(a)
+
     # Step 6: Git init if requested
     if getattr(args, "git_init", False):
         print("\nInitializing git repository...")