https://github.com/alto9/forge
VSCode extension to provide behavior driven planning and development to your project
https://github.com/alto9/forge
ai context-engineering vscode-extension
Last synced: 25 days ago
JSON representation
VSCode extension to provide behavior driven planning and development to your project
- Host: GitHub
- URL: https://github.com/alto9/forge
- Owner: alto9
- License: mit
- Created: 2025-11-09T01:27:29.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T12:33:50.000Z (27 days ago)
- Last Synced: 2026-03-31T12:47:43.642Z (27 days ago)
- Topics: ai, context-engineering, vscode-extension
- Language: TypeScript
- Homepage:
- Size: 15.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Forge Studio
VSCode/Cursor extension for context engineering and agentic development. Forge Studio helps teams maintain product vision, technical concepts, and roadmaps—then turns milestones into actionable, implementation-ready issues via a staged agent workflow.
## Overview
Forge Studio provides:
- **Initialize Cursor Agents** – Installs agents/commands/skills/hooks to `~/.cursor/` (user-level)
- **Initialize Project** – Creates `.forge/` in the current project
- **Forge Help persona** – Workflow explainer for command/agent guidance and handoff questions
- **Agent workflow** – Six-step flow: **Product Owner** → **Architect** → **Planner** → **Technical Writer** → **Engineer** → **Quality Assurance**, plus **Forge Help** for workflow questions. Agents install to `~/.cursor/agents/` from `resources/workflow/`. Shared context lives in the project’s **`.forge/`** folder: any agent may update those files when contracts are wrong or unclear; **Product Owner** owns `vision.json` / `project.json`, and **Architect** is the primary steward of `knowledge_map.json` and cross-domain coherence (see `resources/workflow/agents/AGENT_FLOW.md`).
- **Commands** – architect-this, plan-roadmap, refine-issue, build-from-github, build-from-pr-review, review-pr (injected via Cursor-agent initialization)
- **Chat participants** – @forge-help, @product-owner, @architect, @planner, @technical-writer, @engineer, @quality-assurance (VSCode chat participants mirror Cursor agents)
## Quick Start
1. Open a project in Cursor or VSCode
2. On Cursor startup, Forge checks user-level Cursor agents in `~/.cursor/` and prompts before applying updates when changes are needed
3. Run **Forge: Initialize Project** from the Command Palette (`Cmd/Ctrl+Shift+P`) to create project-level `.forge/`
4. Forge creates:
- `~/.cursor/` – agents, commands, skills, hooks (user-level, shared across projects)
- `~/.cursor/hooks.json` – JSON schema validation on .forge file edits
- `.forge/` – vision.json, project.json, skill_registry.json, knowledge_map.json, schemas/ (project-level)
## User Flow
After Cursor-agent initialization, use the injected agents and commands:
- **Architect** (`/architect-this`) – Aligns `.forge/knowledge_map.json` and domain contract docs with product intent; hands off to Planner
- **Plan Roadmap** (`/plan-roadmap`) – Manages GitHub milestones and issues via pull-milestones, pull-milestone-issues
- **Refine Issue** (`/refine-issue`) – Step 4 **orchestration** (normalize input, delegate, verify outputs); the **Technical Writer** agent carries out refinement (parent branch linked, optional sub-issues, no per-sub-issue branches). Authoritative details: `resources/workflow/commands/refine-issue.md` and `resources/workflow/agents/tech-writer.md`.
- **Build from GitHub** (`/build-from-github`) – Creates/links implementation branch for the issue, implements, runs all tests/lint until green, then commit/PR
- **Build from PR Review** (`/build-from-pr-review`) – Retrieves PR feedback, checks out PR branch, applies requested changes, validates, and pushes updates for re-review
- **Review PR** (`/review-pr`) – Reviews code, posts review comments
## Chat Participants (VSCode)
Type `@` in chat to use Forge personas:
| Participant | Purpose |
|-------------|---------|
| **@forge-help** | Workflow guide for Forge steps, commands, handoffs, and quality gates |
| **@product-owner** | Step 1: maintain product vision and project direction |
| **@architect** | Step 2: update technical contracts and knowledge structure |
| **@planner** | Step 3: align milestones and issues with documented direction |
| **@technical-writer** | Step 4: Technical Writer agent refines issues into implementation-ready work (invocation contract for `/refine-issue` is in `resources/workflow/commands/refine-issue.md`) |
| **@engineer** | Step 5: implement scoped issue work and prepare PRs |
| **@quality-assurance** | Step 6: review PRs for correctness and security |
## Project Structure
After setup:
**User-level (~/.cursor/):**
```
~/.cursor/
├── agents/ # product-owner, architect, planner, technical-writer, engineer, quality-assurance, forge-help (+ AGENT_FLOW.md)
├── commands/ # architect-this, plan-roadmap, refine-issue, build-from-github, build-from-pr-review, review-pr
├── skills/ # gh-driven workflow skills (branch, commit, milestone operations)
├── hooks/ # JSON schema validation on .forge file edits
└── hooks.json # Cursor hooks config
```
**Project-level (.forge/):**
```
your-project/
└── .forge/
├── vision.json # Product vision, mission, strategy
├── project.json # Project config (GitHub URL, paths)
├── skill_registry.json # Skill-to-agent assignments
├── knowledge_map.json # Domain structure (vision → runtime, business_logic, data, etc.)
└── schemas/ # JSON schemas for validation
```
## Installation
### From Source (Development)
```bash
npm install
npm run build
npm run package
code --install-extension forge-studio-*.vsix
```
### From VSIX
```bash
code --install-extension forge-studio-*.vsix
```
## Development
```bash
npm install
npm run build
npm run watch # Watch mode
npm run lint
npm run test
npm run package # Package for distribution
```
## License
MIT