Metadata-Version: 2.4
Name: openwish
Version: 0.7.0
Summary: Need-Driven Development for humans and coding agents
License-Expression: MIT
Project-URL: Homepage, https://github.com/yisyang/open-wish
Project-URL: Documentation, https://github.com/yisyang/open-wish/blob/main/README.md
Project-URL: Repository, https://github.com/yisyang/open-wish
Project-URL: Issues, https://github.com/yisyang/open-wish/issues
Project-URL: Releases, https://github.com/yisyang/open-wish/releases
Keywords: need-driven-development,coding-agents,agent-skills,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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.**

```text
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](https://github.com/github/spec-kit) and
[OpenSpec](https://github.com/Fission-AI/OpenSpec). OpenWish **0.7.0** uses
**artifact schema 4**.

## Get started

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

```sh
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:

```text
/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.

| Harness | Invocation |
| --- | --- |
| OpenCode, Claude Code | `/ow-propose`, `/fast-forward`, `/onboard` |
| Codex | `$ow-propose`, `$ow-fast-forward`, `$ow-onboard` |
| Other Agent Skills hosts | Host-specific selection |

## The workflow

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

- **Routine work** (clear, localized, reversible, within existing intent):
  inspect → implement → verify → report. No records.
- **Structured work**: 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.
- **Large work** becomes a sequence of independently reviewable changes, with the
  next one planned in detail.

See [Workflows](docs/workflows.md) for onboarding, large work and the change lifecycle.

| Skill | Responsibility |
| --- | --- |
| `ow-propose` | Reuse or revise needs; size reviewable changes |
| `ow-align` | Working design against all current needs; architecture rubric |
| `ow-plan` | Executable tasks; reconciling plans; strategic verification |
| `ow-implement` | Execute, verify, continue around blockers |
| `ow-review` | Assess all needs; make the change safe to forget; close |
| `ow-consolidate` | Dispose closed changes; compact needs |
| `ow-fast-forward` | Run through review and disposal under explicit delegation |
| `ow-onboard` | Infer needs, assess architecture, propose worthwhile refactoring |

## What persists

| Knowledge | Home |
| --- | --- |
| Actors, outcomes, acceptance, constraints | `openwish/needs/N-001.md` (durable) |
| Implemented behavior | Source code |
| Checks of intent | Tests that mention the need ID they protect (`ow trace`) |
| Module responsibilities | A short header per module; a README at major boundaries |
| Non-obvious rationale | Nearby comments or ordinary docs |
| Working design, tasks, latest review | `openwish/changes/C-001/` (deleted after acceptance) |

Needs have no execution status; closing a change does not retire a need or claim it
is complete. `confirmed_at` records actual human confirmation only.

**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.

```sh
ow new need N-001 --title "Monthly reconciliation"
ow new change C-001 --title "Local export" --need N-001
ow context C-001                     # all current needs + sized retrieval manifest
ow ready C-001                       # ready tasks and blockers
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](src/openwish/assets/artifacts.md).

## 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

```sh
uv tool upgrade openwish
ow init
```

Upgrades older integration files, keeps equal versions and local edits, and asks
before downgrades. 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](docs/product.md) and [framework design](docs/design.md)
- [Workflow policy](src/openwish/assets/policy.md) and [artifact reference](src/openwish/assets/artifacts.md)
- [Skill evaluations](evals/README.md), [changelog](CHANGELOG.md), [releases](docs/releases.md),
  [contributing](CONTRIBUTING.md)

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

MIT licensed.
