# World-Class Open-Source V0 Roadmap

Date: 2026-06-01

Status: HISTORICAL (banner added 2026-06-11). This was the staged v0 build
plan; it is kept as delivery history and is not maintained. Several "Non-Goals
For V0" have since shipped as explicit opt-ins (the OpenAI computer-use actor,
live E2B desktop labs), and the lab schema is now `humanish.lab.v2`. For the
live goal state read [`docs/goals/current.md`](../goals/current.md).

## Target Outcome

A maintainer can install `humanish` into a normal JavaScript app, let their
coding agent run setup, and get a public-safe persona simulation harness with:

- committed `humanish/` source plane;
- ignored `.humanish/` runtime plane;
- `commander` CLI;
- safe `init`;
- synthetic dry-run bundle;
- verifier;
- observer;
- public-safe feedback issue draft;
- clear docs and agent skill.

## Stage 0: Repo Plan And Issue Queue

Status: complete enough to start implementation.

Proof:

- GitHub project `humanish`;
- seeded issues;
- future-public boundary docs;
- feedback issue-draft doctrine.
- layout/install/goal docs;
- implementation tickets for the install path.

Primary issue queue:

- [#13 package: scaffold npm package and Commander humanish binary](https://github.com/danielgwilson/humanish/issues/13)
- [#14 init: scaffold committed humanish source and ignored .humanish runtime layout](https://github.com/danielgwilson/humanish/issues/14)
- [#16 fixtures: create target app fixture for init, dry-run, verify, and observer proof](https://github.com/danielgwilson/humanish/issues/16)
- [#7 cli: scaffold doctor, run --dry-run, review, verify, runs, and watch](https://github.com/danielgwilson/humanish/issues/7)
- [#6 core: run IDs, artifact paths, git state, history, and lifecycle primitives](https://github.com/danielgwilson/humanish/issues/6)
- [#10 observer: static mission-control viewer over fixture bundle](https://github.com/danielgwilson/humanish/issues/10)
- [#5 feedback: specify public issue-draft CLI command](https://github.com/danielgwilson/humanish/issues/5)
- [#15 skill: package agent setup guidance for installing Humanish](https://github.com/danielgwilson/humanish/issues/15)
- [#17 release: open-source readiness, package metadata, license, and publish dry-run](https://github.com/danielgwilson/humanish/issues/17)

## Stage 1: Package Scaffold

Build the minimum npm package:

- `package.json`;
- TypeScript config;
- `src/cli.ts`;
- `commander`;
- test runner;
- lint/typecheck/check scripts;
- binary name `humanish`;
- stable JSON command envelope.

Proof:

```bash
pnpm install
pnpm check
pnpm humanish -- --help
```

## Stage 2: Project Layout And Init

Implement `humanish init`:

- creates committed `humanish/`;
- creates ignored `.humanish/`;
- writes starter synthetic personas/scenarios/policies;
- patches `package.json` scripts;
- updates `.gitignore`;
- supports `--dry-run`, `--yes`, and `--json`.

Proof:

```bash
pnpm test
pnpm humanish -- init --dry-run --json
```

Fixture proof should run against a temporary app fixture, not this repo only.

## Stage 3: Run Bundle And Verify

Implement a synthetic dry-run bundle:

- run id;
- manifest;
- scenario/persona selection;
- lifecycle events;
- review skeleton;
- redaction result;
- artifact paths;
- source/git state.

Implement `humanish verify` over that bundle.

Proof:

```bash
pnpm humanish -- run --dry-run --json
pnpm humanish -- verify --run latest --json
```

## Stage 4: Observer

Status: upgraded from static report to mission-control substrate for synthetic
stream contracts.

Implemented:

- normalized `observer/observer-data.json` view model;
- `events.ndjson` event stream contract;
- stream-shaped sim lanes for UI, CLI, TUI, and Codex UI;
- localhost watch server with no-store polling;
- mission-control grid and focus mode;
- terminal/TUI transcript stage;
- evidence rail for events, artifacts, and gaps;
- public-safe Codex UI stream contract with no raw provider payloads.

Still next:

- real browser actor adapter;
- real PTY capture;
- native Codex app-server adapter;
- screenshot/trace gallery from real products;
- reviewer acceptance gates over live product behavior.

Proof:

```bash
pnpm humanish -- watch
```

If browser verification is added, use screenshots of the observer as proof.

## Stage 5: Feedback Issue Draft

Status: implemented for the synthetic dry-run bundle path.

Implement:

```bash
humanish feedback draft --run latest --json
humanish feedback issue --run latest --repo owner/repo --format markdown
humanish feedback issue-url --run latest --repo owner/repo
```

Rules:

- no GitHub API mutation;
- no tokens;
- no Projects;
- redaction must pass;
- dry-run-only claims are labeled as contract proof, not product proof;
- issue body includes `humanish_feedback` block.

Proof:

```bash
pnpm humanish -- feedback issue --run latest --repo example/app --format markdown
```

## Stage 6: Agent Skill

Status: implemented as an installer-visible skills.sh skill under
`skills/humanish/SKILL.md`.

Create a shareable skill package that teaches agents to install and configure
Humanish in target repos.

It should cover:

- `npm i -D humanish`;
- `npx humanish init`;
- committed vs ignored layout;
- public-safety rules;
- creating personas;
- creating scenarios;
- adding E2B/OpenAI env var names without values;
- running doctor/run/watch/verify/feedback issue;
- troubleshooting.

Proof:

```bash
DISABLE_TELEMETRY=1 npx skills add . --list
```

Future proof: fresh-agent fixture follows the skill and reaches dry-run +
issue draft.

## Stage 6.5: Release Readiness

Status: public package candidate, blocked only on explicit publish approval.

Readiness lives in
[`docs/release/open-source-readiness.md`](../release/open-source-readiness.md).
The package has MIT metadata and public npm package shape. `npm publish`
remains a human release action.

## Stage 6.75: Self-Dogfood Config

Status: implemented for dry-run contract proof.

The repository now includes committed `humanish/` source files so Humanish can run
against `humanish` itself. This makes `doctor` green on the repo, lets
dry-run bundles read and digest `humanish/personas/synthetic-new-user.yaml` and
`humanish/scenarios/first-run-smoke.yaml`, and keeps the live Codex TUI actor gap
explicit. The live Codex TUI dogfood path and noninteractive `codex-exec`
fanout hardening are tracked in
[#28](https://github.com/danielgwilson/humanish/issues/28).

## Stage 6.8: One-Command Watch UX

Status: implemented for synthetic contract-proof stream lanes.

`humanish watch` now creates a fresh four-lane synthetic run, renders Observer,
starts a localhost watch server, opens the served Observer in the browser, and
keeps the shell attached. The CI-safe form is `humanish watch --json --no-open`.
`--sims <n>` remains the explicit scale control, and `--run <id>` watches
existing evidence.

## Stage 6.8: Lab Manifests

Status: implemented as the generic source shape for reusable runs.

Humanish now resolves `.yaml` lab manifests from committed `humanish/labs/`,
ignored `.humanish/labs/`, ignored `.humanish/local/labs/`, or an explicit
`.yaml` path. The human path is `humanish watch <lab>`; the agent/CI path is
`humanish lab run <lab> --json --no-open`; discovery is `humanish lab list` and
`humanish lab inspect <lab>`.

Private or maintainer-only dogfood belongs in ignored lab manifests plus
explicit `--env-file`; the public package should not hardcode private target
names or require broad inherited job env.

## Stage 6.9: Maintainer OSS Meta-Lab

Status: implemented as repo-owned `humanish/labs/oss.yaml` plus compatibility
aliases, with a retained disposable smoke harness.

`humanish watch oss` opens the top-level Observer for authorized-repo meta-sims.
Each lane is assigned a GitHub `owner/repo` slug from `--repos` or repeated
`--repo` values and carries a headed E2B desktop for setting up Humanish inside
that repo, starting the target app where feasible, and keeping the nested
Observer visible.
Default public targets should be apps, CLIs, or agent-facing tools with
observable user surfaces. Frameworks, starters, and utility libraries are
acceptable only when the explicit scenario is developer-experience testing.
When live keys are present, Humanish launches E2B desktops, uploads the locally
packed Humanish package, starts visible bootstrap terminals, clones each assigned
repo inside the desktop, runs nested Humanish setup/proof commands, opens
desktop/mobile app windows plus the nested Observer in the sandbox browser, and
starts a nonblocking Codex actor attempt. Attached watch mode overlays live E2B
stream URLs only in memory; durable run artifacts keep screenshots/status, not
auth-bearing URLs. Private repos are maintainer-only, require an authorized
runtime GitHub token, and redact repo labels in durable artifacts by default.

`humanish lab run oss-smoke` keeps the earlier clone/discard proof loop: shallow
clone lightweight public GitHub repositories into ignored `.humanish/tmp`, apply
Humanish setup in disposable clones, run the four-lane synthetic Observer proof,
verify it, record git-status evidence, write an ignored
`.humanish/lab/oss/<run-id>/` report, and remove clones by default.

Proof:

```bash
pnpm humanish -- watch oss --detach --open --repos CorentinTh/it-tools,drawdb-io/drawdb
pnpm humanish -- lab run oss --dry-run --json --no-open --repos CorentinTh/it-tools,drawdb-io/drawdb
pnpm humanish -- lab run oss-smoke --limit 1 --json
```

Next substrate work: upgrade nested app-url render proof into provider-backed
browser personas that drive the target app and add richer process/filesystem
telemetry for Codex actor health.

## Stage 7: Local Browser And First Real Adapter

Only after the package and dry-run path are stable:

- local app target detection;
- Playwright/browser substrate;
- first scripted browser scenario;
- browser-app adapter fixture.

Proof:

- real browser screenshots in `.humanish/runs`;
- observer renders screenshots;
- `verify` validates bundle.

## Non-Goals For V0

- live E2B as required first-run behavior;
- OpenAI computer-use actor;
- live GitHub mutation;
- hosted queues/databases/webhooks;
- provider spend as required first-run behavior;
- production deploys;
- real user/persona data;
- private upstream artifacts.