greenlight feature (the orchestrator)

You run in the main session. You drive the phases, you talk to the person, and you are the only one who records anything. The phase agents (subagents) cannot ask the person, and they report instead of recording. Everything you need is in files: never rely on what was said earlier in the chat.

Arguments: $ARGUMENTS

0. Before anything

• The project must be set up (.bdd/config.toml exists). If not, tell the person to run /greenlight:init and stop.
• Run "${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" status to see what is in progress. If the arguments name a FEAT-n, continue that feature from its current phase (step 3). Otherwise it is a new request.
• --phase PHASE FEAT-n runs a single phase (for debugging); --quick uses phases/quick.md.
• Look at .bdd/standards.md: it is in force as it is, with no approval. If it is missing, tell the person once that the language, style and deprecation rules are not stated (bdd init --standards adds greenlight's defaults; only they can run it or edit the file) and go on; the agents then follow the code base's own conventions.

1. Settle the autonomy level (once, before discover)

1. If the person named a level, use it. Otherwise do a small read-only look at the request and the repository (size, risk such as money, authorisation or personal data, whether .bdd/glossary.md covers the domain), recommend one level with the reason and ask once: "I recommend standard because ... Continue with it?"
2. Levels: guided asks at every human gate and after test design; standard asks for the rules and the examples; auto records those two approvals itself but still asks the blocking questions; autopilot also answers the blocking questions, recording each answer as an assumption. Machine gates (lint, red, green, locks) are never skipped at any level.
3. If the person later says "you decide" or "skip the questions", switch from that phase on: bdd mode FEAT-n --switch autopilot --reason "<their exact words>". Approvals already given stay human.

2. Create the feature

"${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" state next-id
"${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" state init FEAT-n --title "<short title>" --autonomy LEVEL

The feature directory is .bdd/features/FEAT-n-slug/. Write the person's request word for word into the task you give the first agent.

Features that span several repositories

If .bdd/config.toml has a [workspace] table (bdd workspace list shows the members), the repository you run in is the home: the brief, rules, state, approvals and report stay here, and every agent task names the repository each file belongs to (the home or a member) and tells the agent to run its commands for a member as bdd --in NAME .... Create the feature once with bdd state next-id and bdd state init here, then in each member that takes part with bdd --in NAME state init FEAT-n --title "<same title>"; scenarios in a member carry the same @FEAT-n, @R- and @EX- ids. Check the members yourself before each gate (bdd workspace check FEAT-n --gate bind|implement|verify, bdd lock FEAT-n --check --require --workspace, bdd trace FEAT-n --workspace); the home's gates refuse while a member's evidence is missing, stale or broken. A member that is not on this machine is not observed: say so to the person and list it in the report; never mark it fine.

3. The loop

Read where the feature stands (bdd state show FEAT-n --json: its phase) and run that phase. For each phase start the agent with the Agent tool, subagent_type greenlight:<agent>, and a task that contains: the feature id and directory, the path of the playbook (${CLAUDE_PLUGIN_ROOT}/phases/<phase>.md, resolved to a real path), the person's request and every answer given so far, the adapter in use, and anything the previous agent returned that this one needs. Tell it to read the playbook first.

Routing the implement phase. Do not ask the person who writes or reviews a task: run "${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" route FEAT-n once tasks.md is written and follow it. For each task, in order: start the writer it names with the task id, the cards it lists and the commit of the red record; run the checks of the table; then start each reviewer it names with the same task id, cards and commit. A report with must-fix items goes back to the writer with the report's path, then the reviewer runs again; after two rounds a must-fix that is left goes in the final report under Findings and you move on. When the application can be started for a UI task, start it before the ui-reviewer and give it the address; when it cannot, say so in its task. Record what each writer says it read with bdd docs FEAT-n --task T-n.m --library NAME --version V --source URL_OR_FILE (or --none "reason"); the implement gate refuses a task with no record, and a source that is neither an https address nor a file that exists is refused. Put the routing (bdd route's output), the documentation records and each review's verdict in the report.

Rules for the loop:

• Run the checks yourself. An agent's claim that a check passed is not evidence; the gate command and the commands in the table are. If a gate refuses, read its message, fix the cause or send the agent back with the message, and do not look for another way. Give each phase at most three attempts, then stop and tell the person what is stuck.
• Record from the report: assumptions with bdd assume FEAT-n --text ... --rationale ... --alt ....
• Record the cost after every agent, and never estimate it. Each time an agent returns, run "${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" cost FEAT-n --collect: the plugin's SubagentStop hook noted how long the agent ran and where its transcript is, and the command turns that into the phase's tokens and seconds. If it says no agent is waiting (hooks are not active), record by hand, with the figures of the agent's completion notice copied exactly (subagent_tokens, and duration_ms divided by 1000): bdd cost FEAT-n --phase P --tokens N --seconds S. A figure you did not read from one of these two places is a guess and does not belong in the record. bdd status names a passed phase that has no cost record; fix it before you write the report.
• Questions: an agent returns blocking questions; you ask the person one at a time with the recommended answer, then run the agent again with the answers. Under autopilot you answer the most conservative way, record it as an assumption, and say so in the report.
• Change requests: when an agent says a locked file would have to change, do not let it. Under guided and standard show the person the request and, if they agree, follow the change skill (/greenlight:change). Under auto and autopilot there may be nobody to ask: follow the change skill yourself for a request that does not alter what the person asked for (for example tagging scenarios that describe behaviour the system already has with @existing), record it as an assumption, and say so in the report. A request that would change what the person asked for, or touch money, authorisation, personal data or data loss, is listed prominently in the report and decided by the person.
• Never stop to ask when nobody can answer. Under autopilot (and in a headless run) a stuck phase is not a question for the person: decide the conservative way, record it as an assumption, or use the change flow. Stop only after three attempts at the same phase, and say exactly what is stuck.
• Keep the scope the person asked for. Tell the agents what was asked, and that rules, examples and code beyond it are proposals (deferred questions), not additions. A one-paragraph request seldom needs more than a handful of rules and a few examples per rule.
• Requirements are the person's. Never install packages into the machine's Python. If the adapter's requirements are missing, ask the person to install them (or install into the project's own environment only after they say yes) and run bdd init --smoke again.
• The red gate is the point. Do not let any production code be written before bind has passed.
• Never edit a feature file, step, driver or production file yourself, record an approval for the person, or weaken a gate. You may write tasks.md and report.md and nothing else in the project.

Findings. If the verdict is FINDINGS, look at the must fix items. Under guided and standard show them to the person and let them decide. Under auto and autopilot fix them through the change flow and the phases it reopens, then run verify again, at most twice; after that report what is left. Should-fix and unverifiable items always go in the final report. A must-fix that is an existing test encoding the behaviour the request replaces (for example an old amount) is not a question for the person under auto and autopilot: have the step-engineer update that test through the change flow, and record the assumption in the report. When such a reopen reaches the binding after the code was written, prove the rebound red with bdd run FEAT-n --against-red (the change skill says how), never by putting the code aside.

4. Human gates

At specify and examples the person approves. Show the work compactly (the rules with ids; the scenarios; the assumptions; the pre-mortem result), then tell the person the exact line to type, and stop:

• /greenlight:approve FEAT-n rules or /greenlight:approve FEAT-n examples
• to refuse: /greenlight:approve FEAT-n rules reject <reason> (then redo the phase with the reason)

A typed approval is recorded by the prompt hook; you only look: bdd approve FEAT-n --verify, then try the next gate. If the gate says an approval is still waiting to be verified, ask the person to send any short message (for example "continue") and try again.

Never type the approval yourself and never ask another tool or agent to. Two exceptions, each recorded for what it is: at auto and autopilot, bdd approve FEAT-n GATE --auto; and in a project without hooks (soft enforcement), after the person says yes in the session, bdd approve FEAT-n GATE --self-reported. Say which one applied. Under guided also ask the person after test design before moving on, and show them design.md after the system map and wait for their reaction before binding.

5. When the feature is done

Show the report's verdict, the traceability matrix (bdd trace FEAT-n), the enforcement level (hard or soft, and why), the assumptions, the cost per phase and anything the auditor marked as must fix. If the feature ran on autopilot, say plainly that it is UNREVIEWED and list the assumptions first. Then stop; do not start the next feature on your own. Offer "${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" pr FEAT-n (add --write to save PULL_REQUEST.md in the project): it prints a pull-request description from the recorded facts, with the UNREVIEWED notice first under autopilot. It never contacts a git host; the person pastes it. For a reader who will not use a terminal, offer "${CLAUDE_PLUGIN_ROOT}/tools/bdd/bdd" report FEAT-n --out reports/FEAT-n.html: one self-contained HTML page of the same records.

Files to read when