vibe-forge 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/.claude/commands/forge.md +147 -0
  2. package/.claude/settings.local.json +16 -0
  3. package/LICENSE +21 -21
  4. package/README.md +230 -211
  5. package/agents/forge-master/capabilities.md +144 -144
  6. package/agents/forge-master/context-template.md +128 -128
  7. package/bin/cli.js +3 -1
  8. package/bin/forge-daemon.sh +195 -71
  9. package/bin/forge-setup.sh +43 -12
  10. package/bin/forge-spawn.sh +46 -46
  11. package/bin/forge.sh +76 -127
  12. package/bin/lib/agents.sh +157 -0
  13. package/bin/lib/colors.sh +44 -0
  14. package/bin/lib/config.sh +259 -0
  15. package/bin/lib/constants.sh +143 -0
  16. package/config/agents.json +76 -0
  17. package/config/task-template.md +87 -87
  18. package/docs/TODO.md +65 -0
  19. package/docs/npm-publishing.md +95 -0
  20. package/docs/security.md +144 -0
  21. package/package.json +11 -2
package/.claude/commands/forge.md ADDED
@@ -0,0 +1,147 @@
1
+ ---
2
+ description: Vibe Forge - multi-agent development orchestration
3
+ argument-hint: [status|spawn <agent>|task [desc]|help]
4
+ ---
5
+
6
+ # Vibe Forge Command Router
7
+
8
+ **Command:** `/forge $ARGUMENTS`
9
+
10
+ ## Route the Command
11
+
12
+ Based on the first argument, do ONE of the following:
13
+
14
+ ---
15
+
16
+ ### If `$1` is empty OR `$1` is "plan" → Start Planning Hub
17
+
18
+ You are now the **Vibe Forge Planning Hub** - a multi-expert planning team.
19
+
20
+ #### Your Identity
21
+ @_vibe-forge/agents/planning-hub/personality.md
22
+
23
+ #### Project Context
24
+ @context/project-context.md
25
+
26
+ #### Current Forge State
27
+ @_vibe-forge/context/forge-state.yaml
28
+
29
+ #### Task Overview
30
+ Pending tasks:
31
+ !`ls _vibe-forge/tasks/pending/ 2>/dev/null || echo "None"`
32
+
33
+ In-progress tasks:
34
+ !`ls _vibe-forge/tasks/in-progress/ 2>/dev/null || echo "None"`
35
+
36
+ Tasks needing changes:
37
+ !`ls _vibe-forge/tasks/needs-changes/ 2>/dev/null || echo "None"`
38
+
39
+ **Startup:** Display the team assembly welcome as shown in your personality's Startup Behavior section. Show the forge council assembling, then check current work status.
40
+
41
+ ---
42
+
43
+ ### If `$1` is "status" → Show Status Dashboard
44
+
45
+ Display a formatted status dashboard:
46
+
47
+ #### Forge State
48
+ @_vibe-forge/context/forge-state.yaml
49
+
50
+ #### Task Counts
51
+ !`echo "Pending: $(ls _vibe-forge/tasks/pending/*.md 2>/dev/null | wc -l || echo 0)"`
52
+ !`echo "In Progress: $(ls _vibe-forge/tasks/in-progress/*.md 2>/dev/null | wc -l || echo 0)"`
53
+ !`echo "Completed: $(ls _vibe-forge/tasks/completed/*.md 2>/dev/null | wc -l || echo 0)"`
54
+ !`echo "In Review: $(ls _vibe-forge/tasks/review/*.md 2>/dev/null | wc -l || echo 0)"`
55
+ !`echo "Needs Changes: $(ls _vibe-forge/tasks/needs-changes/*.md 2>/dev/null | wc -l || echo 0)"`
56
+ !`echo "Approved: $(ls _vibe-forge/tasks/approved/*.md 2>/dev/null | wc -l || echo 0)"`
57
+
58
+ Format output like:
59
+ ```
60
+ 🔥 VIBE FORGE - Status Dashboard
61
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
62
+ [Task counts and state summary]
63
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
64
+ ```
65
+
66
+ ---
67
+
68
+ ### If `$1` is "spawn" → Spawn Worker Agent
69
+
70
+ **Agent requested:** `$2`
71
+
72
+ Available agents (with aliases):
73
+
74
+ | Agent | Aliases | Role |
75
+ |-------|---------|------|
76
+ | anvil | frontend, ui, fe | Frontend Developer |
77
+ | furnace | backend, api, be | Backend Developer |
78
+ | crucible | test, testing, qa | Tester / QA |
79
+ | sentinel | review, reviewer, cr | Code Reviewer |
80
+ | scribe | docs, documentation | Documentation |
81
+ | herald | release, deploy | Release Manager |
82
+ | ember | devops, ops, infra | DevOps |
83
+ | aegis | security, sec, appsec | Security |
84
+
85
+ If `$2` is empty, show the table above and ask which agent to spawn.
86
+
87
+ If `$2` is provided, run:
88
+
89
+ ```bash
90
+ ./_vibe-forge/bin/forge-spawn.sh $2
91
+ ```
92
+
93
+ Confirm the spawn. If an alias was used (e.g., "frontend"), mention the resolved name: "Spawning **Anvil** (frontend)..."
94
+
95
+ ---
96
+
97
+ ### If `$1` is "task" → Create Task
98
+
99
+ **Task description:** `$2` `$3` `$4` (remaining arguments)
100
+
101
+ #### Task Template
102
+ @_vibe-forge/config/task-template.md
103
+
104
+ #### Existing Tasks
105
+ !`ls _vibe-forge/tasks/pending/ 2>/dev/null || echo "None pending"`
106
+
107
+ If no description provided, ask:
108
+ - What needs to be done?
109
+ - Which agent? (anvil, furnace, crucible, sentinel, scribe, herald, ember, aegis)
110
+ - Priority? (high, medium, low)
111
+
112
+ Generate task ID as `task-XXX` (next sequential number), create file at `_vibe-forge/tasks/pending/task-XXX.md`.
113
+
114
+ ---
115
+
116
+ ### If `$1` is "help" → Show Help
117
+
118
+ Display:
119
+
120
+ ```text
121
+ 🔥 VIBE FORGE - Commands
122
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
123
+
124
+ /forge Start the Planning Hub (default)
125
+ /forge status Show status dashboard
126
+ /forge spawn <agent> Spawn worker in new terminal
127
+ /forge task [desc] Create a new task
128
+ /forge help Show this help
129
+
130
+ Agents (with aliases):
131
+ anvil (frontend, ui, fe) - Frontend Developer
132
+ furnace (backend, api, be) - Backend Developer
133
+ crucible (test, testing, qa) - Tester / QA
134
+ sentinel (review, reviewer, cr) - Code Reviewer
135
+ scribe (docs, documentation) - Documentation
136
+ herald (release, deploy) - Release Manager
137
+ ember (devops, ops, infra) - DevOps
138
+ aegis (security, sec, appsec) - Security
139
+
140
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
141
+ ```
142
+
143
+ ---
144
+
145
+ ### Otherwise → Unknown Command
146
+
147
+ Tell the user: "Unknown command: $1. Run `/forge help` for available commands."
package/.claude/settings.local.json ADDED
@@ -0,0 +1,16 @@
1
+ {
2
+ "permissions": {
3
+ "allow": [
4
+ "Bash(ls:*)",
5
+ "Bash(git pull:*)",
6
+ "Bash(npm view:*)",
7
+ "Bash(gh run list:*)",
8
+ "Bash(gh run view:*)",
9
+ "Bash(gh secret list:*)",
10
+ "Bash(git add:*)",
11
+ "Bash(git commit:*)",
12
+ "Bash(gh workflow run:*)",
13
+ "Bash(gh repo view:*)"
14
+ ]
15
+ }
16
+ }
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 SpasticPalate
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SpasticPalate
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,211 +1,230 @@
1
- # Vibe Forge ⚒️
2
-
3
- A multi-agent development orchestration system for terminal-native vibe coding.
4
-
5
- ## Vision
6
-
7
- Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents - each with distinct personalities and specializations - work together to build software, coordinated through a file-based task system.
8
-
9
- ```
10
- ┌─────────────────────────────────────────────────────────────────┐
11
- │ PLANNING HUB │
12
- │ (Your main terminal session) │
13
- │ │
14
- │ You + Sage (Architect) + Oracle (Analyst) + Quartermaster (PM)│
15
- └─────────────────────────────────────────────────────────────────┘
16
- │
17
- ▼
18
- ┌─────────────────────────────────────────────────────────────────┐
19
- │ FORGE MASTER ⚒️ │
20
- │ Task Distribution & Orchestration │
21
- └─────────────────────────────────────────────────────────────────┘
22
- │
23
- ┌────────────┬───────┴───────┬────────────┐
24
- ▼ ▼ ▼ ▼
25
- ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
26
- │ Anvil │ │ Furnace │ │Crucible │ │Sentinel │
27
- │ 🔨 │ │ 🔥 │ │ 🧪 │ │ 🛡️ │
28
- │Frontend │ │ Backend │ │ Testing │ │ Review │
29
- └─────────┘ └─────────┘ └─────────┘ └─────────┘
30
- ```
31
-
32
- ## Key Features
33
-
34
- - **Personality-driven agents** - Each agent has a distinct voice, expertise, and decision-making style
35
- - **File-based task coordination** - Reliable, debuggable, no WebSocket complexity
36
- - **Token-efficient design** - Context stored locally, minimal wire traffic
37
- - **Terminal-native** - Built for Windows Terminal, works with any terminal supporting tabs
38
-
39
- ## Agents
40
-
41
- ### Core Agents (Always Running)
42
- | Agent | Icon | Role |
43
- |-------|------|------|
44
- | Forge Master | ⚒️ | Chief Orchestrator - distributes tasks, tracks progress |
45
- | Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |
46
-
47
- ### Worker Agents (Per-Task)
48
- | Agent | Icon | Role |
49
- |-------|------|------|
50
- | Anvil | 🔨 | Frontend Dev - components, UI, styling |
51
- | Furnace | 🔥 | Backend Dev - APIs, database, services |
52
- | Crucible | 🧪 | Tester/QA - tests, bug hunting |
53
- | Scribe | 📜 | Documentation - docs, README, API specs |
54
- | Herald | 📯 | Release Manager - versioning, deployment |
55
-
56
- ### Planning Hub Agents (Your Terminal)
57
- | Agent | Icon | Role |
58
- |-------|------|------|
59
- | Sage | 🏛️ | System Architect |
60
- | Oracle | 🔮 | Requirements Analyst |
61
- | Quartermaster | 📋 | Product Manager |
62
-
63
- ### Specialists (On-Demand)
64
- | Agent | Icon | Role |
65
- |-------|------|------|
66
- | Ember | ⚙️ | DevOps/Infrastructure |
67
- | Aegis | 🔒 | Security Specialist |
68
-
69
- ## Project Structure
70
-
71
- ```
72
- vibe-forge/
73
- ├── agents/ # Agent definitions
74
- │ ├── forge-master/
75
- │ │ ├── personality.md # Identity, voice, principles
76
- │ │ ├── capabilities.md # Commands, tools, decisions
77
- │ │ └── context-template.md # Session startup context
78
- │ ├── sentinel/
79
- │ ├── anvil/
80
- │ ├── furnace/
81
- │ ├── crucible/
82
- │ └── ...
83
- ├── tasks/ # Task lifecycle folders
84
- │ ├── pending/ # New tasks waiting for pickup
85
- │ ├── in-progress/ # Currently being worked on
86
- │ ├── completed/ # Done, ready for review
87
- │ ├── review/ # Under Sentinel review
88
- │ ├── approved/ # Passed review
89
- │ ├── needs-changes/ # Review feedback to address
90
- │ └── merged/ # Archive
91
- ├── specs/ # Planning documents
92
- │ ├── epics/
93
- │ └── stories/
94
- ├── context/ # Shared context files
95
- │ ├── project-context.md # Tech stack, patterns, rules
96
- │ └── forge-state.yaml # Current forge status
97
- └── config/ # Configuration
98
- ├── agent-manifest.yaml # Agent roster
99
- ├── task-template.md # Task file template
100
- └── task-types.yaml # Task routing rules
101
- ```
102
-
103
- ## Task Lifecycle
104
-
105
- ```
106
- ┌─────────┐ ┌─────────────┐ ┌───────────┐ ┌────────┐
107
- │ pending │ -> │ in-progress │ -> │ completed │ -> │ review │
108
- └─────────┘ └─────────────┘ └───────────┘ └────────┘
109
- │
110
- ┌──────────────┐ │
111
- │ needs-changes│ <────────────────┤
112
- └──────────────┘ │
113
- │ │
114
- ▼ ▼
115
- ┌─────────────┐ ┌──────────┐
116
- │ in-progress │ │ approved │
117
- └─────────────┘ └──────────┘
118
- │
119
- ▼
120
- ┌─────────┐
121
- │ merged │
122
- └─────────┘
123
- ```
124
-
125
- ## Getting Started
126
-
127
- ### Prerequisites
128
-
129
- - Claude Code CLI ([install](https://claude.ai/download))
130
- - Windows Terminal (recommended) or any terminal with tabs
131
- - Node.js 16+ (for npx installer)
132
- - Git
133
-
134
- ### Quick Start
135
-
136
- ```bash
137
- # In your project directory
138
- npx vibe-forge init
139
- ```
140
-
141
- This will:
142
-
143
- 1. Clone Vibe Forge into `_vibe-forge/`
144
- 2. Detect your platform and terminal
145
- 3. Set up the daemon and configuration
146
- 4. Create a project context file
147
-
148
- Then start the Planning Hub:
149
- ```bash
150
- cd _vibe-forge
151
- ./bin/forge.sh
152
- ```
153
-
154
- ### Manual Setup
155
-
156
- If you prefer not to use npx:
157
-
158
- ```bash
159
- # Clone into your project
160
- git clone https://github.com/SpasticPalate/vibe-forge.git _vibe-forge
161
-
162
- # Run setup
163
- cd _vibe-forge
164
- ./bin/forge-setup.sh
165
-
166
- # Start the Planning Hub
167
- ./bin/forge.sh
168
- ```
169
-
170
- ### Updating
171
-
172
- ```bash
173
- npx vibe-forge update
174
- ```
175
-
176
- ## Slash Commands
177
-
178
- All commands use the `/forge` prefix:
179
-
180
- ```
181
- /forge status - Full dashboard
182
- /forge task:create - Create new task
183
- /forge task:assign - Assign to agent
184
- /forge agents - List agent status
185
- /forge blockers - Current blockers
186
- /forge progress - Epic progress
187
- ```
188
-
189
- ## Token Efficiency
190
-
191
- Vibe Forge is designed for minimal token usage:
192
-
193
- 1. **Local context** - Agents read from files, not conversation history
194
- 2. **Task files as truth** - Instructions in files, not repeated in chat
195
- 3. **Reference, don't duplicate** - Point to paths, don't paste contents
196
- 4. **Batch updates** - One status report per cycle, not per task
197
- 5. **Exception-based** - Report problems, not smooth operations
198
-
199
- ## Philosophy
200
-
201
- > "A forge is not a factory. Each piece is crafted with intention."
202
-
203
- Vibe Forge embraces the craft of software development. Each agent brings expertise and personality to their work. The goal isn't maximum automation - it's maximum collaboration between human and AI.
204
-
205
- ## Acknowledgments
206
-
207
- Inspired by BMAD (Business Model-Agnostic Development) methodology and its multi-agent workflow system.
208
-
209
- ## License
210
-
211
- MIT
1
+ # Vibe Forge ⚒️
2
+
3
+ A multi-agent development orchestration system for terminal-native vibe coding.
4
+
5
+ ## Vision
6
+
7
+ Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents - each with distinct personalities and specializations - work together to build software, coordinated through a file-based task system.
8
+
9
+ ```
10
+ ┌─────────────────────────────────────────────────────────────────┐
11
+ │ PLANNING HUB │
12
+ │ (Your main terminal session) │
13
+ │ │
14
+ │ You + Sage (Architect) + Oracle (Analyst) + Quartermaster (PM)│
15
+ └─────────────────────────────────────────────────────────────────┘
16
+ │
17
+ ▼
18
+ ┌─────────────────────────────────────────────────────────────────┐
19
+ │ FORGE MASTER ⚒️ │
20
+ │ Task Distribution & Orchestration │
21
+ └─────────────────────────────────────────────────────────────────┘
22
+ │
23
+ ┌────────────┬───────┴───────┬────────────┐
24
+ ▼ ▼ ▼ ▼
25
+ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
26
+ │ Anvil │ │ Furnace │ │Crucible │ │Sentinel │
27
+ │ 🔨 │ │ 🔥 │ │ 🧪 │ │ 🛡️ │
28
+ │Frontend │ │ Backend │ │ Testing │ │ Review │
29
+ └─────────┘ └─────────┘ └─────────┘ └─────────┘
30
+ ```
31
+
32
+ ## Key Features
33
+
34
+ - **Personality-driven agents** - Each agent has a distinct voice, expertise, and decision-making style
35
+ - **File-based task coordination** - Reliable, debuggable, no WebSocket complexity
36
+ - **Token-efficient design** - Context stored locally, minimal wire traffic
37
+ - **Terminal-native** - Built for Windows Terminal, works with any terminal supporting tabs
38
+
39
+ ## Agents
40
+
41
+ ### Core Agents (Always Running)
42
+
43
+ | Agent | Icon | Role |
44
+ |-------|------|------|
45
+ | Forge Master | ⚒️ | Chief Orchestrator - distributes tasks, tracks progress |
46
+ | Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |
47
+
48
+ ### Worker Agents (Per-Task)
49
+
50
+ | Agent | Icon | Role |
51
+ |-------|------|------|
52
+ | Anvil | 🔨 | Frontend Dev - components, UI, styling |
53
+ | Furnace | 🔥 | Backend Dev - APIs, database, services |
54
+ | Crucible | 🧪 | Tester/QA - tests, bug hunting |
55
+ | Scribe | 📜 | Documentation - docs, README, API specs |
56
+ | Herald | 📯 | Release Manager - versioning, deployment |
57
+
58
+ ### Planning Hub Agents (Your Terminal)
59
+
60
+ | Agent | Icon | Role |
61
+ |-------|------|------|
62
+ | Sage | 🏛️ | System Architect |
63
+ | Oracle | 🔮 | Requirements Analyst |
64
+ | Quartermaster | 📋 | Product Manager |
65
+
66
+ ### Specialists (On-Demand)
67
+
68
+ | Agent | Icon | Role |
69
+ |-------|------|------|
70
+ | Ember | ⚙️ | DevOps/Infrastructure |
71
+ | Aegis | 🔒 | Security Specialist |
72
+
73
+ ## Project Structure
74
+
75
+ ```
76
+ vibe-forge/
77
+ ├── agents/ # Agent definitions
78
+ │ ├── forge-master/
79
+ │ │ ├── personality.md # Identity, voice, principles
80
+ │ │ ├── capabilities.md # Commands, tools, decisions
81
+ │ │ └── context-template.md # Session startup context
82
+ │ ├── sentinel/
83
+ │ ├── anvil/
84
+ │ ├── furnace/
85
+ │ ├── crucible/
86
+ │ └── ...
87
+ ├── tasks/ # Task lifecycle folders
88
+ │ ├── pending/ # New tasks waiting for pickup
89
+ │ ├── in-progress/ # Currently being worked on
90
+ │ ├── completed/ # Done, ready for review
91
+ │ ├── review/ # Under Sentinel review
92
+ │ ├── approved/ # Passed review
93
+ │ ├── needs-changes/ # Review feedback to address
94
+ │ └── merged/ # Archive
95
+ ├── specs/ # Planning documents
96
+ │ ├── epics/
97
+ │ └── stories/
98
+ ├── context/ # Shared context files
99
+ │ ├── project-context.md # Tech stack, patterns, rules
100
+ │ └── forge-state.yaml # Current forge status
101
+ └── config/ # Configuration
102
+ ├── agent-manifest.yaml # Agent roster
103
+ ├── task-template.md # Task file template
104
+ └── task-types.yaml # Task routing rules
105
+ ```
106
+
107
+ ## Task Lifecycle
108
+
109
+ ```
110
+ ┌─────────┐ ┌─────────────┐ ┌───────────┐ ┌────────┐
111
+ │ pending │ -> │ in-progress │ -> │ completed │ -> │ review │
112
+ └─────────┘ └─────────────┘ └───────────┘ └────────┘
113
+ │
114
+ ┌──────────────┐ │
115
+ │ needs-changes│ <────────────────┤
116
+ └──────────────┘ │
117
+ │ │
118
+ ▼ ▼
119
+ ┌─────────────┐ ┌──────────┐
120
+ │ in-progress │ │ approved │
121
+ └─────────────┘ └──────────┘
122
+ │
123
+ ▼
124
+ ┌─────────┐
125
+ │ merged │
126
+ └─────────┘
127
+ ```
128
+
129
+ ## Getting Started
130
+
131
+ ### Prerequisites
132
+
133
+ - Claude Code CLI ([install](https://claude.ai/download))
134
+ - Windows Terminal (recommended) or any terminal with tabs
135
+ - Node.js 16+ (for npx installer)
136
+ - Git
137
+
138
+ ### Quick Start
139
+
140
+ ```bash
141
+ # In your project directory
142
+ npx vibe-forge init
143
+ ```
144
+
145
+ This will:
146
+
147
+ 1. Clone Vibe Forge into `_vibe-forge/`
148
+ 2. Detect your platform and terminal
149
+ 3. Set up the daemon and configuration
150
+ 4. Create a project context file
151
+
152
+ Then start the Planning Hub:
153
+
154
+ ```bash
155
+ cd _vibe-forge
156
+ ./bin/forge.sh
157
+ ```
158
+
159
+ ### Manual Setup
160
+
161
+ If you prefer not to use npx:
162
+
163
+ ```bash
164
+ # Clone into your project
165
+ git clone https://github.com/SpasticPalate/vibe-forge.git _vibe-forge
166
+
167
+ # Run setup
168
+ cd _vibe-forge
169
+ ./bin/forge-setup.sh
170
+
171
+ # Start the Planning Hub
172
+ ./bin/forge.sh
173
+ ```
174
+
175
+ ### Updating
176
+
177
+ ```bash
178
+ npx vibe-forge update
179
+ ```
180
+
181
+ ## Slash Commands
182
+
183
+ When using Claude Code inside your project, use the `/forge` command:
184
+
185
+ ```
186
+ /forge - Start the Planning Hub (default)
187
+ /forge status - Show status dashboard
188
+ /forge spawn <agent> - Spawn worker in new terminal
189
+ /forge task [desc] - Create a new task
190
+ /forge help - Show available commands
191
+ ```
192
+
193
+ Agents (with aliases):
194
+
195
+ | Agent | Aliases | Role |
196
+ |-------|---------|------|
197
+ | anvil | frontend, ui, fe | Frontend Developer |
198
+ | furnace | backend, api, be | Backend Developer |
199
+ | crucible | test, testing, qa | Tester / QA |
200
+ | sentinel | review, reviewer, cr | Code Reviewer |
201
+ | scribe | docs, documentation | Documentation |
202
+ | herald | release, deploy | Release Manager |
203
+ | ember | devops, ops, infra | DevOps |
204
+ | aegis | security, sec, appsec | Security |
205
+
206
+ Use either the forge name or any alias: `/forge spawn frontend` or `/forge spawn anvil`
207
+
208
+ ## Token Efficiency
209
+
210
+ Vibe Forge is designed for minimal token usage:
211
+
212
+ 1. **Local context** - Agents read from files, not conversation history
213
+ 2. **Task files as truth** - Instructions in files, not repeated in chat
214
+ 3. **Reference, don't duplicate** - Point to paths, don't paste contents
215
+ 4. **Batch updates** - One status report per cycle, not per task
216
+ 5. **Exception-based** - Report problems, not smooth operations
217
+
218
+ ## Philosophy
219
+
220
+ > "A forge is not a factory. Each piece is crafted with intention."
221
+
222
+ Vibe Forge embraces the craft of software development. Each agent brings expertise and personality to their work. The goal isn't maximum automation - it's maximum collaboration between human and AI.
223
+
224
+ ## Acknowledgments
225
+
226
+ Inspired by BMAD (Business Model-Agnostic Development) methodology and its multi-agent workflow system.
227
+
228
+ ## License
229
+
230
+ MIT