vibe-forge 0.4.0 → 0.8.1

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)

package/docs/workflows/bitbucket.md

@@ -1,104 +0,0 @@
-# Bitbucket Workflow Guide
-
-Git workflow guidance for projects hosted on Bitbucket.
-
-## 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
-
-Bitbucket doesn't have an official CLI. Create PRs via:
-
-1. **Web UI**: After pushing, visit Bitbucket and click "Create pull request"
-2. **API** (if needed):
-   ```bash
-   curl -X POST \
-     -H "Authorization: Bearer $BITBUCKET_TOKEN" \
-     -H "Content-Type: application/json" \
-     -d '{"title":"TASK-XXX: Add feature X","source":{"branch":{"name":"task/TASK-XXX-description"}},"destination":{"branch":{"name":"main"}}}' \
-     https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pullrequests
-   ```
-
-### After PR Approval
-
-```bash
-# Merge via Bitbucket UI (squash merge recommended)
-
-# Clean up local branch
-git checkout main
-git pull origin main
-git branch -d task/TASK-XXX-description
-```
-
-## CI/CD
-
-Bitbucket Pipelines configuration goes in `bitbucket-pipelines.yml`:
-
-```yaml
-# bitbucket-pipelines.yml
-image: node:20
-
-pipelines:
-  default:
-    - step:
-        name: Test
-        caches:
-          - node
-        script:
-          - npm ci
-          - npm test
-
-  branches:
-    main:
-      - step:
-          name: Build and Deploy
-          script:
-            - npm ci
-            - npm run build
-```
-
-## Useful Tips
-
-- **Jira Integration**: Link commits with Jira issue keys (e.g., `PROJ-123`)
-- **PR Templates**: Create `PULL_REQUEST_TEMPLATE.md` in repo root
-- **Reviewers**: Set default reviewers in repository settings
-
-## Branch Permissions
-
-Configure in Repository settings > Branch permissions:
-- Require pull request before merging
-- Require approvals
-- Require passing builds
-- Prevent direct pushes to main

package/docs/workflows/git-only.md

@@ -1,130 +0,0 @@
-# Git-Only Workflow Guide
-
-Git workflow guidance for projects using Git without a hosted platform (self-hosted, local-only, or minimal setup).
-
-## 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  # if remote exists
-
-# 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 (if configured)
-git push -u origin task/TASK-XXX-description
-```
-
-### Completing a Task
-
-Without a PR platform, use one of these approaches:
-
-#### Option 1: Direct Merge (Solo Developer)
-
-```bash
-# Switch to main
-git checkout main
-git pull origin main  # if remote
-
-# Merge with squash
-git merge --squash task/TASK-XXX-description
-git commit -m "TASK-XXX: Add feature X"
-
-# Push
-git push origin main
-
-# Clean up
-git branch -d task/TASK-XXX-description
-```
-
-#### Option 2: Code Review via Diff
-
-```bash
-# Generate diff for review
-git diff main...task/TASK-XXX-description > review.patch
-
-# After review approval, merge as above
-```
-
-#### Option 3: Email Workflow
-
-```bash
-# Format patches for email review
-git format-patch main..task/TASK-XXX-description -o patches/
-
-# Apply approved patches
-git am patches/*.patch
-```
-
-## Local CI
-
-Without a hosted CI platform, consider:
-
-### Git Hooks
-
-```bash
-# .git/hooks/pre-commit
-#!/bin/bash
-npm test
-```
-
-### Manual CI Script
-
-```bash
-# scripts/ci.sh
-#!/bin/bash
-set -e
-npm ci
-npm run lint
-npm test
-npm run build
-echo "CI passed!"
-```
-
-## Useful Commands
-
-```bash
-# View branch history
-git log --oneline --graph main..HEAD
-
-# Interactive rebase before merge
-git rebase -i main
-
-# Diff summary
-git diff --stat main...HEAD
-
-# List branches
-git branch -a
-```
-
-## Best Practices
-
-1. **Commit Often**: Small, focused commits are easier to review and revert
-2. **Write Good Messages**: Include context for future reference
-3. **Rebase Before Merge**: Keep history clean with interactive rebase
-4. **Tag Releases**: Use semantic versioning tags
-
-```bash
-git tag -a v1.0.0 -m "Release version 1.0.0"
-git push origin v1.0.0
-```