OpenWish (OW)

Need-Driven Development for humans and coding agents.

Humans ask. AI identifies needs, aligns solutions, plans, implements, and reviews. Humans review the results. Current needs remain binding after implementation, so the next feature does not quietly undo what the previous one accomplished. OW operates on needs. Asks stay in conversation; existing needs are revised or reopened, and distinct outcomes become new needs. There are no change records. Small, clear changes within existing intent go straight to implementation and verification. OW's structured workflow is for work that benefits from it.

OpenWish takes inspiration from Spec Kit and OpenSpec, with durable needs and bounded agent context at the center of the workflow.

Get started

Requires Python 3.11+. The runtime has no third-party dependencies. Install the CLI from PyPI with uv:

uv tool install openwish
cd /path/to/your/product
ow init

To install from a source checkout, use uv tool install .. The package name is openwish. The installed commands are ow (the canonical short form used here) and its exact alias openwish. If your shell cannot find them, run uv tool update-shell and open a new terminal.

ow init opens a terminal multi-select for OpenCode, Claude Code, Codex, and generic Agent Skills. Move with the arrow keys, toggle with Space, and press Enter to initialize all selected harnesses. Press A to toggle all or Q/Esc to cancel. Installed harnesses are preselected on subsequent runs. Basic or narrow terminals use a numbered multi-select instead.

To select harnesses directly, including in scripts:

ow init --harness opencode claude codex
# Equivalent: ow init --harness opencode --harness claude --harness codex

Without an interactive terminal, specify --harness. Codex and generic Agent Skills share .agents/skills, so selecting both installs one copy. One product/domain in one repository, including a monorepo, is the default.

Updating installed skills

Upgrade the CLI, then run ow init again in your project:

uv tool upgrade openwish
ow init

Initialization installs missing integrations and compares each selected file's installed version with the CLI's bundled version:

Downgrades require explicit terminal confirmation; scripts fail before writing if confirmation is needed. Declining keeps newer files while other selected installs/upgrades proceed. Deselection does not uninstall existing integrations.

Version stamps and openwish/installation.json track installed skills and command adapters. Exact unversioned v0.2 templates are recognized and upgraded; unknown unversioned files are preserved with an actionable error. Existing needs, specs, project configuration, policy, and knowledge are preserved when reinitializing. For the proportional workflow introduced in 0.4, see upgrade guidance.

In OpenCode, start with:

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

Or explicitly choose the uninterrupted workflow:

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

/fast-forward skips all OW confirmations and approvals, including final acceptance, for the selected needs' current implementation revisions. It still performs alignment, planning, implementation, verification, and AI review. It asks only for genuinely blocking clarification, access, or manual observations, after continuing any independent ready work.

The workflow

OW is opt-in. Installing its skills does not require using them for every edit, and instructions to work without OW are respected.

Routine changes: inspect → implement → verify → report. A localized, reversible fix, exact command alias, documentation update, or small refactor within clear existing intent needs no new need, epic, gate receipt, or acceptance prompt. Update an existing spec when its contract would otherwise become inaccurate.

Structured work: use when outcomes or constraints change, work requires substantial coordination, or consequential product/compatibility/data decisions remain. Preparation is continuous:

Ask → Propose → Align → Plan → Implement ↔ Review → Accepted results
       └── prepare together ──┘                    │
         one authorization                final acceptance
         if still needed                  in default mode

A clear instruction to implement already supplies authority for that scope. Otherwise, ask once about the combined outcome, approach, and implementation. Clarify genuine ambiguity early. Plan-only requests stop at the plan. Technical repairs or artifact relinking within authorized scope do not require renewed permission. Implementation continues through ready work and review/remediation; structured default work requests final acceptance once available work is finished.

Harness invocation

Add or update integrations later with ow init, or ow skills --harness NAME .... Both commands use the same version-aware installer. The same workflow is used everywhere; command adapters do not contain divergent process logic.

Needs are first-class

Each need records its actor, desired outcome, observable acceptance, human confirmation date, and latest verified implementation date.

Two independent state dimensions avoid confusing delivery with relevance:

