forgecraft 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to ForgeAI are documented here.
+
+## [1.0.0] - 2026-03-15
+
+### Added
+- **`forge doctor`** — diagnose setup issues: checks Node, Git, Claude CLI, auth, framework tools, GitHub CLI
+- **`forge diff <v1> [v2]`** — show colorized diff between any two versions, tags, or commits with summary stats
+- **`forge clean`** — reset sprint state (plan, snapshots, designs) while preserving config; `--snapshots` flag for partial clean
+- **`forge export`** — export sprint plan as formatted markdown with checkboxes, dependencies, and progress
+- **Config validation** — validates `forge.config.json` on every command with clear error messages and fix suggestions
+- **Graceful shutdown** — SIGINT/SIGTERM handler saves plan state and commits progress before exit; shows `forge resume` hint
+- **`add-story` in `forge fix`** — when the Orchestrator detects a new feature request, it now actually adds the story to the plan (was a TODO stub)
+
+### Changed
+- **Pipeline rewrite** — step-by-step Pipeline no longer creates feature branches (was causing merge conflicts); builds on main with per-story commits, matching the AutoPipeline strategy
+- **Framework-aware Orchestrator** — plan generation prompt now includes framework name, language, design support status; example JSON uses the actual configured framework
+- **JSON validation** — plan generation now validates the response has required fields (epics array) and provides clear error messages on malformed JSON
+- **Routing fallback** — `routeUserInput` returns a text answer instead of crashing when the AI returns non-JSON
+- **Regen depth limit** — `runPlanPhase` recursion capped at 5 attempts to prevent stack overflow
+- **Design phase skip** — Pipeline auto-skips design for frameworks without Storybook support (Django)
+- **Review error handling** — Pipeline review phase now catches errors per-story instead of crashing the entire phase
+- **Worker constructor** — all callers updated to use the new `(config, sandboxOpts, mute)` signature
+- **Removed peerDependencies** — `next` and `@storybook/react` removed from package.json (this is a CLI tool, not a library that depends on frameworks)
+- **18 total commands** — up from 14 in v0.3
+- **Version bumped** to 1.0.0
+
+### Fixed
+- Worker constructor mismatch: Pipeline was calling `new Worker(config)` but Worker requires 2-3 args — runtime crash
+- `forge fix` created feature branches and merge conflicts — now works on main
+- `forge fix` "add-story" action showed success message but never actually added the story to the plan
+- Orchestrator plan prompt hardcoded `"framework": "nextjs"` in example JSON
+- Pipeline review phase had no error handling — one failed review crashed all subsequent reviews
+- `forge init` showed "Coming in v0.4" for Flutter — updated to generic "coming soon"
+- Unused `processingQueue` property removed from AutoPipeline
+
+## [0.3.0] - 2026-03-14
+
+### Added
+- **React + Vite adapter** — `forge init` now supports React + Vite (TypeScript SPA with Tailwind, React Router, Vite)
+- **Django adapter** — `forge init` now supports Django (Python + DRF + django-cors-headers)
+- **Framework adapter system** — pluggable adapter architecture in `src/core/adapters/` so adding new frameworks is straightforward
+- **`forge map`** — terminal sprint visualization showing stories as a tree with status icons, dependency arrows, progress bar, and git tags
+- **`forge resume`** — resume an interrupted sprint from where it left off, with option to retry blocked stories
+- **Token expiry handling** — Worker and Orchestrator detect auth/token errors (401, expired session), notify the user, and automatically retry after re-authentication (up to 3 attempts, 30s between retries)
+- **Chat queue improvements** — readline no longer conflicts with ora spinners, shows `[queued #N]` confirmation with count, re-shows input hint after each queued message
+- **Progress save on error** — pipeline saves plan state and commits before failing, so no work is lost on crashes or auth expiry
+- **Framework-aware prompts** — Worker build/review/fix prompts now include framework-specific instructions (Next.js App Router, Vite config, Django migrations, etc.)
+
+### Changed
+- **State Manager caching** — in-memory cache with mtime validation avoids redundant disk reads; directory creation cache skips repeated `mkdir` calls
+- **Worker memory optimization** — removed `messages[]` array from WorkerResult (was storing every SDK message in memory); only tracks files, errors, usage, summary
+- **Git operation reduction** — branch name caching, repo verification caching, `commitAll` catches "nothing to commit" instead of running a separate `status` check
+- **Version bumped** to 0.3.0
+
+### Fixed
+- readline `output: process.stdout` was interfering with ora spinners — now uses `terminal: false`
+- Git `ensureMainBranch` was listing all branches even when already on main
+
+## [0.2.0] - 2026-03-13
+
+### Added
+- **Autonomous mode** (`forge auto`) — fully autonomous pipeline with no human gates (except review gate after build)
+- **Parallel story execution** — stories grouped by dependency, independent stories built concurrently with `Promise.all`
+- **`forge undo`** — interactive commit selection with `git revert`, conflict handling, story status reset
+- **`forge history`** — version timeline with checkpoints, color-coded activity log
+- **`forge checkout`** — jump to any forge tag or commit hash
+- **Design import** (`forge design --import <path>`) — import screenshots/mockups as design references
+- **GitHub Issues sync** — `GitHubSync` class creates/updates GitHub Issues with labels from sprint plan
+- **Safety caps** — per-mode turn limits (design: 30, build: 50, review: 20, fix: 15) prevent agent loops
+- **Review gate** — pause after build phase with notification sound, user chooses: continue/skip/abort
+- **Live elapsed timer** — `[M:SS]` prefix on all spinner text, 1s interval keeps ticking during agent thinking
+- **Sound notifications** — macOS `afplay`, Linux `paplay`, fallback terminal bell
+- **Auto-generated README** — Worker generates README.md based on plan + actual code after build
+- **GitHub Pages deploy** (`--deploy` flag) — configures next.config for static export + GitHub Actions workflow
+- **`--skip-design`** flag — skip Storybook design phase for faster builds
+- **`--mute`** flag — suppress notification sounds
+- **`--quiet`** flag — spinners only, hide tool details
+- **Auth check** — verifies Claude Code CLI is installed and logged in before running
+- **SEO/assets in prompts** — favicon, og.png, metadata, robots.txt, sitemap.xml, manifest.json
+
+### Changed
+- Git strategy: build on `main` with per-story commits + tags (no more feature branches in auto mode — prevents merge conflicts)
+- Token usage display: uses `=` not `+=` for SDK cumulative totals
+
+### Fixed
+- Merge conflicts during autonomous mode caused by multiple branches adding same config files
+- Token usage double-counting from SDK result messages
+- Agent infinite loops (now capped by `MODE_MAX_TURNS`)
+
+## [0.1.0] - 2026-03-12
+
+### Added
+- Initial release
+- Two-agent architecture: Orchestrator (plans, routes, reviews) + Worker (design, build, review, fix modes)
+- Step-by-step pipeline: `forge plan` → `forge design` → `forge build` → `forge review`
+- `forge sprint` — full pipeline with human gates between phases
+- `forge init` — initialize project with framework/model selection
+- `forge status` — show sprint progress
+- `forge fix` — targeted bug fixes and small changes
+- Next.js support with App Router, Tailwind CSS, shadcn/ui
+- Storybook design previews with CSF3 format
+- Git integration with per-story commits, tags, and snapshots
+- `.forge/` directory for state management (plan.json, state.json, snapshots/)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel John
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/forgeai?style=flat-square&color=000" alt="npm version" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-000?style=flat-square" alt="node version" />
+  <img src="https://img.shields.io/github/license/joeljohn159/forgeai?style=flat-square&color=000" alt="license" />
+  <img src="https://img.shields.io/badge/frameworks-Next.js%20%7C%20React%20%7C%20Django-000?style=flat-square" alt="frameworks" />
+</p>
+
+<h1 align="center">ForgeAI</h1>
+
+<p align="center">
+  <strong>Ship production apps from a single sentence.</strong><br/>
+  An AI orchestration framework that plans, designs, builds, reviews, and deploys software<br/>using a structured multi-agent pipeline — not a chat window.
+</p>
+
+<br/>
+
+```
+$ forge auto "a personal finance tracker with budget categories, expense logging, and monthly reports"
+
+  forge auto
+  sandbox on · type a message anytime to queue feedback
+
+  [0:03] Plan ready
+
+  Personal Finance Tracker · nextjs
+  12 stories across 4 epics
+
+  Layout & Navigation
+    [full] App shell with sidebar navigation
+    [full] Dashboard landing page
+  Expense Management
+    [full] Add expense form with categories
+    [full] Expense list with filters
+    [ui]   Category management page
+  Budget Tracking
+    [full] Budget setup per category
+    [ui]   Budget vs actual progress bars
+    [full] Budget alerts and notifications
+  Reports
+    [ui]   Monthly expense breakdown chart
+    [ui]   Category pie chart
+    [full] Export to CSV
+    [full] Date range selector
+
+  Build · 12 stories
+
+  [0:15] [1/12] App shell with sidebar navigation · 8 files  2.1k in / 18.4k out
+  [0:48] [2/12] Dashboard landing page · 4 files              1.8k in / 12.1k out
+  [1:22] parallel: Add expense form, Category management
+  [2:01] [3/12] Add expense form with categories · 6 files    2.4k in / 21.0k out
+  [2:01] [4/12] Category management page · 3 files            1.2k in / 9.8k out
+  ...
+
+  [14:02] Pushed to GitHub
+  ─────────────────────────────────
+  Done in 14m 23s · 12/12 stories
+  28.4k in / 198.2k out
+```
+
+<br/>
+
+---
+
+<br/>
+
+## The Problem
+
+Every AI coding tool today works the same way: you type into a chat, the AI writes some code, you paste it in, something breaks, you go back and forth. There is no structure, no planning, no design phase, no review. You are the project manager, the QA engineer, and the glue holding it all together.
+
+ForgeAI replaces that entire loop.
+
+<br/>
+
+## How It Works
+
+ForgeAI runs a complete software development pipeline autonomously. One command, six phases, zero copy-pasting.
+
+```
+ PLAN            DESIGN           BUILD            REVIEW           PUSH            SHIP
+ ────            ──────           ─────            ──────           ────            ────
+ Break into      Generate         Implement        QA check         Auto-push       Tag, merge,
+ epics &         Storybook        each story       each story,      commits &       deploy
+ stories         previews         with full        auto-fix         tags to
+                                  CLI power        minor issues     GitHub
+
+ Orchestrator    Worker           Worker           Worker           Git             Git
+ Agent           (design mode)    (build mode)     (review mode)    Manager         Manager
+```
+
+Each phase has a clear input, a clear output, and a gate between them. Stories that don't depend on each other build **in parallel**. After everything completes, the project is **automatically pushed to GitHub** (if a remote is configured). The whole thing runs on `main` with per-story commits and tags for easy rollback.
+
+<br/>
+
+## Quick Start
+
+```bash
+# Prerequisites: Node 18+, Claude Code CLI (logged in)
+
+# Install globally
+npm install -g forgeai
+
+# Create a new project directory
+mkdir my-app && cd my-app
+
+# Initialize (choose Next.js, React+Vite, or Django)
+forge init
+
+# Build something
+forge auto "a task management app with projects, due dates, and team assignment"
+
+# Start the dev server
+forge start
+
+# If interrupted, resume where you left off
+forge resume
+
+# Fix a bug (supports screenshots)
+forge fix "the sidebar overlaps on mobile" --image screenshot.png
+
+# Push to GitHub manually (auto-push happens after forge auto)
+forge push
+```
+
+That's it. Come back in 15 minutes to a working app with proper types, responsive design, SEO metadata, favicons, and a README — already pushed to your repo.
+
+<br/>
+
+## Features
+
+### Structured Pipeline, Not a Chat
+Every project goes through Plan, Design, Build, Review, Push. Each phase has specialized prompts, tool permissions, and quality gates. The AI doesn't just write code — it writes code that builds, lints, and type-checks before moving on.
+
+### Two-Agent Architecture
+Instead of one monolithic agent or a swarm of disconnected ones, ForgeAI uses two:
+
+- **Orchestrator** — The tech lead. Plans the sprint, crafts detailed prompts for each story, routes your feedback, reviews output. Never touches code.
+- **Worker** — The engineer. Same agent, four modes (`design`, `build`, `review`, `fix`), each with different system prompts and tool permissions. Preserves context across the entire build.
+
+### Parallel Execution
+Stories are grouped by dependency. Independent stories build concurrently using `Promise.all`, cutting total build time significantly. A 12-story app that takes 45 minutes sequentially finishes in ~15 minutes.
+
+### Live Feedback Loop
+Type a message at any point during the build. It gets queued and processed at the next safe point between stories. The Orchestrator classifies your input and routes it:
+
+```
+"make the header sticky"              → Worker fix mode
+"redesign the settings page"          → Worker design mode → build mode
+"the API returns 404 on /expenses"    → Worker fix mode (debug)
+"add a dark mode toggle"              → New story added to sprint
+"what's the database schema?"         → Orchestrator answers directly
+```
+
+### Screenshot-Based Bug Fixing
+Pass a screenshot to `forge fix` and Claude reads the image to understand the visual issue:
+
+```bash
+forge fix "the button is cut off on mobile" --image screenshot.png
+```
+
+### Auto-Push to GitHub
+After `forge auto` or `forge resume` completes, commits and tags are automatically pushed to your GitHub remote. No manual `git push` needed. If the push fails, a warning is shown and you can retry with `forge push`.
+
+### Safety Caps
+Each worker mode has a maximum turn limit (`design: 30`, `build: 50`, `review: 20`, `fix: 15`). If an agent gets stuck in a loop, it stops gracefully instead of burning through your usage.
+
+### Review Gate
+After the build phase completes, ForgeAI pauses and plays a notification sound. You choose: continue to review, skip review, or abort. You're always in control.
+
+### Production Defaults
+Every project gets the things most AI tools forget:
+- `favicon.ico`, `icon.svg`, `apple-touch-icon.png`
+- Open Graph image (`og.png`) for social sharing
+- Complete metadata — title, description, OG tags, Twitter cards
+- `robots.txt`, `sitemap.xml`, `manifest.json`
+- `next/image` for all images
+- Auto-generated `README.md` based on what was actually built
+
+### Multi-Framework Support
+ForgeAI isn't locked to one framework. Each adapter knows how to scaffold, build, lint, and run a project in its stack:
+
+| Framework | Language | Design Phase | Status |
+|-----------|----------|-------------|--------|
+| **Next.js** | TypeScript | Storybook | Stable |
+| **React + Vite** | TypeScript | Storybook | Stable |
+| **Django** | Python | Skipped | Stable |
+| Flutter | Dart | — | Planned |
+
+Worker prompts automatically adapt to the framework — Next.js gets App Router instructions, Vite gets SPA routing, Django gets migration commands.
+
+### Sprint Resume
+If a build gets interrupted (auth expires, network drops, you close the terminal), your progress is saved. Run `forge resume` to pick up exactly where you left off. Blocked stories can be retried.
+
+### Optional GitHub Pages Deploy
+Pass `--deploy` and ForgeAI configures `next.config` for static export and creates a GitHub Actions workflow for automatic deployment.
+
+<br/>
+
+## Commands
+
+### Autonomous Mode (recommended)
+
+```bash
+forge auto "description"              # Full autonomous pipeline (auto-pushes to GitHub)
+forge auto "description" --skip-design  # Skip Storybook previews (faster)
+forge auto "description" --deploy     # Add GitHub Pages deployment
+forge auto "description" --mute       # No notification sounds
+forge auto "description" --quiet      # Spinners only, no tool details
+```
+
+### Step-by-Step Mode
+
+```bash
+forge init                            # Initialize ForgeAI in current directory
+forge plan "description"              # Generate sprint plan
+forge design                          # Generate Storybook design previews
+forge build                           # Build stories sequentially
+forge review                          # Run QA review on built stories
+forge sprint "description"            # Run full pipeline with human gates
+```
+
+### Run & Deploy
+
+```bash
+forge start                           # Start the dev server (auto-detects framework)
+forge push                            # Push commits + tags to GitHub
+```
+
+### Utilities
+
+```bash
+forge status                          # Show current sprint progress
+forge map                             # Visual sprint map with status + dependencies
+forge diff <v1> [v2]                  # Show changes between two versions
+forge fix "description"               # Fix a bug or make a small change
+forge fix "desc" --image <path>       # Fix with a screenshot for visual context
+forge undo                            # Revert the last agent action
+forge resume                          # Resume an interrupted sprint (auto-pushes)
+forge history                         # Show version timeline and activity log
+forge checkout <version>              # Jump to a specific version or checkpoint
+forge export                          # Export sprint plan as markdown
+forge clean                           # Reset sprint state (keeps config)
+forge doctor                          # Diagnose setup issues
+```
+
+<br/>
+
+## Architecture
+
+```
+src/
+├── cli/
+│   ├── index.ts                      # CLI entry point (commander)
+│   └── commands/
+│       ├── auto.ts                   # forge auto — autonomous mode
+│       ├── resume.ts                 # forge resume — resume interrupted sprint
+│       ├── start.ts                  # forge start — start dev server
+│       ├── push.ts                   # forge push — push to GitHub
+│       ├── init.ts                   # forge init
+│       ├── plan.ts                   # forge plan
+│       ├── design.ts                 # forge design
+│       ├── build.ts                  # forge build
+│       ├── review.ts                 # forge review
+│       ├── sprint.ts                 # forge sprint
+│       ├── status.ts                 # forge status
+│       ├── map.ts                    # forge map — visual sprint map
+│       ├── fix.ts                    # forge fix (supports --image)
+│       ├── undo.ts                   # forge undo
+│       └── history.ts               # forge history + forge checkout
+│
+├── core/
+│   ├── orchestrator/
+│   │   ├── index.ts                  # Orchestrator agent — plans, routes, reviews
+│   │   └── prompts.ts                # Orchestrator system prompt
+│   │
+│   ├── worker/
+│   │   ├── index.ts                  # Worker agent — executes in 4 modes
+│   │   └── prompts/
+│   │       └── index.ts              # Framework-aware mode-specific prompts
+│   │
+│   ├── pipeline/
+│   │   ├── index.ts                  # Step-by-step pipeline
+│   │   └── auto.ts                   # Autonomous pipeline (parallel, timer, gates, resume, auto-push)
+│   │
+│   ├── adapters/
+│   │   ├── base.ts                   # FrameworkAdapter interface
+│   │   ├── nextjs.ts                 # Next.js adapter
+│   │   ├── react-vite.ts             # React + Vite adapter
+│   │   ├── django.ts                 # Django adapter
+│   │   └── index.ts                  # Adapter registry + factory
+│   │
+│   ├── git/
+│   │   └── index.ts                  # Git operations (branch, commit, tag, push)
+│   │
+│   ├── github/
+│   │   └── index.ts                  # GitHub Issues sync (via gh CLI)
+│   │
+│   └── utils/
+│       ├── config.ts                 # Config validation
+│       └── sound.ts                  # Notification sounds (macOS/Linux/fallback)
+│
+├── state/
+│   └── index.ts                      # State manager (.forge/ directory, cached)
+│
+└── types/
+    └── plan.ts                       # TypeScript types for the entire system
+```
+
+<br/>
+
+## State & Git
+
+ForgeAI tracks everything in a `.forge/` directory inside your repo:
+
+```
+.forge/
+├── plan.json                         # Epics, stories, status, dependencies
+├── state.json                        # Current phase, queue, history
+├── config.json                       # Framework, model, preferences
+├── snapshots/                        # Pre-action snapshots for undo
+└── designs/                          # Design approval metadata
+```
+
+Every story gets a commit. Every milestone gets a tag:
+
+```
+main ────●────●────●────●────●────●──── HEAD → pushed to origin
+         │    │    │    │    │    │
+         │    │    │    │    │    └── forge/v0.6-export-csv
+         │    │    │    │    └── forge/v0.5-budget-alerts
+         │    │    │    └── forge/v0.4-budget-setup
+         │    │    └── forge/v0.3-expense-list
+         │    └── forge/v0.2-add-expense
+         └── forge/v0.1-designs
+```
+
+Roll back to any point with `git checkout forge/v0.3-expense-list`.
+
+<br/>
+
+## Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Node.js** | v18 or higher |
+| **Claude Code** | Installed and logged in (`npm i -g @anthropic-ai/claude-code && claude login`) |
+| **Git** | Any recent version |
+| **Subscription** | Claude Max, Team, or Enterprise |
+
+ForgeAI uses the Claude Agent SDK which authenticates through your Claude Code session. No separate API key needed.
+
+<br/>
+
+## Configuration
+
+After `forge init`, your `forge.config.json` controls:
+
+```json
+{
+  "framework": "nextjs",
+  "model": "sonnet",
+  "designPreview": "storybook",
+  "autoCommit": true,
+  "storybook": {
+    "port": 6006
+  }
+}
+```
+
+<br/>
+
+## Comparison
+
+| | ChatGPT / Claude Chat | GitHub Copilot | Cursor | **ForgeAI** |
+|---|---|---|---|---|
+| Planning | Manual | None | None | **Automated sprint planning** |
+| Design preview | None | None | None | **Storybook generation** |
+| Build | Copy-paste | Autocomplete | Inline edit | **Full autonomous build** |
+| Review | Manual | None | None | **Automated QA + auto-fix** |
+| Git strategy | Manual | Manual | Manual | **Auto commits + tags + push** |
+| Parallelism | N/A | N/A | N/A | **Dependency-grouped parallel** |
+| Human oversight | Full control | None | Approve/reject | **Stage gates + live feedback** |
+| Bug fix with screenshots | N/A | N/A | N/A | **forge fix --image** |
+| SEO & assets | You remember | You remember | You remember | **Built-in defaults** |
+| Multi-framework | N/A | Any | Any | **Next.js, React, Django** |
+| Resume on failure | Start over | N/A | N/A | **Auto-save + resume** |
+
+<br/>
+
+## Roadmap
+
+**v0.1** — Core pipeline, two-agent architecture, Next.js support
+
+**v0.2** — Autonomous mode, parallel execution, undo/history, GitHub sync
+
+**v0.3** — React + Vite and Django adapters, `forge map`, `forge resume`
+
+**v1.0** — Current
+- 21 CLI commands covering the full development lifecycle
+- 3 framework adapters (Next.js, React + Vite, Django)
+- Framework-aware prompts via pluggable adapter system
+- `forge start` — auto-detect and launch dev server
+- `forge push` — push commits + tags to GitHub
+- `forge fix --image` — screenshot-based bug fixing
+- Auto-push to GitHub after `forge auto` and `forge resume`
+- Graceful shutdown with automatic progress save
+- Config validation with actionable error messages
+- Token expiry handling with auto-retry
+
+**v1.1** — Next Up
+- **Flutter adapter** — Dart support with widget-based design previews
+- **Vue.js / Nuxt adapter** — Vue 3 + Composition API + Nuxt 3 SSR support
+- **Svelte / SvelteKit adapter** — Svelte 5 with runes and SvelteKit routing
+- **Test generation phase** — auto-generate unit and integration tests after build (Vitest, pytest, Flutter test)
+- **Custom adapter plugin API** — drop a JS file in `.forge/adapters/` to add your own framework
+
+**v1.2** — Planned
+- **Multi-provider support** — swap Claude for OpenAI, Gemini, or local models (Ollama) per agent
+- **Web dashboard** — browser-based sprint monitoring with real-time build progress, token usage charts, and story diffs
+- **CI/CD integration** — GitHub Actions / GitLab CI pipeline generation, auto-run tests on PR, deploy previews
+- **Cost estimation** — token budget planning before sprint starts, per-story cost breakdown, spending alerts
+
+**v2.0** — Future
+- **Team collaboration** — multiple users can queue feedback on the same sprint, role-based permissions (lead reviews, dev builds)
+- **Monorepo support** — run separate pipelines for `packages/*` with shared dependency tracking
+- **Visual regression testing** — screenshot comparison between versions, flag UI drift automatically
+- **Database schema generation** — auto-generate migrations, seed data, and ERD diagrams from plan descriptions
+- **Accessibility audit phase** — automated WCAG checks after build, auto-fix common a11y issues
+- **i18n / localization** — generate translation keys and locale files from built UI, support RTL layouts
+- **Plugin system** — community-built pipeline phases (e.g., performance audit, API docs, Docker setup)
+- **Template library** — starter templates for common app types (SaaS dashboard, e-commerce, blog, landing page)
+
+<br/>
+
+## Contributing
+
+```bash
+git clone https://github.com/joeljohn159/forgeai.git
+cd forgeai
+npm install
+npm run build
+npm link                              # Makes 'forge' available globally
+```
+
+Make changes in `src/`, then `npm run build` to test.
+
+<br/>
+
+## License
+
+MIT
+
+<br/>
+
+---
+
+<p align="center">
+  Built by <a href="https://github.com/joeljohn159">Joel John</a>
+</p>