@shahboura/harness 3.0.4

package/.opencode/skills/init-workspace/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: init-workspace
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  One-time workspace setup for the ai-sdlc-harness pipeline. USER-ENTRY and
+  HUMAN-ONLY — invoke only when the user explicitly runs /init-workspace;
+---
+
+
+# init-workspace — the interview (M7)
+
+Human-only: the user's consent point for the whole workspace. Every command
+below is `bin/harness <verb> …` — always the full
+path; a bare `harness` is not on PATH, and shell variables set in one Bash
+call do not persist to the next. Re-running refreshes **one section at a
+time** (`init-section`), never a full-nuke.
+
+## 0 · Environment bootstrap (do this FIRST)
+
+The harness needs PyYAML; system pythons are often externally managed
+(PEP 668), so the plugin owns a venv that `bin/harness` resolves
+automatically on every future call:
+
+```
+PY=".venv/bin/python"
+[ -x "$PY" ] || PY=".venv/Scripts/python.exe"
+"$PY" -c "import yaml" 2>/dev/null || {
+  SYS="$(command -v python3 || command -v python)" &&
+  "$SYS" -m venv ".venv" &&
+  PY=".venv/bin/python" &&
+  { [ -x "$PY" ] || PY=".venv/Scripts/python.exe"; } &&
+  "$PY" -m pip install --quiet pyyaml; }
+```
+
+One snippet for every OS: the Bash tool is Git Bash on Windows, so this
+stays POSIX shell there too — the two `.venv` probes cover the `bin/` (POSIX)
+vs `Scripts/` (Windows) venv layouts, and the `python3 || python` fallback
+covers hosts where only one spelling exists. Until this step runs,
+`bin/harness` itself still works (it falls back to the same system
+interpreter probe, which is what fails on a PyYAML-less system — that's why
+this step exists), and the spawn/skill guards degrade open with a one-line
+notice rather than erroring — expected pre-setup behavior, not a bug to chase.
+
+## 1 · Must-provide (no defaults — ask)
+
+- **Work-item provider**: local-markdown / github / gitlab / ado (CLI) /
+  ado-mcp / jira / zoho (MCP — walk the user through the model-in-the-loop MCP
+  integration probe). ADO is available on either transport (`ado` = `az boards`,
+  `ado-mcp` = Azure DevOps MCP server). Plus its specifics (stories dir,
+  `github_repo`, `ado_org`, `ado_project`, …).
+- **Git provider**: local / github / gitlab / ado (CLI) / ado-mcp (MCP).
+  If the user didn't state one, `local` is the sanctioned inference ONLY
+  when every registered repo has no remote (`git remote` empty) — say so
+  in one line rather than asking; any repo with a remote → ask.
+- **Repos**: `name=path` per target repo.
+
+Every `init-section` write is merged straight into the flat config by its
+top-level keys, so `provider`, `repos`, and `language` payloads must be
+**self-nested** under their own section key:
+
+```
+bin/harness init-section --section provider --json \
+  '{"provider": {"work_item": "local-markdown", "git": "local", "stories_dir": "stories"}}'
+bin/harness init-section --section repos --json \
+  '{"repos": {"backend": "/path/to/backend", "frontend": "/path/to/frontend"}}'
+```
+
+`overrides` is the one exception on both counts: it's a flat grab-bag of
+top-level config keys (`status_mapping`, `subagent_models`, `quick_mode`,
+…), never self-nested under an `"overrides"` key, and unlike
+`provider`/`repos`/`language` (each write replaces the whole file — always
+send the complete current set) its writes **merge**, so separate
+`--section overrides` calls for different settings accumulate rather than
+clobbering each other. See step 3.
+
+## 2 · Discovered, then confirmed
+
+Run `bin/harness discover --repo <path>` per repo. `discover` first
+ensures the repo is clean and on its default branch (`ensure_default_branch`
+— the same reusable precondition `preflight` uses later): a dirty repo, or
+one mid-rebase/merge, refuses with a clear error — surface it to the user
+(never auto-stash/discard/continue) — and a clean repo on a different
+branch is switched, reported back in `branch_check` so the interview can
+tell the user it happened. If the guessed default branch doesn't exist
+locally (no resolvable `origin/HEAD`), pass `--branch <name>` explicitly —
+note this only catches a *nonexistent* guess; a repo with no `origin` and
+a stray local branch that happens to be named `main` cannot be told apart
+from a genuine one, so confirm the branch name with the user for any repo
+without a resolvable `origin/HEAD`.
+**Known risk:** re-running this against a repo that already has an active
+`/dev-workflow` run in progress can switch that run's feature-branch
+checkout back to default — avoid re-running discovery for a repo with
+in-flight work. Present the proposals (language, `test_cmd`, default
+branch) as defaults-to-confirm. A `monorepo_split` proposal means this "one
+repo" is actually several logical repos sharing one `.git` at the physical
+root — **this isn't yet representable as separate registered repos**
+(`init-verify`'s `repo:<name>` check requires a `.git` directly under the
+registered path, which no subtree has, so registering subtrees separately
+leaves every one of them permanently failing verification with no
+available fix). Tell the user this is a known gap; register the repo once,
+at its physical root.
+**Language-config is per repo**, under `language.repos`, keyed by the same
+names used in `--section repos` (a sub-key, not a sibling of the global
+`test_paths`/`test_closure` settings, so a repo name can never collide with
+those) — confirm each repo's own `test_cmd` by running it, never collapse
+differing repos onto one command. **`coverage_cmd` gets the same
+treatment**: discover proposes one only on repo evidence (a `coverage`
+script, jest/vitest+provider, jacoco in the pom) — confirm it by running
+it. No proposal → ask the user for one (the harden step consumes it and
+never improvises); an explicit skip is a valid answer, recorded by simply
+omitting the key — tell the user harden will re-ask at run time. Write the
+whole set in one `--section language` call, e.g. `{"language": {"repos":
+{"backend": {"test_cmd": "sh mvnw -q test", "coverage_cmd": "sh mvnw -q
+test jacoco:report"}, "frontend": {"test_cmd": "npm test"}}}}`.
+
+## 3 · Choose-or-default (offer "default" explicitly, every time)
+
+Status-mapping override (provider defaults usually suffice), change-types +
+naming templates, `subagent_models` (default all `inherit`), quick-mode
+thresholds/keywords, repo-map staleness N, review-policy team rules,
+`security.scan_cmd` (if a scanner is configured, it's per-repo-keyed the
+same way `language` is — no scanner configured stays informational-only).
+Only what the user changes goes in `--section overrides` — shipped
+defaults cover the rest. Unlike `provider`/`repos`/`language`, this payload
+is **flat, not self-nested** (these are top-level config keys in their own
+right), e.g. `--section overrides --json '{"quick_mode": {"loc_max":
+50}}'` — never `{"overrides": {...}}`. Each call deep-merges into whatever is
+already there, so it's fine to write these one setting at a time as the
+user decides them; there's no way to *unset* a previously-written override
+through this verb though — that needs a direct edit to `overrides.yaml`.
+
+## 4 · Verify (a real gate) + finish
+
+1. `bin/harness init-verify` — every check must pass
+   (or be `manual` with the user's explicit acknowledgment for MCP
+   providers). Failures show remediation; fix and re-run. **Do not proceed
+   on failures.**
+2. `bin/harness init-finalize` — writes the permissions
+   allowlist and the bootstrap marker (section writes alone do not write
+   either of these). It re-runs the same verify gate itself and refuses
+   (exit 1) if any check still fails, so it can't mark a half-configured
+   workspace bootstrapped even if step 1 above was skipped by mistake.
+   Confirm `.claude/settings.json` merged cleanly (non-destructive).
+3. **Repo-map**: offer to generate one now per repo, following
+   `/repo-map-refresh`'s step 2 exactly (subagent_type-guessing warning,
+   `harness-mode: repo-map` header, and stamp-it-yourself rule all live
+   there — this file doesn't keep its own copy).
+4. Tell the user: `/dev-workflow <work-item-id>` is ready.
+
+## 5 · Adding a repo after the fact
+
+Use the dedicated `/add-repo` skill — it's the one place this procedure
+(discover → confirm → register → verify → finalize) is maintained; don't
+hand-roll it here too.

