codeforge-dev 1.11.0 → 1.13.0

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/team/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: team
+description: >-
+  This skill should be used when the user asks to "spawn a team",
+  "create a team of agents", "use a swarm", "work in parallel with agents",
+  "team up agents", "coordinate multiple agents", "split this across agents",
+  or needs to orchestrate parallel agent work using Claude Code Teams.
+version: 0.1.0
+---
+
+# Agent Team Orchestration
+
+## Mental Model
+
+A team is a group of specialist agents working in parallel under a lead (you). Each teammate runs independently with its own context — they share a task list but not conversation history. The lead decomposes work into parallel streams, spawns specialists, assigns tasks, and coordinates integration.
+
+Teams add value only when work can be parallelized. If every task depends on the previous one, a single agent is faster. The threshold: **3+ independent workstreams** that can run concurrently.
+
+```
+Lead (you)
+├── TeamCreate         → creates the team
+├── TaskCreate (×N)    → defines work units
+├── Task (×N)          → spawns specialist teammates
+├── TaskUpdate (×N)    → assigns tasks to teammates
+├── SendMessage        → coordinates during execution
+└── TeamDelete         → cleans up after completion
+```
+
+---
+
+## Two Modes
+
+Parse `$ARGUMENTS` for an optional `--now` flag to determine behavior:
+
+| Input | Mode | Behavior |
+|-------|------|----------|
+| `/team refactor the auth module` | Guidance | Absorb team knowledge, propose a plan, discuss with user |
+| `/team --now refactor the auth module` | Immediate | Create team, spawn agents, start work without waiting |
+| `/team` | Guidance | Ask the user what the team should accomplish |
+
+Strip `--now` from the purpose string before using it. Everything remaining is `<PURPOSE>`.
+
+### Guidance Mode (default — no `--now`)
+
+Inject the knowledge in this skill into context. **Do not force immediate action.** Analyze the purpose, propose a team composition, and discuss the approach with the user before acting. Use your judgment about when to create the team.
+
+### Immediate Mode (`--now` flag present)
+
+Act now without waiting for further input:
+
+1. **Analyze purpose** — determine workstreams and specialist roles needed
+2. **Create team** — `TeamCreate` with a kebab-case name derived from purpose
+3. **Create tasks** — `TaskCreate` for each work unit with dependencies via `TaskUpdate`
+4. **Spawn teammates** — `Task` with `team_name`, specialist `subagent_type`, descriptive `name`
+5. **Assign tasks** — `TaskUpdate` with `owner` set to each teammate's name
+6. **Coordinate** — monitor via `TaskList`, message via `SendMessage`
+7. **Shutdown** — `shutdown_request` to all teammates, then `TeamDelete`
+
+---
+
+## Team Lifecycle
+
+### 1. Create the Team
+
+```
+TeamCreate:
+  team_name: "auth-refactor"     # kebab-case, descriptive
+  description: "Refactor auth module for OAuth2 support"
+```
+
+One team per lead session. No nested teams.
+
+### 2. Create Tasks
+
+Each task should be independently completable by one agent:
+
+```
+TaskCreate:
+  subject: "Write unit tests for OAuth2 flow"          # imperative
+  description: "Full context the assignee needs..."     # self-contained
+  activeForm: "Writing OAuth2 unit tests"               # present continuous
+```
+
+Set ordering constraints with `TaskUpdate`:
+- `addBlockedBy: ["1"]` — this task waits for task 1
+- `addBlocks: ["3"]` — task 3 waits for this task
+
+### 3. Spawn Teammates
+
+Each teammate is spawned via the `Task` tool with `team_name`:
+
+```
+Task:
+  team_name: "auth-refactor"
+  subagent_type: "agent-system:test-writer"   # specialist agent type
+  name: "test-writer"                            # used for messaging and assignment
+  prompt: "All context needed for the work..."   # teammates have NO prior history
+```
+
+**Critical:** Teammates do not inherit your conversation. The spawn `prompt` must include every piece of context the teammate needs — file paths, requirements, constraints, conventions.
+
+### 4. Assign Tasks
+
+```
+TaskUpdate:
+  taskId: "2"
+  owner: "test-writer"    # matches the teammate's name
+```
+
+### 5. Coordinate
+
+- **Check progress:** `TaskList` shows all tasks with status and owner
+- **Direct message:** `SendMessage` with `type: "message"` and `recipient: "test-writer"`
+- **Broadcast:** `SendMessage` with `type: "broadcast"` — use ONLY for critical team-wide issues
+- **Idle is normal:** Teammates go idle after each turn. This is expected. Send a message to wake them.
+
+### 6. Shutdown
+
+When all tasks are complete:
+
+1. Send `shutdown_request` to each teammate via `SendMessage`
+2. Wait for confirmations
+3. `TeamDelete` to remove team and task directories
+4. Report results to the user
+
+---
+
+## Specialist Agent Types
+
+Choose the agent whose domain matches the work. **Generalist is a last resort.**
+
+| Agent Type | Domain | Capabilities |
+|-----------|--------|-------------|
+| `researcher` | Codebase & web research | Read-only |
+| `test-writer` | Write test suites | Read + Write + Bash |
+| `refactorer` | Safe code transformations | Read + Write + Bash |
+| `doc-writer` | README, API docs, docstrings | Read + Write |
+| `migrator` | Framework upgrades, version bumps | Read + Write + Bash |
+| `security-auditor` | OWASP audit, secrets scan | Read-only |
+| `git-archaeologist` | Git history investigation | Read-only + Bash |
+| `dependency-analyst` | Outdated/vulnerable deps | Read-only + Bash |
+| `spec-writer` | Requirements & acceptance criteria | Read-only |
+| `perf-profiler` | Profiling & benchmarks | Read-only + Bash |
+| `debug-logs` | Log analysis & diagnostics | Read-only + Bash |
+| `architect` | Implementation planning | Read-only |
+| `explorer` | Fast codebase search | Read-only |
+| `generalist` | Multi-step tasks (last resort) | All tools |
+| `bash-exec` | Command execution | Bash only |
+
+Prefix with `agent-system:` when spawning (e.g., `agent-system:test-writer`).
+
+---
+
+## Team Composition Examples
+
+| Purpose | Recommended Team |
+|---------|-----------------|
+| Feature build | `researcher` + `test-writer` + `doc-writer` |
+| Security hardening | `security-auditor` + `dependency-analyst` |
+| Codebase cleanup | `refactorer` + `test-writer` |
+| Migration project | `researcher` + `migrator` |
+| Performance work | `perf-profiler` + `refactorer` |
+| Full-stack feature | `architect` + `generalist` (backend) + `generalist` (frontend) + `test-writer` |
+| Code audit | `security-auditor` + `dependency-analyst` + `perf-profiler` |
+| Documentation sprint | `researcher` + `doc-writer` |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| More than 5 teammates | Coordination overhead outweighs parallelism | Limit to 2–5, matching actual parallel workstreams |
+| Same-file edits by two agents | Merge conflicts are unrecoverable | Assign file ownership — one agent per file |
+| Sequential-only work | Team adds overhead with zero parallel benefit | Use a single agent |
+| Generalist everywhere | Specialists carry domain knowledge and safety hooks | Pick the specialist whose domain matches |
+| Empty spawn prompts | Teammates have no prior context | Include all requirements, file paths, conventions |
+| Skipping shutdown | Orphaned agents consume resources | Always send `shutdown_request` + `TeamDelete` |
+| Broadcasting for routine updates | Each broadcast = N messages (one per teammate) | Use direct `message` to specific teammates |
+
+---
+
+## Tool Reference
+
+| Tool | Purpose | Key Parameters |
+|------|---------|---------------|
+| `TeamCreate` | Create the team | `team_name`, `description` |
+| `Task` | Spawn teammate into team | `team_name`, `subagent_type`, `name`, `prompt` |
+| `TaskCreate` | Add task to shared list | `subject`, `description`, `activeForm` |
+| `TaskUpdate` | Assign, depend, complete | `taskId`, `owner`, `status`, `addBlockedBy` |
+| `TaskList` | View all tasks and status | (none) |
+| `TaskGet` | Read full task details | `taskId` |
+| `SendMessage` | Communicate with teammates | `type`, `recipient`, `content`, `summary` |
+| `TeamDelete` | Clean up after completion | (none) |
+
+---
+
+## Ambiguity Policy
+
+- If `$ARGUMENTS` is empty (no purpose provided), ask: "What should the team accomplish?"
+- If the purpose maps to a single workstream with no parallelism, advise against a team and offer to do the work directly.
+- If unsure which specialists to pick, present 2–3 composition options with trade-offs and let the user choose.
+- If the purpose is vague ("make the app better"), ask for specifics before composing a team.
+- If a teammate reports a blocker, attempt to resolve it yourself or reassign the task before escalating to the user.
+- In immediate mode, default to the most natural team composition. If genuinely ambiguous, fall back to guidance mode and ask.

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+	"name": "spec-workflow",
+	"description": "Specification lifecycle management: creation, refinement, building, reviewing, updating, and auditing",
+	"version": "1.0.0",
+	"author": {
+		"name": "AnExiledDev"
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+	"description": "Spec reminder advisory when code is modified but specs are not updated",
+	"hooks": {
+		"Stop": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/spec-reminder.py",
+						"timeout": 8
+					}
+				]
+			}
+		]
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/spec-init/references/roadmap-template.md

