Operating manual
You are working in the software repository in your current directory, one request at a time.
- Each request is a new session. Nothing carries over from one request to the next except the repository itself: what is not written in it is gone.
- The project is described in
README.md. Read it before you start. - Work inside this repository. Whatever you leave in its working tree is committed for you when the request ends; you may also commit yourself.
This arm
This project is managed with WingFoil, installed as the command wingfoil. Always call it that way, never npx wingfoil, which would fetch a different version. This section follows WingFoil's guide for AI agents, release 0.3.1, and says below where this arm departs from it.
This file is your operating manual, the same text under every agent: you read it as CLAUDE.md under Claude Code and as AGENTS.md under Codex. WingFoil's MCP server, wingfoil, is configured for you: under Claude Code in the session's MCP configuration, under Codex in Codex's config.toml. Do not edit this file, nor write another agent's.
How WingFoil works:
- The project's shared knowledge is in the repository: its documents (tasks, decisions and others) under
docs/memory/, and the rules for each role. - A document's state is the
status:line of its frontmatter. It changes only through WingFoil's verbs, and each verb makes one git commit. The verbs act only on committed documents: create one withwingfoil memory add, never by copying a file. - The project's work follows a workflow. WingFoil records and routes it, and does not carry out its steps: you do. The setup opened an instance of the workflow
sw-life-cycle, at its delivery, for the first request; each later request opens its own, as below.
Following the workflow
For each request, in this order:
- Where the work stands. Run
wingfoil workflow status, thenwingfoil workflow next. The next step names its role, that role's rules, the document it works on, what it still lacks, and the exact command each of its actions expects. - A new instance for a new request. If the next step is
sw-life-cycle.sunset, the open instance's delivery is done: this request needs an instance of its own. Runwingfoil workflow start sw-life-cycle --title "<the request, in a few words>", thenwingfoil workflow finalizetwice (this project is already past its inception and specification), thenwingfoil workflow nextagain. - Act in the step's role, with its context. Read it through the command line: the role's rules with
wingfoil directives list --role <role>, then each file it lists; the decisions already taken withwingfoil memory search --type decision-log --status approved; the document the step works on, its file underdocs/memory/, and what it still lacks, fromwingfoil workflow next. WingFoil's guide gives the same context through its MCP server, as the Prompt<role>-sessionand the resourcewingfoil://session/<role>/<type>:<id>/<commit>; you need not read them through the MCP server. - Every request has its task. Before you build, the request needs a task of its own, submitted. If the step asks for one, add it with the command
nextprints. If it does not (the step counts an earlier request's task), or that command is refused, add it without--workflow:wingfoil memory add --type task --title "<the request, in a few words>", write in it what the request asks, and runwingfoil memory submit <id>before you build. - Do the step's work, and record its outcome as the step asks: run the commands
workflow nextprints, exceptwingfoil memory approve, which only the approver's reply allows (see Approvals below); write what you did in the document they create, and move it only with the verbs. WingFoil reads, from the documents as committed, that the step is done; whennextsays a step isfinalizable, record it withwingfoil workflow finalize. - At a gate, finish the work first. When a step needs an approval (
nextsayshuman needed), complete the request's work before you ask: the code written, its tests passing, the document updated and submitted. Then end your message with the request "Please approve <id>." for each documentnextlists, and stop. A statement that the work waits for an approval is not a request: nobody answers it. - Until the delivery is recorded. Run
wingfoil workflow nextagain after each step, until the request's delivery is recorded.
General rules:
- Change a document's state only through the verbs: never edit the
status:line of a document, nor write awf(...)commit by hand. - Do not invent document types or roles that the configuration does not declare.
- If a
wingfoilcommand refuses, do not work around it: an exit code 1 is a rule speaking. Read itserror:line, report it, and do not edit files to get past it. An exit code 2 means your command line is wrong: fix it and run it again.
Where this arm departs from the guide
- Starting a workflow. The guide starts or ends a workflow only when asked. Here the setup opened the first instance, and the rule A new instance for a new request asks you to open one for each later request: on this release's Kanban workflow an instance's delivery runs once.
- A task for every request. The guide records what each step's evidence asks for. Here every request gets its own task, as the rule Every request has its task says, even when an earlier request's task already meets the step's evidence, so that its review has a document to approve.
- Configuration. The guide lets an agent change the project's configuration, through WingFoil's verbs or by committed edits under
.wingfoil/. Here the configuration belongs to the scenario: never edit a file under.wingfoil/, and do not use thednaordirectivecommands that change it. - Approvals. The guide says an agent never approves or rejects. In this benchmark the decision is never yours: it is the reply of a fixed approver, and you only carry it out, which is why your git identity holds the approver role, unless the project names another approver (below). You never approve on your own initiative, and you never run the approver's other verbs:
wingfoil memory amend,wingfoil memory reject,wingfoil memory rekeyorwingfoil memory deprecate. If the reply is "Approved. Proceed.", runwingfoil memory approve <id> --reason "Approved. Proceed."for each document you asked about, then continue with the workflow's next step. Any other reply is not an approval: do not approve on it, say that the approval is still missing, and stop. In a project whose.wingfoil/dna.yamlnames another member as its approver, the paragraph above does not apply: your identity holds no approver role, and that member's verdict is carried out for you: a reply that gives it ("Approved by …" or "Rejected by …") has already been recorded by her. Check the document's state withwingfoil memory search, and continue from it; never runwingfoil memory approveorwingfoil memory rejectyourself.