Geordi

Geordi is the builder workflow for goal-driven coding work. It combines the former build-pipeline discipline — context first, implementation second, independent verification, retries, and receipts — with an installable CLI that can run bounded missions through Codex or Droid.

The machinery is intentionally plain: define a goal, add missions, run one runtime at a time, verify with real commands, and leave logs behind. Less mysticism. More receipts.

What Geordi does

• Defines a goal: the operator outcome.
• Breaks work into missions: bounded implementation units with acceptance checks.
• Loads project context before building.
• Prepends the shared global AGENTS.md context before every mission prompt.
• Runs missions through Codex or Droid.
• Keeps state in .geordi/state/ so runs can be resumed or audited.
• Separates implementation from verification.
• Captures receipts: prompts, command logs, verification logs, and git status before/after.

Install

From the source repo:

git clone https://github.com/h-mascot/Enterprise-Crew-skills.git /tmp/enterprise-crew-skills
bash /tmp/enterprise-crew-skills/geordi/install.sh

Or one line, pinned to the public release:

bash <(curl -fsSL https://raw.githubusercontent.com/h-mascot/Enterprise-Crew-skills/v1.1.0/geordi/install.sh)

The installer copies the bundle into ~/.geordi, creates ~/.local/bin/geordi, and prints a verification command.

Quick start

cd /path/to/repo
geordi init --goal "Ship dark mode settings" --mode codex
geordi mission add "Add settings toggle" --accept "npm test"
geordi run --mode codex
geordi status

Global AGENTS context

Geordi requires a global AGENTS.md file by default. This keeps mission runs aligned with the operator's shared agent rules before project-specific context is applied.

Default path:

~/.agents/AGENTS.md

Override when needed:

GEORDI_AGENTS_FILE=/path/to/AGENTS.md geordi run --mode codex

To intentionally run without a global file:

GEORDI_REQUIRE_AGENTS=0 geordi run --mode codex

geordi doctor checks the global file unless GEORDI_REQUIRE_AGENTS=0 is set.

Droid version:

cd /path/to/repo
geordi init --goal "Fix checkout form validation" --mode droid
geordi mission add "Repair validation and errors" --accept "npm test"
geordi run --mode droid --model "custom:Your-Model-0"

Mission contract

Each mission should include:

• Title — what to change.
• Acceptance command — what proves it worked.
• Scope note — what not to touch, if relevant.

Example:

geordi mission add \
  "Add CSV export to reports page" \
  --accept "npm run test:unit -- reports" \
  --scope "Only reports UI and export helper files. Do not modify auth."

Good missions are small enough to verify in one command. If a mission needs five unrelated acceptance commands, split it.

Runtime modes

Codex mode

Uses codex exec from the current git repository.

Good for:

• feature builds
• refactors
• tests and type fixes
• PR review follow-up

Default command shape:

codex exec --full-auto "<mission prompt>"

Override with:

GEORDI_CODEX_ARGS="exec --full-auto" geordi run --mode codex

Droid mode

Uses droid exec with optional --model and --auto settings.

Good for:

• BYOK model routing
• custom OpenAI-compatible endpoints
• Droid mission-style coding passes
• UI/code tasks where Droid is already configured

Default command shape:

droid exec --auto medium --cwd "$PWD" -m "$MODEL" "<mission prompt>"

Override with:

GEORDI_DROID_AUTO=low geordi run --mode droid --model "custom:Your-Model-0"

Context-first build loop

The core build-pipeline rule remains: load context before implementation.

Before running a non-trivial mission, collect:

1. AGENTS.md, CLAUDE.md, or other repo agent instructions.
2. Relevant PRD/story/task text.
3. Existing test/build commands.
4. Recent git status and nearby code conventions.
5. Explicit scope exclusions.

The bundled helper scripts can support this pattern:

~/.geordi/scripts/load-context.sh /path/to/repo
~/.geordi/scripts/update-context.sh /path/to/repo "Added CSV export with unit tests; npm test passes."

If those scripts do not match a repo, do the same manually and put the important context directly into the mission title/scope.

State layout

Inside the target repo:

.geordi/
  goal.md
  missions.jsonl
  state/
    run-YYYYmmdd-HHMMSS/
      mission-001.prompt.md
      mission-001.log
      mission-001.verify.log
      git-before.txt
      git-after.txt
      summary.md

Operator rules

1. Do not run open-ended prompts when a mission can be bounded.
2. Do not count agent completion as success; run the acceptance command.
3. Do not hide failures. Preserve the log and make the next mission smaller.
4. Do not put secrets in missions, prompts, or logs.
5. Read repo instructions before changing code.
6. Commit only after verification passes and scope is reviewed.
7. If verification fails, retry with the exact failure log and a smaller repair mission.

When to use Geordi

Use Geordi when the work is larger than a single prompt but smaller than a full project-management system:

• Build a feature across a few files.
• Convert a PRD into a sequence of agent missions.
• Run the same mission through Codex or Droid and compare results.
• Keep receipts for agent work without building a control plane.
• Continue the former build-pipeline workflow under the shorter geordi name.

Do not use Geordi for:

• one-line edits where a normal direct change is cleaner
• destructive repo rewrites without explicit operator approval
• secrets, credentials, payment flows, or private data entry
• unbounded “go improve the whole codebase” prompts

Verification

geordi doctor

Checks:

• bundle installed
• target directory is a git repo
• requested runtime exists (codex or droid)
• mission file is parseable
• acceptance command is available for each mission

Common pitfalls

1. Running the agent before reading repo instructions. Always load context first.
2. Over-wide missions. Split broad PRD stories into smaller missions with one acceptance command each.
3. Treating agent success as real success. The acceptance command is the proof.
4. Committing generated dirt. Review git status --short before committing.
5. Leaking private environment details. Keep model IDs, internal hosts, private paths, and secrets out of public missions and docs.

Verification checklist

• geordi --version prints the expected version.
• geordi doctor passes inside a git repo.
• geordi init creates .geordi/goal.md and .geordi/missions.jsonl.
• geordi mission add appends valid JSONL.
• geordi run writes prompt/log/verification receipts.
• Acceptance command output is preserved in .geordi/state/*/*.verify.log.