vibe-forge 0.4.0 → 0.8.1

package/docs/security.md

@@ -1,144 +1,195 @@
-# Vibe Forge Security Documentation
-
-This document explains security considerations and intentional design decisions in Vibe Forge.
-
-## The `--dangerously-skip-permissions` Flag
-
-### What It Does
-
-When starting agents, Vibe Forge uses Claude Code's `--dangerously-skip-permissions` flag:
-
-```bash
-claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
-```
-
-This flag disables Claude Code's permission prompts for file operations, command execution, and other actions that would normally require user confirmation.
-
-### Why We Use It
-
-Vibe Forge is designed for **terminal-native vibe coding** - a workflow where you launch multiple AI agents that work autonomously on your codebase. The typical workflow involves:
-
-1. Starting a Planning Hub that coordinates work
-2. Spawning worker agents (frontend, backend, testing, etc.) in separate terminals
-3. Agents working autonomously on assigned tasks
-4. Human review at defined checkpoints
-
-With permission prompts enabled, each agent would constantly interrupt for confirmation, breaking the autonomous workflow that makes Vibe Forge effective.
-
-### Security Mitigations
-
-We implement several security measures to offset the risks:
-
-#### 1. Agent Whitelist Validation
-
-All agent names go through strict whitelist validation before execution:
-
-```bash
-# bin/lib/constants.sh
-VALID_AGENTS=("anvil" "furnace" "crucible" ...)
-
-# bin/lib/agents.sh
-resolve_agent() {
-    local canonical="${AGENT_ALIASES[$normalized]:-}"
-    if [[ -n "$canonical" ]]; then
-        echo "$canonical"
-        return 0
-    fi
-    return 1  # Reject unknown agents
-}
-```
-
-This prevents command injection through agent names.
-
-#### 2. Path Traversal Protection
-
-Personality file paths are validated to ensure they remain within the expected directory:
-
-```bash
-get_agent_personality_path() {
-    local real_path=$(cd "$(dirname "$personality_path")" && pwd)/$(basename "$personality_path")
-    local agents_dir=$(cd "$forge_root/agents" && pwd)
-
-    if [[ "$real_path" != "$agents_dir"/* ]]; then
-        echo "Security error: Path traversal detected" >&2
-        return 1
-    fi
-}
-```
-
-#### 3. Safe JSON Parsing
-
-We use Node.js for JSON parsing instead of `grep`/`cut` which could be vulnerable to injection:
-
-```bash
-json_get_string() {
-    node -e "
-        const fs = require('fs');
-        const data = JSON.parse(fs.readFileSync('$file', 'utf8'));
-        if (data['$key'] !== undefined) console.log(String(data['$key']));
-    "
-}
-```
-
-#### 4. Daemon Security
-
-The background daemon includes multiple protections:
-
-- **Symlink protection**: Skips symlinks to prevent symlink attacks
-- **Path validation**: Verifies destinations are within FORGE_ROOT
-- **Atomic operations**: Uses temp files + move for safe writes
-- **Lock files**: Prevents multiple daemon instances
-- **Log rotation**: Bounded log growth prevents disk exhaustion
-
-### Risks to Be Aware Of
-
-Even with mitigations, understand these risks:
-
-1. **AI agents can modify any file** in your project without confirmation
-2. **AI agents can execute any command** without confirmation
-3. **Malicious prompts** could potentially be injected if context files are compromised
-4. **Network access** is unrestricted - agents could make API calls
-
-### Recommendations
-
-1. **Use in development environments only** - Don't run on production systems
-2. **Use with version control** - Git makes it easy to review and revert changes
-3. **Review at checkpoints** - Check agent work during task transitions
-4. **Understand the personality files** - They define agent behavior
-5. **Keep project context secure** - Don't include secrets in context files
-6. **Run in isolated environments** - Consider containers for sensitive projects
-
-### Alternative: Manual Approval Mode
-
-If you prefer permission prompts, you can modify the agent startup in `bin/forge.sh`:
-
-```bash
-# Change this:
-claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
-
-# To this (removes the flag):
-claude --system-prompt "$system_prompt" "startup"
-```
-
-Note: This will significantly impact the autonomous workflow.
-
-## Reporting Security Issues
-
-If you discover a security vulnerability in Vibe Forge:
-
-1. **Do not open a public issue**
-2. Email security concerns to the maintainers
-3. Include steps to reproduce
-4. Allow time for a fix before public disclosure
-
-## Security Checklist for Contributors
-
-When contributing to Vibe Forge:
-
-- [ ] Never pass user input directly to shell commands
-- [ ] Always validate agent names against the whitelist
-- [ ] Use safe JSON parsing (Node.js, not grep/cut)
-- [ ] Validate file paths don't traverse outside expected directories
-- [ ] Use atomic file operations where race conditions are possible
-- [ ] Add tests for security-sensitive functions
-- [ ] Document any new security considerations
+# Vibe Forge Security Documentation
+
+This document explains security considerations and intentional design decisions in Vibe Forge.
+
+## Agent Permission Model
+
+### How It Works
+
+Vibe Forge agents run with **allowlist-based permissions** defined in `.claude/settings.json`. This replaces the previous `--dangerously-skip-permissions` approach with a defense-in-depth model:
+
+1. **Allowlist** (`.claude/settings.json`) - Pre-approves safe operations (file reads, writes, git, npm, etc.)
+2. **Heimdall** (pre-tool hook) - Intercepts and gates forge-specific policy (branch protection, etc.)
+3. **Claude Code native prompts** - Anything not in the allowlist still requires user approval
+
+```
+  Agent wants to run a command
+           |
+           v
+  ┌─────────────────┐
+  │ Allowlist check  │──── Not allowed ──> User prompted
+  └────────┬────────┘
+           │ Allowed
+           v
+  ┌─────────────────┐
+  │ Heimdall hook   │──── Policy violation ──> Blocked
+  └────────┬────────┘
+           │ Pass
+           v
+       Executed
+```
+
+### What Agents Can Do Without Prompting
+
+The allowlist covers normal development operations:
+- Read, write, and edit files
+- Search with glob/grep
+- Run git commands (status, diff, add, commit, push, branch, etc.)
+- Run GitHub CLI (PRs, runs, workflows)
+- Run npm (test, install, audit, build)
+- Run node/npx scripts
+- File operations (ls, cp, mv, mkdir, find)
+- SQLite operations
+
+### What Still Requires Approval
+
+Anything not in the allowlist prompts the user:
+- Installing system packages (apt, brew, etc.)
+- Running unfamiliar binaries
+- Network operations (curl, wget) unless via node
+- Destructive operations not covered by git (rm -rf, etc.)
+
+### Heimdall Policy Layer
+
+Heimdall is a pre-tool hook that enforces forge-specific rules on top of the allowlist:
+- Blocks direct pushes to main/master
+- Enforces branch naming conventions
+- Gates security-sensitive operations
+
+Heimdall runs on every Bash tool call regardless of allowlist status.
+
+### Why Not --dangerously-skip-permissions?
+
+The `--dsp` flag disables ALL permission checks. The allowlist approach is better because:
+- Only known-safe operations are pre-approved
+- Unknown commands still prompt for approval
+- Heimdall policies still enforce forge rules
+- The security posture is auditable (read `.claude/settings.json`)
+
+Users who prefer the fully autonomous workflow can still use `--dsp` in their own terminals.
+
+### Trust Boundary: Shared Allowlist
+
+All forge agents share a single allowlist defined in `.claude/settings.json`. There are no per-agent permission boundaries. This means:
+
+- **Anvil** (frontend) has the same file-write permissions as **Aegis** (security)
+- A compromised or confused agent personality cannot be contained by permissions alone
+- Heimdall policies provide some per-agent gating (e.g. branch protection) but do not restrict filesystem scope
+
+This is an accepted architectural trade-off. Per-agent permission boundaries would require separate `settings.json` files per agent and a launcher that selects the correct one, which adds complexity without proportional security benefit in a single-developer, local-only workflow.
+
+**Mitigations:**
+- Version control (git) makes all file changes reviewable and revertible
+- Heimdall enforces structural policies (no direct push to main, naming conventions)
+- Sentinel code review catches inappropriate changes before merge
+- The dashboard provides visibility into what each agent is doing
+
+**Future consideration:** If Vibe Forge supports multi-developer or remote execution (T3-4), per-agent permission boundaries should be revisited.
+
+## Dashboard Security
+
+### Session Token Authentication
+
+The dashboard server generates a cryptographic session token at startup:
+- Written to `.forge/dashboard.token` with mode 0600
+- All API endpoints require `X-Forge-Token` header
+- WebSocket connections require `?token=` query parameter
+- Token is cleaned up on server shutdown
+- `/api/health` is exempt (monitoring probes)
+
+### Same-Origin Protection
+
+The dashboard serves no CORS headers. Browsers enforce same-origin policy, meaning:
+- Only the dashboard UI (served from the same origin) can call the API
+- Cross-origin requests from malicious websites are blocked
+- The `/api/token` bootstrap endpoint is protected by same-origin policy
+
+### Why This Matters
+
+Without these protections, any website you visit could dispatch tasks to your forge agents via cross-origin API calls. Combined with agent permissions, this would allow arbitrary code execution. The session token + same-origin combination eliminates this attack vector.
+
+## Additional Security Measures
+
+### Agent Whitelist Validation
+
+All agent names go through strict whitelist validation before execution:
+
+```bash
+resolve_agent() {
+    local canonical="${AGENT_ALIASES[$normalized]:-}"
+    if [[ -n "$canonical" ]]; then
+        echo "$canonical"
+        return 0
+    fi
+    return 1  # Reject unknown agents
+}
+```
+
+### Path Traversal Protection
+
+Personality file paths are validated to remain within expected directories:
+
+```bash
+get_agent_personality_path() {
+    local real_path=$(cd "$(dirname "$personality_path")" && pwd)/$(basename "$personality_path")
+    local agents_dir=$(cd "$forge_root/agents" && pwd)
+    if [[ "$real_path" != "$agents_dir"/* ]]; then
+        echo "Security error: Path traversal detected" >&2
+        return 1
+    fi
+}
+```
+
+### Daemon Security
+
+The background daemon includes:
+- **Symlink protection**: Skips symlinks to prevent symlink attacks
+- **Path validation**: Verifies destinations within FORGE_ROOT
+- **Atomic operations**: Temp files + move for safe writes
+- **Lock files**: Prevents multiple daemon instances
+- **SQL escaping**: All database inputs go through `db_escape()`
+- **Input sanitization**: Frontmatter extraction strips shell metacharacters
+
+### Alias Collision Detection
+
+Agent alias collisions are checked at three levels:
+- Pre-commit hook (local development)
+- CI lint job (GitHub Actions)
+- `forge init` (project setup)
+
+## Risks to Be Aware Of
+
+1. **Allowlisted operations execute without confirmation** - agents can modify files, run tests, and push code
+2. **Prompt injection** - crafted task files or context could influence agent behavior
+3. **Heimdall is not exhaustive** - it enforces known policies, not all possible risks
+4. **Local network exposure** - the dashboard binds to localhost only; changing this has security implications
+
+## Recommendations
+
+1. **Use in development environments only**
+2. **Use with version control** - git makes it easy to review and revert
+3. **Review at checkpoints** - check agent work during task transitions
+4. **Keep project context secure** - don't include secrets in context files
+5. **Audit the allowlist** - review `.claude/settings.json` for your comfort level
+6. **Run in isolated environments** - consider containers for sensitive projects
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in Vibe Forge:
+
+1. **Do not open a public issue**
+2. Email security concerns to the maintainers
+3. Include steps to reproduce
+4. Allow time for a fix before public disclosure
+
+## Security Checklist for Contributors
+
+When contributing to Vibe Forge:
+
+- [ ] Never pass user input directly to shell commands
+- [ ] Always validate agent names against the whitelist
+- [ ] Use safe JSON parsing (Node.js, not grep/cut)
+- [ ] Validate file paths don't traverse outside expected directories
+- [ ] Use atomic file operations where race conditions are possible
+- [ ] Add tests for security-sensitive functions
+- [ ] Document any new security considerations

