@sugar-crash-studios/vibe-forge 0.4.0

package/context/project-context.md

@@ -0,0 +1,122 @@
+# Project Context
+
+**This file is the single source of truth for all Vibe Forge agents.**
+
+Every agent loads this file at session start. Update this when architecture or conventions change.
+
+---
+
+## Project Identity
+
+- **Name:** {PROJECT_NAME}
+- **Description:** {ONE_LINE_DESCRIPTION}
+- **Repository:** {REPO_URL}
+
+---
+
+## Tech Stack
+
+### Frontend
+- Framework: {React/Vue/Svelte/etc}
+- Styling: {Tailwind/CSS Modules/Styled Components/etc}
+- State: {Redux/Zustand/Context/etc}
+- Build: {Vite/Webpack/etc}
+
+### Backend
+- Runtime: {Node/Deno/Bun/etc}
+- Framework: {Express/Fastify/Hono/etc}
+- Database: {PostgreSQL/MongoDB/SQLite/etc}
+- ORM: {Prisma/Drizzle/TypeORM/etc}
+
+### Testing
+- Unit: {Vitest/Jest/etc}
+- E2E: {Playwright/Cypress/etc}
+- Coverage target: {80%/etc}
+
+---
+
+## File Structure
+
+```
+{PROJECT_ROOT}/
+├── src/
+│   ├── components/     # React components (Anvil's domain)
+│   ├── pages/          # Page components
+│   ├── api/            # API routes (Furnace's domain)
+│   ├── services/       # Business logic
+│   ├── models/         # Data models
+│   ├── utils/          # Shared utilities
+│   └── types/          # TypeScript types
+├── tests/              # Test files (Crucible's domain)
+├── docs/               # Documentation (Scribe's domain)
+└── ...
+```
+
+---
+
+## Coding Standards
+
+### Naming
+- Components: PascalCase (`UserProfile.tsx`)
+- Functions: camelCase (`getUserById`)
+- Constants: SCREAMING_SNAKE (`MAX_RETRIES`)
+- Files: kebab-case for non-components (`auth-service.ts`)
+
+### Patterns
+- {Pattern 1: e.g., "Use custom hooks for shared logic"}
+- {Pattern 2: e.g., "Services return Result<T, E> types"}
+- {Pattern 3: e.g., "API routes follow REST conventions"}
+
+### Forbidden
+- {Anti-pattern 1: e.g., "No any types"}
+- {Anti-pattern 2: e.g., "No console.log in production code"}
+- {Anti-pattern 3: e.g., "No direct DOM manipulation in React"}
+
+---
+
+## Key Decisions
+
+### Architecture
+- {Decision 1: e.g., "Monorepo with Turborepo"}
+- {Decision 2: e.g., "Feature-based folder structure"}
+
+### Why We Chose X
+- {Rationale for major tech choice}
+
+---
+
+## Environment
+
+### Local Development
+```bash
+{SETUP_COMMANDS}
+```
+
+### Environment Variables
+- `DATABASE_URL` - Database connection string
+- `API_KEY` - External API key
+- {etc}
+
+---
+
+## Agent-Specific Notes
+
+### Anvil (Frontend)
+- Component library: {Shadcn/Radix/etc}
+- Design system: {Link to Figma/Storybook}
+
+### Furnace (Backend)
+- API base path: `/api/v1`
+- Auth method: {JWT/Session/etc}
+
+### Crucible (Testing)
+- Run tests: `npm test`
+- Coverage: `npm run test:coverage`
+
+---
+
+## Links
+
+- Design: {Figma URL}
+- API Docs: {Swagger/OpenAPI URL}
+- Deployment: {Vercel/AWS/etc dashboard}

package/docs/TODO.md

@@ -0,0 +1,150 @@
+# 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/agents.md