• Currency: current, retired.
• Implementation: open, in-progress, review, approved.

A current/approved need still constrains every future design. Fast-forward acceptance records its origin; it is not mislabeled as human confirmation. An inferred need starts unconfirmed, and existing code is not assumed verified.

Spec designs contain authoritative many-to-many references to needs. Specs describe entities, UI modules, or cross-cutting capabilities; epics/tasks organize bounded implementation. Containment and prerequisite relationships are distinct. An epic can select a subset of its specs' needs as execution scope. Other linked needs remain regression constraints without requiring unrelated authorization. Compare actor, outcome, and acceptance before adding needs: a new command, mechanism, platform, or task is usually a spec detail for an existing outcome.

ow reopen N-001 resumes work under the same ID and resets authority to default. Only an explicit new fast-forward request enables it for the reopened revision.

Human-facing communication

Ask only questions whose answers can materially change the work; do not restate clear instructions as confirmation questions. Clarifications use numbered questions and two or three lettered choices, with (Recommended) before the preferred choice text:

1. N-001 already provides local monthly trends. Uploading raw records would
conflict with its local-only constraint. What should I do?
  A. (Recommended) Keep N-001 as-is. No new need or product modification.
  B. Add third-party upload and keep trends local. Revise N-001's allowed-domain exception.
  C. Add third-party upload and computation with local viewing. Revise N-001's constraint.

Final updates lead with need → spec → outcome, followed by verification and any blocker. ow summary N-001 provides that context; reporting only task IDs is insufficient.

Small artifacts, complete intent

• OW-managed knowledge and planning: under 500 lines per artifact.
• All current needs together: under 500 lines, default 6,000 estimated tokens.
• Source: under 500 LOC soft target, under 1000 LOC hard maximum.
• Data formats are exempt from source limits. Low-complexity source exceptions are exact paths with a rationale; they do not exempt OW knowledge artifacts.
• Routine verification should finish within five minutes. Necessary slower checks are explicit, and missing verification never counts as success.
• Latest summaries replace earlier ones. Git holds history; there is no required append-only journal, growing evidence archive, or duplicate needs ledger.

ow context derives the needs register and related spec statuses from authoritative records. ow context N-001 also lists affected contracts and work to retrieve. Agents read detailed designs only for the work at hand.

CLI

The CLI handles deterministic operations. The coding harness supplies reasoning, code execution, and semantic review; OW does not make model-provider API calls.

ow status                           # needs, linked specs, implementation progress
ow context                          # all current needs, including approved ones
ow context N-001 N-002              # plus affected spec/epic IDs
ow check                            # schema, links, cycles, ordering, size budgets
ow ready N-001 N-002                # ready work with spec/need context and blockers
ow summary N-001                    # outcomes, specs, work, and verification

Artifact scaffolding and decision recording are available to agents and humans:

ow new need N-001 --title "Monthly reconciliation"
ow new spec S-001 --title "Transaction export"
ow new epic E-001 --title "Export implementation"
# Fill templates and references before authorization.
ow authorize N-001 --by human        # one decision covers needs, design, and plan
ow reopen N-001                     # reuse a need when further work is necessary

Structured gates are revision-bound: changed need intent invalidates downstream authority, while updating task progress does not. Reviews are bound to the plan and repository content. The CLI records human decisions supplied by the harness; it does not authenticate a conversation or establish semantic correctness on its own.

--root PATH works before the subcommand; otherwise the project root is discovered from the current directory and its parents. check, status, and ready support --json. See ow --help and the installed openwish/artifacts.md for all commands.

Design and contribution

• Framework design
• Product requirements
• Artifact format
• Workflow policy
• Contributing and verification
• Publishing releases to PyPI
• Changelog and release notes

Run directly from a source checkout without installing:

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

This repository is developed directly; shipped skills live only in src/openwish/assets/skills/. Tests exercise OW in temporary projects rather than installing an active OW workflow into this checkout.

OpenWish 0.4.0 uses artifact schema 2. The v0.1 prototype's change records are superseded; see migration guidance. Integration files follow current host documentation; deterministic checks do not substitute for hands-on harness workflow validation. Licensed under MIT.