package/package.json

@@ -1,50 +1,77 @@
-{
-  "name": "vibe-forge",
-  "version": "0.4.0",
-  "description": "Multi-agent development orchestration system for terminal-native vibe coding",
-  "keywords": [
-    "vibe-coding",
-    "claude",
-    "ai",
-    "agents",
-    "multi-agent",
-    "development",
-    "orchestration",
-    "terminal",
-    "cli"
-  ],
-  "author": "SpasticPalate",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/SpasticPalate/vibe-forge.git"
-  },
-  "homepage": "https://github.com/SpasticPalate/vibe-forge#readme",
-  "bugs": {
-    "url": "https://github.com/SpasticPalate/vibe-forge/issues"
-  },
-  "bin": {
-    "vibe-forge": "bin/cli.js"
-  },
-  "files": [
-    "bin/",
-    "agents/",
-    "config/",
-    "context/",
-    "tasks/",
-    ".claude/",
-    "docs/"
-  ],
-  "scripts": {
-    "test": "node --no-warnings node_modules/jest/bin/jest.js tests/unit/",
-    "test:unit": "node --no-warnings node_modules/jest/bin/jest.js tests/unit/",
-    "test:integration": "node --no-warnings node_modules/jest/bin/jest.js tests/integration/",
-    "test:all": "node --no-warnings node_modules/jest/bin/jest.js tests/"
-  },
-  "devDependencies": {
-    "jest": "^30.0.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  }
-}
+{
+  "name": "vibe-forge",
+  "version": "0.8.1",
+  "description": "Multi-agent development orchestration system for terminal-native vibe coding",
+  "keywords": [
+    "vibe-coding",
+    "claude",
+    "ai",
+    "agents",
+    "multi-agent",
+    "development",
+    "orchestration",
+    "terminal",
+    "cli"
+  ],
+  "author": "sugar-crash-studios",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sugar-crash-studios/vibe-forge.git"
+  },
+  "homepage": "https://github.com/sugar-crash-studios/vibe-forge#readme",
+  "bugs": {
+    "url": "https://github.com/sugar-crash-studios/vibe-forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vibe-forge": "bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "bin/lib/",
+    "bin/forge.cmd",
+    "bin/forge.sh",
+    "bin/forge-daemon.sh",
+    "bin/forge-setup.sh",
+    "bin/forge-spawn.sh",
+    "bin/dashboard/server.js",
+    "bin/dashboard/api/",
+    "bin/dashboard/public/",
+    "agents/",
+    "config/",
+    "context/project-context-template.md",
+    "context/architecture.md",
+    "context/modern-conventions.md",
+    "context/agent-overrides/README.md",
+    ".claude/commands/",
+    ".claude/hooks/",
+    ".claude/scripts/",
+    ".claude/settings.json",
+    "docs/security.md",
+    "docs/architecture.md",
+    "docs/agents.md",
+    "docs/commands.md"
+  ],
+  "scripts": {
+    "prepare": "husky",
+    "test": "node --no-warnings node_modules/jest/bin/jest.js tests/unit/",
+    "test:unit": "node --no-warnings node_modules/jest/bin/jest.js tests/unit/",
+    "test:integration": "node --no-warnings node_modules/jest/bin/jest.js tests/integration/",
+    "test:all": "node --no-warnings node_modules/jest/bin/jest.js tests/"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "jest": "^30.0.0",
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "msedge-tts": "^2.0.4"
+  }
+}

