OpenWish (OW)

Need-Driven Development for humans and coding agents.

Humans ask. AI identifies needs, aligns design and engineering, implements, and reviews. Humans review the results.

Durable intent. Disposable plans. Code and tests carry the solution.

Needs ← referenced by → Changes → contain Tasks
durable                 disposable after review

Specs grow until nobody trusts them. OW keeps only needs durable: who needs what outcome, how to observe it, and which constraints genuinely limit solutions. Each change holds one increment's temporary design, tasks and review, and is deleted once its knowledge lives in code, tests, needs or ordinary docs. Current needs stay binding after delivery, so the next feature does not quietly undo the last one.

OW takes inspiration from Spec Kit and OpenSpec. OpenWish 0.9.1 uses artifact schema 4.

Get started

Requires Python 3.11+, with no third-party runtime dependencies.

uv tool install openwish     # or: uv tool upgrade openwish
cd /path/to/your/product
ow init

ow init offers a multi-select for OpenCode, Claude Code, Codex and generic Agent Skills (arrows move, Space toggles, Enter applies, A toggles all, Q/Esc cancels). For automation: ow init --harness opencode claude codex. Codex and generic Agent Skills share .agents/skills. Both ow and openwish invoke the CLI.

Then, in your agent:

/onboard
/ow-propose Let operations reconcile this month's transactions without copying rows.
/fast-forward Let operations reconcile this month's transactions without copying rows.

/fast-forward does the same design, implementation, verification and review, but delegates final acceptance of that change to the agent. It still stops for genuine blocking questions, missing access and manual observations.

The workflow

OW is opt-in; installed skills never force it on an edit.

• Every product change recovers current intent, clarifies only what matters, designs, verifies and reviews, in proportion to the ask.
• Direct delivery (one result, finished and verified in one session, nothing deferred or undecided): no change records, though needs are revised when intent changes.
• Managed delivery (several increments, resumption, deferred work, sequencing, manual blockers or delayed acceptance): propose → align → plan → implement ↔ review → human acceptance → dispose. A clear instruction to implement authorizes its scope; plan-only requests stop at the plan; only material intent or scope decisions go back to the human. Confirming a need's wording is never a gate.
• Large work becomes a sequence of independently reviewable changes, with the next one planned in detail.

See Workflows for onboarding, large work and the change lifecycle.

What persists

Needs have no execution status; closing a change does not retire a need or claim it is complete. confirmed_at records that a human confirmed every acceptance criterion; undecided questions and proposals wait in the need's open list. Each fact has one home, and other files link to it.

Sequences. A change can name predecessors with after. Successors become plannable once predecessors pass review (set successors_wait_for to acceptance to wait for acceptance instead); acceptance follows the sequence, and ow ready lists what to plan next.

Safe to forget. Before a change passes review, every material rule it introduced has a retained home: product files with independent checks, a need or doc, or another open change for approved unfinished work. The CLI checks those files exist and keeps the assessment inside the disposable review.

CLI

The CLI does deterministic storage, validation, scheduling, freshness and cleanup; the harness does the reasoning. OW makes no model API calls.

ow new need N-001 --title "Monthly reconciliation"
ow new change C-001 --title "Local export" --need N-001
ow new change C-002 --title "Scheduled export" --need N-001 --after C-001
ow context C-001                     # all current needs, work state, sized retrieval manifest
ow ready C-001                       # ready tasks, blockers, unplanned changes
ow task C-001/T-001 done --evidence "tests/test_export.py: 4 passed"
ow trace N-001                       # tests and files that mention N-001
ow record-review C-001 --summary "Reconciliation no longer needs row copying" \
  --check "python -m unittest: 12 passed" --handoff /tmp/ow-handoff.json
ow summary C-001                     # need → outcome → evidence; why a review is stale
ow close C-001 --by human            # after actual human acceptance
ow clean C-001 --dry-run && ow clean C-001
ow status --json                     # needs, changes, review state, retention groups
ow graph --json                      # recorded need relations
ow check --json                      # structure, references, size targets

Review freshness covers the change, tasks, all current needs, config, policy, the handoff and every product file, including submodules. Any edit makes a pending review stale, and ow summary names what changed. Linked needs are always recorded as affected; --affected adds others; every remaining current need is recorded as assessed and unaffected. See the artifact reference.

Size guidance

• Current needs: 24,000 estimated-token soft target (configurable), never truncated.
• Each OW artifact warns at 8,000 estimated tokens; source warns at 500 nonblank lines. A source_hard_limit is opt-in.
• Routine verification should finish within five minutes.

Updating

uv tool upgrade openwish
ow init

Upgrades older integration files, keeps equal versions and local edits, and asks before downgrades. The artifact reference upgrades with the skills; project policy, needs and work are preserved. Before v1.0.0 only the current schema is supported, with no migration tooling.

Design and contribution

• Product requirements and framework design
• Workflow policy and artifact reference
• Skill evaluations, changelog, releases, contributing

PYTHONPATH=src python3 -m openwish --help
PYTHONPATH=src python3 -m unittest discover -s tests -v

MIT licensed.