@zhuk/spego 0.22.0 → 0.23.0

package/docs/estimation.md

@@ -0,0 +1,90 @@
+# Estimation
+
+The board prices changes in hours when the workspace declares a `flows` block. Every figure is derived on render and never stored.
+
+Vocabulary — Flow, Harness, Flow Hours, Human Hours, Size Tier, Flow Profile, Bias — is defined in [`CONTEXT.md`](../CONTEXT.md).
+
+## Configuration
+
+Declared in `.spego/config.yaml`. The hours below are illustrative — seed your own, or derive them from history (see [Seeding the first profile](#seeding-the-first-profile)).
+
+```yaml
+flows:
+  default: zapply
+  crossProject: false
+  profiles:
+    zapply:
+      xs: 0.5
+      s: 1
+      m: 2
+      l: 4
+      xl: 8
+  human:
+    xs: 2
+    s: 4
+    m: 8
+    l: 16
+    xl: 32
+```
+
+- `default` names the Flow that prices changes with no per-epic override.
+- `profiles` maps each declared Flow to a seed table over the fixed Size Tier scale (`xs`, `s`, `m`, `l`, `xl`). The scale is not configurable.
+- `human` is one table shared across every Flow.
+- `crossProject` opts into the cross-project rung and defaults to off.
+
+Config parsing rejects a `default` naming no declared profile, a table missing a tier or declaring an unknown one, and any hours value that is negative or not finite. A workspace with no `flows` block stays valid and prices nothing.
+
+## Pricing
+
+For every change whose epic carries a `tier`, the board derives a Flow Estimate from the epic's `flow` profile — the workspace default when unset — and a Human Estimate from the shared table.
+
+A change without a `tier`, or naming a `flow` absent from `flows.profiles`, renders `?` in the `hours` column and does not count toward its sprint's total; a sprint holding such pending changes renders its total with a `+?` suffix. Hours render as decimals with trailing zeros trimmed, and sprint totals sum unrounded values. Each sprint panel's title reports the remaining total Flow Estimate of its pending changes.
+
+`--json` carries `flowEstimate`, `humanEstimate`, `rung`, and `bias` per priced change, and `flowTotal` and `unpricedPending` per sprint. A workspace with no `flows` block omits the column, the totals, and every one of those fields.
+
+## The ladder
+
+Each price reports the rung it came from, so a measured number is never mistaken for a guess. Rungs resolve independently per Flow and Size Tier pair — one tier can price from observation while another falls back to the seed on the same board — and runs recorded under one Flow never price another.
+
+| Rung | Source | Condition |
+|------|--------|-----------|
+| `observed` | median of this repo's recorded runs | at least three runs for the pair |
+| `cross-project` | median of the cross-project store | `crossProject: true`, local runs below the threshold, store holds three or more |
+| `config-seed` | the declared `profiles` table | everything else |
+
+Observed hours carry a `*` in the `hours` column, with a dim legend line whenever a rendered change is observed.
+
+Runs arrive through `spego record <change> --flow <name> --hours <n>`, which appends to the epic's `actuals` rather than overwriting — a change delivered across several runs accumulates.
+
+## Bias
+
+The mirror derives a bias per Flow and Size Tier pair: the median ratio of recorded runs over the price those runs' changes carried. Seeded prices are corrected by it, clamped to `[0.5, 2]` so one pathological run cannot swing a profile. An observed price is never corrected by its own residual. `--json` carries the unclamped `bias`.
+
+A pair whose bias falls outside `[1/1.5, 1.5]` raises the `stale-profile` warning, naming the Flow, the tier, and the direction. The repair is judgment — a wrong seed, or inconsistent tier calls — so the warning points at re-grooming, not at an automatic fix. Several drifted pairs aggregate into one human Warnings row while `--json` keeps one entry per pair.
+
+## Cross-project history
+
+`spego record` appends every tiered run to an append-only `runs.jsonl` under the platform configuration directory — `$XDG_CONFIG_HOME/spego` or `~/.config/spego`, `%APPDATA%\spego` on Windows, `~/Library/Application Support/spego` on macOS. Each line is one `{flow, tier, hours}` record with no repo attribution.
+
+With `crossProject: true`, a pair whose local runs are below the sample threshold prices from the store's median once the store holds three or more runs for that pair. The flag defaults to off: a workspace that says nothing prices from repo observations and the seed alone, and its board stays reproducible from the repo. Opting in trades that reproducibility away, since the store lives outside the repo and grows with every run recorded anywhere.
+
+`SPEGO_STORE_ROOT` overrides the store root ahead of the configuration directory, so a test suite or a reproducible run can point it somewhere hermetic; the suite sets it for every spawned CLI run. The store is plain data, not a workspace — losing it costs evidence, not correctness, and the ladder simply falls back a rung. Recording writes the epic first and the store second, so a failed store write (`WRITE_FAILED`) never costs the epic entry, and the store is written whether or not the workspace opts in.
+
+## Seeding the first profile
+
+The first seed does not have to be invented. `node scripts/calibrate-seed.mjs` joins the agent sessions already recorded for this project to archived changes by time window and branch, sums elapsed wall-clock per change, and prints a per-change table for review — then, given a Size Tier per change, a `flows` block holding the median hours per tier, ready to paste into `.spego/config.yaml`.
+
+The script is calibration scaffolding, not product code: it reads a vendor-specific session format, its join is a heuristic the maintainer confirms before trusting, and it ships nowhere. It lives under `scripts/`, outside the published package, which is where the CLI's design keeps that format out of the npm artifact.
+
+## Authoring a priced change
+
+This project forks OpenSpec's `spec-driven` schema into `openspec/schemas/spec-driven-custom` (selected in `openspec/config.yaml`) and adds an `estimating` artifact between `proposal` and `tasks`. Once the proposal settles the scope, the author judges the change's Size Tier — sizing the change itself, not the flow machinery that will build it — and persists it through `spego sync` plus `spego update` onto the change's epic.
+
+The generated `estimating.md` records the tier and its one-line rationale as the human-readable trace; the epic's `tier` meta is the state the board prices from, so a change arrives priced instead of waiting for the next groom run. OpenSpec owns the ritual, spego owns the state — the step writes nothing under `openspec/` beyond its own artifact file.
+
+Changes authored without the fork are unaffected: grooming judges their tier as before. The `openspec schema` surface is experimental; if it changes, the prompt disappears and every recorded tier stays on its epic.
+
+## Related
+
+- [Delivery board](delivery-board.md) — where prices and sprint totals render
+- [Workflows](workflows.md#groom) — groom judges each epic's `tier` during analyze

package/docs/openspec-adapter.md

@@ -0,0 +1,40 @@
+# OpenSpec delivery adapter
+
+The default delivery adapter is OpenSpec. `spego epics` exposes active OpenSpec changes as delivery epics, and `spego tasks --change <name>` exposes checklist items from the change's `tasks.md`.
+
+| Source | spego view |
+|--------|------------|
+| `openspec/changes/<name>/proposal.md` | Epic title |
+| `openspec/changes/<name>/tasks.md` | Task status and counts |
+
+The `openspec` binary is not required on PATH — board and epics resolve status entirely from `tasks.md` on disk.
+
+## Read-only contract
+
+The adapter observes OpenSpec state. It does not create, continue, apply, verify, sync, or archive OpenSpec changes.
+
+`spego sync` reconciles the delivery mirror — it creates a missing epic for every ungroomed change, closes every finished sprint, and retires the epic of any archived change. It is unrelated to OpenSpec's own `sync` / `/opsx:sync`, which merges a change's spec deltas into the main specs tree.
+
+## Status derivation
+
+Archived changes under `openspec/changes/archive/` are excluded from the active set. Of the remainder:
+
+- no `tasks.md`, an empty one, or one whose items are all unchecked → `backlog`
+- some items checked, some not → `in-progress`
+- all items checked → `done`
+
+A task item is a Markdown checkbox line — `-`, `*`, or `+`, at any indent. A change with no items at all also raises a `no-task-plan` warning, so a change nobody has planned stays distinguishable from one that is planned but unstarted.
+
+Archived changes always resolve to `completed`. See [Delivery board](delivery-board.md#status) for how the two finished states differ and how manual overrides interact with them.
+
+## Example
+
+```sh
+spego epics --json
+spego tasks --change <change-name> --json
+```
+
+## Related
+
+- [Delivery board](delivery-board.md)
+- [Workflows](workflows.md#combined-openspec--spego-workflows) — which surface owns which state

package/docs/workflows.md

@@ -0,0 +1,129 @@
+# Workflow skills
+
+Workflow skills guide an agent through a multi-persona process inside the chat, persisting results as spego artifacts at well-defined checkpoints. They are generated per agent target — see [Agent targets](agent-targets.md).
+
+`spego workflows` lists them with their metadata.
+
+| Skill | Personas | Output |
+|-------|----------|--------|
+| [`brainstorm-party`](#brainstorm-party) | PM, Architect, UX, Dev, QA, Skeptic | `brainstorm`, optionally `prd` or `design` |
+| [`brainstorm-deep`](#brainstorm-deep) | Ideator | `brainstorm` |
+| [`review-adversarial`](#review-adversarial) | Skeptic, Security, Reliability, UX, Cost | `qa` or `risk`, optionally `decision` or `retro` |
+| [`review-edge-cases`](#review-edge-cases) | Path-tracer, Boundary-checker, Concurrency-skeptic | `qa` |
+| [`editorial-prose`](#editorial-prose) | Copy-editor | `qa` plus in-place edits |
+| [`editorial-structure`](#editorial-structure) | Structural editor | `qa` |
+| [`elicit`](#elicit) | Refiner | `qa` plus in-place edits |
+| [`groom`](#groom) | Groomer | `epic`, `sprint-plan` |
+| [`help`](#help) | Guide | none — chat only |
+
+## brainstorm-party
+
+Multi-persona collaborative brainstorming. Six roles take turns framing, expanding, challenging, and converging on ideas.
+
+Use when exploring a problem space broadly or stress-testing a concept before committing.
+
+## brainstorm-deep
+
+Single-persona, high-volume ideation targeting 50-100 ideas on a focused topic. One Ideator generates breadth, then clusters, deduplicates, and ranks the output.
+
+Use when you have a focused problem and want maximum idea throughput without persona debate.
+
+| Scenario | Use |
+|----------|-----|
+| Focused problem, need volume | `brainstorm-deep` |
+| Broad problem, need diverse perspectives | `brainstorm-party` |
+| One voice, fast iteration | `brainstorm-deep` |
+| Multiple viewpoints, stress-test ideas | `brainstorm-party` |
+
+## review-adversarial
+
+Adversarial critique of an existing artifact. Five roles attack from different angles, surface gaps, and prioritize findings.
+
+Use when you need rigorous review before approval or implementation.
+
+## review-edge-cases
+
+Method-driven edge-case enumeration. Three roles mechanically trace branching paths, derive edge classes (off-by-one, unguarded inputs, missing else/default, race conditions, timeout gaps), filter already-handled cases, and report only unhandled paths. The `qa` artifact carries a fenced JSON array of findings.
+
+Use when you need to find logic defects that adversarial review may miss.
+
+## editorial-prose
+
+Clinical copy-edit pass. The Copy-editor identifies ambiguous sentences, unnecessary jargon, long sentences, passive voice, and redundancy. Confirmed edits are applied in place via `spego update --expected-revision`; declined edits are recorded as recommendations.
+
+Use when the ideas are sound but the prose needs tightening.
+
+## editorial-structure
+
+Structural review without mutation. The Structural editor outlines the current structure, proposes cuts, merges, reorders, and splits, and produces a prioritized recommendation list. The source artifact is not modified.
+
+Use when content is correct but organization needs improvement.
+
+## elicit
+
+Iterative refinement of an existing artifact using named methods: clarify, sharpen, generalize, specialize, stress-test, contextualize, simplify, formalize. The Refiner proposes changes, confirms with the user, and applies via `spego update --expected-revision`. Maximum 5 cycles per session.
+
+Use when you have a draft that needs systematic improvement.
+
+## groom
+
+Delivery-mirror workflow reconciling active OpenSpec changes with `epic` and `sprint-plan` artifacts. Five phases:
+
+1. `orient` — read `spego board --json` and `spego epics --json`, then classify drift warnings.
+2. `sync` — run `spego sync` to mechanically create missing epics, close finished sprints, and retire epics of archived changes, then propose disposition for orphans resolving to no OpenSpec change.
+3. `analyze` — update deps, requires, supporting links, gap notes, conflict tracks, and Size Tiers on epics.
+4. `plan` — propose releasable, testable sprint groupings and create or update `sprint-plan` artifacts after confirmation.
+5. `summarize` — report epics, dispositions, sprint plans, and the next-change suggestion.
+
+Sole writers: groom and `spego sync` persist mirror state only through `spego create` / `spego update` with `--expected-revision`. Neither writes `openspec/` or mutates OpenSpec lifecycle state. Orphan disposition — only for epics resolving to no OpenSpec change — requires explicit confirmation; the default is keep. Epics of archived changes are retired, and finished sprints closed, deterministically by `spego sync` (preview with `--dry-run`), not by hand in groom.
+
+## help
+
+Orientation workflow that reads workspace state and recommends next steps. The Guide runs `spego status`, `spego list`, and `spego epics`, then applies a recommendation rubric to suggest the most impactful action. Produces no artifact.
+
+Use when starting a session, unsure what to do next, or asking "what should I work on?".
+
+## Authoring loop
+
+1. **Orient** — `spego-help` for workspace state and recommendations.
+2. **Ideate** — `spego-brainstorm-party` (multi-perspective breadth) or `spego-brainstorm-deep` (single-voice volume).
+3. **Capture** — `spego create --type prd` (or `architecture`, `design`, …) to persist the output.
+4. **Refine** — `spego-elicit` to iteratively improve the draft with structured methods.
+5. **Review** — `spego-review-adversarial` and `spego-review-edge-cases` for technical coverage, `spego-editorial-prose` / `spego-editorial-structure` for communication quality.
+
+## Complementary reviews
+
+Combine reviewers for orthogonal coverage:
+
+- **Technical defects** — `review-adversarial` is attitude-driven, hunting gaps and weak assumptions; `review-edge-cases` is method-driven, enumerating unhandled branching paths. Together they catch almost all technical defects.
+- **Communication defects** — `editorial-prose` (copy-edit) and `editorial-structure` (organizational review) catch confusion, ambiguity, and poor organization that technical reviewers do not flag.
+- **Recommended minimum** — at least one technical reviewer and at least one editorial reviewer before declaring an artifact ready.
+
+## Combined OpenSpec + spego workflows
+
+OpenSpec prompts and spego workflow skills are separate surfaces:
+
+- OPSX/OpenSpec prompts live under `.claude/commands/opsx/` and `.claude/skills/openspec-*/`.
+- spego-generated commands and workflow skills live under `.claude/commands/spego/` and `.claude/skills/spego-*/`.
+
+OpenSpec owns change execution and lifecycle state: proposal, design, specs, tasks, apply, verify, sync, archive. spego owns durable product-thinking artifacts — `brainstorm`, `qa`, `risk`, `retro` — plus delivery-mirror state, `epic` and `sprint-plan`, written only by the groom workflow. The [OpenSpec delivery adapter](openspec-adapter.md) is read-only.
+
+Use combined workflows when an OpenSpec change needs durable thinking around it:
+
+| Lane | OpenSpec action | spego action |
+|------|-----------------|--------------|
+| Before implementation | Create or continue a change with OPSX/OpenSpec, then read `proposal.md`, `design.md`, specs, and `tasks.md` | `spego-groom` grooms the delivery mirror; `spego-change-brainstorm` creates a `brainstorm` artifact |
+| During implementation | Keep task state and artifact mutations in OPSX/OpenSpec | `spego-change-review` creates `qa` or `risk` findings |
+| Before archive | Run OPSX/OpenSpec verification | `spego-change-verify-report` creates a `qa` verification report |
+| After completion | Archive or complete the OpenSpec change | `spego-change-retro` creates a `retro` artifact |
+
+Persistence checkpoints:
+
+```sh
+spego --json create --type brainstorm --title "<change-name> brainstorm" --body "<brainstorm output>"
+spego --json create --type qa --title "<change-name> review" --body "<quality findings>"
+spego --json create --type risk --title "<change-name> risks" --body "<risk findings>"
+spego --json create --type retro --title "<change-name> retro" --body "<retrospective>"
+```
+
+If a combined workflow discovers that OpenSpec artifacts need to change, use the matching OPSX/OpenSpec command. Do not mutate OpenSpec lifecycle state through spego.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuk/spego",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Agent-first product orchestration: markdown-first artifact engine with SQLite indexing.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "docs/*.md",
     "README.md",
     "CHANGELOG.md"
   ],