geode-workflow git:20260825.9516eabA

Immutable. This exact content is served forever at /api/v1/blob/307a7997930daa36.

---
name: geode-workflow
description: GEODE evidence-first development workflow. Use for feature work, provider/model changes, GUI/computer-use work, PDF/document ingestion, observability/schema/event/state changes, verification planning, GitFlow merge prep, and requests to "follow the workflow" or "scaffold the process".
---

# GEODE Workflow

Use this skill as GEODE's default execution scaffold. It replaces the older
issue-first workflow with an evidence-first loop: inspect existing code, ground
external contracts, define the observable surface, implement narrowly, verify,
then report honestly.

## Core Loop

1. **Scope**: confirm branch, dirty files, objective, and unrelated work.
2. **GAP audit**: search before designing; classify existing, partial, absent,
   or misfit. For architecture/extensibility work, read
   `docs/architecture/extensibility-roadmap.md`, claim a `READY` work package
   on canonical `develop`, and carry its stable GAP IDs through the PR and
   reconciliation flow.
3. **Grounding**: use official docs/source for provider, SDK, model, OS,
   browser, package, or current external behaviour.
4. **Preflight**: classify task type, affected providers, required tools,
   evidence class, and out-of-scope surfaces.
5. **Design contract**: define schema, log, event, state, trajectory, provider
   split, and rollback behaviour before code.
6. **Implement**: use existing registries, adapters, redaction helpers,
   transcript helpers, and atomic-write utilities.
7. **Observe**: make runtime behaviour inspectable with bounded structured
   records.
8. **Verify**: run targeted checks first, then broaden when risk justifies
   it. Non-trivial PRs also get a Codex MCP second-opinion review of the
   committed diff before push (see `references/verification-gates.md`).
9. **Report/GitFlow**: state what changed, what ran, what failed or was
   skipped, and only claim merge/push/cleanup after commands complete.

## Reference Routing

Read only the reference needed for the current task:

| Need | Read |
|---|---|
| Phase-by-phase checklist for ordinary code work | `references/phase-checklist.md` |
| Provider/model/API capability claims | `references/provider-grounding.md` |
| Schema/log/event/state/trajectory consistency | `references/observability-contract.md` |
| Same-task Codex–GEODE production and comparison | `references/codex-geode-paired-coding.md` |
| Test, lint, type, prompt, and full-suite reporting gates | `references/verification-gates.md` |
| Branch, PR, merge, and cleanup operations | `references/gitflow.md` |

For simple docs or trivial bug fixes, use the core loop and skip references
that do not affect the task.

## Non-Negotiables

- Do not switch branches inside an active worktree.
- Do not revert unrelated dirty work.
- Architecture/extensibility implementation work starts only after a
  roadmap-only claim PR moves the package from `READY` to `IN_PROGRESS` on
  canonical `develop` and names its owner/implementation branch. Claim and
  reconciliation PRs establish that prerequisite; they do not require an
  earlier claim. The implementation PR preserves the claimed status and never
  predicts `IN_DEVELOP` or `DONE`.
- Register architecture scope discovered during implementation through a
  separate roadmap-only GAP-registration PR. Registration may add an `OPEN`
  package without a prior claim, but does not authorize implementing it.
- Within the architecture/extensibility program, use `origin/main` only for a
  tracking-only roadmap `DONE` worktree after release. Its PR targets `main`,
  carries no implementation code, and is followed by a CI-gated
  `main -> develop` sync.
- Do not mark unsupported provider behaviour as supported without grounding.
- Do not add ad hoc observability strings when the capability/evidence
  vocabulary should be extended.
- Do not log raw screenshots, base64 blobs, API keys, tokens, passwords, or
  secret fragments.
- Do not imply a full-suite pass if only targeted checks ran.

## Output Contract

When finishing, include:

- implementation summary
- key files changed
- verification commands and results
- known failures, skipped gates, or live-test uncertainty
- GitFlow state if any branch/PR/merge action was requested