geode-workflow · diff
git:20260825.1d02089 to git:20260907.97cb78b
6 added, 24 removed. Audit A to A.
---
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. For abstraction, naming,
- type/class, persisted-schema, test-placement, site, or version decisions,
- use `$geode-code-conventions`.
- 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.
+ Follow the [canonical workflow](../../../docs/workflow.md#core-loop) and its
+ [execution scope](../../../docs/workflow.md#execution-scope). Produce the
+ requested reviewable result; load only the references relevant to the task.
+ For abstraction, naming, type/class, schema, test, site, or version decisions,
+ use `$geode-code-conventions`.
## 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` |
| Abstraction, naming, type/class, schema, test, site, and version conventions | `$geode-code-conventions` (follow its task-specific SOT routing) |
| 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` |
+ | Test, lint, type, prompt, full-suite reporting, or failure-to-rule review | `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