package/.opencode/skills/migrate-workspace/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: migrate-workspace
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  Adopt a v2.x ai-sdlc-harness workspace into v3.0 — config carries over,
+  run history stays archived in place. USER-ENTRY and HUMAN-ONLY — invoke
+  only when the user explicitly runs /migrate-workspace; never autonomously,
+---
+
+
+# migrate-workspace — adopt a v2.x workspace
+
+**The fork seam:** this file and `harness/migrate.py` are the replaceable
+unit — forks ship different adoption logic by swapping them and nothing
+else. Everything that WRITES goes through the same owned path as
+`/init-workspace` (`init-section` → `init-verify` → `init-finalize`);
+migrate verbs are read-only proposals.
+
+Human-only, same invocation rules as every skill here: always the full
+`bin/harness <verb>` path. First run
+`/init-workspace`'s **step 0 environment bootstrap** exactly as written
+there (that file owns the procedure — don't re-derive it).
+
+## 1 · Detect (stop conditions first)
+
+```
+bin/harness migrate-detect
+```
+
+- Surface `warnings` verbatim whenever present — e.g. an unreadable
+  `overrides.yaml` reports as bootstrapped *fail-closed*, and the
+  remediation lives in the warning, not here.
+- `already_bootstrapped: true` → this workspace already runs v3.0. If
+  `inventory.legacy_context_files` is non-empty, a prior migration stopped
+  before archiving — offer the **archive-only finish** (steps 5–6; the
+  report on this path records `inventory` only, since `migrate-extract`
+  rightly refuses post-bootstrap — the carried-config record lives in the
+  earlier attempt's confirmations); otherwise **stop** and point the user
+  at `/workspace-config`.
+- `legacy: null` → **stop**: nothing to adopt; point at `/init-workspace`.
+- Otherwise show the `evidence` list (why this looks like v2.x), then the
+  `inventory`:
+  - **`in_flight` runs get a hard boundary, stated plainly:** run history
+    is never converted — v3.0 state is sealed evidence (red-proofs,
+    ledgers) that v2.x never produced, so migrating a half-done run would
+    fabricate its audit trail. **Recommend finishing or abandoning those
+    stories on v2.x before migrating**: step 5 archives the very config
+    files v2.x resumes from, so proceeding now means a later v2.x session
+    must first hand-restore them from `legacy-2.1/`. Proceeding anyway is
+    the user's call — record the choice in the step-5 report.
+  - Old `ai/` run dirs and `aborted` leftovers stay exactly where they are
+    as readable archives; v3.0 run discovery ignores them.
+
+## 2 · Extract & confirm (propose-only)
+
+```
+bin/harness migrate-extract
+```
+
+Present the proposal per section — `provider`, `repos`, `language` — next
+to every `notes` entry (missing repo paths, unverifiable stories_dir) and
+the `unmapped` list (what v2.x config has no v3.0 home, and why). The user
+confirms or corrects **each section**; anything extract could not fill
+falls through to the matching `/init-workspace` interview question — never
+guess a value extraction didn't find.
+
+**Re-entry:** if a target section file already exists under
+`.claude/context/` (a prior attempt got that far), read it and present its
+current value next to the legacy-derived proposal — never silently
+re-propose stale legacy data over a correction the user already confirmed.
+
+`optional_overrides.naming` is **opt-in, default NO**: translated v2.1
+naming templates are usually the v2.1 defaults the user never chose, and
+v3.0's `{type}/{id}-{slug}` handles change-types better than a frozen
+`feature/` prefix. Offer it only as "did you deliberately customize
+naming in v2.x?".
+
+## 3 · Apply through the owned init path
+
+Write each confirmed section with `init-section` exactly as
+`/init-workspace` step 1 documents (self-nested payloads; `overrides`
+flat). Then fill the gaps the same way that interview does:
+
+- No `language` proposal for a repo → `discover --repo <path>` and confirm
+  (its dirty-repo/default-branch cautions live in `/init-workspace` step 2).
+  **`discover` switches a clean repo back to its default branch** — if
+  `inventory.in_flight` names a story whose v2.x feature branch may be
+  checked out in that repo, say so and get explicit confirmation first.
+- MCP-transport providers (`jira`, `zoho`, `ado-mcp`) → the
+  model-in-the-loop MCP checklist from the interview applies unchanged.
+
+## 4 · Verify + finalize (the same real gate)
+
+`/init-workspace` step 4, verbatim: `init-verify` must pass (fix failures,
+re-run), then `init-finalize`. A migrated workspace ends in exactly the
+state a freshly-interviewed one does — there is no "migrated" flavor to
+special-case later.
+
+## 5 · Archive the legacy config
+
+List the v2.x context files (`inventory.legacy_context_files`), confirm
+with the user, then move them aside so nobody mistakes them for live
+config:
+
+```
+mkdir -p .claude/context/legacy-2.1 && mv .claude/context/*.md .claude/context/legacy-2.1/
+```
+
+Write `.claude/context/legacy-2.1/migration-report.md`: what carried over
+(per section), the full `unmapped` and `notes` lists, and any in-flight
+v2.x stories with the finish-on-v2.x guidance. The old `ai/` dirs are the
+run archive; this report is the config-decision record.
+
+## 6 · Hand over
+
+- `local-markdown` users: existing story files work in place — v2.1
+  `> Status:` blockquotes are read tolerantly and upgrade to the v3.0
+  `Status:` form on first write-back.
+- Remote-provider users: work items live server-side; nothing moved.
+- Offer repo-map generation (`/repo-map-refresh` owns the procedure),
+  then: `/dev-workflow <work-item-id>` is ready.

package/.opencode/skills/repo-map-refresh/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: repo-map-refresh
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  Regenerate the auto-generated repo map the planner grounds its plans in.
+  USER-ENTRY — invoke only when the user explicitly runs /repo-map-refresh;
+---
+
+
+# repo-map-refresh
+
+The repo map is a navigation aid, never hand-maintained — corrections go
+through regeneration (design.md piece 5B). `/init-workspace` and
+`/add-repo` both point here for the identical generate-or-regenerate
+procedure (step 2 below) — this is the one place it's maintained; don't
+fork a second copy of it elsewhere.
+
+1. `bin/harness repo-map-check --repo-name <n> --repo <path>` — report
+   missing / fresh / stale (+ commits behind) to the user.
+2. To regenerate: spawn the planner shape with `harness-mode: repo-map` as
+   the prompt's FIRST line (the spawn guard regex-matches this exact
+   header — prose that merely mentions repo-map does not satisfy it; this
+   is a declared out-of-run spawn, `pipeline/surfaces.yaml`'s
+   `out_of_run_spawns`, legal regardless of whether other runs exist in the
+   workspace) and the repo path. Do not guess the planner's `subagent_type`
+   string: check your currently available subagent types for whichever one
+   corresponds to this plugin's planner (`agents/planner.md`'s frontmatter
+   `name: planner` is the identifying detail to match against) —
+   `hooks/guards.py`'s spawn guard matches on this shape by the LAST
+   `:`-segment of whatever string you pass, and a wrong guess doesn't
+   error, it just silently skips the guard's enforcement (fail-closed
+   spawn gating, planner's write-confinement to `ai/`/`.claude/context/`),
+   which is worse than the guess looking right. The planner can only write
+   under `ai/<run>/` and `.claude/context/` (guard-enforced — never repo
+   source), so point it at `.claude/context/repo-map/<name>/`. It writes
+   the tiered map there: a short top-level index (directories/modules by
+   purpose) plus per-area detail files, each loadable alone.
+3. Stamp it yourself, not the planner:
+   `bin/harness repo-map-stamp --repo-name <n> --repo <path>`
+   — stamping is the orchestrator's job, never the planner's own.
+4. Remind the user: the planner still reads real code for areas it plans to
+   touch — the map speeds targeting, it doesn't replace reading.

