@sugar-crash-studios/vibe-forge 0.4.0

package/.claude/commands/clear-attention.md

@@ -0,0 +1,63 @@
+---
+description: Clear an attention signal after helping a worker
+argument-hint: [agent-name | all]
+---
+
+# Clear Attention Command
+
+Use this command to clear attention signals after you've helped a blocked worker.
+
+## Usage
+
+```
+/clear-attention anvil    # Clear Anvil's attention signal
+/clear-attention all      # Clear all attention signals
+/clear-attention          # List current attention signals
+```
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+### If no argument or empty
+
+List all current attention signals from `tasks/attention/`:
+
+```
+🔔 Current Attention Signals:
+
+1. Anvil (5 min ago): Need clarification on auth implementation
+2. Crucible (2 min ago): Tests failing, unsure of expected behavior
+
+Use /clear-attention <agent> to resolve.
+```
+
+### If argument is "all"
+
+Remove all files from `tasks/attention/` and confirm:
+
+```
+✅ Cleared all attention signals (2 resolved)
+```
+
+### If argument is an agent name
+
+1. Find and remove files matching that agent in `tasks/attention/`
+2. Confirm removal:
+
+```
+✅ Cleared attention signal for Anvil
+```
+
+If no matching signal found:
+
+```
+No attention signal found for Anvil
+```
+
+## Notes
+
+- Attention files are created by workers using `/need-help`
+- The daemon watches this folder and sends notifications
+- Clearing signals is a way to acknowledge you've responded
+- Workers can also clear their own signals when unblocked

package/.claude/commands/compact-context.md

@@ -0,0 +1,52 @@
+# Compact Context
+
+Compress the current conversation to free up context window space while preserving all essential information.
+
+## When to Use
+
+Use this when:
+- You notice response quality degrading (repetitive, forgetting earlier decisions)
+- A task is running long and you want to continue without starting fresh
+- The conversation history is getting unwieldy
+- Before picking up a new task in the same session
+
+## How to Compact
+
+Summarize the current conversation into a dense brief using this format:
+
+```
+## Context Compact — [timestamp]
+
+### Work In Progress
+- Task: [task ID and title]
+- Status: [what's done, what's not]
+- Files touched: [list]
+
+### Key Decisions Made
+- [decision 1 and the reason behind it]
+- [decision 2 and the reason behind it]
+
+### Architecture Constraints Discovered
+- [any patterns, restrictions, or conventions learned from reading code]
+
+### Tests Written
+- [test file: X tests passing]
+
+### Blockers / Open Questions
+- [anything unresolved]
+
+### Next Step
+[Exactly what to do next when work resumes]
+```
+
+After writing the summary, respond with:
+
+> Context compacted. Summary above replaces prior conversation history.
+> Ready to continue with: [next step].
+
+## Rules
+
+- Never lose acceptance criteria state -- list any unchecked ACs explicitly
+- Never lose test counts -- the DoD requires accurate numbers
+- Keep the summary under 400 words -- longer defeats the purpose
+- If mid-task: the summary IS the handoff. Make it complete enough to resume cold.

package/.claude/commands/configure-vcs.md

