The Orient manual.

Install

Orient requires Node.js 20+ and Git. The GitHub CLI (gh) is needed only for an approved pull request. Installation writes user-scope, tool-owned runtime files; it never creates or edits a project's .orient/ directory.

The npm release is pending. After it ships, use npx orient-sdd install claude hermes codex opencode instead. With a checkout, install one or more runtimes:

node bin/install.js install claude
node bin/install.js install hermes
node bin/install.js install codex
node bin/install.js install opencode

Restart the runtime or start a new session after installation. Do not edit installed copies; rerun the installer to update them.

The six commands

A complete first phase

/orient-new-project
/clear
/orient-phase 1
/clear
/orient-build 1
/clear
/orient-verify 1
/clear
/orient-ship 1
/clear
/orient-status

Codex uses $orient-new-project and $orient-…. Each successful mutating command prints the exact reset and next action; do not type ahead around an approval gate.

Artifacts and ownership

ROADMAP.md owns phase definitions. REQUIREMENTS.md owns stable requirement IDs. STATE.md owns current position and status. The state helper is the only writer of STATE.md.

.orient/
├── PROJECT.md
├── REQUIREMENTS.md
├── ROADMAP.md
├── STATE.md
└── phases/
    └── 01-authentication/
        ├── SPEC.md
        ├── PLAN.md
        ├── SUMMARY.md
        ├── VERIFICATION.md
        ├── FIX.md
        └── SHIP.md

PROJECT.md

Outcome, users, constraints, observed repository facts, and non-goals.

SPEC.md + PLAN.md

Approved decisions, cited research, exact files, test-first tasks, and requirement traceability.

SUMMARY.md

Changed files, commit hashes, truthful command results, deviations, and unresolved issues.

VERIFICATION.md

Exactly one Verdict: PASS or Verdict: FAIL, evidence, exit codes, human acceptance, and gaps.

FIX.md

Only the failed requirements and narrow repair tasks. It drives the return to build.

SHIP.md

Included commits and evidence, plus a real HTTPS pull-request URL or explicit local-only completion.

Verification is a gate.

Behavior changes follow one loop: write the failing test, observe the failure, implement minimally, observe the pass, commit the focused change. Orient never treats a plan or summary as proof of working code.

1. Map every phase requirement to actual code, tests, and observable behavior.
2. Run the real application or user path when applicable. Record commands and exit codes.
3. Walk through the small human acceptance set. Automated tests alone are not acceptance.
4. On failure, write Verdict: FAIL and FIX.md, clear the context, then rerun /orient-build N.
5. Only a complete Verdict: PASS unlocks ship. Unrun checks must be named as unrun.

Recovery and local completion

Run /orient-status after a pause or interrupted command. It validates the roadmap and current artifacts without changing state. specifying, building, verifying, and shipping are resumable.

Out-of-order commands and malformed state exit nonzero without advancing the workflow. Missing artifacts name the file to repair. Do not hand-edit STATE.md; rerun the action that owns the transition.

Shipping never merges. If you decline a PR, Orient can leave the phase prepared for resume or, after another explicit choice, record PR URL: local-only and complete the phase locally.

Native runtime syntax

The workflow and artifacts are identical across runtimes. Only invocation syntax and installation locations differ.