@shahboura/harness 3.0.4

package/.opencode/skills/story-workflow/shared/provider-io.md

@@ -0,0 +1,73 @@
+# shared/provider-io.md — fetch a work item, post a result back
+
+The configured work-item provider is resolved by the harness from
+`.claude/context/provider.yaml`; you never name it. There are two transports,
+and the recipe differs slightly between them. This file is the single source —
+every command cites it.
+
+## Fetch a work item
+
+Run:
+
+```
+bin/harness provider --op work_item.fetch --id <id>
+```
+
+**CLI / file transport** (`local-markdown`, `github`, `gitlab`, `ado`) prints
+the normalized item directly:
+
+```
+{"ok": true, "result": {"id": "...", "title": "...", "type": "...",
+  "state": "...", "description": "...", "acceptance_criteria": ["…", "…"],
+  "provider_ref": "…"}}
+```
+
+Work from those fields. For `local-markdown`, `<id>` is the file **stem** inside
+`provider.stories_dir` (`WORK-7`, not `stories/WORK-7.md`) — the harness refuses
+an id that escapes the stories dir.
+
+**MCP transport** (`ado-mcp`, `jira`, `zoho`): a script cannot call an MCP tool,
+so the same command **exits non-zero** and prints the exact MCP tool + args to
+invoke — that refusal *is* the instruction. Invoke that tool yourself, capture
+its raw JSON, then normalize it to the shape above:
+
+```
+printf '%s' '<raw-json>' | bin/harness provider-normalize --op work_item.fetch
+```
+
+⚠️ That refusal message ends by telling you to pipe the raw result into the
+`--from-raw` bootstrap. That is the **/dev-workflow** path — it starts a dev run
+and seeds `state.yaml`. story-workflow must never start a run, so ignore that
+last line and use `provider-normalize` (above), which runs the identical
+normalize with no run side-effects.
+
+If the fetch fails or the item isn't found, tell the user plainly and stop.
+
+## Post a result back (only after the user approves)
+
+Story-quality output goes back as a **comment** — never by editing the item's
+Description or Acceptance-Criteria fields:
+
+```
+bin/harness provider --op work_item.add_comment --id <id> --text '<markdown>'
+```
+
+- **CLI / file transport** posts directly (`local-markdown` appends under a
+  `## Comments` section in the story file; ADO renders the markdown; GitHub and
+  GitLab post native markdown).
+- **MCP transport**: as with fetch, the command exits non-zero and names the
+  comment tool + args — invoke that MCP tool yourself with the same `<text>`.
+
+Always show the artifact in the conversation and get an explicit yes before
+posting. If the user wants changes, iterate first, then post once.
+
+## local-markdown: rewriting a story in place
+
+`add_comment` is non-destructive (a comment bullet), which is exactly what
+`analyze` and `groom` want. For `improve` / `refine`, the user may instead want
+the refined story to **replace** the source file. That is the one sanctioned
+direct write: with the user's explicit go-ahead, use the `Write` tool on the
+story's `provider_ref` path (returned by the fetch) to overwrite it with the
+refined markdown. If the user declines both a comment and an overwrite, leave
+the output in the conversation for them to copy — never overwrite silently, and
+never overwrite for `analyze` / `groom` (that would destroy the story).

package/.opencode/skills/story-workflow/templates/readiness-report.md

