BriefGate

BriefGate is a standalone Codex skill that turns ambiguous, high-impact work into an evidence-backed brief and asks for explicit approval before execution. It resolves facts from the environment, batches only independent decisions into visual questionnaires, adapts later rounds, and stops when the remaining ambiguity no longer changes the work.

BriefGate product alignment

Why

Complex tasks often fail before implementation starts:

facts are asked as questions instead of being inspected;
independent decisions arrive as a long chat sequence;
dependent decisions are asked too early;
prior answers are lost between rounds;
"looks good" is treated as permission to publish or modify live state.

BriefGate separates facts from decisions and makes authorization explicit.

How It Works

flowchart LR
  A["Inspect facts"] --> B["Build decision graph"]
  B --> C["Ask current frontier visually"]
  C --> D["Merge answers and investigate"]
  D -->|"material ambiguity remains"| C
  D --> E["Present testable brief"]
  E --> F{"Explicit approval"}
  F -->|"direct mode"| G["Start approved work"]
  F -->|"controller return"| H["Return brief to caller"]

Inspect files, tools, documentation, and current state before asking.
Track confirmed, proposed, open, blocked, deferred, and conflicting items.
Show 4-8 independent decisions in one accessible visual round.
Preserve answers and ask only the next decision frontier.
Present a fixed-format brief and require a final approval action.

BriefGate usually converges in one to three discovery rounds.

Features

Evidence-first requirements discovery
Visual radio, checkbox, select, text, and textarea controls
Recommended answers with visible tradeoffs
Adaptive multi-round decision ledger
Localized labels and validation messages
Direct execution and generic controller-return modes
Explicit approval before implementation, publication, restart, or deletion
Deterministic local generator with no network calls
No runtime dependency on Super PM or any other skill

Install

Ask Codex to install the skill from:

https://github.com/Surfire/brief-gate/tree/main/skills/brief-gate

Or install it manually:

git clone --depth 1 https://github.com/Surfire/brief-gate.git
mkdir -p ~/.codex/skills
mkdir -p ~/.codex/skills/brief-gate
cp -R brief-gate/skills/brief-gate/. ~/.codex/skills/brief-gate/

Restart Codex after installation so the new skill metadata is discovered.

Use

Invoke it directly:

Use $brief-gate to align this migration with me before changing production.

Other useful prompts:

Use $brief-gate to clarify the scope, risks, and acceptance criteria first.

Grill me visually before we start this complex redesign.

The skill can also trigger implicitly when unresolved decisions could materially change a complex task.

Independent Controller Integration

BriefGate is standalone. An optional caller can set returnTo to its own skill reference in every round. After approval, BriefGate returns the approved brief and does not set goals, decompose work, or launch execution itself.

{
  "round": 1,
  "totalRounds": 2,
  "stage": "Project boundaries",
  "returnTo": "$project-controller",
  "questions": [
    {
      "id": "priority",
      "label": "Which outcome should dominate tradeoffs?",
      "type": "radio",
      "required": true,
      "options": [
        { "value": "quality", "label": "Quality" },
        { "value": "speed", "label": "Speed" }
      ]
    }
  ]
}

$project-controller is a neutral example, not a dependency. The caller owns its integration and BriefGate does not need to know which controller is used.

Examples

The repository includes three real multi-round flows generated by the bundled script:

Each has a discovery round, an approval round, generated Codex HTML fragments, and desktop/mobile captures. See the example gallery.

Controller-return approval on mobile

Generate A Questionnaire

Create a UTF-8 JSON spec that contains questions only:

node skills/brief-gate/scripts/build-questionnaire.mjs \
  --input questions.json \
  --output brief-gate-round.html

The output is an HTML fragment for the Codex inline visual surface. It contains no document wrapper and makes no network requests. Read the questionnaire schema before changing a spec.

Development

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
npm run examples:check
npm test
npx playwright install chromium
npm run test:visual

The browser smoke test submits a real generated form through a mocked window.openai.sendFollowUpMessage bridge and checks layout at 736px and 320px.

Privacy

Questionnaire specs must contain questions only. Do not persist user answers, credentials, private keys, cookies, patient identifiers, or confidential project data in specs, examples, logs, or commits. Submitted answers stay in the current Codex task unless a user explicitly requests durable state.

Inspiration

BriefGate was inspired by Matt Pocock's grill-me / grilling skill, especially its fact-first decision interview and explicit no-action boundary. BriefGate is an independent implementation adding batch visual frontiers, adaptive rounds, approval gates, localization, and a generic return protocol. See Acknowledgements.

Brief Gate

README