@sugar-crash-studios/vibe-forge 0.4.0

package/docs/getting-started.md

@@ -0,0 +1,261 @@
+# 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
+
+### Open the Dashboard
+
+Launch the web-based dashboard for a visual overview:
+
+```bash
+node bin/dashboard/server.js
+```
+
+Then open `http://localhost:2800` in your browser.
+
+The dashboard provides:
+- Real-time task and agent status
+- Actionable items (stale docs, failing tests)
+- One-click dispatch to assign agents to issues
+- WebSocket updates for live monitoring
+
+**Port 2800?** That's the operating temperature of a forge in degrees Fahrenheit. 🔥
+
+### 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/integration/forge-ownership-policy.md

@@ -0,0 +1,112 @@
+# Forge / Lab Story Ownership Policy
+
+**Status:** Accepted
+**Date:** 2026-04-01
+**Applies to:** vibe-forge v1.0+, vibe-lab v0.9+
+**Co-authored by:** vibe-forge team, vibe-lab team
+
+---
+
+## The Rule
+
+Once a story enters the lab pipeline, **lab owns the execution lifecycle unconditionally.**
+
+This is not a soft guideline. It is the architectural boundary between the two systems.
+
+---
+
+## What This Means in Practice
+
+### For forge
+
+When the Planning Hub submits a story via `create_story` MCP and receives a `lab_story_id` in return:
+
+- Record the entry in `.forge/lab-stories.json` keyed by `{project_id}/{forge_task_id}`
+- Do not submit the same story again — the tracking file is the dedup gate
+- Do not attempt to modify, reprioritize, or cancel the story in lab
+- Do not write directly to lab's `sprint-status.yaml`, `pipeline.db`, or handoff directory
+- Observe status only: via `get_story_status` polling or relay WebSocket events
+- If the story needs to change scope or be cancelled, that is a human action via the lab dashboard
+
+### For lab
+
+When a story has `source: forge` in its metadata:
+
+- Route it to forge workers for execution (via IPC inbox when available, degraded spawn otherwise)
+- Echo `forge_task_id` on all relay events for that story
+- Do not callback to forge to confirm receipt — `create_story` return value is the confirmation
+- If the story fails or is cancelled in lab, emit a `story_transition` relay event with `to_status: cancelled` or `to_status: failed` so forge can update its tracking file
+
+---
+
+## The Promotion Decision
+
+Not every forge task becomes a lab story. The decision belongs to the Planning Hub or the human running the session.
+
+A forge task should be promoted to lab when:
+- It requires the full review chain (arch, code review, tests)
+- It produces a PR that needs to be merged to a shared branch
+- It will be released as part of a versioned delivery
+
+A forge task should stay in forge when:
+- It is exploratory or experimental
+- It will be thrown away or manually applied
+- It is a sub-task of a larger unit that isn't ready to ship independently
+
+This distinction is a human judgment call, not an automated rule. The Planning Hub can recommend, but the submission is intentional.
+
+---
+
+## Duplicate Prevention
+
+Forge must check `.forge/lab-stories.json` before calling `create_story`. The composite key is `{project_id}/{forge_task_id}`.
+
+```json
+{
+  "vibe-lab/FORGE-TASK-42": {
+    "project_id": "vibe-lab",
+    "forge_task_id": "FORGE-TASK-42",
+    "lab_story_id": "FORGE-3",
+    "status": "in-progress",
+    "last_checked": "2026-04-01T12:00:00Z"
+  }
+}
+```
+
+The same `forge_task_id` may exist in multiple projects without collision because the composite key includes `project_id`. This is expected and correct.
+
+---
+
+## Status Visibility
+
+Forge may read story status at any time. It may not write story status.
+
+Read paths:
+- `get_story_status(forge_task_id, project_path)` — on-demand MCP poll
+- Relay WebSocket subscription — real-time `story_transition` events
+
+Write paths: none. All story state transitions belong to lab.
+
+---
+
+## When Things Go Wrong
+
+**Story is stuck in lab (no progress for N hours):**
+Forge observes this via `get_story_status`. It is a human concern, not an automated forge action. The human uses the lab dashboard to investigate or escalate.
+
+**Story fails in lab:**
+Lab emits `story_transition` with `to_status: failed`. Forge updates its tracking file. The Planning Hub can decide whether to resubmit (creating a new story with a new `forge_task_id`) or drop it.
+
+**Heimdall sounds on a worker:**
+Lab routes the story to human review. Forge receives a relay event. The Planning Hub surfaces it. Human resolves.
+
+**Forge daemon restarts mid-story:**
+The `.forge/lab-stories.json` tracking file persists across restarts. On startup, the forge daemon reads the tracking file, identifies in-progress stories, and resumes relay subscription. No re-submission.
+
+---
+
+## Reference
+
+Architecture: `docs/architecture/vibe-lab-integration.md` (vibe-forge repo)
+Lab copy: `_vibe-chain/docs/forge-ownership-policy.md` (vibe-lab repo)
+Both copies must remain identical. When updated, update both.

package/docs/npm-publishing.md

@@ -0,0 +1,132 @@
+# 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.
+
+## How to Release a New Version
+
+**Do NOT run `npm publish` locally.** Publishing is done via GitHub Actions.
+
+### Quick Release Process
+
+```bash
+# 1. Create release branch
+git checkout main && git pull origin main
+git checkout -b release/vX.Y.Z
+
+# 2. Bump version and update CHANGELOG
+npm version minor --no-git-tag-version  # or major/patch
+# Edit CHANGELOG.md with release notes
+
+# 3. Commit, push, create PR
+git add -A
+git commit -m "Release vX.Y.Z"
+git push -u origin release/vX.Y.Z
+gh pr create --title "Release vX.Y.Z"
+
+# 4. Merge PR (squash)
+gh pr merge --squash --delete-branch
+
+# 5. Create git tag and GitHub Release (triggers npm publish)
+git checkout main && git pull origin main
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin vX.Y.Z
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "Release notes here"
+
+# 6. Verify publish succeeded
+gh run list --workflow=publish.yml --limit=1
+npm view vibe-forge version
+```
+
+The `gh release create` command triggers the publish workflow automatically.
+
+## 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/)