@@ -0,0 +1,33 @@
+# Roadmap
+
+> Features live in the priority-graded backlog until pulled into a version.
+> Versions are scoped and spec'd when ready to build — not pre-assigned.
+> See `BACKLOG.md` for the feature backlog.
+
+## How Versioning Works
+
+1. **Backlog** — All desired features live in `BACKLOG.md`, graded by priority.
+2. **Version scoping** — When ready to start a new version, pull features from the backlog.
+3. **Spec first** — Each feature in a version gets a spec before implementation begins.
+4. **Ship** — Version is done when all its specs are implemented and verified.
+
+Only the **next version** is defined in detail. Everything else is backlog.
+
+## Released
+
+_None yet._
+
+## Current
+
+### v0.1.0 — [Name] 🔧
+
+- [ ] [Feature pulled from backlog]
+- [ ] [Feature pulled from backlog]
+
+## Next
+
+> Scoped from `BACKLOG.md` when current version is complete.
+
+## Out of Scope
+
+- [Items explicitly not planned]

package/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/README.md

@@ -0,0 +1,96 @@
+# ticket-workflow
+
+Claude Code plugin that provides an EARS-based ticket workflow with GitHub issues as the single source of truth. Command-driven — no hooks or scripts, just a custom system prompt and four slash commands.
+
+## What It Does
+
+Provides a structured workflow for creating, planning, reviewing, and shipping work through GitHub issues. All major decisions, plans, and progress are posted as issue comments to maintain an audit trail.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ticket:new` | Transform requirements into a structured GitHub issue with EARS-formatted business requirements |
+| `/ticket:work` | Retrieve a ticket, create a technical implementation plan, and post it to the GitHub issue |
+| `/ticket:review-commit` | Conduct a thorough code review, verify requirements are met, and commit with a detailed message |
+| `/ticket:create-pr` | Create a pull request with aggressive security and architecture review |
+
+### EARS Requirement Format
+
+Every requirement uses one of these patterns:
+
+| Type | Template |
+|------|----------|
+| Ubiquitous | The `<system>` shall `<response>`. |
+| Event-Driven | WHEN `<trigger>`, the `<system>` shall `<response>`. |
+| State-Driven | WHILE `<state>`, the `<system>` shall `<response>`. |
+| Unwanted Behavior | IF `<condition>`, THEN the `<system>` shall `<response>`. |
+| Optional Feature | WHERE `<feature>`, the `<system>` shall `<response>`. |
+
+## How It Works
+
+### Workflow Lifecycle
+
+```
+/ticket:new [requirements]
+  │
+  └─→ Gather requirements → Create EARS-formatted GitHub issue
+       │
+       └─→ /ticket:work #123
+            │
+            └─→ Fetch issue → Create technical plan → Post plan as issue comment
+                 │
+                 │  ... implementation work ...
+                 │
+                 └─→ /ticket:review-commit
+                      │
+                      └─→ Review changes → Verify requirements → Commit
+                           │
+                           └─→ /ticket:create-pr
+                                │
+                                └─→ Create PR → Security/architecture review → Post findings
+```
+
+### Ticket Structure
+
+Each ticket created by `/ticket:new` includes:
+- **Overview**: Plain language description
+- **Requirements**: EARS-formatted business requirements
+- **Technical Questions**: Open questions for implementation
+- **Acceptance Criteria**: Verifiable conditions for completion
+
+### Audit Trail
+
+| Action | Destination |
+|--------|-------------|
+| Plans | Issue comment |
+| Decisions | Issue comment |
+| Requirement changes | Issue comment |
+| Commit summaries | Issue comment |
+| Review findings | PR + issue comment |
+| Created sub-issues | Linked to source ticket |
+
+### Custom System Prompt
+
+The plugin injects a system prompt that defines the assistant persona, coding standards (SOLID, DRY, KISS, YAGNI), testing standards, and the ticket workflow rules. This ensures consistent behavior across all four commands.
+
+## Plugin Structure
+
+```
+ticket-workflow/
+├── .claude-plugin/
+│   ├── plugin.json                  # Plugin metadata
+│   ├── system-prompt.md             # Custom system prompt (persona + workflow rules)
+│   └── commands/
+│       ├── ticket:new.md            # Create EARS-formatted issue
+│       ├── ticket:work.md           # Implementation planning
+│       ├── ticket:review-commit.md  # Review and commit
+│       └── ticket:create-pr.md      # PR creation with review
+└── README.md                        # This file
+```
+
+## Requirements
+
+- Claude Code with plugin command support
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated
+- A GitHub repository as the working context

package/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+	"description": "Auto-link GitHub tickets on user prompt submission",
+	"hooks": {
+		"UserPromptSubmit": [
+			{
+				"matcher": "*",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ticket-linker.py",
+						"timeout": 12
+					}
+				]
+			}
+		]
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/README.md

@@ -0,0 +1,94 @@
+# workspace-scope-guard
+
+Claude Code plugin that enforces working directory scope for all file operations. Blocks writes outside the current project directory and warns on reads outside it. Prevents accidental cross-project modifications in multi-project workspaces.
+
+## What It Does
+
+Intercepts file operations (Read, Write, Edit, NotebookEdit, Glob, Grep) and checks whether the target path is within the current working directory:
+
+| Operation | Out-of-scope behavior |
+|-----------|-----------------------|
+| Write, Edit, NotebookEdit | **Blocked** (exit 2) with error message |
+| Read, Glob, Grep | **Warned** (exit 0) with advisory context |
+
+When the current working directory is `/workspaces` (the workspace root), all operations are unrestricted.
+
+### Allowed Prefixes
+
+These paths are always permitted regardless of working directory:
+
+| Path | Reason |
+|------|--------|
+| `/workspaces/.claude/` | Claude Code configuration |
+| `/workspaces/.tmp/` | Temporary files |
+| `/workspaces/.devcontainer/` | Container configuration |
+| `/tmp/` | System temp directory |
+| `/home/vscode/` | User home directory |
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude calls Read, Write, Edit, NotebookEdit, Glob, or Grep
+  │
+  └─→ PreToolUse hook fires
+       │
+       └─→ guard-workspace-scope.py
+            │
+            ├─→ cwd is /workspaces? → allow (unrestricted)
+            ├─→ No target path? → allow (tool defaults to cwd)
+            ├─→ Resolve path via os.path.realpath() (handles symlinks/worktrees)
+            ├─→ Path is within cwd? → allow
+            ├─→ Path matches allowed prefix? → allow
+            ├─→ Write tool + out of scope → exit 2 (block)
+            └─→ Read tool + out of scope → exit 0 (warn via additionalContext)
+```
+
+### Symlink and Worktree Handling
+
+Target paths are resolved with `os.path.realpath()` before scope checking. This correctly handles:
+- Symbolic links that point outside the working directory
+- Git worktree paths (`.git` file containing `gitdir:`)
+
+### Path Field Mapping
+
+The script extracts the target path from different tool input fields:
+
+| Tool | Input Field |
+|------|-------------|
+| Read | `file_path` |
+| Write | `file_path` |
+| Edit | `file_path` |
+| NotebookEdit | `notebook_path` |
+| Glob | `path` |
+| Grep | `path` |
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| JSON parse failure | Fails open (exit 0) |
+| Other exceptions | Fails open (exit 0) — logs error to stderr |
+
+### Timeout
+
+The hook has a 5-second timeout.
+
+## Plugin Structure
+
+```
+workspace-scope-guard/
+├── .claude-plugin/
+│   └── plugin.json                # Plugin metadata
+├── hooks/
+│   └── hooks.json                 # PreToolUse hook registration
+├── scripts/
+│   └── guard-workspace-scope.py   # Scope enforcement (PreToolUse)
+└── README.md                      # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support

package/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/scripts/guard-workspace-scope.py

@@ -17,11 +17,9 @@ import sys
 
 # Paths that are always allowed regardless of working directory
 ALLOWED_PREFIXES = [
-    "/workspaces/.claude/",
     "/workspaces/.tmp/",
-    "/workspaces/.devcontainer/",
     "/tmp/",
-    "/home/",
+    "/home/vscode/",
 ]
 
 WRITE_TOOLS = {"Write", "Edit", "NotebookEdit"}

package/.devcontainer/scripts/check-setup.sh

@@ -34,7 +34,7 @@ warn_check() {
 echo ""
 echo "Core:"
 check "Claude Code installed" "command -v claude"
-warn_check "Claude native binary" "[ -x /usr/local/bin/claude ]"
+warn_check "Claude native binary" "[ -x ~/.local/bin/claude ] || [ -x /usr/local/bin/claude ]"
 check "cc alias configured" "grep -q 'alias cc=' ~/.bashrc 2>/dev/null || grep -q 'alias cc=' ~/.zshrc 2>/dev/null"
 check "Config directory exists" "[ -d '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}' ]"
 check "Settings file exists" "[ -f '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}/settings.json' ]"

package/.devcontainer/scripts/setup-projects.sh

@@ -29,7 +29,7 @@ is_excluded() {
 
 has_project_markers() {
 	local dir="$1"
-	[ -d "$dir/.git" ] || [ -f "$dir/package.json" ] || [ -f "$dir/pyproject.toml" ] ||
+	[ -d "$dir/.git" ] || [ -f "$dir/.git" ] || [ -f "$dir/package.json" ] || [ -f "$dir/pyproject.toml" ] ||
 		[ -f "$dir/Cargo.toml" ] || [ -f "$dir/go.mod" ] || [ -f "$dir/deno.json" ] ||
 		[ -f "$dir/Makefile" ] || [ -f "$dir/CLAUDE.md" ]
 }
@@ -38,7 +38,11 @@ detect_tags() {
 	local dir="$1"
 	local tags=()
 
-	[ -d "$dir/.git" ] && tags+=("git")
+	if [ -f "$dir/.git" ] && grep -q "gitdir:" "$dir/.git" 2>/dev/null; then
+		tags+=("git" "worktree")
+	elif [ -d "$dir/.git" ]; then
+		tags+=("git")
+	fi
 	[ -f "$dir/package.json" ] && tags+=("node")
 	[ -f "$dir/pyproject.toml" ] && tags+=("python")
 	[ -f "$dir/Cargo.toml" ] && tags+=("rust")
@@ -95,6 +99,19 @@ scan_and_update() {
 				is_excluded "$subname" && continue
 				new_projects=$(register_project "$new_projects" "$subname" "$subdir")
 			done
+
+			# Depth 3: .worktrees/ is hidden (not matched by */) — scan explicitly
+			local wtcontainer="${dir%/}/.worktrees"
+			if [ -d "$wtcontainer" ]; then
+				for wtdir in "${wtcontainer%/}"/*/; do
+					[ -d "$wtdir" ] || continue
+					local wtname
+					wtname=$(basename "$wtdir")
+					if has_project_markers "$wtdir"; then
+						new_projects=$(register_project "$new_projects" "$wtname" "$wtdir")
+					fi
+				done
+			fi
 		fi
 	done
 
@@ -158,20 +175,10 @@ start_watcher() {
 		stop_watcher
 	fi
 
-	# Check if inotifywait is available
+	# Check if inotifywait is available (installed by tmux feature at build time)
 	if ! command -v inotifywait &>/dev/null; then
-		echo "$LOG_PREFIX Installing inotify-tools..."
-		if command -v sudo &>/dev/null; then
-			sudo apt-get update -qq && sudo apt-get install -y -qq inotify-tools >/dev/null 2>&1
-		else
-			apt-get update -qq && apt-get install -y -qq inotify-tools >/dev/null 2>&1
-		fi
-
-		if ! command -v inotifywait &>/dev/null; then
-			echo "$LOG_PREFIX WARNING: Could not install inotify-tools, watcher disabled"
-			return 1
-		fi
-		echo "$LOG_PREFIX inotify-tools installed"
+		echo "$LOG_PREFIX WARNING: inotify-tools not installed, watcher disabled"
+		return 1
 	fi
 
 	# Fork background watcher in its own process group for clean shutdown
@@ -181,7 +188,7 @@ start_watcher() {
 		# -r watches subdirectories (catches events inside container dirs like projects/)
 		# --exclude filters noisy dirs that generate frequent irrelevant events
 		inotifywait -m -r -q -e create,delete,moved_to,moved_from \
-			--exclude '(node_modules|\.git/|\.tmp|__pycache__|\.venv)' \
+			--exclude '(node_modules|\.git|\.tmp|__pycache__|\.venv)' \
 			--format '%w%f %e' "$WORKSPACE_ROOT" 2>/dev/null |
 			while read -r _path event; do
 				# Small delay to let filesystem settle (e.g., move operations)
@@ -191,7 +198,7 @@ start_watcher() {
 
 		# Cleanup on exit
 		rm -f "$PID_FILE"
-	) &
+	) &>/dev/null &
 	local watcher_pid=$!
 	set +m
 	echo "$watcher_pid" >"$PID_FILE"

package/.devcontainer/scripts/setup.sh

@@ -22,8 +22,9 @@ fi
 : "${SETUP_UPDATE_CLAUDE:=true}"
 : "${SETUP_PROJECTS:=true}"
 : "${SETUP_TERMINAL:=true}"
+: "${SETUP_POSTSTART:=true}"
 
-export CLAUDE_CONFIG_DIR CONFIG_SOURCE_DIR SETUP_CONFIG SETUP_ALIASES SETUP_AUTH SETUP_PLUGINS SETUP_UPDATE_CLAUDE SETUP_PROJECTS SETUP_TERMINAL
+export CLAUDE_CONFIG_DIR CONFIG_SOURCE_DIR SETUP_CONFIG SETUP_ALIASES SETUP_AUTH SETUP_PLUGINS SETUP_UPDATE_CLAUDE SETUP_PROJECTS SETUP_TERMINAL SETUP_POSTSTART
 
 SETUP_START=$(date +%s)
 SETUP_RESULTS=()
@@ -42,12 +43,16 @@ run_script() {
     if [ "$enabled" = "true" ]; then
         if [ -f "$script" ]; then
             printf "  %-30s" "$name..."
-            if bash "$script" 2>&1; then
+            local output
+            if output=$(bash "$script" 2>&1); then
                 echo "done"
                 SETUP_RESULTS+=("$name:ok")
             else
-                echo "FAILED (exit $?)"
+                local exit_code=$?
+                echo "FAILED (exit $exit_code)"
                 SETUP_RESULTS+=("$name:failed")
+                # Show output on failure for diagnostics
+                echo "$output" | sed 's/^/    /'
             fi
         else
             echo "  $name... not found, skipping"
@@ -59,6 +64,30 @@ run_script() {
     fi
 }
 
+run_poststart_hooks() {
+    local hook_dir="/usr/local/devcontainer-poststart.d"
+    if [ ! -d "$hook_dir" ]; then
+        return 0
+    fi
+    local count=0
+    for hook in "$hook_dir"/*.sh; do
+        [ -f "$hook" ] || continue
+        [ -x "$hook" ] || continue
+        local name
+        name="$(basename "$hook")"
+        printf "  %-30s" "$name..."
+        if bash "$hook" 2>&1; then
+            echo "done"
+            count=$((count + 1))
+        else
+            echo "FAILED (exit $?)"
+        fi
+    done
+    if [ $count -gt 0 ]; then
+        SETUP_RESULTS+=("poststart-hooks:ok ($count)")
+    fi
+}
+
 run_script "$SCRIPT_DIR/setup-symlink-claude.sh" "true"
 run_script "$SCRIPT_DIR/setup-auth.sh" "$SETUP_AUTH"
 run_script "$SCRIPT_DIR/setup-config.sh" "$SETUP_CONFIG"
@@ -66,7 +95,20 @@ run_script "$SCRIPT_DIR/setup-aliases.sh" "$SETUP_ALIASES"
 run_script "$SCRIPT_DIR/setup-plugins.sh" "$SETUP_PLUGINS"
 run_script "$SCRIPT_DIR/setup-projects.sh" "$SETUP_PROJECTS"
 run_script "$SCRIPT_DIR/setup-terminal.sh" "$SETUP_TERMINAL"
-run_script "$SCRIPT_DIR/setup-update-claude.sh" "$SETUP_UPDATE_CLAUDE"
+
+# Background the update to avoid blocking container start
+if [ "$SETUP_UPDATE_CLAUDE" = "true" ] && [ -f "$SCRIPT_DIR/setup-update-claude.sh" ]; then
+    bash "$SCRIPT_DIR/setup-update-claude.sh" &>/dev/null &
+    disown
+    SETUP_RESULTS+=("setup-update-claude:background")
+else
+    SETUP_RESULTS+=("setup-update-claude:disabled")
+fi
+
+# Run post-start hooks
+if [ "$SETUP_POSTSTART" = "true" ]; then
+    run_poststart_hooks
+fi
 
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -77,10 +119,11 @@ for result in "${SETUP_RESULTS[@]}"; do
     name="${result%%:*}"
     status="${result##*:}"
     case "$status" in
-        ok)       printf "  ✓ %s\n" "$name" ;;
+        ok*)      printf "  ✓ %s\n" "$name" ;;
         failed)   printf "  ✗ %s (FAILED)\n" "$name"; FAILURES=$((FAILURES + 1)) ;;
         disabled) printf "  - %s (disabled)\n" "$name" ;;
         missing)  printf "  ? %s (not found)\n" "$name" ;;
+        background) printf "  ⇢ %s (background)\n" "$name" ;;
     esac
 done
 ELAPSED=$(( $(date +%s) - SETUP_START ))