WingFoil

Contributing to WingFoil — through Memory, not (only) code

Version: 1.6 · Date: 2026-10-17

WingFoil is a harness for AI-assisted software development, built to make it deterministic. It manages its own development the same way it asks other projects to (dogfooding): every change flows through Project Memory — typed, versioned, git-backed artifacts — under an explicit Workflow and Directives. This document explains how you contribute to that flow.

The core idea: you contribute intent and decisions as Memory artifacts, and an AI agent turns them into delivered work. You do not need to write the code, the tests, or run wingfoil yourself.

This is the demonstration of WingFoil’s thesis: structured, AI-mediated contribution is more reproducible than an unstructured pull-request inbox. Decision recorded in dl-020-contribution-model.

What you can contribute

Instead of a code pull request, you file one of the five base Memory documents, each via its capture (“ingest”) workflow:

You want to… File a… Via workflow Lands as
report a defect Bug bug-ingest docs/04_memory/bugs/{id}.md
propose a product/process decision Decision-Log (DL) decision-log-ingest …/design/dls/{id}.md
propose an architectural decision ADR adr-ingest …/design/adrs/{id}.md
define a shared format/schema/API Tech-Spec release-planning (identify-specs) …/design/specs/{id}.md
request a feature, or change the vision Change-Proposal vision-change …/change-proposals/{id}.md

Each artifact starts at draft, then moves to its first working state (open / in-discussion / pending / in-analysis) so there is content to discuss. A change-proposal names its impact on every layer below the vision (features, user stories, BDD, SARD requirements, delivered work), “no impact” included, and its work is finished once a release is scheduled to carry it (dl-132). From there:

An AI agent then implements the work under the dev-loop (TDD + BDD, code-review/code-quality directives).

How to contribute (today)

The wingfoil CLI ships (npm wingfoil) and keeps the bookkeeping of a workflow — wingfoil workflow start bug-ingest records the run and wingfoil workflow next names its next step — but it does not carry out the steps, so the ingest workflows are run by a maintainer or an agent. The current path is:

  1. Open a GitHub issue with one of the two issue forms (.github/ISSUE_TEMPLATE/):
    • Bug report, for a defect. Its fields are the bug element’s: the issue title is the bug’s title, then severity, the WingFoil version (release-origin), Summary, Steps to Reproduce, Expected Behavior, Actual Behavior and Notes. bug-ingest’s capture copies every answer except two, which it maps: the title loses its bug: prefix, and the installed version you give (wingfoil --version, e.g. 0.3.0 (<commit>); the commit part is dropped) becomes the release-origin id of the release that published it (v0.3 for a minor’s build such as 0.3.0, v0.2.2 for a patch release).
    • Proposal, for a product or process decision: the context, the options you see and the one you prefer, which decision-log-ingest’s capture records as the decision-log’s Context, Decision and Rationale (the title loses its proposal: prefix). A feature request uses this form too: it changes the vision, so the maintainer captures it as a change-proposal through vision-change instead (dl-132, dl-163).

    Blank issues are off. Questions go to Discussions, and a vulnerability goes through SECURITY.md, never into a public issue.

  2. A maintainer or agent captures it as the matching Memory artifact through the ingest workflow, recording you as its contributor and the issue’s URL beside it (Credit, below).
  3. You are kept in the loop as it is ratified and delivered.

A pull request is welcome too: its template (.github/PULL_REQUEST_TEMPLATE.md) asks for the Memory element the change implements, as the traceability directive requires. Everyone follows the Code of Conduct. CONTRIBUTING.md is the short pointer to this document that GitHub shows contributors (dl-127).

You (or an agent on your behalf) can start an ingest workflow yourself with wingfoil workflow start <name> and follow it with wingfoil workflow next; its steps are still carried out by hand.

Contributor setup — the WingFoil build that manages this repository

WingFoil’s own Memory, DNA and workflows are read through a published, pinned WingFoil build (dl-095); the Memory operations that write a commit run on the code build compiled from your checkout (npm run build, then node dist/cli.js …), as the wingfoil-cli directive (.wingfoil/directives/custom/wingfoil-cli.md) states. It is declared in package.json as the devDependency "wingfoil-released": "npm:wingfoil@<version>", so a clone needs one command and no build step:

git clone <this repository> && cd <it>
npm ci                                   # installs the pinned build with everything else
npm run -s wingfoil -- --version         # prints the pinned version
npm run -s wingfoil -- memory search --type bug

Run it as npm run -s wingfoil -- …, not npx wingfoil: this package is itself named wingfoil, and once npm run build has produced dist/, npx wingfoil runs that build instead. -s keeps npm’s own banner off standard output, so --format json stays parseable.

The MCP server. The repository’s .mcp.json registers the pinned build’s server (dl-026), so an agent session opened at the repository root reads DNA, Memory and workflows through it with no setup:

{ "mcpServers": { "wingfoil": { "command": "node", "args": ["node_modules/wingfoil-released/dist/cli.js", "mcp"] } } }

.mcp.json is the Claude Code format. The server itself is plain MCP over stdio, so any other MCP client registers the same thing: command node, arguments node_modules/wingfoil-released/dist/cli.js mcp, working directory the repository root (the server resolves the configuration from the git root). Use an absolute path to cli.js if your client starts servers from another directory. npm run check:mcp starts the registered server and checks that it is the pinned version and advertises the expected channels.

The pin moves forward only, to published builds, one commit per switch (dl-095 Q3): at the start of each release’s planning (release-planning’s advance-pinned-build step) and after every published patch.

Credit — you are credited for the AI-generated work derived from your contribution

Attribution in WingFoil rides on git identity: every state-change commit records its author and timestamp as the audit trail (adr-006-git-identity-role-based-authz). That records who made the change. It does not, by itself, capture whose idea it was when an AI agent — not the contributor — authors the commits.

So the contribution model layers a credit convention on top of git identity (it does not replace it, and it never rewrites git history):

This keeps credit machine-visible and git-versioned, consistent with WingFoil’s single-source-of- truth model — no external contributor database, no commit rewriting.

Ground rules

Pointers

This site is open source. Improve this page.