@sugar-crash-studios/vibe-forge 0.4.0

package/docs/workflows/gitlab.md

@@ -0,0 +1,105 @@
+# GitLab Workflow Guide
+
+Git workflow guidance for projects hosted on GitLab.
+
+## 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 Merge Request
+
+```bash
+# Push with merge request creation
+git push -o merge_request.create -o merge_request.title="TASK-XXX: Add feature X"
+
+# Or create via GitLab CLI (glab)
+glab mr create --title "TASK-XXX: Add feature X" --description "Description of changes"
+
+# Draft merge request
+glab mr create --draft --title "TASK-XXX: WIP - Add feature X"
+```
+
+### After MR Approval
+
+```bash
+# Merge via GitLab UI (squash merge recommended)
+# Or via CLI
+glab mr merge --squash
+
+# Clean up local branch
+git checkout main
+git pull origin main
+git branch -d task/TASK-XXX-description
+```
+
+## CI/CD
+
+GitLab CI configuration goes in `.gitlab-ci.yml`:
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - test
+  - build
+
+test:
+  stage: test
+  script:
+    - npm ci
+    - npm test
+
+build:
+  stage: build
+  script:
+    - npm run build
+  only:
+    - main
+```
+
+## Useful Commands
+
+```bash
+# Using GitLab CLI (glab)
+glab mr list              # List open MRs
+glab mr view              # View current MR
+glab mr checkout 123      # Checkout MR locally
+glab ci status            # Check pipeline status
+```
+
+## Branch Protection
+
+Configure in Settings > Repository > Protected Branches:
+- Require merge request approval
+- Require pipeline to succeed
+- Prevent force push

package/docs/workflows.md

@@ -0,0 +1,454 @@
+# Common Workflows
+
+This guide covers typical development workflows with Vibe Forge.
+
+## Single Developer Workflow
+
+The simplest way to use Vibe Forge - one developer coordinating AI agents.
+
+### Morning Startup
+
+1. **Open your project** in your terminal
+
+2. **Start Claude Code** and open the Planning Hub:
+   ```
+   /forge
+   ```
+
+3. **Check status** to see where you left off:
+   ```
+   /forge status
+   ```
+
+4. **Review pending tasks** and plan your day
+
+### Feature Development
+
+1. **Discuss the feature** with the Planning Hub:
+   ```
+   I want to add user authentication with email/password login
+   ```
+
+2. **Let the Hub break it down** into tasks for different agents
+
+3. **Spawn the needed workers**:
+   ```
+   /forge spawn furnace    # Backend for auth API
+   /forge spawn anvil      # Frontend for login form
+   ```
+
+4. **Create tasks** (or let the Hub create them):
+   ```
+   /forge task Create authentication API endpoints
+   /forge task Build login form component
+   ```
+
+5. **Monitor progress**:
+   ```
+   /forge status
+   ```
+
+6. **Review completed work** with Sentinel:
+   ```
+   /forge spawn sentinel
+   ```
+
+### End of Day
+
+1. Check `/forge status` for any blocked tasks
+2. Note any attention signals (`/need-help` requests)
+3. Review what was completed
+4. Plan tomorrow's priorities
+
+---
+
+## Multi-Agent Task Workflow
+
+Coordinating multiple agents working in parallel.
+
+### Setup
+
+1. **Start the Planning Hub**:
+   ```
+   /forge
+   ```
+
+2. **Spawn your team** (each in its own terminal):
+   ```
+   /forge spawn anvil
+   /forge spawn furnace
+   /forge spawn crucible
+   ```
+
+3. **Enable worker loops** for continuous work:
+   In each worker terminal:
+   ```
+   /worker-loop anvil
+   /worker-loop furnace
+   /worker-loop crucible
+   ```
+
+### Task Distribution
+
+1. **Create tasks** from the Planning Hub:
+   ```
+   /forge task [frontend] Create product listing component
+   /forge task [backend] Build product API with pagination
+   /forge task [test] Write tests for product endpoints
+   ```
+
+2. **Tasks are picked up automatically** by workers in loop mode
+
+3. **Monitor from the Hub**:
+   ```
+   /forge status
+   ```
+
+### Handling Dependencies
+
+When tasks depend on each other:
+
+1. **Furnace completes the API** - task moves to `completed/`
+
+2. **Anvil picks up frontend task** - can now integrate with API
+
+3. **Crucible writes tests** - validates both frontend and backend
+
+### Resolving Blocks
+
+When a worker signals for help:
+
+```
+# In worker terminal
+/need-help API spec unclear - should pagination be cursor or offset?
+```
+
+1. **Hub sees the attention signal** in status
+
+2. **You respond** in the Planning Hub or directly to the worker
+
+3. **Worker continues** after getting guidance
+
+---
+
+## Code Review Workflow
+
+Systematic code review with Sentinel.
+
+### Automatic Review
+
+1. **Worker completes a task** and moves it to `review/`
+
+2. **Sentinel picks up the review**:
+   ```
+   /forge spawn sentinel
+   ```
+
+3. **Sentinel examines the changes**:
+   - Code correctness
+   - Security concerns
+   - Performance implications
+   - Test coverage
+
+4. **Sentinel provides feedback**:
+   - Approves: Task moves to `approved/`
+   - Requests changes: Task moves to `needs-changes/`
+
+### Manual Review Request
+
+Request a review of specific code:
+
+```
+# In Planning Hub
+Ask Sentinel to review the authentication implementation in src/auth/
+```
+
+Or spawn Sentinel directly:
+
+```
+/forge spawn sentinel
+```
+
+Then in Sentinel's terminal:
+```
+Review the recent changes to the user service
+```
+
+### Handling Review Feedback
+
+When Sentinel requests changes:
+
+1. **Task moves to `needs-changes/`**
+
+2. **Original worker sees the task** and picks it up
+
+3. **Worker addresses feedback**
+
+4. **Task goes back to `review/`**
+
+5. **Sentinel re-reviews**
+
+---
+
+## Planning and Breaking Down Tasks
+
+Using the Planning Hub to decompose large features.
+
+### Feature Decomposition
+
+1. **Describe the feature**:
+   ```
+   /forge
+
+   I need to build a shopping cart with:
+   - Add/remove items
+   - Quantity adjustment
+   - Price calculation
+   - Checkout flow
+   ```
+
+2. **Hub engages advisors**:
+   - **Sage** considers architecture
+   - **Oracle** clarifies requirements
+   - **Quartermaster** suggests priorities
+
+3. **Hub proposes task breakdown**:
+   ```
+   Suggested tasks:
+
+   [backend] Cart data model and API
+   [backend] Price calculation service
+   [frontend] Cart component with item list
+   [frontend] Checkout form and flow
+   [test] Cart API integration tests
+   [test] Checkout e2e tests
+   ```
+
+4. **Refine and approve**:
+   ```
+   Looks good, but add a task for cart persistence across sessions
+   ```
+
+5. **Create the tasks**:
+   ```
+   Create these tasks and assign priorities
+   ```
+
+### Estimating Complexity
+
+Ask the Hub for estimates:
+
+```
+How complex is the checkout flow? What are the main risks?
+```
+
+The Hub will engage relevant advisors:
+- Sage on technical complexity
+- Oracle on requirement gaps
+- Quartermaster on timeline
+
+### Handling Ambiguity
+
+When requirements are unclear:
+
+1. **Hub identifies gaps**:
+   ```
+   Before we proceed, I need clarity on:
+   - Should guest checkout be supported?
+   - What payment providers to integrate?
+   - Are there shipping calculation requirements?
+   ```
+
+2. **You provide answers** or mark as assumptions
+
+3. **Hub documents decisions** in task files
+
+---
+
+## Release Workflow
+
+Preparing and executing releases with Herald.
+
+### Pre-Release Checklist
+
+1. **Check status**:
+   ```
+   /forge status
+   ```
+   Ensure no tasks are in-progress or blocked.
+
+2. **Spawn Herald**:
+   ```
+   /forge spawn herald
+   ```
+
+3. **Prepare release**:
+   ```
+   Prepare release v1.2.0 with all completed work since v1.1.0
+   ```
+
+4. **Herald generates**:
+   - Changelog entries
+   - Release notes
+   - Version bump
+
+### Release Execution
+
+1. **Review Herald's output**
+
+2. **Approve the release**:
+   ```
+   Proceed with the release
+   ```
+
+3. **Herald executes**:
+   - Commits version changes
+   - Creates git tag
+   - Prepares deployment notes
+
+### Hotfix Release
+
+For urgent fixes:
+
+1. **Create hotfix task**:
+   ```
+   /forge task [urgent] Fix payment processing bug
+   ```
+
+2. **Spawn appropriate worker**:
+   ```
+   /forge spawn furnace
+   ```
+
+3. **After fix, spawn Herald**:
+   ```
+   /forge spawn herald
+   ```
+
+4. **Prepare patch release**:
+   ```
+   Prepare hotfix release v1.1.1 for the payment bug fix
+   ```
+
+---
+
+## DevOps Workflow
+
+Infrastructure and deployment with Ember.
+
+### CI/CD Setup
+
+1. **Spawn Ember**:
+   ```
+   /forge spawn ember
+   ```
+
+2. **Describe your needs**:
+   ```
+   Set up CI/CD pipeline with:
+   - Run tests on PR
+   - Build and deploy on merge to main
+   - Deploy to staging automatically
+   - Manual promotion to production
+   ```
+
+3. **Ember creates**:
+   - GitHub Actions workflows
+   - Dockerfile if needed
+   - Deployment scripts
+
+### Infrastructure Changes
+
+1. **Create infrastructure task**:
+   ```
+   /forge task [devops] Add Redis caching layer
+   ```
+
+2. **Ember handles**:
+   - Docker compose updates
+   - Environment configuration
+   - Monitoring setup
+
+---
+
+## Security Review Workflow
+
+Security auditing with Aegis.
+
+### Scheduled Security Review
+
+1. **Spawn Aegis**:
+   ```
+   /forge spawn aegis
+   ```
+
+2. **Request audit**:
+   ```
+   Perform security review of the authentication system
+   ```
+
+3. **Aegis examines**:
+   - Authentication flows
+   - Input validation
+   - Dependency vulnerabilities
+   - Security headers
+
+4. **Aegis reports findings** with severity levels
+
+### Pre-Release Security Check
+
+Before major releases:
+
+1. **Create security task**:
+   ```
+   /forge task [security] Pre-release security audit for v2.0
+   ```
+
+2. **Aegis reviews**:
+   - All changes since last audit
+   - New dependencies
+   - Configuration changes
+
+3. **Address findings** before release
+
+---
+
+## Tips for Effective Workflows
+
+### Keep Context Updated
+
+Edit `context/project-context.md` as your project evolves:
+- Architecture decisions
+- Coding conventions
+- Team agreements
+
+### Use Worker Loop for Long Sessions
+
+Enable persistent mode for extended work:
+```
+/worker-loop anvil --max-idle 20
+```
+
+### Monitor Regularly
+
+Check status frequently:
+```
+/forge status
+```
+
+Look for:
+- Blocked tasks
+- Attention signals
+- Completed work ready for review
+
+### Document Decisions
+
+When the Hub makes recommendations, capture important decisions in:
+- Task files (for task-specific context)
+- Project context (for project-wide patterns)
+
+### Balance Automation and Control
+
+- **Worker Loop** for routine tasks
+- **Manual spawning** for specific needs
+- **Hub coordination** for complex features

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@sugar-crash-studios/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": "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/",
+    "bin/dashboard/frontend/index.html",
+    "bin/dashboard/frontend/package.json",
+    "bin/dashboard/frontend/src/",
+    "bin/dashboard/frontend/svelte.config.js",
+    "bin/dashboard/frontend/vite.config.js",
+    "agents/",
+    "config/",
+    "context/",
+    "tasks/",
+    ".claude/",
+    "docs/"
+  ],
+  "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": {
+    "msedge-tts": "^2.0.4"
+  }
+}