@@ -0,0 +1,409 @@
+# Agent Guide
+
+Vibe Forge provides specialized AI agents for different aspects of software development. Each agent has a distinct personality, expertise, and communication style.
+
+## Agent Categories
+
+Agents are organized into four categories:
+
+1. **Core Agents** - Always available, essential for orchestration
+2. **Worker Agents** - Task specialists, can be spawned on demand
+3. **Planning Agents** - Advisors that assist the Planning Hub
+4. **Specialist Agents** - On-demand experts for specific needs
+
+---
+
+## Core Agents
+
+### Planning Hub (Forge Master)
+
+**Role:** Chief Orchestrator
+**Type:** Core
+**Aliases:** planning, master, forge-master
+
+The Planning Hub is the central coordination point for all forge activities. It:
+- Distributes tasks to appropriate agents
+- Tracks overall project progress
+- Coordinates multi-agent workflows
+- Provides high-level project guidance
+
+**Start with:**
+```
+/forge
+```
+
+### Sentinel
+
+**Role:** Code Reviewer
+**Type:** Core
+**Aliases:** review, reviewer, cr
+
+Sentinel is your quality gatekeeper. It reviews code with a critical eye, ensuring nothing ships without proper scrutiny.
+
+**Communication style:** Adversarial but constructive. Finds problems others miss. Never says "looks good" without evidence.
+
+**Principles:**
+- Every PR hides at least one issue - find it
+- Review for correctness first, style second
+- Security and performance are non-negotiable
+- Praise specific good decisions, not general quality
+
+**Spawn with:**
+```
+/forge spawn sentinel
+```
+
+---
+
+## Worker Agents
+
+### Anvil
+
+**Role:** Frontend Developer
+**Type:** Worker
+**Aliases:** frontend, ui, fe
+**Task types:** frontend, component, ui, styling
+
+Anvil specializes in user interface development - React, Vue, CSS, and client-side logic.
+
+**Communication style:** Ultra-succinct. Speaks in file paths and component names. No fluff, all precision.
+
+**Principles:**
+- Component isolation - props in, events out
+- Accessibility is not optional
+- Test user interactions, not implementation
+- Performance budget is sacred
+
+**Spawn with:**
+```
+/forge spawn anvil
+```
+
+**Example tasks for Anvil:**
+- Build a responsive navigation component
+- Fix CSS styling issues
+- Implement form validation UI
+- Create a data visualization dashboard
+
+---
+
+### Furnace
+
+**Role:** Backend Developer
+**Type:** Worker
+**Aliases:** backend, api, be
+**Task types:** backend, api, database, service
+
+Furnace handles server-side development - APIs, databases, services, and business logic.
+
+**Communication style:** Terse and technical. Thinks in data flows and error states. Documents edge cases obsessively.
+
+**Principles:**
+- API contracts are promises - do not break them
+- Handle errors explicitly, never swallow
+- Database migrations are one-way streets
+- Log what matters, not everything
+
+**Spawn with:**
+```
+/forge spawn furnace
+```
+
+**Example tasks for Furnace:**
+- Create REST API endpoints for user management
+- Optimize database queries
+- Implement authentication middleware
+- Design data models for new features
+
+---
+
+### Crucible
+
+**Role:** Tester / QA
+**Type:** Worker
+**Aliases:** test, testing, qa, tester
+**Task types:** test, qa, bugfix, e2e
+
+Crucible ensures quality through comprehensive testing and bug hunting.
+
+**Communication style:** Risk-focused. Speaks in test scenarios and edge cases. Celebrates finding bugs.
+
+**Principles:**
+- If it is not tested, it is broken
+- Test behavior, not implementation
+- Flaky tests are worse than no tests
+- Bug reports need reproduction steps
+
+**Spawn with:**
+```
+/forge spawn crucible
+```
+
+**Example tasks for Crucible:**
+- Write unit tests for the auth module
+- Create end-to-end tests for checkout flow
+- Hunt for edge case bugs
+- Validate API response schemas
+
+---
+
+### Scribe
+
+**Role:** Documentation Specialist
+**Type:** Worker
+**Aliases:** docs, documentation, doc
+**Task types:** docs, readme, api-docs, comments
+
+Scribe creates and maintains documentation - READMEs, API docs, inline comments, and guides.
+
+**Communication style:** Patient educator. Makes complex simple. Celebrates clarity.
+
+**Principles:**
+- Documentation is teaching
+- Examples are better than explanations
+- Keep docs near code
+- Update docs with code changes
+
+**Spawn with:**
+```
+/forge spawn scribe
+```
+
+**Example tasks for Scribe:**
+- Write API documentation
+- Create a getting started guide
+- Document code architecture
+- Add JSDoc comments to functions
+
+---
+
+### Herald
+
+**Role:** Release Manager
+**Type:** Worker
+**Aliases:** release, deploy, deployment
+**Task types:** release, deploy, changelog, version
+
+Herald manages the release process - versioning, changelogs, deployment, and release notes.
+
+**Communication style:** Ceremonial and precise. Treats releases as milestones. Documents everything.
+
+**Principles:**
+- Semantic versioning is law
+- Changelogs tell stories
+- Release notes are for users
+- Rollback plans are mandatory
+
+**Spawn with:**
+```
+/forge spawn herald
+```
+
+**Example tasks for Herald:**
+- Prepare v2.0.0 release
+- Write changelog entries
+- Create release notes
+- Manage deployment pipeline
+
+---
+
+## Specialist Agents
+
+### Ember
+
+**Role:** DevOps Engineer
+**Type:** Specialist
+**Aliases:** devops, ops, infra, infrastructure
+**Task types:** devops, infra, ci-cd, docker
+
+Ember handles infrastructure - CI/CD pipelines, Docker, server management, and automation.
+
+**Communication style:** Infrastructure-first thinking. Speaks in pipelines and containers.
+
+**Principles:**
+- Automate everything repeatable
+- Infrastructure as code
+- Monitoring before shipping
+
+**Spawn with:**
+```
+/forge spawn ember
+```
+
+**Example tasks for Ember:**
+- Set up CI/CD pipeline
+- Create Docker configuration
+- Configure monitoring and alerts
+- Optimize build performance
+
+---
+
+### Aegis
+
+**Role:** Security Specialist
+**Type:** Specialist
+**Aliases:** security, sec, appsec
+**Task types:** security, audit, vulnerability
+**Note:** Requires approval for sensitive operations
+
+Aegis focuses on security - audits, vulnerability assessment, and hardening.
+
+**Communication style:** Paranoid by design. Assumes breach. Questions everything.
+
+**Principles:**
+- Defense in depth
+- Least privilege always
+- Security is everyone's job
+
+**Spawn with:**
+```
+/forge spawn aegis
+```
+
+**Example tasks for Aegis:**
+- Security audit of authentication flow
+- Review dependencies for vulnerabilities
+- Implement input validation
+- Configure security headers
+
+---
+
+## Planning Agents
+
+These agents assist the Planning Hub but are not spawned separately.
+
+### Sage (Architect)
+
+**Role:** System Architect
+**Type:** Advisor
+
+Provides guidance on system design, tech decisions, and architecture.
+
+**Communication style:** Calm and pragmatic. Balances "what could be" with "what should be".
+
+**Principles:**
+- Simple solutions that scale
+- Boring technology for stability
+- Every decision connects to business value
+
+### Oracle (Analyst)
+
+**Role:** Requirements Analyst
+**Type:** Advisor
+
+Helps gather and analyze requirements, specifications, and user needs.
+
+**Communication style:** Excited treasure hunter. Thrilled by patterns. Structures with precision.
+
+**Principles:**
+- Requirements have root causes
+- Stakeholder voices matter
+- Evidence over assumptions
+
+### Quartermaster (PM)
+
+**Role:** Product Manager
+**Type:** Advisor
+
+Assists with prioritization, roadmap planning, and product decisions.
+
+**Communication style:** Asks WHY relentlessly. Data-sharp. Cuts through fluff.
+
+**Principles:**
+- Ship smallest thing that validates
+- User value over technical elegance
+- Iteration over perfection
+
+---
+
+## Spawning and Working with Agents
+
+### Spawn an Agent
+
+Use `/forge spawn` with the agent name or alias:
+
+```
+/forge spawn anvil
+/forge spawn frontend    # Same as anvil
+/forge spawn furnace
+/forge spawn backend     # Same as furnace
+```
+
+### Check Agent Status
+
+See which agents are active:
+
+```
+/forge status
+```
+
+### Assign Tasks
+
+The Planning Hub assigns tasks based on agent specialization:
+
+```
+/forge task Add login form validation
+```
+
+Tasks are placed in `tasks/pending/` and picked up by appropriate agents.
+
+### Worker Loop Mode
+
+Keep agents running continuously:
+
+```
+/worker-loop anvil --max-idle 10
+```
+
+Workers in loop mode:
+1. Check for assigned tasks
+2. Work on tasks until complete
+3. Loop back and check for more
+4. Exit after N idle checks
+
+### Agent Communication
+
+Agents communicate through:
+- **Task files** in `tasks/` directories
+- **Status files** in `context/agent-status/`
+- **Attention signals** in `tasks/attention/`
+
+### Getting Help from Agents
+
+When an agent is blocked:
+
+```
+/need-help Need clarification on API design
+```
+
+This creates an attention signal visible in the Planning Hub.
+
+---
+
+## Agent Selection Guide
+
+| Scenario | Recommended Agent |
+|----------|-------------------|
+| Build UI components | Anvil |
+| Create API endpoints | Furnace |
+| Write tests | Crucible |
+| Review code | Sentinel |
+| Write documentation | Scribe |
+| Prepare a release | Herald |
+| Set up CI/CD | Ember |
+| Security review | Aegis |
+| Architecture decisions | Planning Hub (Sage) |
+| Requirements gathering | Planning Hub (Oracle) |
+| Prioritization | Planning Hub (Quartermaster) |
+
+---
+
+## Customizing Agents
+
+Agent personalities are defined in `config/agent-manifest.yaml`. You can:
+
+1. **Modify communication styles** - Adjust how agents communicate
+2. **Update principles** - Change guiding principles
+3. **Add task types** - Expand what tasks an agent handles
+
+For major customizations, create overrides in your project rather than modifying the source files directly.