vibe-forge 0.4.0 → 0.8.2

package/docs/TODO.md

@@ -1,150 +0,0 @@
-# Vibe Forge - Future Improvements
-
-This document tracks long-term vision, feature ideas, and historical decisions.
-
-**For actionable items, see:** `tasks/pending/` directory
-
----
-
-## Completed Items (Historical Reference)
-
-### Security Fixes
-- ~~**L-2: Terminal escape sequences in task parsing**~~ - Fixed in 0.3.7
-- ~~**L-3: Workflow version injection**~~ - Fixed in 0.3.7
-- ~~**SEC-001 through SEC-005**~~ - Various security fixes completed
-
-### Architecture Fixes
-- ~~**Silent error suppression for JSON loading**~~ - Fixed in 0.3.7
-- ~~**Inconsistent exit codes**~~ - Fixed (see `bin/lib/constants.sh`)
-- ~~**Hardcoded agent list in cmd_help()**~~ - Fixed in 0.3.7
-- ~~**Raw echo -e instead of log_* functions**~~ - Fixed
-- ~~**Duplicate color definitions in cli.js**~~ - Documented as intentional
-
----
-
-## Open Tasks (See tasks/pending/)
-
-The following items have been migrated to task files:
-
-| Item | Task ID | Description |
-|------|---------|-------------|
-| M-1 eval() vulnerability | SEC-006 | Agent name validation |
-| L-1 Windows escaping | SEC-007 | printf %q for spawn |
-
-### Completed Architecture Items
-- ~~**ARCH-014: sed -i incompatibility**~~ - Fixed with cross-platform `sed_inplace()` helper in `bin/lib/util.sh`
-- ~~**ARCH-012: tmpclaude-* temp files**~~ - Cleaned up, .gitignore already configured
-
----
-
-## Testing Gaps (Low Priority)
-
-These testing gaps are known but low priority:
-
-- `show_available_agents()` not tested
-- `setup_windows_env()` not tested (hard to test in CI)
-- `colors.sh` log functions not tested (display-only)
-- CLI `init`/`update` commands not tested (side effects)
-
-### Shell Tests - RESOLVED (ARCH-009)
-
-Shell tests have been converted from BATS to Jest:
-
-- **Root cause**: Bash associative arrays (`declare -A`) are not exported to subshells. BATS runs each `@test` in a subshell, causing associative arrays to be unavailable.
-- **Solution**: Converted all BATS tests to Jest tests that invoke bash via `child_process.spawnSync()`. This avoids the subshell inheritance issue.
-- **Result**: 80 tests now passing in CI, covering:
-  - `bin/lib/constants.sh` - Exit codes, directory constants, agent arrays
-  - `bin/lib/config.sh` - JSON parsing, config loading
-  - `bin/lib/agents.sh` - Agent resolution, validation, security tests
-  - `bin/cli.js` - Help, version, command handling
-
----
-
-## Feature Ideas
-
-### LSP/Tooling Selection During Init
-
-Add multi-select during `vibe-forge init` for tech stack:
-- **Languages:** TypeScript, Python, Rust, Go, Java, C#
-- **Frameworks:** React, Vue, Next.js, FastAPI, Django, Express
-- **Infrastructure:** Docker, Kubernetes, Terraform, AWS, GCP
-- **Databases:** PostgreSQL, MongoDB, Redis, SQLite
-
-Would generate customized `context/project-stack.md` based on selections with:
-- Relevant LSP configs
-- Linter recommendations
-- Modern conventions
-- Auto-detection from existing files
-
-### Auto Status on /forge Startup
-
-Removed in 0.3.6 to reduce 45s to ~15s startup time. Could re-add with:
-- "show status on startup" config option
-- Lazy loading of status data
-- Cached status with staleness check
-
----
-
-## V2 Architecture (Major Refactor)
-
-### Problem
-
-Current design clones the entire vibe-forge repo into each project as `_vibe-forge/`. This has issues:
-
-- Commits 50+ tool files into user's repo that are not their code
-- Updates are awkward (re-run init? git pull?)
-- Pollutes git history with tool internals
-- Merge conflicts when updating
-
-### Proposed Solution: Tool vs Data Separation
-
-**Tool** (from npm, NOT committed):
-
-```text
-npx vibe-forge ...           # Runs from npm cache
-~/.vibe-forge/               # Or global install location
-├── bin/                     # Scripts
-├── agents/                  # Agent personalities
-└── config/                  # Default configs
-```
-
-**Project Data** (committed, project-specific):
-
-```text
-your-project/
-├── .forge/                  # Local config (gitignored)
-│   ├── config.json         # Terminal type, paths, preferences
-│   └── state.yaml          # Current session state
-└── .vibe-forge/            # Project data (committed)
-    ├── tasks/              # Task files
-    │   ├── pending/
-    │   ├── in-progress/
-    │   └── completed/
-    ├── context/            # Project context
-    │   └── project-context.md
-    └── overrides/          # Optional: project-specific agent tweaks
-        └── agents.json     # Override default agent config
-```
-
-### Benefits
-
-1. **Clean git history** - Only project data committed, not tool code
-2. **Easy updates** - `npm update -g vibe-forge` or `npx vibe-forge@latest`
-3. **Single source of truth** - Tool version consistent across projects
-4. **Smaller footprint** - ~10 files vs 50+
-5. **No vendoring** - Do not commit dependencies into your repo
-
-### Migration Path
-
-1. **v0.4.x (current)**: Add `.gitignore` entries for tool internals (stopgap)
-2. **v1.0**: Refactor to proper tool/data separation
-   - Tool runs from npm package directly
-   - Only `.vibe-forge/` folder in project
-   - Backward compat: detect old `_vibe-forge/` and migrate
-
-### Implementation Notes
-
-- `npx vibe-forge` already works - just need to make scripts runnable from npm location
-- Agent personalities loaded from npm package by default, with project overrides
-- Tasks/context remain project-local
-- `.forge/config.json` stays gitignored (machine-specific)