package/.opencode/skills/story-workflow/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: story-workflow
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  Refine, analyze, improve, and groom user stories / work items for quality —
+  readiness reports, template restructuring, adaptive gap-filling, and
+  codebase-aware technical grooming. USER-ENTRY and HUMAN-ONLY — invoke only
+  when the user explicitly runs /story-workflow <command>; never autonomously
+  from conversation, never from a subagent (guard-enforced). Distinct from the
+---
+
+
+# story-workflow — story-quality refinement (PO-facing)
+
+Improves work-item quality through four commands. Read-mostly: it fetches a
+work item, helps shape it, and — only with the user's consent — posts the
+result back as a comment. It never starts a dev run and never touches
+`ai/<run>/` run state.
+
+Every harness call is `bin/harness <verb> …` — the full
+path, run by you via Bash (a bare `harness` is not on PATH, and shell variables
+set in one Bash call do not persist to the next). Non-zero exit = refused; read
+the JSON error and act on it.
+
+## Usage
+
+```
+/story-workflow <command> <work-item-id> [session-notes…]
+```
+
+`<command>` is one of `analyze`, `refine`, `improve`, `groom`. `<work-item-id>`
+is whatever the configured provider uses — a number (ADO / GitHub / GitLab), a
+key (`PROJ-123`, Jira), or, for `local-markdown`, the story's **id** (the file
+stem inside `provider.stories_dir`, e.g. `WORK-7` for `WORK-7.md` — not a
+path). Any trailing tokens are session notes, passed through to `improve` and
+`refine`.
+
+## Routing
+
+| command | file | one-line |
+|---|---|---|
+| `improve` | `commands/improve.md` | adaptive single-pass: assess → gap-fill → draft (the recommended default) |
+| `analyze` | `commands/analyze.md` | standalone readiness report with flags |
+| `refine`  | `commands/refine.md`  | slow, section-by-section interactive restructure |
+| `groom`   | `commands/groom.md`   | codebase-aware per-repo technical notes |
+
+Parse `$ARGUMENTS`: the first token is the command, the second is the work-item
+id, the rest are notes. If the command is missing or unknown, print the usage
+line plus the table above and stop — do not guess. If the id is missing, ask
+for it — never proceed without one. Then read the one matching command file and
+follow it (context economy: load a single command file, not all four).
+
+## Before routing
+
+1. Confirm the workspace is bootstrapped: `.claude/context/provider.yaml` must
+   exist. If it doesn't, `/init-workspace` never ran — send the user there and
+   stop. The active provider is resolved from config by the harness; you never
+   hand-pick it.
+2. The recipe for fetching a work item and posting a result back — for every
+   provider and both transports — lives once in `shared/provider-io.md`. Read
+   it; the commands cite it instead of repeating it.
+3. Domain and convention context (for `improve` and `groom`) lives once in
+   `shared/context.md`.
+
+## Guardrails (all four commands)
+
+- On a remote provider, never edit the item's Description or Acceptance-Criteria
+  fields — post back as a **comment** only. The single exception is a
+  `local-markdown` story the user explicitly asks you to rewrite in place; see
+  `shared/provider-io.md`.
+- Never invent business requirements. A gap is a question for the human, not an
+  assertion of what "should" be there.
+- Mirror the user's domain language; don't rename their "platform" to "system".
+- Files in `templates/` are read-only references — don't modify them while a
+  command runs.
+- If a story is already well-formed, say so. "This looks ready" is a valid,
+  valuable outcome — don't manufacture flags or questions to look busy.