package/.claude/settings.local.json

@@ -1,33 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(ls:*)",
-      "Bash(git pull:*)",
-      "Bash(npm view:*)",
-      "Bash(gh run list:*)",
-      "Bash(gh run view:*)",
-      "Bash(gh secret list:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(gh workflow run:*)",
-      "Bash(gh repo view:*)",
-      "Bash(git push:*)",
-      "Bash(sqlite3:*)",
-      "Bash(npm test)",
-      "Bash(git rm:*)"
-    ]
-  },
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/worker-loop.js"
-          }
-        ]
-      }
-    ]
-  }
-}

package/agents/forge-master/capabilities.md

@@ -1,144 +0,0 @@
-# Forge Master Capabilities
-
-## Tools & Commands
-
-### Task Management
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `/forge task:create` | Create a new task file | `/forge task:create --type=backend --title="Add auth endpoint"` |
-| `/forge task:assign` | Assign task to agent | `/forge task:assign task-021 furnace` |
-| `/forge task:status` | Get status of task(s) | `/forge task:status` or `/forge task:status task-021` |
-| `/forge task:block` | Mark task as blocked | `/forge task:block task-022 --reason="Awaiting API spec"` |
-| `/forge task:unblock` | Unblock a task | `/forge task:unblock task-022` |
-| `/forge task:priority` | Change task priority | `/forge task:priority task-021 critical` |
-
-### Agent Coordination
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `/forge agents` | List all agents and status | `/forge agents` |
-| `/forge agent:wake` | Spin up an agent terminal | `/forge agent:wake anvil` |
-| `/forge agent:status` | Check specific agent status | `/forge agent:status furnace` |
-| `/forge agent:notify` | Send message to agent | `/forge agent:notify anvil "task-015 priority elevated"` |
-
-### Progress & Reporting
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `/forge status` | Full forge status dashboard | `/forge status` |
-| `/forge progress` | Progress on current epic | `/forge progress epic-003` |
-| `/forge blockers` | List all current blockers | `/forge blockers` |
-| `/forge today` | Summary of today's activity | `/forge today` |
-
-### Epic & Planning
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `/forge epic:decompose` | Break epic into tasks | `/forge epic:decompose epic-003` |
-| `/forge epic:status` | Epic completion status | `/forge epic:status epic-003` |
-
----
-
-## File Operations
-
-### Task Lifecycle Management
-
-```
-READ:  /tasks/*/task-*.md           # Monitor all task states
-WRITE: /tasks/pending/*.md          # Create new tasks
-MOVE:  /tasks/{from}/* → /tasks/{to}/*  # Transition task states
-```
-
-### Directories Monitored
-
-| Directory | Watches For | Action |
-|-----------|-------------|--------|
-| `/tasks/completed/` | New completions | Route to Sentinel |
-| `/tasks/needs-changes/` | Review rejections | Re-assign to original worker |
-| `/tasks/approved/` | Review passes | Move to merged, notify Planning Hub |
-
----
-
-## Decision Matrix
-
-### Task Assignment Logic
-
-```
-IF task.type == "frontend" OR task.type == "component" OR task.type == "ui"
-  → Assign to Anvil
-
-IF task.type == "backend" OR task.type == "api" OR task.type == "database"
-  → Assign to Furnace
-
-IF task.type == "test" OR task.type == "qa" OR task.type == "bugfix"
-  → Assign to Crucible
-
-IF task.type == "docs" OR task.type == "readme" OR task.type == "api-docs"
-  → Assign to Scribe
-
-IF task.type == "release" OR task.type == "deploy" OR task.type == "changelog"
-  → Assign to Herald
-
-IF task.type == "review"
-  → Assign to Sentinel (automatic for all completed work)
-
-IF task.type == "devops" OR task.type == "infra" OR task.type == "ci-cd"
-  → Assign to Ember
-
-IF task.type == "security" OR task.type == "audit"
-  → Assign to Aegis
-```
-
-### Priority Levels
-
-| Priority | Meaning | SLA |
-|----------|---------|-----|
-| `critical` | Blocking other work | Immediate |
-| `high` | Sprint commitment | Today |
-| `medium` | Sprint goal | This sprint |
-| `low` | Nice to have | When available |
-
----
-
-## Integration Points
-
-### Inputs (Forge Master Receives)
-- Epic files from Planning Hub (`/specs/epics/*.md`)
-- Completion signals from Workers (`/tasks/completed/*.md`)
-- Review results from Sentinel (`/tasks/approved/*.md` or `/tasks/needs-changes/*.md`)
-- Blocker escalations from Workers
-- Priority changes from Quartermaster
-
-### Outputs (Forge Master Produces)
-- Task files for Workers (`/tasks/pending/*.md`)
-- Status reports for Planning Hub
-- Notifications to specific agents
-- Progress updates to Dashboard
-
----
-
-## State Management
-
-### Forge Master Maintains
-
-```yaml
-# /context/forge-state.yaml
-current_epic: epic-003
-tasks_pending: 5
-tasks_in_progress: 3
-tasks_blocked: 1
-tasks_in_review: 2
-tasks_completed_today: 7
-agents_active:
-  - anvil
-  - furnace
-  - crucible
-last_updated: 2026-01-11T14:30:00Z
-```
-
-### Does NOT Maintain
-- Code state (that's git)
-- Test results (that's Crucible)
-- Release state (that's Herald)
-- Architecture decisions (that's Sage)