package/docs/getting-started.md

@@ -1,243 +0,0 @@
-# Getting Started with Vibe Forge
-
-Vibe Forge is a multi-agent development orchestration tool for Claude Code. It helps you coordinate multiple AI agents working on different aspects of your project - frontend, backend, testing, documentation, and more.
-
-## Prerequisites
-
-Before installing Vibe Forge, ensure you have:
-
-1. **Node.js** (v18 or later)
-2. **Git** - Required for installation and version control
-3. **Claude Code CLI** - Install from [claude.ai/download](https://claude.ai/download)
-
-### Windows Users
-
-Git Bash is required. Install Git via:
-```bash
-winget install Git.Git
-```
-
-## Installation
-
-### Quick Start (Recommended)
-
-Run this command in your project directory:
-
-```bash
-npx vibe-forge init
-```
-
-This will:
-1. Clone Vibe Forge into `_vibe-forge/`
-2. Check prerequisites (Git, Claude Code)
-3. Run the interactive setup wizard
-4. Install the `/forge` slash command
-5. Create a project context file
-
-### Global Installation
-
-If you prefer a global install:
-
-```bash
-npm install -g vibe-forge
-vibe-forge init
-```
-
-### Update to Latest Version
-
-```bash
-npx vibe-forge update
-```
-
-## First-Time Setup
-
-When you run `npx vibe-forge init`, you will be guided through configuration:
-
-### 1. Platform Detection
-
-Vibe Forge automatically detects your operating system (Windows, macOS, or Linux) and configures paths accordingly.
-
-### 2. Terminal Selection
-
-Choose your terminal for spawning worker agents:
-
-- **Windows Terminal** (recommended for Windows) - Workers spawn in new tabs
-- **Manual** - You will receive instructions to start workers manually
-
-### 3. Daemon Configuration
-
-The forge daemon monitors task folders and routes work automatically:
-
-```
-Enable daemon orchestration? (Y/n):
-```
-
-The daemon runs in the background and keeps track of:
-- Pending tasks
-- Worker status
-- Task assignments
-
-### 4. Worker Loop Configuration
-
-Worker Loop keeps agents running continuously:
-
-```
-Enable persistent worker mode? (y/N):
-```
-
-When enabled, workers automatically check for new tasks after completing their current work instead of exiting.
-
-### 5. Project Context
-
-Vibe Forge creates `context/project-context.md` with detected information about your project. Edit this file to add:
-- Project description
-- Architecture overview
-- Coding conventions
-- Team guidelines
-
-## Basic Usage
-
-### Start the Planning Hub
-
-Open Claude Code in your project and run:
-
-```
-/forge
-```
-
-This starts the Planning Hub - a multi-expert planning team that helps you:
-- Break down features into tasks
-- Assign work to specialized agents
-- Coordinate development efforts
-
-### Check Status
-
-View the current state of your forge:
-
-```
-/forge status
-```
-
-This shows:
-- Active agents and their status
-- Pending tasks by category
-- Tasks in progress
-- Completed work
-
-### Spawn a Worker
-
-Start a specialized agent in a new terminal:
-
-```
-/forge spawn anvil
-```
-
-Available agents:
-- `anvil` - Frontend Developer
-- `furnace` - Backend Developer
-- `crucible` - Tester / QA
-- `sentinel` - Code Reviewer
-- `scribe` - Documentation
-- `herald` - Release Manager
-- `ember` - DevOps
-- `aegis` - Security
-
-### Create a Task
-
-Add a new task to the queue:
-
-```
-/forge task Add user authentication to the login page
-```
-
-The Planning Hub will help you:
-- Clarify requirements
-- Assign the appropriate agent
-- Set priority
-
-## Project Structure
-
-After setup, your project will have:
-
-```
-your-project/
-├── _vibe-forge/           # Vibe Forge tool (mostly gitignored)
-│   ├── bin/               # CLI scripts
-│   ├── config/            # Configuration files
-│   ├── agents/            # Agent personalities
-│   └── .forge/            # Local config (gitignored)
-├── context/               # Project context (committed)
-│   └── project-context.md # Your project description
-├── tasks/                 # Task files (committed)
-│   ├── pending/           # Awaiting assignment
-│   ├── in-progress/       # Currently being worked
-│   ├── review/            # Ready for review
-│   └── completed/         # Done
-└── .claude/
-    └── commands/
-        └── forge.md       # The /forge slash command
-```
-
-## Example Workflow
-
-Here is a typical development session:
-
-1. **Start your day** - Open Claude Code and run `/forge`
-
-2. **Plan features** - Discuss what you want to build with the Planning Hub
-
-3. **Spawn workers** - `/forge spawn anvil` for frontend, `/forge spawn furnace` for backend
-
-4. **Create tasks** - `/forge task Implement shopping cart component`
-
-5. **Monitor progress** - `/forge status` to see what is happening
-
-6. **Review work** - Sentinel reviews completed code automatically
-
-7. **Ship** - Herald manages releases when ready
-
-## Next Steps
-
-- Read [Commands Reference](./commands.md) for all available commands
-- Read [Agent Guide](./agents.md) to learn about each specialist
-- Read [Workflows](./workflows.md) for common patterns
-
-## Troubleshooting
-
-### Claude Code not found
-
-Ensure Claude Code CLI is installed and in your PATH:
-```bash
-claude --version
-```
-
-If not found, install from [claude.ai/download](https://claude.ai/download).
-
-### Git Bash not found (Windows)
-
-Install Git with Git Bash:
-```bash
-winget install Git.Git
-```
-
-Restart your terminal after installation.
-
-### Slash command not working
-
-The `/forge` command should be installed in `.claude/commands/forge.md`. If missing, copy it manually:
-
-```bash
-cp _vibe-forge/.claude/commands/forge.md .claude/commands/
-```
-
-### Daemon not starting
-
-Check if the daemon is already running:
-```bash
-./bin/forge-daemon.sh status
-```
-
-Start it manually:
-```bash
-./bin/forge-daemon.sh start
-```

package/docs/npm-publishing.md

@@ -1,95 +0,0 @@
-# npm Publishing with OIDC Trusted Publishing
-
-This document explains how Vibe Forge publishes to npm using GitHub Actions OIDC trusted publishing - no npm tokens required.
-
-## Overview
-
-npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) uses OpenID Connect (OIDC) to authenticate GitHub Actions workflows directly with npm. This eliminates the need to store npm tokens as secrets.
-
-## Requirements
-
-1. **npm CLI v11.5.1+** - OIDC support was added in npm 11.5.1
-2. **Public GitHub repository** - Provenance attestation only works with public repos
-3. **Trusted Publisher configured on npmjs.com** - Links your package to your GitHub repo
-
-## Setup
-
-### 1. Configure Trusted Publisher on npm
-
-1. Go to https://www.npmjs.com/package/vibe-forge/access
-2. Under "Trusted Publishers", add a new publisher:
-   - **Publisher**: GitHub Actions
-   - **Organization/user**: SpasticPalate
-   - **Repository**: vibe-forge
-   - **Workflow filename**: publish.yml
-   - **Environment name**: (leave empty)
-
-### 2. GitHub Actions Workflow
-
-The workflow requires specific permissions and npm version:
-
-```yaml
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write  # Required for OIDC token generation
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-
-      # npm 11.5.1+ required for OIDC
-      - run: npm install -g npm@latest
-
-      - run: npm publish --provenance --access public
-```
-
-Key points:
-- `id-token: write` permission enables OIDC token generation
-- `--provenance` flag enables signed provenance attestation
-- No `NODE_AUTH_TOKEN` or `NPM_TOKEN` needed
-
-## Troubleshooting
-
-### "Access token expired or revoked" with E404
-
-**Cause**: npm CLI version is too old (< 11.5.1)
-
-**Fix**: Add `npm install -g npm@latest` before publishing
-
-### "Unsupported GitHub Actions source repository visibility: private"
-
-**Cause**: Provenance attestation only works with public repositories
-
-**Fix**: Either make the repo public, or remove `--provenance` and use a granular npm token instead
-
-### "ENEEDAUTH - need auth"
-
-**Cause**: OIDC token not being generated/used
-
-**Fix**: Ensure `id-token: write` permission is set on the job
-
-### 404 on publish despite correct setup
-
-**Cause**: Trusted Publisher configuration doesn't match workflow
-
-**Fix**: Verify on npmjs.com that:
-- Organization/user matches exactly (case-sensitive)
-- Repository name matches exactly
-- Workflow filename matches exactly (e.g., `publish.yml`)
-
-## Benefits
-
-- **No secrets to manage** - No npm tokens to rotate or accidentally expose
-- **Provenance attestation** - Packages are cryptographically signed with build info
-- **Audit trail** - Provenance is published to Sigstore transparency log
-
-## References
-
-- [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers/)
-- [npm Provenance](https://docs.npmjs.com/generating-provenance-statements/)
-- [GitHub: npm trusted publishing GA](https://github.blog/changelog/2025-07-31-npm-trusted-publishing-with-oidc-is-generally-available/)

package/docs/workflows/README.md

@@ -1,32 +0,0 @@
-# VCS Workflow Guides
-
-Platform-specific workflow guidance for Vibe Forge agents. The appropriate guide is selected based on the project's VCS configuration (see `/configure-vcs`).
-
-## Available Guides
-
-| Platform | File | Use Case |
-|----------|------|----------|
-| [GitHub](./github.md) | `github.md` | GitHub with Actions CI |
-| [GitLab](./gitlab.md) | `gitlab.md` | GitLab with GitLab CI |
-| [Gitea](./gitea.md) | `gitea.md` | Gitea/Codeberg with Gitea Actions |
-| [Azure DevOps](./azure-devops.md) | `azure-devops.md` | Azure DevOps with Pipelines |
-| [Bitbucket](./bitbucket.md) | `bitbucket.md` | Bitbucket with Pipelines |
-| [Git Only](./git-only.md) | `git-only.md` | Git without hosted platform |
-
-## Configuration
-
-VCS type is set during `forge init` or via `/configure-vcs`. Configuration stored in `.forge/config.json`:
-
-```json
-{
-  "vcs": {
-    "type": "github",
-    "name": "GitHub",
-    "autoDetected": true
-  }
-}
-```
-
-## Agent Integration
-
-Agents read the VCS configuration and reference the appropriate workflow guide. The git workflow section in agent personalities is dynamically adjusted based on the configured platform.

package/docs/workflows/azure-devops.md

@@ -1,108 +0,0 @@
-# Azure DevOps Workflow Guide
-
-Git workflow guidance for projects hosted on Azure DevOps.
-
-## Branch Naming
-
-```
-task/TASK-XXX-description     # Task branches
-feature/feature-name          # Feature branches
-bugfix/bug-description        # Bug fix branches
-hotfix/urgent-fix             # Urgent production fixes
-```
-
-## Daily Workflow
-
-### Starting a Task
-
-```bash
-# Ensure you're on latest main
-git checkout main && git pull origin main
-
-# Create feature branch
-git checkout -b task/TASK-XXX-description
-```
-
-### During Development
-
-```bash
-# Stage and commit changes
-git add .
-git commit -m "Add feature X"
-
-# Push to remote (first time)
-git push -u origin task/TASK-XXX-description
-
-# Subsequent pushes
-git push
-```
-
-### Creating a Pull Request
-
-```bash
-# Using Azure CLI
-az repos pr create \
-  --title "TASK-XXX: Add feature X" \
-  --description "Description of changes" \
-  --source-branch task/TASK-XXX-description \
-  --target-branch main
-
-# Set to draft
-az repos pr create --draft \
-  --title "TASK-XXX: WIP - Add feature X" \
-  --source-branch task/TASK-XXX-description
-```
-
-### After PR Approval
-
-```bash
-# Complete PR via Azure CLI
-az repos pr update --id <pr-id> --status completed
-
-# Clean up local branch
-git checkout main
-git pull origin main
-git branch -d task/TASK-XXX-description
-```
-
-## CI/CD
-
-Azure Pipelines configuration goes in `azure-pipelines.yml`:
-
-```yaml
-# azure-pipelines.yml
-trigger:
-  - main
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-steps:
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '20.x'
-
-  - script: npm ci
-    displayName: 'Install dependencies'
-
-  - script: npm test
-    displayName: 'Run tests'
-```
-
-## Useful Commands
-
-```bash
-# Azure CLI for repos
-az repos pr list                    # List open PRs
-az repos pr show --id 123           # Show PR details
-az repos pr checkout --id 123       # Checkout PR locally
-az pipelines run list               # List pipeline runs
-```
-
-## Branch Policies
-
-Configure in Repos > Branches > Branch policies:
-- Require minimum number of reviewers
-- Check for linked work items
-- Build validation
-- Require merge strategy (squash)