package/.opencode/skills/story-workflow/commands/analyze.md

@@ -0,0 +1,40 @@
+# /story-workflow analyze
+
+Pre-refinement readiness check. Evaluates a work item against quality criteria
+and produces a readiness report with actionable flags. Standalone and
+non-destructive — it never rewrites the story.
+
+> For most sessions `improve` is the better choice — it folds readiness analysis
+> into refinement in one adaptive pass. Reach for `analyze` when you want a
+> standalone report to share with the PO *before* touching the story.
+
+## Steps
+
+1. **Fetch** the work item per `shared/provider-io.md`. Extract title, type,
+   state, description, and acceptance criteria. If it isn't found, stop.
+2. **Domain context (optional)**: skim `shared/context.md` only if you need the
+   repo landscape to judge whether the story's scope is realistic.
+3. **Evaluate** the story against every dimension in
+   `templates/readiness-report.md`. For each, assign a 🔴/🟡/🟢 flag with a
+   *specific* explanation. Rules:
+   - **Be specific, not generic.** Not "ACs could be improved" but "AC #2 says
+     'handles errors gracefully' — untestable; suggest 'Given an invalid token,
+     When login is attempted, Then a 401 with code `AUTH_INVALID_TOKEN` is
+     returned'."
+   - **Suggest, don't only critique.** Every 🔴/🟡 carries a concrete fix —
+     draft the replacement text where you can.
+   - **Constructive tone.** The PO and team will read this.
+4. **Write the report** in the `templates/readiness-report.md` format: flags
+   with explanations, suggested improvements (draft Given/When/Then ACs where
+   ACs are missing or vague), and a 2–3 sentence summary assessment.
+5. **Present** the full report in the conversation, then ask whether to post it
+   as a comment on the item. On yes, post it per `shared/provider-io.md`. For
+   `local-markdown` (or any provider), the report is a **comment** — never
+   overwrite the story with it; if the user wants it persisted separately,
+   offer a sibling file (e.g. `<id>-readiness.md`) via the `Write` tool.
+
+## Notes
+
+- Never modify the item's Description or AC fields — comments only.
+- Don't force flags. A report that says "this story is ready" is a good result.
+- Flag missing pieces as **questions**, not assertions about what should exist.

