vibe-forge 0.4.0 → 0.8.2

package/docs/workflows.md

@@ -1,454 +0,0 @@
-# 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/tasks/completed/ARCH-001-duplicate-agent-config.md

@@ -1,121 +0,0 @@
----
-id: ARCH-001
-title: "Consolidate duplicate agent configuration sources"
-type: architecture
-priority: high
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
-completed_at: 2026-01-16T10:30:00Z
-completed_by: architect
----
-
-## Summary
-Agent configuration is defined in three separate locations with overlapping but inconsistent data, creating maintenance burden and risk of drift.
-
-## Current State
-Agent definitions exist in:
-
-1. **config/agents.json** - JSON format with name, icon, role, aliases, type, personality_file, tab_color
-2. **config/agent-manifest.yaml** - YAML format with much richer data (principles, communication_style, task_types, terminal_tab, description, source)
-3. **bin/lib/constants.sh** - Bash fallback arrays (VALID_AGENTS, AGENT_ALIASES, AGENT_DISPLAY_NAMES, AGENT_ROLES, AGENT_PERSONALITY_FILES, AGENT_ICONS, AGENT_TAB_COLORS)
-
-Problems:
-- `agent-manifest.yaml` has "forge-master" vs `agents.json` has "hub" naming
-- `agent-manifest.yaml` has extra agents (sage, oracle, quartermaster) not in `agents.json`
-- Rich data in manifest (principles, communication_style) is not being used
-- Bash fallbacks duplicate JSON, risking drift
-
-## Proposed State
-Single source of truth with clear hierarchy:
-
-1. **config/agents.json** - Primary machine-readable configuration
-   - All agent data consolidated here
-   - Used by bash scripts via `load_agents_from_json()`
-   - Used by Node.js scripts directly
-
-2. **config/agent-manifest.yaml** - DEPRECATED or converted
-   - Either delete (migrate data to agents.json)
-   - Or keep as human documentation only, clearly marked as non-normative
-
-3. **bin/lib/constants.sh** - Minimal fallback
-   - Keep only as emergency fallback for environments without Node.js
-   - Auto-generate from agents.json during release process
-   - Or remove entirely if Node.js is a hard requirement
-
-## Affected Files
-- G:\dev\vibe-forge\config\agents.json
-- G:\dev\vibe-forge\config\agent-manifest.yaml
-- G:\dev\vibe-forge\bin\lib\constants.sh
-- G:\dev\vibe-forge\bin\lib\config.sh (load_agents_from_json)
-
-## Migration/Remediation Steps
-1. Decide which extra agents to include (sage, oracle, quartermaster, or delete)
-2. Add missing fields from agent-manifest.yaml to agents.json (principles, communication_style, etc.)
-3. Either delete agent-manifest.yaml or add clear header marking it as documentation-only
-4. Evaluate whether bash fallback in constants.sh is needed
-5. If keeping fallback, create build script to auto-generate from agents.json
-6. Update tests to verify single source of truth
-
-## Acceptance Criteria
-- [x] Single authoritative agent configuration source
-- [x] No duplicate agent definitions across files
-- [x] Clear documentation on which file is source of truth
-- [x] Existing functionality unchanged
-- [x] All tests passing
-
-## Resolution
-
-### Decision Made
-Established `config/agents.json` as the SINGLE SOURCE OF TRUTH for agent configuration. The other files serve specific purposes:
-
-- **agents.json**: Primary, authoritative configuration (used by code)
-- **agent-manifest.yaml**: Non-normative documentation with rich personality info
-- **constants.sh**: Fallback defaults for environments without Node.js
-
-### Changes Implemented
-
-1. **Enhanced agents.json (v1.1.0)**
-   - Added `_comment` field documenting it as source of truth
-   - Added `version` field for tracking schema changes
-   - Added fields from manifest: `persistent`, `terminal_tab`, `description`, `task_types`
-   - Standardized on "hub" as canonical name (with "forge-master" alias)
-   - Changed hub icon from fire to forge hammer to match orchestrator role
-   - Added `architect` agent (consolidating sage/oracle/quartermaster functionality)
-
-2. **Updated agent-manifest.yaml**
-   - Added prominent header marking file as DOCUMENTATION ONLY / NON-NORMATIVE
-   - Added `_status: documentation-only` field
-   - Preserved rich personality data as reference for personality file authors
-
-3. **Updated constants.sh**
-   - Added `architect` agent to all arrays
-   - Added sync date comments to remind maintainers to check agents.json
-   - Reordered arrays to match agents.json ordering (hub first as core)
-   - Updated hub icon to forge hammer
-
-4. **Created architect agent**
-   - New directory: `agents/architect/`
-   - New personality file: `agents/architect/personality.md`
-   - Consolidates system architect role (similar to sage from manifest)
-
-5. **Updated README.md**
-   - Added Architect to specialists list
-   - Updated project structure to show agents.json as roster source
-
-### Files Modified
-- `config/agents.json` - Enhanced with new fields, architect agent, version
-- `config/agent-manifest.yaml` - Added documentation-only header
-- `bin/lib/constants.sh` - Added architect, sync date comments
-- `README.md` - Updated structure and agent list
-- `agents/architect/personality.md` - Created
-
-### Tests
-All 80 tests passing:
-- 4 test suites (cli, constants, config, agents)
-- No regressions
-
-### Future Considerations
-- Consider auto-generating constants.sh from agents.json in build process
-- Consider a validation script to check sync between files
-- Rich personality data (principles, communication_style) kept in manifest for now - could be moved to personality files

