Ferguson — Architecture Engine for VS Code

Ferguson is a VS Code extension that guides you through the full architectural design process before you write a single line of production code. It walks you through an 8-step wizard — from requirements to skeleton — and generates a set of living documents that coding agents (Copilot, Cursor, Claude) can use to understand and contribute to your project.

What It Does

Ferguson follows the Double Diamond design process, structured as an 8-gate wizard:

Step	Gate	Output
1	EARS Requirements	Parsed + typed requirements
2	Research Launchpad	AI-synthesised research notes
3	Tech Stack	ADR-001 architecture decision
4	C4 Model	Context → Container → Component diagram
5	Testing Strategy	Test config (Jest/Cucumber)
6	CI/CD Platform	`ci.yml` for GitHub/GitLab/Bitbucket
7	System Wiring	`.ferguson/system-wiring.md`
8	Generate	Full project skeleton + all artifacts

Generated Artifacts

When you complete all 8 gates, Ferguson generates:

Project skeleton — MERN, SvelteKit, or Next.js starter files
AGENT_STATUS.md — Machine-readable briefing for AI coding agents (tech stack, test methodology, CI checks, C4 summary)
.ferguson/system-wiring.md — Folder tree, data models, API endpoints, database schema
.ferguson/decisions/adr-001-architecture.md — Architecture Decision Record (Michael Nygard format)
.ferguson/kanban.md — Task board pre-populated from EARS rules and C4 components
.ferguson/traceability.md — Requirements → Components → Test files matrix
CI config — ci.yml / .gitlab-ci.yml / bitbucket-pipelines.yml

Getting Started

Install the extension
Open a workspace folder (or create one)
Run Ferguson: Start Architecture from the Command Palette (Ctrl+Shift+P)
Work through the 8-step wizard
Hit Generate on Step 8 to scaffold the project

EARS Requirements

Create an ears-final.md file in your workspace with requirements in EARS syntax:

The system shall allow users to register an account.
When a user submits invalid credentials, the system shall display an error message.
While the session is active, the system shall refresh the auth token every 15 minutes.
If a payment fails, the system shall notify the user and cancel the order.

Ferguson parses these into typed rules (Ubiquitous, Event-Driven, State-Driven, Unwanted, Optional, Complex) and uses them to populate the Kanban board and Traceability Matrix.

Research Launchpad

Create a research.yaml in your workspace to define topics for AI-assisted research:

- title: "SvelteKit vs Next.js"
  description: "Compare frameworks for this use case"
  url: "https://kit.svelte.dev/docs"
  tags: [framework, frontend]
  llm_fetch_prompt: "Compare SvelteKit and Next.js for a multi-user SaaS product. Focus on SSR, auth, and deployment."

Ferguson fetches the URL and uses your configured AI provider to synthesise the content, saving notes to .doublediamond/research/.

AI Provider Setup

Ferguson supports multiple AI providers for research synthesis. Run Ferguson: Select AI Provider from the Command Palette to choose:

GitHub Copilot — Auto-detected if the Copilot extension is active
Anthropic Claude — Enter your API key (stored in VS Code SecretStorage)
Google Gemini — Enter your Google AI Studio API key
Continue.dev — Connects to Continue's local OpenAI-compatible proxy

API keys are stored securely in VS Code's built-in SecretStorage and never written to disk.

Extension Settings

Setting	Default	Description
`ferguson.freakMode`	`false`	Strict gate enforcement — prevents advancing until the current gate passes
`ferguson.earsFilePath`	`ears-final.md`	Relative path to your EARS requirements file
`ferguson.researchPath`	`research.yaml`	Relative path to your research YAML
`ferguson.outputDir`	`.ferguson/`	Directory for generated artifacts
`ferguson.testMethodology`	`tdd`	Default testing methodology (`tdd`, `bdd`, `after`)

Commands

Command	Description
`Ferguson: Start Architecture`	Open Mission Control
`Ferguson: Select AI Provider`	Configure AI integration
`Ferguson: Generate AGENT_STATUS.md`	Generate agent briefing file
`Ferguson: Generate Kanban Board`	Generate `.ferguson/kanban.md`
`Ferguson: Generate Traceability Matrix`	Generate `.ferguson/traceability.md`

The Ferguson sidebar (activity bar) shows a live list of all architectural decisions made in the current workspace. Click Open Mission Control to jump to the main wizard.

Requirements

VS Code 1.90+
Node.js 18+ (for built-in fetch support)
An AI provider extension (optional, for research synthesis)

Workspace Trust

Ferguson respects VS Code's Workspace Trust model. Research URL fetching is disabled in untrusted workspaces.

Licence

MIT — see LICENSE.

Ferguson

davidcockson