@@ -0,0 +1,102 @@
+---
+description: Configure or re-detect version control system settings
+argument-hint: [detect|set <type>]
+---
+
+# Configure VCS Command
+
+Configure or re-detect the version control system for this project. This affects how agents handle branching, PRs, and CI workflows.
+
+## Usage
+
+```
+/configure-vcs                  # Interactive configuration
+/configure-vcs detect           # Auto-detect from project structure
+/configure-vcs set github       # Manually set to GitHub
+/configure-vcs set gitlab       # Manually set to GitLab
+/configure-vcs set gitea        # Manually set to Gitea (self-hosted)
+/configure-vcs set azure-devops # Manually set to Azure DevOps
+/configure-vcs set bitbucket    # Manually set to Bitbucket
+/configure-vcs set git-only     # Git without platform
+/configure-vcs set none         # No version control
+```
+
+## Supported Platforms
+
+| Type | Platform | PR Command | CI Config |
+|------|----------|------------|-----------|
+| `github` | GitHub | `gh pr create` | `.github/workflows/` |
+| `gitlab` | GitLab | `git push -o merge_request.create` | `.gitlab-ci.yml` |
+| `gitea` | Gitea/Codeberg | `tea pr create` | `.gitea/workflows/` |
+| `azure-devops` | Azure DevOps | `az repos pr create` | `azure-pipelines.yml` |
+| `bitbucket` | Bitbucket | Manual via UI | `bitbucket-pipelines.yml` |
+| `git-only` | Git (no platform) | N/A | N/A |
+| `none` | No VCS | N/A | N/A |
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+### If no arguments (interactive mode):
+
+1. Run detection: `node bin/lib/vcs.js detect`
+2. Show current setting and detected type
+3. Ask user to confirm or change
+4. Run `node bin/lib/vcs.js init <type>` to create folders
+5. Report configuration saved
+
+### If `detect`:
+
+1. Run: `node bin/lib/vcs.js detect`
+2. Display detected type and confidence
+3. If confident detection, ask to apply
+4. Run `node bin/lib/vcs.js set <type>` to save
+
+### If `set <type>`:
+
+1. Validate type is one of: github, gitlab, azure-devops, bitbucket, git-only, none
+2. Run: `node bin/lib/vcs.js init <type>`
+3. Report folders created (if any)
+4. Confirm configuration saved
+
+## Detection Logic
+
+The VCS detector checks (in order of priority):
+
+1. **Platform folders**: `.github/`, `.gitlab/`, `.gitea/`, `.azure/`
+2. **CI config files**: `.gitlab-ci.yml`, `azure-pipelines.yml`, `bitbucket-pipelines.yml`
+3. **Git remote URL**: Parses `.git/config` for github.com, gitlab.com, gitea, codeberg.org, etc.
+4. **Fallback**: `git-only` if `.git/` exists, `none` otherwise
+
+## Impact on Agents
+
+When VCS is configured, agents will:
+
+- **github**: Use `gh pr create`, reference GitHub Actions
+- **gitlab**: Use merge request workflow, reference GitLab CI
+- **azure-devops**: Use `az repos pr create`, reference Azure Pipelines
+- **bitbucket**: Provide manual PR instructions, reference Bitbucket Pipelines
+- **git-only**: Use branch workflow without PR commands
+- **none**: Skip all git-related instructions
+
+## Configuration File
+
+VCS config is stored in `.forge/config.json`:
+
+```json
+{
+  "vcs": {
+    "type": "github",
+    "name": "GitHub",
+    "autoDetected": false,
+    "lastUpdated": "2026-01-16T12:00:00Z"
+  }
+}
+```
+
+## When to Use
+
+- **Initial setup**: Automatically run during `forge init`
+- **Adding git later**: Run `/configure-vcs detect` after `git init`
+- **Switching platforms**: Run `/configure-vcs set <type>` when migrating
+- **Troubleshooting**: Run `/configure-vcs` if agents give wrong git instructions

package/.claude/commands/forge.md