package/tasks/completed/ARCH-002-mixed-bash-node-implementation.md

@@ -1,88 +0,0 @@
----
-id: ARCH-002
-title: "Standardize on single implementation language"
-type: architecture
-priority: medium
-assigned_to: architect
-created_at: 2026-01-15T17:00:00Z
-created_by: architect-review
-completed_at: 2026-01-16T11:00:00Z
-completed_by: architect
----
-
-## Summary
-The codebase uses a mix of Bash and Node.js for similar functionality, increasing maintenance burden and complexity. Since Node.js is already a requirement (Node 16+), consider standardizing on Node.js.
-
-## Current State (Reassessed)
-Implementation split:
-
-**Bash (bin/*.sh, bin/lib/*.sh):**
-- forge.sh - Main entry point
-- forge-setup.sh - Setup/init
-- forge-spawn.sh - Terminal spawning
-- forge-daemon.sh - Background daemon
-- lib/colors.sh - Color output
-- lib/constants.sh - Constants
-- lib/config.sh - Configuration loading
-- lib/agents.sh - Agent resolution
-- lib/database.sh - SQLite operations
-- lib/json.sh - JSON utilities (Node.js-based)
-- lib/util.sh - Utility functions
-
-**Node.js (bin/*.js, bin/lib/*.js):**
-- cli.js - npx entry point
-- terminal.js - Cross-platform terminal detection
-
-**Bash calling Node.js:**
-- config.sh uses Node.js for JSON parsing
-- json.sh provides unified JSON operations via Node.js
-- All jq usage has been removed
-
-## Analysis Findings
-
-**Good news:** The task description was outdated. The codebase has already:
-1. Removed all jq dependencies
-2. Unified JSON handling via `bin/lib/json.sh` using Node.js
-3. Established clear separation of concerns
-
-**Current architecture is intentional:**
-- Bash for orchestration (process management, file watching, terminal control)
-- Node.js for cross-platform utilities (terminal detection, JSON parsing)
-- This hybrid approach is appropriate for a shell orchestration tool
-
-## Decision: Option B - Document and Maintain Hybrid
-
-After analysis, Option B (keep hybrid, document clearly) is the better choice because:
-
-1. **Bash is appropriate for shell orchestration** - Vibe Forge manages terminals and processes, which are inherently shell operations
-2. **Full migration is high risk/effort** - Would require rewriting ~70KB of tested Bash code
-3. **Current split is clean** - Clear boundaries between Bash (orchestration) and Node.js (cross-platform utilities)
-4. **jq dependency already removed** - The main inconsistency (JSON handling) is already resolved
-
-## Changes Implemented
-
-1. **Created docs/architecture.md** - Comprehensive documentation of:
-   - Language strategy and rationale
-   - Directory structure
-   - Data flow diagram
-   - JSON handling patterns
-   - Future migration considerations
-
-2. **Verified jq removal** - Confirmed all JSON operations use json.sh/Node.js
-
-## Acceptance Criteria
-- [x] Decision documented on language strategy - See docs/architecture.md
-- [x] Consistent JSON parsing approach - All uses json.sh (Node.js-based)
-- [x] Windows compatibility maintained - Git Bash + forge.cmd wrapper
-- [x] All tests passing - 80 tests pass
-- [N/A] If migrating: at least one component fully migrated - Decided not to migrate
-
-## Files Modified
-- `docs/architecture.md` - Created (new architectural documentation)
-
-## Future Work (Out of Scope)
-If full Node.js migration is desired later:
-1. Create `src/` directory structure
-2. Migrate incrementally: config -> agents -> database -> daemon -> CLI
-3. Keep Bash wrappers during transition
-4. See migration path in docs/architecture.md