ReasonFirst¶
Reasoning-first coding orchestration
Strong reasoning plans. Coding agents execute. Evidence comes back for review.¶
ReasonFirst keeps ChatGPT (or another deliberately chosen strong reasoning interface) responsible for architecture, diagnosis, scope, acceptance criteria, and review. Replaceable coding agents handle implementation inside a controlled workspace.
Install ReasonFirst Start in 10 minutes See the daily workflow 中文
How ReasonFirst works¶
One primary loop
ActualCoder can also run directly from a terminal, CI job, IDE, or another client. That is useful for testing, recovery, and automation, but it is a secondary operational capability—not a separate product mode.
v0.5.1 guided setup and installation¶
The 0.5.1 source brings the five setup slices together: the canonical reasonfirst setup wizard, verified project grants and worker selection, packaged read MCP, optional packaged full-chat Bridge, managed tunnel runtimes, and recorded-state repair/resume. Packaged and source installation remain first-class routes to the same configuration and state. Detailed/manual guides are still supported.
The integrated feature baseline passed all ten CI jobs, including real packaged/source install E2E on Ubuntu, macOS and Windows. Release preparation needs its own fresh validation; installation tests do not establish provider login or browser-side ChatGPT authorization. Use the release wheel only after a maintainer publishes v0.5.1 and the Release assets workflow successfully attaches it. A source version alone does not establish release availability.
Read the v0.5.1 release notes Choose an installation route
v0.5.0 validated baseline¶
v0.5.0 brings the architecture shown above together as one tested system: three worker backends (codex-cli, copilot-cli, codex-desktop), two deliberately different MCP surfaces (read-only GitLab evidence vs. optional Bridge Preview orchestration), persistent TaskSpec/attempt state, cross-process workspace mutation locking, bounded EvidencePack, shared finish/review gates, and matching-HEAD CI feedback.
The pre-release audit baseline 7d16061061f6337604bd3135c9e4a693ad1fd68a passed all seven release-critical CI jobs plus the documentation deployment. The main validation job ran 445 tests; the package job built wheel + sdist, inspected archive paths, clean-installed the wheel, verified version/CLI entry points, and reran source/full-history secret scanning. The published v0.5.0 tag identifies the frozen release, not this earlier audit baseline. This historical test count is not the current suite count.
Read the v0.5.0 release notes Review the architecture
Bridge Preview availability
The read-only GitLab MCP is the portable evidence connection. Bridge Preview requires a connected client/workspace that permits its more privileged custom-MCP actions. If that surface is unavailable, use terminal ActualCoder; TaskSpec, workspace identity, validation and review gates remain the same.
Where should I start?¶
-
I am new to ReasonFirst
Start with Install & update. Choose the packaged quick route or the fully supported source/developer route; both converge on
reasonfirst setup. Then use First 10 minutes for the shortest guided loop. -
I already connected ChatGPT to GitLab
Follow the daily workflow: reason in ChatGPT, hand off a bounded task, then return evidence for review.
-
I need to configure the coding worker
Use the worker / CLI setup guide. This is the execution-engine reference.
-
Something is not working
Use troubleshooting and keep API, Git, Tunnel, worker login, workspace, and CI failures separate.
Core concepts¶
| Concept | What it means |
|---|---|
| Reasoning layer | ChatGPT reads evidence, diagnoses, chooses architecture, constrains scope, and reviews outcomes. |
| TaskSpec | Persistent goal, acceptance criteria, non-goals, and workspace/base identity. |
| Worker | Replaceable executor: Codex CLI, Copilot CLI, or Codex Desktop/App Server. |
| WorkerPolicy | User-owned model/effort/sandbox/approval/network/tool constraints. |
| EvidencePack | Bounded, recursively redacted, read-only evidence for returning implementation state to the reasoning layer. |
| Finish gates | Validation, reviewability, protected-path, secret/history, and candidate-identity checks before publication. |
What ReasonFirst is not¶
ReasonFirst is not a model proxy, quota-transfer service, universal security sandbox, or auto-merge bot. It does not make direct model-inference API calls. Coding backends use their own authentication and entitlement.
For the detailed trust model, see Architecture and Security.