package/.opencode/skills/story-workflow/commands/groom.md

@@ -0,0 +1,58 @@
+# /story-workflow groom
+
+Technical enrichment pass. Analyzes the relevant repos to identify affected
+components, migration concerns, testing strategy, and risks, and produces
+per-repo technical notes. This is where Claude Code's native codebase awareness
+is the main tool.
+
+## Steps
+
+1. **Fetch** the work item per `shared/provider-io.md`. If it has no clear ACs
+   yet, offer to run `improve` first — grooming is more effective on a refined
+   story — but proceed if the user wants to.
+2. **Identify relevant repos.** Read the repo landscape per `shared/context.md`
+   (`repos.yaml` + each `repo-map/<name>/`). From the story, propose which repos
+   are affected, each with a one-line reason, and **wait for the user to confirm**
+   before scanning anything. Don't scan repos they didn't approve.
+3. **Refresh remote knowledge, then check position (never mutate the tree).**
+   For each confirmed repo, using its path from `repos.yaml`:
+   - `git -C "<path>" fetch origin` — allowed, and updates remote refs without
+     touching the working tree. If it fails (no network/remote), report and skip
+     that repo — don't scan a repo you couldn't refresh.
+   - `git -C "<path>" rev-list HEAD..origin/<default-branch> --count` — a read;
+     how far behind the checkout is.
+   - **The harness blocks raw `git pull` / `merge` inside any workspace that has
+     completed `/init-workspace`** (owned-entry-point rule; this skill only ever
+     runs inside one), so this command does **not** update the working
+     tree. If a repo is behind, say so and offer two choices: **(a)** analyze the
+     current checkout as-is — and stamp the staleness into the notes so the
+     reader knows the analysis reflects commit `<short-sha>`, N commits behind
+     `origin/<default>`; or **(b)** stop for that repo so the user can update it
+     themselves (outside the harness) and re-run `groom`. Never switch branches
+     or discard changes to "help".
+4. **Analyze each confirmed, fetched repo** against the story. Use `Grep` for
+   content, `Glob` for file patterns, `Read` for inspection — not `Bash` for
+   searches. Look for: affected files/classes/methods; database & migration
+   impact; API surface (controllers, routes, DTOs); configuration & DI; existing
+   test coverage for the touched areas; and cross-service dependencies. Align
+   with the team's real patterns from the repo-map (repository pattern, MediatR,
+   etc.). **Be concrete** — name the file and method, e.g. "`AuthService.cs`
+   `ValidateToken` (~line 45) is what this story changes; tests live in
+   `AuthServiceTests.cs`", not "the auth module might be affected."
+5. **Produce technical notes** in `templates/technical-notes.md` — a section per
+   repo, plus Cross-Repo Considerations when more than one repo is involved.
+6. **Present** the notes and ask whether to post them as a comment. Iterate on
+   the user's input (they know planned refactors and constraints the code
+   doesn't show), then post per `shared/provider-io.md`. For `local-markdown`,
+   notes are a **comment** by default; do not overwrite the story — if the user
+   wants them persisted separately, offer a sibling `<id>-technical-notes.md`.
+
+## Notes
+
+- Comments only — never edit the item's Description or AC fields.
+- Frame findings as "here's what I see in the code," not "here's how to build
+  it." The goal is a head start on scope, not a prescribed implementation.
+- If you can't determine the impact with confidence, say so — "I couldn't tell
+  how X is handled; discuss at grooming" is a valid, useful finding.
+- Note unrelated concerns (a bug, tech debt) in one line, but don't derail the
+  grooming with them.