@@ -0,0 +1,171 @@
+---
+description: Vibe Forge - multi-agent development orchestration
+argument-hint: [status|spawn <agent>|task [desc]|help]
+---
+
+# Vibe Forge Command Router
+
+**Command:** `/forge $ARGUMENTS`
+
+## Route the Command
+
+Based on the first argument, do ONE of the following:
+
+---
+
+### If `$1` is empty OR `$1` is "plan" → Start Planning Hub
+
+You are now the **Vibe Forge Planning Hub** - a multi-expert planning team.
+
+#### Your Identity
+
+@_vibe-forge/agents/planning-hub/personality.md
+
+#### Project Context
+
+@context/project-context.md
+
+#### Modern Tooling Reference (avoid outdated suggestions)
+
+@_vibe-forge/context/modern-conventions.md
+
+**Startup:** Display the team assembly welcome:
+
+```text
+🔥 VIBE FORGE - Planning Hub
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+The forge council assembles...
+
+  🔥 Forge Master  - Orchestration & Tasks
+  🏛️ Architect     - Technical Design
+  🛡️ Aegis         - Security
+  ⚙️ Ember         - DevOps & Infrastructure
+  🎨 Pixel         - User Experience
+  📊 Oracle        - Product & Requirements
+  🧪 Crucible      - Quality & Testing
+
+Ready to plan, review, or coordinate.
+Use /forge status to check current tasks.
+
+What's on the anvil today?
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Do NOT automatically scan task folders - wait for user to ask or use `/forge status`.
+
+---
+
+### If `$1` is "status" → Show Status Dashboard
+
+Display a formatted status dashboard.
+
+#### Forge State
+
+@_vibe-forge/context/forge-state.yaml
+
+#### Task Counts
+
+Use the Glob tool to count .md files in each task folder:
+
+- `_vibe-forge/tasks/pending/*.md` - Pending
+- `_vibe-forge/tasks/in-progress/*.md` - In Progress
+- `_vibe-forge/tasks/completed/*.md` - Completed
+- `_vibe-forge/tasks/review/*.md` - In Review
+- `_vibe-forge/tasks/needs-changes/*.md` - Needs Changes
+- `_vibe-forge/tasks/approved/*.md` - Approved
+
+Format output like:
+
+```text
+🔥 VIBE FORGE - Status Dashboard
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Task counts and state summary]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+### If `$1` is "spawn" → Spawn Worker Agent
+
+**Agent requested:** `$2`
+
+Available agents (with aliases):
+
+| Agent    | Aliases              | Role              |
+| -------- | -------------------- | ----------------- |
+| anvil    | frontend, ui, fe     | Frontend Developer |
+| furnace  | backend, api, be     | Backend Developer |
+| crucible | test, testing, qa    | Tester / QA       |
+| sentinel | review, reviewer, cr | Code Reviewer     |
+| scribe   | docs, documentation  | Documentation     |
+| herald   | release, deploy      | Release Manager   |
+| ember    | devops, ops, infra   | DevOps            |
+| aegis    | security, sec, appsec | Security         |
+
+If `$2` is empty, show the table above and ask which agent to spawn.
+
+If `$2` is provided, run:
+
+```bash
+./_vibe-forge/bin/forge-spawn.sh $2
+```
+
+Confirm the spawn. If an alias was used (e.g., "frontend"), mention the resolved name: "Spawning **Anvil** (frontend)..."
+
+---
+
+### If `$1` is "task" → Create Task
+
+**Task description:** `$2` `$3` `$4` (remaining arguments)
+
+#### Task Template
+
+@_vibe-forge/config/task-template.md
+
+#### Existing Tasks
+
+Use the Glob tool to list files in `_vibe-forge/tasks/pending/*.md`
+
+If no description provided, ask:
+
+- What needs to be done?
+- Which agent? (anvil, furnace, crucible, sentinel, scribe, herald, ember, aegis)
+- Priority? (high, medium, low)
+
+Generate task ID as `task-XXX` (next sequential number), create file at `_vibe-forge/tasks/pending/task-XXX.md`.
+
+---
+
+### If `$1` is "help" → Show Help
+
+Display:
+
+```text
+🔥 VIBE FORGE - Commands
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/forge              Start the Planning Hub (default)
+/forge status       Show status dashboard
+/forge spawn <agent> Spawn worker in new terminal
+/forge task [desc]  Create a new task
+/forge help         Show this help
+
+Agents (with aliases):
+  anvil     (frontend, ui, fe)      - Frontend Developer
+  furnace   (backend, api, be)      - Backend Developer
+  crucible  (test, testing, qa)     - Tester / QA
+  sentinel  (review, reviewer, cr)  - Code Reviewer
+  scribe    (docs, documentation)   - Documentation
+  herald    (release, deploy)       - Release Manager
+  ember     (devops, ops, infra)    - DevOps
+  aegis     (security, sec, appsec) - Security
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+### Otherwise → Unknown Command
+
+Tell the user: "Unknown command: $1. Run `/forge help` for available commands."

package/.claude/commands/need-help.md

@@ -0,0 +1,77 @@
+---
+description: Signal that you need human attention/input
+argument-hint: <brief reason>
+---
+
+# Need Help Command
+
+Use this command when you're blocked and need human input. This will:
+
+1. Create an attention file in `tasks/attention/`
+2. Ring the terminal bell for immediate notification
+3. Trigger a system toast notification (if daemon is running)
+4. Show in the Planning Hub's status display
+
+## Usage
+
+```
+/need-help Need clarification on auth implementation approach
+/need-help Blocked on API design decision - REST vs GraphQL?
+/need-help Tests failing, need guidance on expected behavior
+```
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+1. Determine your agent identity from your system prompt or context
+2. Create an attention file at `tasks/attention/<agent>-<timestamp>.md`:
+
+```markdown
+---
+agent: <your-agent-name>
+created: <ISO timestamp>
+status: pending
+---
+
+# Attention Needed
+
+**Agent:** <icon> <display-name>
+**Time:** <human-readable time>
+
+## Issue
+
+$ARGUMENTS
+
+## Context
+
+<Brief context about what you were working on>
+```
+
+3. Ring the terminal bell:
+
+```bash
+printf '\a'
+```
+
+4. Announce that you've signaled for help and will wait.
+
+## Resolving Attention
+
+When a human responds (via Hub or directly), they can:
+- Delete the attention file to clear the flag
+- Move it to a resolved folder
+- Or just respond - the worker can delete their own attention file once unblocked
+
+## Example Output
+
+After running `/need-help Need decision on caching strategy`:
+
+```
+🔔 Attention signal sent!
+
+I've created tasks/attention/anvil-20240115-143022.md
+The Planning Hub and daemon have been notified.
+
+I'll wait for guidance. You can respond here or via the Hub.
+```

package/.claude/commands/update-status.md

@@ -0,0 +1,64 @@
+---
+description: Update your agent status for the forge dashboard
+argument-hint: <status> [task-id]
+---
+
+# Update Status Command
+
+Report your current status to the forge daemon and Planning Hub. This enables real-time visibility into what each worker is doing.
+
+## Usage
+
+```
+/update-status working TASK-001       # Working on a specific task
+/update-status idle                   # Waiting for tasks
+/update-status blocked                # Stuck, may need help
+/update-status reviewing PR-123       # Reviewing something
+/update-status testing TASK-001       # Running tests
+```
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `idle` | No current task, ready for work |
+| `working` | Actively working on a task |
+| `blocked` | Stuck, needs input (consider `/need-help`) |
+| `reviewing` | Reviewing code or PR |
+| `testing` | Running tests |
+| `waiting` | Waiting for external dependency |
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+1. Parse the status and optional task ID from arguments
+2. Determine your agent identity from your system prompt
+3. Write status file to `context/agent-status/<agent>.json`:
+
+```json
+{
+  "agent": "anvil",
+  "status": "working",
+  "task": "TASK-001",
+  "message": "Implementing user authentication",
+  "updated": "2026-01-15T14:30:22Z"  // ISO 8601 timestamp (auto-generated)
+}
+```
+
+4. The daemon reads these files and includes them in `forge-state.yaml`
+5. The Planning Hub sees your status in the dashboard
+
+## Auto-Status Updates
+
+Workers should update their status at these key moments:
+
+1. **On startup**: `/update-status idle` (or working if picking up a task)
+2. **When picking up a task**: `/update-status working TASK-XXX`
+3. **When completing a task**: `/update-status idle`
+4. **When blocked**: `/update-status blocked` (then `/need-help` if needed)
+5. **Before exiting**: Status file can remain (daemon marks stale after timeout)
+
+## Stale Status
+
+The daemon considers a status stale if not updated for 5+ minutes. Stale statuses are shown with a warning indicator in the dashboard.

package/.claude/commands/worker-loop.md

@@ -0,0 +1,106 @@
+---
+description: Start a persistent worker loop (Ralph-style)
+argument-hint: <agent> [--max-idle 10] | stop
+---
+
+# Worker Loop Command
+
+Start a persistent worker loop for the specified agent. The worker will:
+1. Check for assigned tasks
+2. Work on tasks until complete
+3. Loop back and check for more tasks
+4. Only exit after N idle checks with no work found
+
+## Activation Modes
+
+Worker Loop can be activated in two ways:
+
+### 1. Config-based (Recommended)
+
+Enable during `forge init` or toggle anytime:
+
+```bash
+forge config worker-loop on     # Enable for all workers
+forge config worker-loop off    # Disable
+forge config worker-loop        # Check status
+```
+
+When enabled, ALL workers will automatically stay running and check for new tasks.
+
+### 2. Runtime (Per-session)
+
+Use this command for fine-grained control:
+
+```
+/worker-loop anvil              # Start Anvil in persistent loop
+/worker-loop furnace --max-idle 20  # Custom idle limit
+/worker-loop stop               # Stop the current loop
+```
+
+## Arguments
+
+- `$1` - Agent name (anvil, furnace, crucible, etc.) or "stop"
+- `--max-idle N` - Exit after N checks with no tasks (default: 10)
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+### If first argument is "stop"
+
+Remove the worker loop state file and confirm:
+
+```bash
+rm -f "${CLAUDE_LOCAL_DIR:-$HOME/.claude}/forge-worker-loop.json"
+```
+
+Output: "Worker loop stopped."
+
+### Otherwise, start a loop
+
+1. Resolve the agent name to canonical form
+2. Create state file at `${CLAUDE_LOCAL_DIR}/forge-worker-loop.json`:
+
+```json
+{
+  "agent": "<resolved-agent>",
+  "max_idle_checks": 10,
+  "idle_count": 0,
+  "poll_interval": 5,
+  "started_at": "<ISO timestamp>"
+}
+```
+
+3. Load the agent's personality file
+4. Start working with this system prompt addition:
+
+```
+You are in PERSISTENT WORKER MODE. After completing each task:
+1. Check for more tasks assigned to you in tasks/pending/ and tasks/needs-changes/
+2. If tasks found, immediately begin working
+3. If no tasks, announce you are idle and waiting
+
+Do NOT ask permission to continue - work autonomously until no tasks remain.
+```
+
+5. The stop hook (hooks/worker-loop.js) will intercept exit attempts and:
+   - If tasks exist: feed prompt to continue working
+   - If no tasks: increment idle counter
+   - If max idle reached: allow exit
+
+## How It Works
+
+The Worker Loop uses Claude Code's **Stop Hook** feature:
+
+1. When a worker tries to exit, the hook script runs
+2. It checks for pending tasks in `tasks/pending/` and `tasks/needs-changes/`
+3. If tasks found: blocks exit and feeds a prompt to continue working
+4. If no tasks: allows exit (or waits, depending on config)
+
+## Benefits
+
+- Workers stay active and pick up new tasks automatically
+- No need to manually respawn workers
+- Tasks can be added to pending/ and workers will find them
+- Config-based mode requires zero per-session setup
+- Configurable idle timeout prevents infinite waiting