@@ -0,0 +1,57 @@
+# Readiness Report Template
+
+The output format for `analyze`, and the internal rubric `improve` scores
+against. A qualitative assessment of story readiness with actionable flags.
+
+```markdown
+## Story Readiness Report
+**Work Item:** #[ID] — [Title]
+**Assessed:** [date]
+
+### Flags
+
+🔴 **[Flag Name]**
+[What's missing or problematic, with a specific suggestion for improvement.]
+
+🟡 **[Flag Name]**
+[A concern that isn't blocking but should be addressed.]
+
+🟢 **[Flag Name]**
+[Something done well — reinforces good practice.]
+
+### Suggested Improvements
+
+[Concrete, story-specific suggestions — draft acceptance criteria, proposed
+scope boundaries, or questions to raise in refinement. Not generic advice.]
+
+### Summary
+
+[2–3 sentence overall assessment. Ready for a refinement discussion, or does it
+need pre-work from the PO first?]
+```
+
+## Flag catalog
+
+The readiness dimensions to evaluate. Not every flag applies to every story —
+use judgment.
+
+**Context & Motivation** — 🔴 Missing Context (no "why") · 🟡 Vague Context
+(present but not tied to a business need) · 🟢 Clear Context.
+
+**Description Quality** — 🔴 No User-Story Format (no persona/capability/outcome)
+· 🟡 Ambiguous Persona ("as a user" is too generic) · 🟢 Well-Formed.
+
+**Acceptance Criteria** — 🔴 Missing ACs · 🔴 Untestable ACs ("should work
+well") · 🟡 Incomplete ACs (obvious error/edge cases missing) · 🟡 Too Many ACs
+(>7 suggests a split) · 🟢 Solid ACs.
+
+**Scope** — 🔴 Unbounded Scope · 🟡 Implicit Assumptions · 🟡 No Out-of-Scope ·
+🟢 Well-Bounded.
+
+**Dependencies & Risks** — 🟡 Implicit Dependencies · 🟡 Cross-Team Dependency ·
+🟢 Self-Contained.
+
+## Tone
+
+Constructive and specific. Every 🔴/🟡 carries a concrete fix. 🟢 flags matter
+too — they reinforce what the PO and team are doing well.

package/.opencode/skills/story-workflow/templates/story-template.md

@@ -0,0 +1,51 @@
+# Story Template
+
+The canonical format for user stories. All four commands produce output that
+follows this structure.
+
+```markdown
+## Context
+[Why does this story exist? What business problem or user need does it address?
+Background that helps developers understand the motivation.]
+
+## Description
+As a [persona], I want [capability], so that [outcome].
+
+## Acceptance Criteria
+- [ ] Given [precondition], When [action], Then [expected result]
+- [ ] Given [precondition], When [action], Then [expected result]
+- [ ] ...
+
+## Out of Scope
+[Explicitly what this story does NOT cover. Prevents scope creep and sets clear
+boundaries for the implementation.]
+
+## Open Questions
+[Anything unresolved, each prefixed with who answers it. Cleared during
+refinement or grooming — remove items as they get answered.]
+
+## Technical Notes
+[Added during or after grooming. Per-repo breakdown of affected components,
+migration concerns, testing strategy, and risk flags. See technical-notes.md.]
+```
+
+## Section guidelines
+
+**Context** — 2–4 sentences on the "why," not the "what." A developer reading
+only this should understand the business motivation. No implementation detail.
+
+**Description** — one sentence in user-story format. Needing multiple `As a…`
+statements usually means the story is too large and should be split.
+
+**Acceptance Criteria** — each AC independently testable, in Given/When/Then.
+Aim for 3–7. Fewer than 3 usually means missing edge cases; more than 7 usually
+means the story is too large.
+
+**Out of Scope** — 1–3 items someone might reasonably assume are included but
+aren't. If nothing is ambiguous, write "No explicit exclusions identified."
+
+**Open Questions** — prefix each with `[PO]`, `[Tech]`, or `[Team]`. Example:
+`[PO] Should existing users be migrated automatically or opt-in?`
+
+**Technical Notes** — only populated during grooming; left empty or absent
+before. See `technical-notes.md` for the per-repo format.

package/.opencode/skills/story-workflow/templates/technical-notes.md

@@ -0,0 +1,48 @@
+# Technical Notes Template
+
+The output format for the Technical Notes produced by `groom` — a per-repo
+breakdown of technical impact.
+
+```markdown
+## Technical Notes
+
+### [repo-name]
+- **Affected Components:** [specific files, classes, services, or modules]
+- **What Changes:** [brief description of the changes needed in this repo]
+- **Database/Migration:** [schema changes / migrations, additive vs breaking; "None" if N/A]
+- **API Contract:** [new/changed endpoints, request/response models; "None" if N/A]
+- **Testing Strategy:** [test types + specific areas to cover]
+- **Risk:** [Low / Medium / High — with a brief why]
+
+### [another-repo-name]
+- ...
+
+### Cross-Repo Considerations
+[Only when the story spans multiple repos: deployment order, shared contracts,
+feature flags needed for safe independent rollout.]
+```
+
+## Guidelines
+
+**Affected Components** — name the actual classes/services/config files.
+`AuthenticationService.cs`, `SamlConfigurationProvider.cs` — not "the auth
+module."
+
+**What Changes** — 1–3 sentences on the nature of the change, not the
+implementation steps. Developers work out the how; they need the what.
+
+**Database/Migration** — note additive (safe to deploy independently) vs
+breaking (needs coordinated deploy), and any data-migration concern.
+
+**API Contract** — new endpoint, modified contract (breaking vs non-breaking),
+or deprecation.
+
+**Testing Strategy** — specific, not "add unit tests." e.g. "Unit-test the new
+validation; integration-test the full feature flow against the test env."
+
+**Risk** — Low = straightforward, well-understood. Medium = some complexity or
+uncertainty. High = significant regression/data/cross-system risk. Always
+explain the rating.
+
+**Cross-Repo Considerations** — deployment order, shared models/contracts to
+align, feature flags for independent deploys.

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

@@ -0,0 +1,30 @@
+---
+name: workflow-status
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  Read-only dashboard of ai-sdlc-harness runs in this workspace. USER-ENTRY —
+  invoke only when the user explicitly runs /workflow-status; never
+---
+
+
+# workflow-status (read-only)
+
+1. `bin/harness status` — every run: cursor, mode, work item, task statuses,
+   decided gates, flagged-event count. An `aborted` field marks a run ended
+   by the abort verb (terminal); an `error` field marks a run whose state
+   failed integrity verification (its `remediation` names the reseal
+   command) — the rest of the dashboard still renders.
+2. Render it as a compact table for the user; for a run they ask about,
+   drill in with `bin/harness show --run <run>` plus the ledgers
+   (`events.ndjson` — the "what happened" trail; `tokens.ndjson` — spend)
+   and compose the per-task timeline: status + review rounds + stalls +
+   flagged events + gate evidence.
+3. Offer `bin/harness metrics --run <run>` — regenerates
+   `reports/metrics.md`, the human-readable table view of the same ledgers
+   (timings, tasks, verdicts, aggregated tokens, flagged events). Works at
+   any live step, not just the terminal metrics step; it's a deterministic
+   projection, so regenerating is always safe.
+4. Otherwise STRICTLY read-only: no state changes, no cursor moves, no
+   ledger writes — the report above is the one derived, regenerable output;
+   everything else only reads what the authority already records.

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

@@ -0,0 +1,97 @@
+---
+name: workspace-config
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  Change one config section (overrides / provider / language / repos) on an
+  already-bootstrapped workspace, without re-running the full /init-workspace
+  interview. USER-ENTRY — invoke only when the user explicitly runs
+  /workspace-config; never autonomously, never from a subagent
+---
+
+
+# workspace-config
+
+Every command below is `bin/harness <verb> …` — run it
+yourself via Bash. Never ask the user to type a `harness` command; the user
+only answers the questions below.
+
+Not this skill's job: **registering a brand-new repo** (that's `/add-repo` —
+discovery, duplicate-name/path refusal, permission-allowlist refresh; this
+skill only *changes* an already-registered repo's path/name/`test_cmd`), and
+**first-time setup** (`/init-workspace`'s interview).
+
+## 0 · Confirm the workspace is actually bootstrapped
+
+Read `.claude/context/overrides.yaml`. Missing, or no `bootstrap_completed`
+key: `/init-workspace` never finished — stop and send the user there.
+Proceeding anyway reports "the change is live," and the user only learns
+otherwise later, at a confusing `bootstrap incomplete` refusal the next
+time `/dev-workflow` runs.
+
+## 1 · Ask which section, and what's changing
+
+- `overrides` — any top-level key in `config/defaults/*.yaml` other than
+  `provider`/`repos`/`language` (`status_mapping`, `subagent_models`,
+  `quick_mode`, `naming` + `change_types`, `review_rounds`, `stall`,
+  `repo_map` staleness N, `review_policy`, `security.scan_cmd`/
+  `severity_order`, …). Most single-setting changes land here.
+- `provider` — work-item/git provider + specifics (`stories_dir`,
+  `github_repo`, `ado_org`, `ado_project`, …).
+- `language` — per-repo `test_cmd`, under `language.repos.<name>` (not the
+  whole-workspace `test_paths`/`test_closure`).
+- `repos` — repointing or renaming an *existing* entry's path.
+
+## 2 · Read the current section before writing it
+
+`overrides` deep-merges — a call only needs the keys actually changing:
+`init-section --section overrides --json '{"quick_mode": {"loc_max": 50}}'`.
+Exception: a **list**-valued key (`review_policy` is the only shipped one)
+still replaces wholesale — dicts recurse, list items don't — so resend the
+whole list, including entries you're not changing, or one silently vanishes.
+
+`provider`/`language`/`repos` are full-**replace**: the write IS the whole
+file. Read `.claude/context/<section>.yaml` first (Read tool, never a Bash
+one-liner), splice in the change, resend the **complete** set — a partial
+payload, or a forgotten self-nesting (`{"repos": {...}}` — `overrides` is
+the one flat, non-nested exception), silently drops every entry you didn't
+restate. For `repos`/`language` this is NOT caught by `init-verify` if it
+zeroes the whole map (step 4 covers what verify does check).
+
+**Known gap**: `overrides` only adds/updates keys, never unsets — removing
+one needs a direct edit to `overrides.yaml`; say so rather than improvising.
+
+## 3 · Confirm a `test_cmd` change by running it, and mind two risks
+
+Confirm any `test_cmd` change by actually running it in that repo — same
+rule `/add-repo`/`/init-workspace` follow, never accept it unconfirmed.
+
+**Known risks**: (1) `init-section --section repos` has none of `/add-repo`'s
+collision checks — a duplicate name (case-insensitive: collides on-disk on
+a case-insensitive filesystem) or a path under two names (misattributes
+`test_cmd`/`scan_cmd`) writes cleanly; check the full map yourself before
+sending it. Renaming also orphans `language.repos.<old-name>`,
+`security.scan_cmd.<old-name>`, and `.claude/context/repo-map/<old-name>/`
+— carry them to the new name or tell the user to. (2) Avoid repointing a
+path or changing a `test_cmd` while a `/dev-workflow` run has in-flight
+tasks against that repo — resolution is by exact registered path, so a
+run mid-flight can start failing with a confusing "no test command" error.
+
+## 4 · Re-verify if the section could affect verify or permissions
+
+`init-verify` covers `provider`, `repos` (≥1 registered, each a real git
+checkout), and `language` (`test_cmd` runnability) — **not** `overrides`.
+
+- `provider` only: re-run `init-verify`, fix any failure.
+- `repos` (a path) or `language` (a `test_cmd` binary): re-run `init-verify`,
+  **then** `init-finalize` too — that's what refreshes the permission
+  allowlist (`Read` on the repo path, `Bash` on the `test_cmd` binary) to
+  the new value; skip it and the OLD path/binary stays allow-listed while
+  the new one doesn't, so a background/`mode:auto` run hits an unprompted
+  permission stall the first time it touches the changed repo.
+- `overrides` only: no re-verify/re-finalize needed.
+
+## 5 · Tell the user what changed
+
+State the section, the exact keys written, and (if re-verified/re-finalized)
+the result.

package/.opencode/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["@opencode-ai/plugin", "node"],
+    "strict": true,
+    "noEmit": true
+  },
+  "include": ["plugins/**/*.ts"]
+}