Turn messy client briefs, PDFs, and WhatsApp voice notes into client-approved scopes, defensible P80 estimates, and executable Jira/Linear sprint tasks.
π Live Interactive Demo β’ Core Workflow β’ Key Capabilities β’ Quick Start β’ 24/7 Deployment β’ Architecture
SpecForge eliminates the #1 cause of agency unprofitability and client disputes: unbounded scope creep and guesswork estimation.
Unlike generic document editors or raw chat interfaces, SpecForge enforces an immutable 11-stage delivery pipeline with strict human-in-the-loop verification, mathematical contingency modeling, cryptographic client sign-offs, and automated task dispatch.
Every project follows an auditable, deterministic lifecycle:
flowchart LR
A["1. Client Brief<br/>(Audio, PDF, Text)"] --> B["2. AI Extraction<br/>(Provenance & Citations)"]
B --> C["3. Human Review<br/>(Confirm/Reject Suggestions)"]
C --> D["4. Scope Freeze<br/>(Versioned Immutable Tree)"]
D --> E["5. Defensible Estimate<br/>(Rate Cards + P80 Contingency)"]
E --> F["6. Branded Proposal<br/>(Tokenized Read-Only Portal)"]
F --> G["7. Client Sign-Off<br/>(Cryptographic SHA-256 Seal)"]
G --> H["8. Task Generation<br/>(Epics, Stories & Checklists)"]
H --> I["9. Delivery Handover<br/>(Jira, Linear, GitHub, Trello)"]
I --> J["10. Change Control<br/>(Delta Impact Approval)"]
J --> K["11. Payment Tracking<br/>(Milestone Reconciliation)"]
style A fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px
style B fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5px
style C fill:#fef3c7,stroke:#f59e0b,stroke-width:1.5px
style D fill:#e0e7ff,stroke:#6366f1,stroke-width:1.5px
style E fill:#ecfdf5,stroke:#10b981,stroke-width:1.5px
style F fill:#f5f3ff,stroke:#8b5cf6,stroke-width:1.5px
style G fill:#fdf2f8,stroke:#ec4899,stroke-width:1.5px
style H fill:#f8fafc,stroke:#334155,stroke-width:1.5px
style I fill:#f0fdf4,stroke:#22c55e,stroke-width:1.5px
style J fill:#fff7ed,stroke:#ea580c,stroke-width:1.5px
style K fill:#eff6ff,stroke:#2563eb,stroke-width:1.5px
- Ingest client brief text, email chains, PDFs, DOCX specifications, and WhatsApp voice notes (up to 10 minutes).
- Automated speech-to-text pipeline preserves timestamps, raw verbatim transcripts, and uploaded assets.
- Extracts structured Personas, Core Features, Architectural Constraints, Risks, and Open Questions.
- Zero-Hallucination Provenance: Every AI-extracted item is linked to exact sentence offsets in the source text.
- Clear distinction between
AI_SUGGESTION(amber badge) andUSER_CONFIRMED(green badge) for human oversight.
- Hierarchical breakdown: Features β User Stories (
As a... I want to... So that...) β Acceptance Criteria. - Dedicated sections for explicit Assumptions (what is included) and Exclusions (what is strictly out of scope).
- Instant scope version freezing with full visual diff comparison (
v1.0vsv1.1).
- Role-based rate cards (Senior Architect, Full-Stack Engineer, UI/UX Designer, QA Automation).
- Feature-by-feature complexity sizing (
LOW,MEDIUM,HIGH) with configurable confidence factors. - Monte Carlo P80 Contingency Buffer: Dynamically adds 15%β25% contingency curves to defend agency margin against third-party API delays and revisions.
- Multi-currency rate card support with live conversion (USD, EUR, GBP, PKR, CAD, AUD).
- Tokenized, unguessable client-safe proposal URLs (e.g.,
/portal/{token}). - Clients leave pinned inline comments and request revisions without modifying underlying specifications.
- Cryptographic Audit Seal: Digital approval generates an immutable SHA-256 hash containing scope version, timestamp, client IP, and signer metadata.
- One-click task generation from approved acceptance criteria.
- Outbox event bus with exponential backoff and dead-letter queue (DLQ) support.
- One-way push integrations with deduplication headers to:
- Linear (Issues & Projects)
- Jira Cloud (Epics, Stories & Sub-tasks)
- GitHub Issues (Labels & Milestones)
- Trello (Cards & Checklists)
- When clients request modifications mid-sprint, SpecForge analyzes the delta impact on budget, timeline, and deliverables.
- Requires mutual client approval before task boards are modified, preventing silent scope creep.
- Strict organization boundary checks on every API route (
x-workspace-id). - Deny-by-default RBAC (
OWNER,ADMIN,MEMBER,GUEST). - AES-256 encryption for integration OAuth tokens and webhooks.
- Stripe billing event idempotency and reconciliation engine.
| Layer | Technologies |
|---|---|
| Frontend | Next.js 14+ (App Router), React 18, Tailwind CSS 3.4, Radix UI, Lucide Icons |
| Backend | Next.js Server Components, Server Actions & Route Handlers, Node.js 20+ |
| Data & ORM | Prisma ORM 5.22, PostgreSQL 16 (Compatible with Neon, Supabase, RDS) |
| Validation | Zod 3.23 (Strict server-side runtime schemas) |
| Security | SHA-256 Digital Signatures, AES-256 Secret Storage, NextAuth.js JWT, Strict Content-Security-Policy |
| Testing | Jest 29, Playwright 1.65 (Cross-browser E2E) |
| Observability | Structured JSON logging, Health Probes (/api/health/live, /api/health/ready), Circuit Breakers |
- Node.js
20.xor later - npm or pnpm
- PostgreSQL database (or local Docker container)
git clone https://github.com/MTLab1122/SpecForge.git
cd SpecForgenpm install --ignore-scriptsCopy the template and provide your database connection:
cp .env.example .env.localEdit .env.local:
DATABASE_URL="postgresql://postgres:password@localhost:5432/specforge?schema=public"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-32-byte-hex-secret-here"
ENCRYPTION_KEY="0123456789abcdef0123456789abcdef"npx prisma generate
npx prisma db pushnpm run devVisit http://localhost:3000 to access the interactive dashboard.
SpecForge is designed for uninterrupted 24/7 high availability across serverless edge networks, containers, or dedicated cloud VMs.
The fastest path to zero-maintenance 24/7 global availability:
- Import your repository into Vercel.
- Attach a managed PostgreSQL database (e.g. Neon, Supabase, or Vercel Postgres).
- Set the following Environment Variables in the Vercel dashboard:
DATABASE_URLNEXTAUTH_URL(https://your-domain.com)NEXTAUTH_SECRETENCRYPTION_KEY
- Deploy! Vercel handles SSL, CDN edge caching, and 99.99% 24/7 availability automatically.
Run a fully self-contained production stack with automatic restart policies:
# 1. Start SpecForge App and PostgreSQL with auto-restart on reboot/crash
docker compose up -d --build
# 2. View running containers
docker compose ps
# 3. Check live application logs
docker compose logs -f app- Uptime Assurance:
restart: alwaysensures the service recovers instantly from host reboots or unexpected process termination. - Built-in Healthcheck: Docker continuously polls
/api/health/liveto guarantee container liveness.
For high-traffic production environments on Ubuntu/Debian/AWS EC2:
# 1. Install PM2 globally
npm install -g pm2
# 2. Build the application
npx prisma generate
npm run build
# 3. Launch SpecForge in multi-core cluster mode
pm2 start ecosystem.config.js
# 4. Configure PM2 to restart automatically on system reboot
pm2 startup
pm2 saveSpecForge provides native health probes for cloud load balancers and uptime monitors (e.g., BetterStack, Datadog, UptimeKuma):
| Endpoint | Method | Purpose | Response |
|---|---|---|---|
/api/health/live |
GET |
Container liveness check | {"status":"ALIVE","uptimeSeconds":136} |
/api/health/ready |
GET |
Readiness check (DB + 12 downstream services) | {"ready":true,"status":"HEALTHY","checks":{...}} |
/api/v1/reliability/slo |
GET |
Real-time SLO & error budget metrics | {"availability":"99.95%","errorBudget":100} |
/api/v1/platform/feature-flags |
GET |
Workspace feature-flag engine | Returns active flags, A/B variants & rollouts |
Run the comprehensive master verification suite before any production release:
# Run master launch-readiness verification (49 automated checks)
node scratch/verify-launch-readiness-master.mjs
# Run phase 5 modular architecture verification (124 tests)
node scratch/verify-phase5-modular-architecture.mjs
# Run full TypeScript static analysis
npm run typecheckAll 49 quality, security, and invariant checks pass 100% Green.
SpecForge is licensed under the MIT License.