package/.opencode/skills/story-workflow/commands/improve.md

@@ -0,0 +1,47 @@
+# /story-workflow improve
+
+Single-pass story improvement — assess readiness internally, fill gaps
+conversationally, and produce a refined story, all in one adaptive flow. This
+is the recommended default: it replaces the separate analyze-then-refine dance.
+
+## Steps
+
+1. **Fetch** the work item per `shared/provider-io.md` (title, description,
+   acceptance criteria, state, links). If it isn't found, stop.
+2. **Load** `templates/story-template.md` (target format),
+   `templates/readiness-report.md` (used only as an internal rubric — do *not*
+   present a standalone report), and `shared/context.md` for domain language.
+3. **Assess readiness internally** against the rubric, then classify into a tier:
+   - **Tier 1 — Solid**: ≤1–2 yellow flags, no red. Draft immediately.
+   - **Tier 2 — Some gaps**: 1–3 issues. Specific areas need clarification.
+   - **Tier 3 — Rough**: 4+ issues, or a whole section missing (no ACs, no
+     description). Needs substantial input.
+4. **Fill gaps conversationally**, adapted to the tier:
+   - **Tier 1**: skip questions, acknowledge what's good, draft.
+   - **Tier 2**: ask 2–5 targeted questions — each references the specific gap
+     and *proposes an answer to confirm or correct* (the user validates, not
+     drafts). Present them all at once.
+   - **Tier 3**: say so honestly, ask up to 5 questions, then (if critical gaps
+     remain) one more round of up to 3, then draft.
+   - **Session notes** (passed after the id) are gold: mine them before asking
+     anything, and don't ask what they already answer. If none and the story is
+     Tier 2/3, ask once whether any exist.
+5. **Draft the whole story at once** in `templates/story-template.md`: Context,
+   Description, Acceptance Criteria (happy path then error/edge), Out of Scope,
+   Open Questions (`[PO]`/`[Tech]`/`[Team]`), and an empty Technical Notes
+   (that's `groom`'s). For Tier 2/3, prepend a short "What was improved" list;
+   skip it for Tier 1.
+6. **Review and iterate** — present the full draft, adjust any section the user
+   flags. If it's grown too large (>7 ACs, multiple capabilities), suggest a
+   split. After minor edits, just confirm the change; don't re-dump the story.
+7. **Post** on approval per `shared/provider-io.md` — one comment carrying the
+   "What was improved" summary (if any) plus the full story. For
+   `local-markdown`, offer the in-place overwrite of the source file (this
+   command is one of the two that may rewrite a story in place).
+
+## Notes
+
+- **Adapt, don't interrogate.** If the story is good, say so and draft fast.
+- **Suggest answers.** The user should be confirming, not drafting from scratch.
+- **One comment, one artifact** — the whole output in a single comment, not one
+  per section.

