SpecForge.AI

SpecForge.AI is an early-stage developer tool for running structured SDD workflows inside VS Code.

The project focuses on governing how AI-assisted development happens, not only on generating code. It introduces explicit phases, persisted artifacts, human checkpoints, regressions, timeline tracking, and a minimal execution core that can evolve into a full MCP-backed workflow system.

Status

This repository is currently a working foundation, not a finished product.

Implemented today:

• documented phase-1 workflow and persistence model
• .NET domain core for workflow rules and transitions
• local YAML persistence for state.yaml and branch.yaml
• local timeline and artifact generation via a workflow runner
• minimal VS Code extension scaffold
• user story explorer over .specs/us/
• minimal MCP server over stdio
• OpenAI-compatible phase provider infrastructure

Not implemented yet:

• full PR integration
• richer prompt inspection UX, diffing, and effective prompt visibility

Features

• Canonical user story workflow:
  • capture
  • refinement
  • technical_design
  • implementation
  • review
  • release_approval
  • pr_preparation
• Phase execution semantics are explicit:
  • automatic/system-driven phases: capture, technical_design, implementation, review, pr_preparation
  • human checkpoint phases: clarification, refinement, and release_approval
• Explicit approval gates and regression rules
• Local workspace persistence under .specs/us/us.<us-id>/
• Human-readable artifacts in Markdown
• Shared audit trail in timeline.md with actor and UTC timestamp for user actions
• Explicit artifact operation logs such as phases/01-spec.ops.md when a developer asks the model to operate over the current spec
• Technical state in YAML
• Minimal workflow automation through a .NET runner
• Minimal VS Code extension for creating, importing, listing, and opening user stories

Repository Layout

.
├── doc/                       # Product, architecture, workflow, templates, roadmap
├── media/                     # VS Code extension assets
├── src-vscode/                # VS Code extension source
├── src/SpecForge.Domain/      # Workflow domain and application core
├── tests/SpecForge.Domain.Tests/
├── .specs/                    # Runtime user story persistence in the workspace
├── package.json               # VS Code extension manifest
└── SpecForge.AI.slnx          # .NET solution

Architecture

The current design is intentionally split into layers:

• VS Code extension:
  • user-facing commands and explorer UI
  • workspace interaction
  • artifact opening and local user story discovery
• Domain and application core:
  • workflow rules
  • approval requirements
  • regression validation
  • local artifact and YAML persistence
  • minimal workflow runner
• MCP layer:
  • stdio MCP server with initialize, tools/list, and tools/call
  • orchestration boundary between extension and backend execution
  • base for future provider abstraction and richer backend execution
  • workflow file tools for listing, adding, and reclassifying context files versus user story info

See the detailed design documents in:

• doc/product-vision.md
• doc/architecture.md
• doc/workflow-canonico-fase-1.md
• doc/spec-schema-fase-1.md
• doc/mcp-contract-fase-1.md
• doc/implementation-plan.md

Installation

Prerequisites

• .NET SDK 10
• Node.js 23+
• npm 10+
• VS Code 1.100+

Clone

git clone <your-fork-or-repo-url>
cd SpecForge.AI

Install Node dependencies

npm install

Build the VS Code extension sources

npm run compile

The npm scripts invoke the local TypeScript compiler entrypoint directly, so the extension and test builds do not depend on a global tsc.

Run .NET tests

dotnet test SpecForge.AI.slnx

Run TypeScript tests

npm run test:ts

Provider Configuration

By default, phase execution uses a deterministic local provider.

To enable an OpenAI-compatible provider:

export SPECFORGE_PHASE_PROVIDER=openai-compatible
export SPECFORGE_OPENAI_BASE_URL=https://api.openai.com/v1
export SPECFORGE_OPENAI_API_KEY=<your-api-key>
export SPECFORGE_OPENAI_MODEL=gpt-4.1-mini
export SPECFORGE_CAPTURE_TOLERANCE=balanced
export SPECFORGE_REVIEW_TOLERANCE=balanced

For named routing across workflow phases, the extension can also send a profile catalog plus phase assignments:

{
  "specForge.execution.modelProfiles": [
    {
      "name": "light",
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "",
      "model": "llama3.1"
    },
    {
      "name": "top",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "<your-api-key>",
      "model": "gpt-4.1"
    },
    {
      "name": "review",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "<your-api-key>",
      "model": "gpt-4.1-mini"
    }
  ],
  "specForge.execution.phaseModels": {
    "defaultProfile": "light",
    "implementationProfile": "top",
    "reviewProfile": "review"
  }
}

With that setup, capture, clarification, refinement, technical design, release approval, and PR preparation use defaultProfile; implementation can be routed to the strongest model; review can stay on the same model or use a separate middle tier. If no named profiles are configured, SpecForge.AI keeps using the legacy single baseUrl/apiKey/model path.

For local testing with Ollama:

export SPECFORGE_PHASE_PROVIDER=openai-compatible
export SPECFORGE_OPENAI_BASE_URL=http://localhost:11434/v1
export SPECFORGE_OPENAI_API_KEY=ollama-local
export SPECFORGE_OPENAI_MODEL=llama3.1
export SPECFORGE_CAPTURE_TOLERANCE=balanced
export SPECFORGE_REVIEW_TOLERANCE=balanced

The provider targets the OpenAI-compatible chat completions shape, so OpenAI and Ollama can share the same backend integration path. For clarification, the backend supports three tolerance levels: strict, balanced, and inferential. This value is sent as SPECFORGE_CAPTURE_TOLERANCE, adds explicit guidance to the clarification prompt, and maps clarification-only temperature as follows:

• strict -> 0.0
• balanced -> 0.2
• inferential -> 0.4

For review, the backend supports the same three levels through SPECFORGE_REVIEW_TOLERANCE. It adds explicit review guidance to the prompt and maps review-only temperature using the same values:

• strict -> 0.0
• balanced -> 0.2
• inferential -> 0.4

temperature is not exposed as an independent extension setting. The supported knobs are clarificationTolerance and reviewTolerance, and the provider derives temperature from them for the corresponding phases only.

Before executing real provider-backed phases, initialize the repository prompt set through the MCP backend. This materializes .specs/config.yaml and .specs/prompts/, and the engine will fail fast if the required prompt files are missing.

Usage

Domain core

The .NET core already supports:

• creating a user story root
• persisting state.yaml and branch.yaml
• validating explicit user-story categories against the repo catalog in .specs/config.yaml
• advancing to the next valid phase
• approving approval-required phases
• creating the work branch metadata when the refinement/spec phase is approved using <kind>/us-xxxx-short-slug
• generating minimal phase artifacts and timeline entries
• initializing versioned repo prompts under .specs/prompts/
• requiring prompt initialization for real provider-backed phase execution
• composing effective phase prompts from repo templates and runtime artifacts

VS Code extension

The extension currently provides:

• a SpecForge.AI activity bar view
• a sidebar webview with embedded user-story intake
• an optional guided wizard in that intake to collect the minimum and recommended user-story information before creating the workflow
• a single high-contrast Create User Story empty state in the sidebar
• a compact header action in the sidebar to initialize or reinitialize .specs/prompts/
• per-user starred user stories persisted on disk inside the workspace
• automatic reopening of the starred user story in workflow view for the same local user
• a default navigation focus on active user stories and active workflows
• a workflow webview opened directly from a user story click
• per-phase detail inside the workflow view with artifact preview
• per-phase prompt access inside the workflow view when the selected phase exposes execute or approve templates
• user-story file management inside the workflow view, split between context files and user story info
• only context files are injected into provider-backed runtime context; user story info remains attached to the workflow without entering the model prompt by default
• MCP tools to list, add, and reclassify workflow files so models can attach repo context without going through the VS Code UI
• clarification guidance inside the workflow view inviting the user to add more repo context when the model gets blocked
• local context-file suggestions during clarification using two default-enabled strategies: keyword heuristics and repo-neighborhood discovery
• a feature flag to disable clarification context suggestions without removing manual context-file intake
• persisted runtime status per user story so MCP clients can see whether a long-running phase generation is still active
• duplicate generate_next_phase requests are rejected while the same user story already has a live runtime operation
• inline audit stream sourced from timeline.md
• play / pause / stop controls for workflow execution
• unified workflow/sidebar state colors documented in doc/workflow-visual-states.md
• Create User Story
• Import User Story
• Initialize Repo Prompts
• Open Prompt Templates
• Open Main Artifact
• Continue Phase
• explicit feature / bug / hotfix selection when creating or importing a US
• explicit category selection from the repo category catalog when creating or importing a US
• user-story intake guidance that distinguishes minimum information from recommended extra detail
• extension settings for provider, connection, API key, model, watcher, and attention notifications
• visible configuration warnings with a direct link to extension settings when the active provider is not fully configured
• auto-refresh watcher over .specs/us/** when enabled
• lightweight TypeScript tests for explorer grouping, detail rendering, MCP client payload/parsing, and extension command wiring

Current limitation:

• stop is best-effort: it cancels the local MCP backend process for the workspace, but it is not yet a durable job-control protocol
• the extension still does not provide a richer prompt editor, diffing, or effective prompt inspection UX
• the sidebar does not yet expose completed user stories through a visibility switch or search; for the MVP it stays focused on active work
• workflow execution controls such as Play and Continue remain disabled until the active provider configuration is complete

User-story intake guidance

SpecForge.AI now helps both the user and any MCP-driven model understand what a usable user story should contain.

Minimum information:

• who or what is affected
• what change is requested
• how success will be validated

Recommended detail:

• expected scope or touched areas
• relevant repo context or likely files
• constraints, out-of-scope notes, or extra reviewer context

The sidebar intake keeps the original freeform source box, but also offers an optional guided wizard that turns those answers into structured source text before the user story is created.

Spec baseline

The refinement phase is the functional checkpoint of the workflow. Its output is no longer treated as lightweight prose; it is the approved baseline spec for downstream work.

Current expectation for 01-spec.md:

• inputs
• outputs
• business rules
• edge cases
• errors and failure modes
• constraints
• acceptance criteria
• explicit ambiguities and approval questions

This reduces approval fatigue versus forcing the user to approve both a weak refinement and a separate technical design by default. The technical design remains important, but phase 1 now treats it as a derived execution artifact rather than as a mandatory blocking checkpoint in every story.

The exact required schema for that artifact lives in doc/spec-schema-fase-1.md. The approval path now validates that schema before the spec baseline can be frozen.

Workflow readability

The workflow view intentionally distinguishes between:

• automatic phases that the system can execute when the provider and prompts are ready
• user-driven checkpoints that require explicit approval before the next transition

Today the canonical checkpoints are refinement as the spec baseline and release_approval as the final human release gate. The graph and phase detail make this visible so the operator can see where the workflow will stop and wait for attention.

Running the extension locally

1. Open the repository in VS Code.
2. Run npm run compile.
3. Start the extension from the VS Code Extension Development Host workflow.
4. Use the SpecForge.AI activity bar view.

Extension settings

The extension contributes these settings:

• specForge.execution.provider
• specForge.execution.baseUrl
• specForge.execution.apiKey
• specForge.execution.model
• specForge.execution.modelProfiles
• specForge.execution.phaseModels
• specForge.execution.clarificationTolerance
• specForge.execution.reviewTolerance
• specForge.ui.enableWatcher
• specForge.ui.notifyOnAttention
• specForge.features.enableContextSuggestions

Persistence Model

Each user story lives under:

.specs/us/us.<us-id>/

Typical contents:

.specs/us/us.US-0001/
  us.md
  clarification.md
  state.yaml
  branch.yaml
  timeline.md
  phases/
    01-spec.md
    02-technical-design.md
    03-implementation.md
    04-review.md

Per-user VS Code workspace preferences are stored separately:

.specs/users/<local-user>/vscode-preferences.json

This preference file currently stores the starred user story that should reopen automatically for that same developer. It is ignored by git by default, so several developers can share the same workspace without overwriting each other's VS Code UX state.

clarification.md is persisted separately from us.md. The workflow UI keeps the accumulated clarification questions there, while us.md remains the stable source artifact instead of being rewritten with each clarification round.

Roadmap

Phase 1 foundation

• define workflow, persistence, and templates
• implement workflow domain rules
• implement local YAML persistence
• implement minimal workflow runner
• create minimal VS Code extension scaffold

Next

• wire the VS Code extension to the local workflow runner
• introduce a stable application/MCP boundary between UI and backend
• replace placeholder artifact generation with real phase execution
• refresh the explorer and open generated artifacts after workflow actions
• add approval and user-story detail actions to the extension
• add an OpenAI-compatible provider layer usable with OpenAI or Ollama
• export versioned prompts per phase into .specs/prompts/
• require repo prompt initialization before executing real providers
• compose effective per-phase prompts from repo templates plus runtime context
• expose explicit phase regression through domain, MCP, and VS Code
• implement safe restart from source and archive superseded derived state
• derive branch names from explicit US kind plus short slug
• validate explicit US categories against a repo-configured catalog
• group the VS Code explorer by user-story category
• open user stories into a workflow view with phase detail and timeline audit
• add extension settings for provider connection and watcher behavior
• add watcher-driven refresh, attention notifications, and playback controls with best-effort stop
• keep the default navigation focused on active user stories and workflows for the MVP
• persist a per-user starred user story on disk and autoopen it when reopening the workspace
• suggest clarification-time context files through local heuristics and repo neighborhood, behind a default-enabled feature flag
• expose persisted runtime status so MCP clients can avoid duplicating long-running workflow executions
• finalize richer branch lifecycle rules and Git/PR metadata
• add richer phase detail UI and graph visualization
• add issue and PR preparation integration
• support customizable workflows and agent profiles
• add a switch to show completed user stories and workflows
• add sidebar search across user stories and workflows

MVP Roadmap

The current target is an MVP, not a feature-complete product.

MVP scope

• create and import user stories
• persist workflow state and artifacts under .specs/
• advance the canonical phase workflow with approvals
• expose the workflow through a local MCP backend
• support repo-initialized prompts and an OpenAI-compatible provider path
• support explicit regression to an earlier valid phase
• support safe restart from the original source
• support per-user starred user stories with automatic reopening

Post-MVP

• graph visualization and richer workflow observability
• prompt diffing and effective prompt inspection UX
• GitHub PR / issue integration
• customizable workflows and agent profiles
• completed user story visibility toggle in the sidebar
• user story and workflow search in the sidebar

Development

Useful commands:

npm install
npm run compile
dotnet test SpecForge.AI.slnx

The repository also contains local VS Code task files and tool manifests. Some of them may still reflect older local conventions and should not be treated as the primary source of truth over the documents in doc/ and the current codebase.

Contributing

This repository is still in early design and foundation stages. If you contribute:

• keep the workflow model explicit
• prefer persisted state over implicit conversational state
• avoid adding hidden environment-specific behavior
• update the design docs when you change workflow semantics

License

MIT