odd-custom-flow

An agent skill (SKILL.md format) that extends Organic Driven Development (ODD) for projects that keep their specs in OpenSpec (openspec/specs/).

It adds product discipline on top of ODD:

• Mockup-first UI lane — every user-facing change starts with exploration and navigable HTML mockups; no source write happens before explicit mockup approval. Work closes with a screen-by-screen, state-by-state visual fidelity check against the approved mockup.
• Spec-first backend lane — contracts, permissions, invariants, and a states/transitions table are written to the spec before code, with safe migration rules and a BEGIN/ROLLBACK rehearsal.
• Canonical specs — openspec/specs/<area>/spec.md is the source of truth, edited in place (no deltas, no openspec CLI required). Every spec change stops for explicit approval.
• Work-unit commits — each task closes with a Conventional Commit on the feature branch after its checks pass. Push, PRs, and merges stay with the human. No AI attribution.
• Real smoke tests — against a local, session-owned database, with external side effects pointed to sandboxes.
• Disposable artifacts stay out of git — mockup drafts go to .mockups/ and smoke evidence to .smoke/; both are created and added to .gitignore on first use. Only the approved mockup is committed.

Install

With the skills CLI:

npx skills add JorgeLBJ/odd-custom-flow

Or manually, copy skills/odd-custom-flow/ into a skills directory your agent reads:

Agent	Global	Project
OpenCode	~/.config/opencode/skills/, ~/.agents/skills/, or ~/.claude/skills/	.opencode/skills/, .agents/skills/, or .claude/skills/
Pi	~/.agents/skills/	.agents/skills/
Claude Code	~/.claude/skills/	.claude/skills/

~/.agents/skills/ is shared by OpenCode and Pi, so one copy serves both.

Usage

The skill is meant to be invoked explicitly, never auto-loaded:

Agent	Invocation	Manual-only enforcement
OpenCode	Ask for it by name, e.g. "use the odd-custom-flow skill to …"	OpenCode ignores disable-model-invocation; the skill's own activation rule forbids self-loading. To enforce it, set the skill permission to ask in opencode.json ("permission": { "skill": { "odd-custom-flow": "ask" } })
Pi	/skill:odd-custom-flow <what you want to change>	disable-model-invocation: true hides it from automatic selection
Claude Code	/odd-custom-flow <what you want to change>	disable-model-invocation: true

Requirements

This skill complements an existing ODD setup; it does not define ODD by itself.

Dependency	Required	Used for
An agent that supports SKILL.md skills (Claude Code, Codex, OpenCode, Cursor, …)	Yes	Loading the skill and its references/ and assets/ files
ODD protocol in your global agent instructions (e.g. Gentle AI's CLAUDE.md / AGENTS.md)	Yes	Task document odd/tasks/<feature>.md, task-by-task flow, TDD mode
Engram MCP	Recommended	Recovery mirror of the task document; skipped when unavailable
judgment-day skill	Yes, when RDD is off	Review of substantial or high-risk work; if missing, the agent stops and asks how to review
gentle-ai CLI	Optional	Receipt-driven review (RDD) and risk assessment; treated as off when missing

Locations

Resolved as: explicit user location > project instructions (CLAUDE.md / AGENTS.md) > skill default.

Artifact	Default	Versioned
Specs	openspec/specs/<area>/spec.md	Yes
Approved mockup + CHANGELOG.md	docs/mockups/<feature>/	Yes
Mockup drafts	.mockups/<feature>/	No (git-ignored)
Smoke evidence	.smoke/<feature>/	No (git-ignored)
Task document	odd/tasks/<feature>.md (owned by ODD)	Per your ODD setup

Layout

skills/odd-custom-flow/
  SKILL.md                     # activation, hard rules, steps, output contract
  references/                  # lanes, locations, smoke, fidelity, review
  assets/                      # task-doc and spec templates

License

Apache-2.0 — see LICENSE.