WingFoil

WingFoil

A structured harness for AI-assisted software development, built to make it deterministic.

WingFoil solves a critical problem: as your software project grows, AI agents lose consistency and control. Context gets scattered, conventions drift, and decisions made in one session don't carry forward to the next.

WingFoil centralizes your project's memory, DNA, and directives in a structured, git-backed format — giving both humans and AI agents a shared source of truth.

*The first example, docs/examples/01-first-project, recorded from docs/examples/01-first-project/demo.tape. The example checks its own results, and the recording stops if a check fails, so if WingFoil stops matching the example the recording fails instead of going stale.*

---

The Problem

When using AI agents to write software, you face growing friction:

• Context collapse: Large context windows and full codebase scans become expensive and noisy
• Convention drift: Agents don't respect established patterns unless you re-explain them every session
• Decision scatter: Architectural decisions, patterns, and constraints live in Slack, old docs, or nowhere
• Governance gaps: No way to enforce rules consistently across human developers and AI agents

The larger the project, the worse the signal-to-noise ratio.

---

The Solution

WingFoil provides a structured, authoritative interface to your project:

• Project Memory — Git-backed storage for decisions, artifacts, and domain knowledge
• Project DNA — Structural map of modules, tech stack, and conventions
• Project Directives — Role-based rules that both humans and agents respect
• Workflow State Management — Unified tracking and communication of project flow, progress, and blockers
• Interaction Layer — CLI for humans, MCP for agents

This keeps everything synchronized, so that two runs from the same specs and configuration can produce equivalent software: the goal the *Determinism Index* measures (see *Success Metric* below).

---

Who It's For

Alex, the Solo Developer Every new AI session forces you to re-explain context. WingFoil loads relevant info in seconds — no more context loss between sessions.

Sam, the Code Reviewer You're starting with AI for code review but aren't confident enough for full development yet. WingFoil lets you enforce quality standards and gradually expand AI usage as you gain confidence.

Jordan, the Team Developer You don't know what conventions your tech lead has defined, and agents ignore team rules. WingFoil keeps everyone aligned on directives, decisions, and project state without constant manual updates.

Morgan, the Tech Lead You need agents to follow the team's rules automatically, not invent new ones. WingFoil encodes governance once; it auto-loads for every agent. It also keeps the whole team synchronized on progress and blockers.

Casey, the Manager You need visibility into decisions and methodology. WingFoil provides an audit trail, queryable knowledge base, and real-time tracking of project state.

---

Key Features

Five Pillars — status in 0.3

• ✓ Project Memory — Git-backed documents (tasks, ADRs, decision-logs, bugs, specs…) with per-type state machines, approval gates and an audit trail (shipped: create, search, submit, approve, reject, deprecate, history; new in 0.3: amend, park, work-in-progress limits)
• ✓ Project DNA — Structured config: modules, tech stack, team & roles, resource paths (shipped: show, set, add, update, remove)
• ✓ Project Directives — Role-scoped rules: six built-in templates installed by init, your own custom directives, role assignments (shipped in 0.2)
• ✓ Interaction Layer — CLI for humans and agents; MCP server for agents with read-only Resources and one Prompt per role (shipped); agent execute launches Claude Code or Codex CLI on a Memory element with its context assembled and checked first, and records the run (new in 0.3)
• ✓ Workflow State Management — start, follow and end workflows: the next step and its role, the open workflows, approvals routed to the approver, checkpoints (new in 0.3). WingFoil records and routes the steps; people and agents carry them out

CLI at a glance

Every command accepts --format console|json|yaml and ends with exit code 0 (success), 1 (refused) or 2 (bad command line); every command that commits accepts --dry-run, except init. Full details: [CLI reference](docs/cli-reference.md).

For AI Agents

• ✓ MCP server (wingfoil mcp, stdio) — DNA, Memory and workflows as read-only Resources, the workflow state as wingfoil://workflows/-/next and wingfoil://workflows/-/status, plus a -session Prompt per role that embeds the role's directives; given an element and a state (a commit), the Prompt — and the Resource wingfoil://session/{role}/{element}/{state} — return the agent's execution context for that element
• ✓ Read-only by construction — the MCP surface has no Tools; changes go through the CLI, and approvals belong to a human holding the approver role
• ✓ [`docs/agents.md`](docs/agents.md) — the same knowledge as a document an agent can read from a link: what WingFoil is, the rules to follow, the CLI equivalent of every MCP Resource and Prompt

---

Getting Started

Installation

npm install -g wingfoil

This installs the wingfoil binary (Node.js 22.12+ required). Verify it:

wingfoil --version

Quick Start

Run this from the root of a git repository with a git identity configured (git config user.name / user.email).

1. Initialize WingFoil — scaffolds .wingfoil/ (DNA, Memory schema and templates, directives, workflows) and commits it:

$ wingfoil init --template Scrum

It also installs the built-in agent adapters (claude-code, codex-cli) under .wingfoil/agents/.

2. Name the project and register yourself as the approver — approvals need a team member holding the approver role, with your git email:

$ wingfoil dna set project.name --value "My Project"

{ "key": "project.name", "value": "My Project" } $ wingfoil dna add team.members --value "Ada Lovelace" --entry-email ada@example.com --entry-roles approver,developer { "key": "team.members", "value": "Ada Lovelace" }

3. Create a task, write it, submit it:

$ wingfoil memory add --type task --title "My first task"

{ "id": "task-001-my-first-task", "path": "docs/memory/task/task-001-my-first-task.md" } $ wingfoil memory submit task-001-my-first-task { "id": "task-001-my-first-task", "path": "docs/memory/task/task-001-my-first-task.md", "from": "draft", "to": "pending" }

(Write the task's body in the file before submitting — the submit commit records it.)

4. Approve it — the commit records who approved and why:

$ wingfoil memory approve task-001-my-first-task --reason "Scope is clear."

{ "id": "task-001-my-first-task", "path": "docs/memory/task/task-001-my-first-task.md", "from": "pending", "to": "approved" } $ git log -1 --format=%B wf(task): approve task-001-my-first-task [pending → approved]

Approver: Ada Lovelace (approver) Reason: Scope is clear.

WingFoil-Version: 0.3.0 (6ca54978a01dc29c81e395d363efcdeac8a513fd)

5. Connect your AI agent — for Claude Code, add .mcp.json at the repository root:

{ "mcpServers": { "wingfoil": { "command": "wingfoil", "args": ["mcp"] } } }

Documentation

---

Value Proposition

For developers and teams already using AI agents WingFoil is built to make the development process deterministic, and measures how far it does By centralizing memory, conventions, and directives — keeping them synchronized across all actors

Success Metric: Determinism Index

Two independent development runs from the same specs + WingFoil config using different AI agents should produce substantially equivalent software, with all team members and agents maintaining shared understanding of project workflow state, progress, and alignment. This is the goal WingFoil is measured against, not a property it already has.

*Substantially equivalent* means behaviourally equivalent: both codebases pass the same acceptance contracts. The Index has three components:

• Input — the context WingFoil assembles is identical for identical inputs: guaranteed, by tests.
• Process conformance — the run followed its workflow (well-formed commits, legal transitions, phase outputs present, roles respected): measured on every run.
• Outcome equivalence — the two runs' software behaves the same: the agents and models write the code, so this is measured, never promised.

---

What Comes Later

0.4 — Interaction Layer + Polish (planned): adopting WingFoil in a project already under way (init --mode infer, dna infer, memory import, audit), MCP Tools through whic