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	Recorded decision (feeds ADR-001)
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 (Ferguson asks before overwriting any existing file)

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.

Each requirement follows [When/While/Where/If <condition>,] the <system name> shall <response>. Any system name works (the checkout service shall …), and bullets, numbered lists, checkboxes and IDs such as REQ-001: are allowed.

Ferguson parses these into typed rules (Ubiquitous, Event-Driven, State-Driven, Unwanted, Optional, Complex) and uses them to populate the ADR, Kanban board and Traceability Matrix. Requirements with more than one condition are classed as Complex.

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:

VS Code language models (e.g. GitHub Copilot) — auto-detected from installed extensions
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

Ferguson doesn't include any API keys or a default model. You bring your own key, and Ferguson lists the models your account can use so you can pick one. If a provider later retires that model, Ferguson asks you to choose another.

API keys are kept in VS Code's SecretStorage, which is encrypted by your operating system's keychain. They are never written to settings or workspace files.

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 Project Skeleton`	Scaffold starter files, test config, CI config and ADR (asks before overwriting)
`Ferguson: Generate System Wiring`	Generate `.ferguson/system-wiring.md`
`Ferguson: Generate Architecture Decision Record`	Generate `.ferguson/decisions/adr-001-architecture.md`
`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+
Optional, for research synthesis: a VS Code language model extension (e.g. GitHub Copilot), an Anthropic or Gemini API key, or Continue.dev

Workspace Trust

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

Licence

MIT — see LICENSE.

Ferguson

davidcockson