package/.opencode/skills/story-workflow/commands/refine.md

@@ -0,0 +1,44 @@
+# /story-workflow refine
+
+Interactive, section-by-section restructuring of a story into the canonical
+template through a collaborative conversation. Slower than `improve` on purpose.
+
+> For most sessions `improve` is the better choice. Reach for `refine` when a
+> story is complex or contentious and you want to work through it one section at
+> a time, confirming each before moving on.
+
+## Steps
+
+1. **Fetch** the work item per `shared/provider-io.md` (title, description,
+   acceptance criteria, state, links).
+2. **Session notes**: if the user passed notes after the id, use them. If not,
+   ask once: "Any notes from the refinement session — bullet points, rough
+   notes, decisions? If not, I'll work from the work item." Notes capture PO
+   clarifications and scope calls that never made it into the item.
+3. **Load** `templates/story-template.md` (the target format) and, for
+   terminology, `shared/context.md`.
+4. **Work the template one section at a time**, proposing content and getting
+   approval before moving on:
+   - **Context** — draft the business "why"; ask if it's captured correctly.
+   - **Description** — one `As a … I want … so that …`. If it spans multiple
+     capabilities, flag a possible split before continuing.
+   - **Acceptance Criteria** — draft Given/When/Then, happy path first then
+     error/edge cases; present them together and ask what's missing.
+   - **Out of Scope** — propose explicit exclusions from the notes and context;
+     ask what else to exclude.
+   - **Open Questions** — collect unresolved items, tag each `[PO]` / `[Tech]` /
+     `[Team]`, ask if any remain.
+   - **Technical Notes** — leave empty; it's populated by `groom`. If the user
+     volunteers technical context, note it but say the full analysis is `groom`.
+5. **Assemble** the complete story and present it whole for a final review.
+6. **Post** on approval per `shared/provider-io.md` — a comment on remote
+   providers; for `local-markdown`, offer the in-place overwrite of the source
+   file (this command is one of the two that may rewrite a story in place).
+
+## Notes
+
+- The interactivity is the value — don't rush sections; give the user room to
+  correct. Be transparent about inferences: "I'm inferring X from the
+  description — right?"
+- If the story looks too large mid-refinement (many ACs, broad scope), suggest
+  splitting rather than pushing a bloated story through.

package/.opencode/skills/story-workflow/shared/context.md

@@ -0,0 +1,22 @@
+# shared/context.md — domain + convention context
+
+`improve` and `groom` are stronger when grounded in the team's actual repos and
+patterns. v3.0 keeps that context in two places (there are no `repos-metadata`
+or `conventions` markdown files — those were v2.x, and are gone):
+
+- **`.claude/context/repos.yaml`** — the registered repos and their local
+  paths. This is the map of what exists and where it lives on disk.
+- **`.claude/context/repo-map/<repo-name>/`** — the auto-generated, tiered
+  codebase map (purpose by directory, key abstractions, notable patterns),
+  stamped with the SHA it was generated at. This is where "the team uses the
+  repository pattern / MediatR / …" comes from; read it rather than re-deriving
+  the codebase from scratch.
+
+Read both with the `Read` tool. Treat them as **context, not gospel**: the
+repo-map may be stale (it records its own generation SHA) and the user knows
+things the code doesn't. If a repo-map is absent for a repo, say so — `groom`
+can still scan the repository directly (see `commands/groom.md`), and `improve`
+proceeds on the work item alone.
+
+Never write anything under `.claude/context/` from this skill — that tree is
+owned by `/init-workspace`, `/add-repo`, and `/repo-map-refresh`.