@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/planning-preflight/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: planning-preflight
+user-invocable: false
+version: 1.1.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal planning gate: consumes the normalized repository state and makes
+  the ONE final architectural classification, using a two-stage contract that
+  allows a lightweight NRS read during planning and a full architectural
+  classification after the plan is cut. Used by plan-feature,
+  plan-feature-from-issue, plan-feature-scaffold, and plan-fix. Not a menu entry.
+---
+
+# Planning Preflight (internal)
+
+The single owner of the planning-side repository gates. `plan-feature` and
+`plan-fix` consume this one contract instead of each internal repeating its own
+normalized-state read and architectural classification.
+
+This skill uses a **two-stage contract** to resolve the tension between:
+(1) the need for planners to read the NRS early (architecture discovery is
+    read-only and required to inform the plan), and
+(2) the requirement that the final architectural classification only happens
+    after the complete engineering plan exists.
+
+## When to use
+
+Any planner route that can write planning artifacts:
+
+- `plan-feature` — every route that will scaffold (scoped, issue, `--next`).
+- `plan-fix` — every fix-SPEC draft.
+
+Composed internals (`plan-feature-from-issue`, `plan-feature-scaffold`)
+consume the same result via the in-turn planning context the router creates;
+they never re-run discovery or classification.
+
+## Two-Stage Contract
+
+### Stage 1 — NRS read during planning (lightweight)
+
+While the plan is still being built, routers may perform a read-only consumption
+of the normalized repository state (NRS) for architectural context. At this
+stage only the NRS port is classified; the architectural classification is
+deferred.
+
+Record the Stage 1 result using the following format:
+
+```text
+Preflight: Stage 1 — NRS <consumed|n/a> · arch: deferred
+```
+
+This result informs the plan but does not block emission.
+
+### Stage 2 — Full classification after plan cut (final)
+
+Once the complete engineering plan exists (the SPEC is filled and the phases
+are cut), run the FULL architectural classification exactly once per plan —
+never per-composed-internal.
+
+Discover the optional project invariant document declared in the documentation
+map (normally `docs/architecture/ARCHITECTURAL_INVARIANTS.md`). If absent,
+record `n/a: no project invariants declared` and pass. For every applicable
+rule, cite its ID and repository evidence and classify the planned change as
+`preserves`, `violates`, `introduces`, or `changes`. Only `preserves` may
+reach emission. A violation, new rule, or changed rule stops for an explicit
+architectural decision through the project's declared authority; never convert
+it into an engineering task or infer approval from the SPEC. Use frozen NRS
+facts when available, but repository inspection remains authoritative.
+
+Record the Stage 2 result using the following format:
+
+```text
+Preflight: NRS <consumed|n/a> · invariant classification: <preserves|violates|introduces|changes> (n/a when no invariants declared)
+```
+
+### When to run Stage 2
+
+Run Stage 2 immediately after the engineering plan is complete and before the
+router emits artifacts. This is the gate that decides whether the plan can be
+emitted or must stop for an architectural decision.
+
+Stage 2 must also run whenever a previously-passed plan is re-validated after
+the engineering plan changes (e.g., a new phase was added or the SPEC was
+expanded). In that case, re-run only the invariant rules that may have been
+affected by the change.
+
+## Step 0 — Consume the normalized repository state
+
+When `docs/workflow/REPOSITORY_STATE.md` exists, plan from its frozen facts and
+decisions. An absent fact may be inspected; a conflict is a resolver
+contradiction, never a rewrite. Planned work and documentation are not
+implementation evidence. A present ledger whose status is `draft`,
+`contradicted`, or `resolved` stops planning and routes to discovery or
+resolution first. If no ledger exists, inspect the repository directly and
+record `n/a: no normalized repository state`; NRS is optional.
+
+## Result — fixed classification record
+
+Return exactly one line back to the router:
+
+- **Stage 1** (while planning):
+
+```text
+Preflight: Stage 1 — NRS <consumed|n/a> · arch: deferred
+```
+
+- **Stage 2** (after plan is cut, final gate):
+
+```text
+Preflight: NRS <consumed|n/a> · invariant classification: <preserves|violates|introduces|changes> (n/a when no invariants declared)
+```
+
+`preserves` (or `n/a: no project invariants declared`) → the router proceeds to
+emit the artifacts and register the roadmap/fix entry. Any other classification
+→ STOP with the fixed ARCHITECTURAL INVARIANT GATE BLOCKED block:
+
+```text
+→ Next: resolve the architectural decision first — <rule-id>: <classification> (<evidence>).
+  Run /design-feature or the project's declared decision authority; do not convert this into a phase task.
+```
+
+## Guardrails
+
+- One classification per plan, taken after the engineering plan exists — never
+  in each composed internal.
+- Never let the SPEC, a passing test, or a roadmap row infer the decision.
+- Docs only — no code, no branch, no forge writes.
+- Two-stage contract: Stage 1 is lightweight NRS read; Stage 2 is the final
+  architectural gate. Stage 2 supersedes Stage 1 for emission decisions.

package/skills/product-audit/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: product-audit
+user-invocable: true
+disable-model-invocation: true
+version: 3.1.0
+metadata:
+  opencode/autoinvoke: false
+argument-hint: <path-or-area> (optional — defaults to the whole product)
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Audit the whole product across code, quality, process, docs, roadmap, and
+  tooling. Persist one severity-ranked, F-numbered report with proposals; never
+  fix or file work. Triggers: "product-audit", "audit the product", "full health
+  check", "are we product-ready", "CTO review".
+---
+
+# Product Audit
+
+Product-wide health check. It only writes
+`docs/audits/<n>-<YYYY-MM-DD>.md`; every proposed action remains a user decision.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The full PRODUCT AUDIT report was printed in the fixed output format (health by dimension, F-numbered ranked findings, four proposal streams — the roadmap streams always present, `none — <why>` when empty)
+✓ The report was WRITTEN to `docs/audits/<n>-<YYYY-MM-DD>.md` (incremental audit id) and committed — the file is the durable deliverable, the chat print is a copy
+✓ Nothing else was fixed, filed, or changed — the report file is the ONLY mutation
+✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
+```
+
+About to end the turn with any box unchecked? The turn is NOT done — complete
+the missing box first (weak models drop end-of-document duties; this list is
+first on purpose).
+
+## When to use
+
+- Periodically (every few features) or at a product-ready milestone.
+- When you want the broad, honest picture — quality, security, debt, docs, and
+  roadmap — not the review of a single change (`review-change`) or PR (`audit-pr`).
+
+Unlike diff, PR, or docs-only reviews, this skill covers the whole product.
+
+## Scope
+
+The entire codebase and its process artifacts: source, tests, the docs tree, the
+roadmap, the fix index, open issues, and every feature folder's planning docs.
+Accept an optional path/area to focus a partial audit; state the scope and, if you
+sample rather than exhaust a dimension, **say what you sampled** — never imply full
+coverage you didn't do.
+
+> **Tip (provisional).** The *user* can turn on `ultracode` (a research-preview
+> Claude Code session setting — no skill can declare it) so this sweep fans out
+> across parallel subagents instead of one context window; without it, sweep the
+> dimensions sequentially — only wall-clock changes, never coverage.
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then read
+what THIS skill needs: the roadmap, the fix index, the feature folder layout, and
+the verification gate. From the map decide the product's nature (web / mobile /
+console / library / backend / infra). Defer deciding which dimensions apply until
+`AUDIT_DIMENSIONS.md` has been loaded; that resource is the authoritative
+applicability matrix. Note any optional platform review skills the project
+installed (extras, never requirements — the internal pack covers every axis).
+
+## Progressive loading — audit route
+
+The reference allowlist is exactly the two paths below. Load both after Step 0,
+in order; they are normative and one hop from this entrypoint.
+
+1. Read [audit dimensions](references/AUDIT_DIMENSIONS.md), mark every dimension
+   applicable or `n-a: <reason>`, and state any sampling.
+2. Read [audit process](references/AUDIT_PROCESS.md), execute all ten steps, then
+   return the fixed report below.
+
+A missing resource stops the audit; never reconstruct it from memory. Optional
+platform review skills remain extras, never replacements for the internal pack.
+
+## Output format
+
+This exact structure is BOTH the persisted file (`docs/audits/<id>-<YYYY-MM-DD>.md`)
+and the chat print — identical content, no free-form variations between runs.
+Every section below appears in every audit; a section with nothing to report
+states `none — <why>` instead of being omitted (the roadmap streams especially:
+"always build the roadmap picture", never silently skip it).
+
+```
+# PRODUCT AUDIT <id> — <product> — <YYYY-MM-DD>
+Scope: <whole product | area>
+Coverage: <dimensions run | sampled vs. exhaustive>
+Verdict: <one-line honest health verdict>
+
+## Health by dimension
+  <dimension> .......... ✓ healthy | ⚠ concerns | ✗ at risk | n-a (why)
+  ...
+  Installed tooling ....... ✓ | ⚠ | ✗ | n-a
+
+## Findings (severity-ranked, one F-sequence for the whole audit)
+  F1 [SEV] <dimension> — <finding> — evidence: <file:line | metric | doc> — class: <fix-now|postpone|tradeoff>
+  F2 [SEV] ...
+  [example — scope-export recurrence] F<k> [med] Workflow discipline — <N>
+    consecutive units exported scope via `## Amendments`/descope issues —
+    features are being cut too big for real capacity — evidence: <unit list +
+    amendments/issues> — class: postpone — route: #64 (atomicity/split rules)
+
+## Delta vs audit <prior-id>
+  New: F<k>
+  Unchanged: F<k> <- audit <prior-id> F<j>
+  Resolved: <prior-id> F<j>
+  (none — <why no equivalent-scope prior exists>)
+
+## Proposals — the user decides which to act on
+
+### Issues to open
+  - <title> [sev] — from: F<k>[, F<j>] — <why> — route: /triage-issue <id> F<k> — evidence: <…>
+  (none — <why>)
+
+### Roadmap — add
+  - <feature> — from: F<k> — <rationale & opportunity> — route: plan-feature
+  (none — <why>)
+
+### Roadmap — remove / revise
+  - <feature> — from: F<k> — <why it no longer fits> — route: triage-issue / roadmap edit
+  (none — <why>)
+
+### Tooling — register / re-design
+  - <skill|MCP> — register in CLAUDE.md (Optional review extras): <why> — route: user edits CLAUDE.md
+  - <skill|MCP> — would change <feature> scope: <why> — route: /design-feature <slug>
+  (none — <why>)
+
+## Manual-verification checklist (what automation can't confirm)
+  - <item> …
+
+Finding set: F<k> + F<j> + F<m> (print every proposed finding; one finding → F<k>)
+→ Next: /triage-issue <id> F<k> F<j> F<m> — classify the complete finding set in one batch (opens the ones that warrant it)
+  · accepted bug/debt → /plan-fix   · accepted capability → /plan-feature
+  · nothing to act on → the persisted report is the record; move on
+```
+
+Replace every finding placeholder with the complete actual set before printing;
+never print `…` or only the first finding in a live hand-off.
+
+`<id>` is the audit's incremental number (Process step 9). A finding is
+addressable forever as `<audit-id> F<k>` — e.g. `triage-issue 3 F2` reads
+`docs/audits/3-*.md`, locates F2, and opens/classifies the issue if warranted.
+Suggest that routing; **never run triage or open issues here**.
+
+Lead with the honest one-line health verdict (e.g. "shippable with 2 high-sev
+security items to track first").
+
+## Guardrails
+
+- **Never auto-fixes, never opens issues, never edits the roadmap.** Output is a
+  report + proposals; **every action is the user's decision.** The one file this
+  skill writes is its own report under `docs/audits/` (plus `mkdir -p
+  docs/audits`) — nothing else in the repo is touched.
+- **Finding ids are `F1, F2, …` only** — one sequence per audit, severity-ranked
+  order, never a different letter per problem type. Once persisted, ids are
+  frozen: a later audit gets a new audit id, never renumbers an old file; cross-audit
+  lineage lives only in Delta mappings as `<audit-id> F<k>`, never global slugs or
+  replaced ids. When the user accepts, route: `triage-issue` files/classifies,
+  `plan-feature` adds roadmap work, `plan-fix` scopes a concrete fix.
+- **Never registers tooling or edits `CLAUDE.md`.** The tooling sweep proposes a
+  skill/MCP to register, but the user (or a routed `design-feature` run)
+  performs the edit; a scope-affecting discovery routes to
+  `/design-feature <slug>`, which the user approves.
+- Platform-adaptive: run only applicable axes; always list what you skipped and why.
+- **No silent caps.** If you sampled, prioritized, or time-boxed a dimension, say
+  so — never present partial coverage as exhaustive.
+- Severity-ranked and deduped: cluster the same issue found via multiple axes or
+  multiple feature docs into one proposal.
+- Honor the project's **Workflow conventions** (docs-language, evidence): every
+  finding/proposal cites a `file:line`/metric/doc/issue source; mark uncertainties *verify*.
+- **Evidence also passes the fixed evidence-provenance gate** in
+  `references/AUDIT_PROCESS.md`; uncertainties stay marked *verify*.
+
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
+  literally, in a fresh conversation: hand-offs assume a clean context.
+- **No per-skill `model:`/`effort:`** — this is the widest, highest-stakes
+  sweep in the workflow: run it on your **strongest** model at its deepest
+  setting, as its own dedicated run — never squeezed into another task's
+  context.
+- **No `ultracode`/subagents** — sweep the dimensions sequentially (see the
+  tip above); state coverage honestly either way.
+
+## Relationship to other skills
+
+```
+product-audit (whole product, all axes, periodic)
+   ├─ composes review-change axes (codebase-wide) + audit-docs (doc coherence)
+   ├─ mines feature docs (decisions / known-issues / architecture-notes)
+   ├─ sweeps installed skills / connected MCP servers (product-wide, periodic)
+   └─ proposes ─┬─ Issues to open ........ ▶ triage-issue / plan-fix
+                ├─ Roadmap: add .......... ▶ plan-feature
+                ├─ Roadmap: remove/revise  ▶ triage-issue / roadmap edit   (user decides)
+                └─ Tooling: register/re-design ▶ user edits CLAUDE.md / design-feature
+```
+
+- Broader than `review-change` (one change) and `audit-pr` (one PR); subsumes
+  `audit-docs`'s coherence check as one of its dimensions.
+- Hands nothing off automatically — it recommends, and the planning/fix/triage
+  skills execute only when the user chooses to.
+
+## Done when
+
+- Every applicable dimension has a health verdict backed by cited evidence, and the
+  skipped or sampled ones are stated.
+- A severity-ranked, **F-numbered** findings list plus four proposal streams
+  (issues to open, roadmap add, roadmap remove/revise, tooling
+  register/re-design) exist — every stream present (`none — <why>` when empty),
+  deduped, each proposal routed and citing its source findings.
+- The report is **persisted and committed** as `docs/audits/<id>-<YYYY-MM-DD>.md`
+  with the next incremental audit id, and printed in chat.
+- Nothing else was fixed, filed, or changed — the user decides what to act on.
+- The **closing `→ Next:` block is printed** — typically a batch
+  `/triage-issue <id> F<k> …` for the proposed issues, then `/plan-feature` /
+  `/plan-fix` for the accepted work.

package/skills/product-audit/references/AUDIT_DIMENSIONS.md

@@ -0,0 +1,24 @@
+## Audit dimensions (platform-adaptive — run only what applies)
+
+| Dimension | What it sweeps product-wide | Applies to |
+|---|---|---|
+| **Correctness & architecture** | Bugs, layer/boundary violations, dead code, overengineering, drift from the architecture doc | all |
+| **Security & cybersecurity** | Secrets in repo, authz gaps, input validation, dependency / supply-chain risk | all |
+| **Performance** | Hotspots, complexity, N+1s, bundle/asset weight (web), resource leaks | all |
+| **Tests** | Coverage of critical paths, missing/!flaky tests, untested failure modes | all |
+| **UX / UI** | Design-system adherence, broken states, inconsistency | web / mobile / TUI |
+| **Accessibility** | a11y conformance for user-facing surfaces | web / mobile |
+| **SEO** | Indexability, metadata, structured data | web |
+| **Brand / voice** | User-facing copy vs. the brand guide | surfaces with copy |
+| **Tech debt** | Accumulated shortcuts, TODO/FIXME, stale abstractions | all |
+| **Process & docs** | Incomplete phases, aging open issues, **solvable known-issues**, doc completeness, missing/optimizable workflow docs, capability-inventory freshness (`docs/CAPABILITIES.md` ↔ code drift) | all |
+| **Workflow discipline** | The workflow's own rules held: branch/PR discipline, `done · #<pr>` links, phase naming (`P1…`), per-phase docs, commit format, dependency closures, artifact language — **run `audit-docs` checks 1–13 mechanically** (compose it); never assume a rule held because it "should". **Scope-export recurrence:** across the most recent units (merged or in-flight), each with a non-empty `## Amendments` descope log or a descope-classified born issue (`audit-pr`'s scope-bleed gate) counts as one scope-exporting unit — **≥ 2 consecutive** such units is a planning-quality finding ("features cut too big for real capacity"), routed to the atomicity/split rules (**#64**), not re-litigated as a per-unit defect | all |
+| **Roadmap coherence** | Stale/obsolete/superseded features, missing dependencies, gaps & opportunities | all |
+| **Installed tooling** | Installed skills + connected MCP servers vs. the project's applicable axes and roadmap features — unregistered-but-useful items, and tooling that would change a feature's scope | all |
+
+Skip inapplicable axes (no a11y/SEO/brand for a CLI/library/infra product) and
+**say which you skipped and why**. Every axis is covered by the workflow's own
+internal review pack (`review-code`, `review-security`, `review-verify`,
+`review-debt`, `review-design`, `review-a11y`, `review-brand`, `review-perf`,
+`review-seo`) — installed with the workflow, so an applicable axis can never be
+"missing". Platform skills the project installed run as optional extras on top.

package/skills/product-audit/references/AUDIT_PROCESS.md

@@ -0,0 +1,85 @@
+## Process
+
+1. **Map & decide axes** — Step 0; mark each dimension applicable / n-a.
+2. **Sweep code & axes** — run the applicable axes across the codebase: compose
+   `review-implementation` plus the internal review pack's applicable passes
+   (each returns its fixed-format table + PASS|FAIL), and any optional installed
+   extras. Classify findings (severity + fix-now / postpone / tradeoff).
+
+**Evidence-provenance gate (fixed):** applies during every evidence-collecting sweep
+step (2–5). Each item ends with exactly one fallback; never pick another one mid-audit.
+
+- Forge state — read live status from the project-declared forge CLI/API: it is
+  authoritative for live issue and pull-request status. Fix-index, worklist and roadmap rows
+  are audited for documentation drift, never treated as the live ledger.
+  Fallback: `mark unverified`.
+- Command-derived metrics — bind the exact command plus its working directory or target and the
+  supporting output line or structured field; an aggregate terminal summary may never be attributed
+  to a narrower scope without a scope-bound rerun. Fallback: `rerun in scope`.
+- Repository inventories — ordered or inventory claims ("decisions through N", "the newest row is
+  X") are recomputed from the current tree with project-compatible tools, citing the terminal
+  path/item found. No hardcoded product names, package managers, runtimes, forge hosts, or
+  non-portable shell recipes inside this portable contract. Fallback: `rerun in scope`.
+- Freshness/timestamps — record when each source was captured and by what method; a stale capture
+  older than the current tree is recomputed before use. Fallback: `mark unverified`.
+- Conflicting sources — resolve by declared authority order (live forge > scope-bound command
+  output > repository inventory > worklist index) and record the winner next to the claim.
+  Fallback: `mark unverified`.
+
+3. **Audit process & docs** — incomplete phases (`progress.md`/`TASKS.md`), aging
+   open issues, **solvable known-issues** (trigger now met), doc-map completeness
+   (compose `audit-docs`), missing/optimizable workflow docs, and **capability
+   inventory freshness**: cross-check `docs/CAPABILITIES.md` against the code —
+   roles, permissions, or cross-cutting subsystems present in the code but
+   missing from the inventory (or vice versa) are a Process & docs finding
+   (`design-feature`'s Integration closure is only as good as this file). If
+   the project has no inventory file, propose seeding it from the template —
+   a finding, never an auto-fix.
+4. **Mine accumulated suggestions** — read every feature folder's `decisions.md`,
+   `known-issues.md`, and `architecture-notes.md`; extract deferred items, open
+   questions, and recorded debt. Cluster duplicates across features.
+5. **Sweep installed tooling** — (a) inventory the installed skills and
+   connected MCP servers available to the agent; (b) cross-reference each
+   against the applicable review axes and the roadmap features; (c) classify
+   each as **register** (useful, not yet named in the project's `CLAUDE.md`),
+   **re-design** (would change a feature's definition/scope), or
+   **not-relevant**; (d) dedupe against what `CLAUDE.md` already registers —
+   only unregistered/relevant items survive into proposals. If the agent
+   cannot enumerate its installed skills / connected MCPs, say so plainly
+   (no silent caps) rather than inventing an inventory.
+6. **Synthesize proposals** — turn findings + mined items into four concrete,
+   deduped, severity-ranked streams:
+   - **Issues to open** — bugs, debt, security/perf items worth tracking.
+   - **Roadmap: add** — features/capabilities the evidence now justifies.
+   - **Roadmap: remove or revise** — features that are obsolete, superseded, or no
+     longer make sense.
+   - **Tooling: register or re-design** — unregistered-but-useful tooling to add
+     to `CLAUDE.md`, or a discovered skill/MCP that would rescope a feature.
+7. **Number the findings.** Assign every finding in the severity-ranked list a
+   sequential id `F1, F2, …` — **one single `F` sequence for the whole audit**,
+   in ranked order, regardless of dimension. Never use a different letter per
+   dimension or per severity; `F` is the only prefix. Proposals reference the
+   finding ids they derive from (`from: F3, F7`).
+8. **Delta vs prior audit of equivalent scope** — only after the findings are
+   synthesized and numbered on your own (step 7), load the newest previous audit
+   in `docs/audits/` with an equivalent scope (whole product, or the same
+   declared area) and fill the `## Delta vs audit <prior-id>` section: **New** =
+   an `F<k>` here with no counterpart there; **Unchanged** =
+   `F<k> <- audit <prior-id> F<j>`; **Resolved** = a prior finding no longer
+   present. Two audits have equivalent scope when they cover the same product or
+   the same area. No equivalent-scope prior exists → the section body is
+   `none — <why no equivalent-scope prior exists>`. Re-auditing the same scope on
+   the same date is allowed when it states a reason plus this delta — a rerun is
+   not forbidden by date alone.
+9. **Persist the report** (the only mutation this skill makes):
+   - Compute the audit id: `mkdir -p docs/audits`, then next id =
+     highest `<n>` among existing `docs/audits/<n>-*.md` files + 1 (first audit
+     → `1`). Plain incremental integer, no zero-padding.
+   - Write the full report (the exact fixed format below, delta section included)
+     to `docs/audits/<id>-<YYYY-MM-DD>.md` (today's date).
+   - Commit it on the current branch with
+     `docs(audits): product audit <id> <YYYY-MM-DD>` (and push if the project's
+     conventions push on commit). If the working tree carries unrelated
+     uncommitted changes, stage **only** the report file.
+10. **Report** — print the same report in chat. Recommend; do not act: filing
+   the proposed issues is `triage-issue`'s job (suggest it, never run it).

package/skills/resolve-repository-state/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: resolve-repository-state
+user-invocable: true
+version: 1.2.0
+argument-hint: <contradiction-id>
+description: >
+  Resolve an explicit Normalized Repository State contradiction. This is the
+  sole writer allowed to update frozen repository facts or accepted decisions.
+  Triggers: "resolve repository state", "resolve contradiction", "update a
+  frozen repository fact".
+---
+
+# Resolve Repository State
+
+Resolve evidence conflicts explicitly and publish the next frozen snapshot.
+
+## Turn contract
+
+```
+✓ A named contradiction and both evidence sources were read
+✓ The disposition is accepted, rejected, or needs-input
+✓ Accepted/rejected results publish a frozen snapshot; needs-input stops without freezing
+✓ No unrelated fact or decision changed
+✓ The closing → Next: block is printed last
+```
+
+## Step 0 — Discover the project (always first)
+
+Read the agent guide, documentation map, frozen ledger, and the requested
+contradiction before deciding anything.
+
+## Process
+
+1. Read the frozen ledger and the contradiction row named by the user.
+2. Verify both the frozen fact's evidence and the proposed new evidence.
+3. Choose one result: accept new evidence, reject it, or request human input.
+4. If human input is required, update the contradiction row with the exact
+   missing evidence or decision, keep snapshot status `contradicted`, and stop
+   without incrementing the snapshot identifier or publishing a frozen snapshot.
+5. For an accepted result, supersede the fact or decision with a new row that
+   cites both evidence sources. For a rejected result, retain the fact and
+   record why.
+6. For accepted or rejected results only, update the contradiction row,
+   increment the snapshot identifier, set status to `frozen`, and record the
+   next frozen snapshot's source revision.
+
+## Guardrails
+
+- This skill is the sole writer for updates to frozen facts and accepted decisions.
+- A consumer may propose a contradiction but never resolve it inline.
+- Inference and documentation alone are insufficient to update a fact.
+
+## Portability
+
+Without a slash menu, open this file and follow its process in a fresh turn.
+
+## Relationship to other skills
+
+Consumes contradictions from every workflow role and produces the snapshot that
+discovery, planning, execution, review, and audit reuse. The contradiction's
+`Reported by` field identifies the interrupted role to resume; resolution never
+defaults a review, audit, or status interruption to planning.
+
+## Done when
+
+The contradiction has a recorded disposition, and either the next frozen
+snapshot is internally consistent or the missing human input is explicit.
+
+If human input is required:
+
+→ Next: provide the requested evidence or decision — resolution cannot continue yet
+  · evidence supplied → rerun /resolve-repository-state <contradiction-id>
+
+Otherwise:
+
+→ Next: resume the interrupted workflow named by `Reported by` — continue from the resolved snapshot
+  · planning was interrupted → /plan-feature <slug>
+  · implementation was interrupted → /execute-phase <NN>
+  · review, audit, or status was interrupted → rerun that same skill

package/skills/review-a11y/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: review-a11y
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal accessibility review pass of the agentic-workflow review pack —
+  composed in-turn by review-change and product-audit; not a menu entry.
+  Checks the changed user-facing surface for accessibility: semantics,
+  keyboard, focus, contrast, and ARIA correctness — applies only to
+  user-facing surfaces. Findings only; never edits code.
+---
+
+# Review Accessibility (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+✓ Semantic elements over generic ones (button not clickable div; headings in order; landmarks present)
+✓ Every input has an associated label; every image an alt (empty alt only when decorative)
+✓ Full keyboard operability of the changed surface (tab order, Enter/Space activation, Escape to dismiss)
+✓ Focus management on dynamic changes (modals trap + restore focus; route changes move focus)
+✓ Contrast of changed text/UI meets the project's declared level (default WCAG AA) — cite computed values where checkable
+✓ ARIA used correctly and only when semantics can't do it (wrong ARIA is a major finding)
+✓ No information conveyed by color alone
+✓ Motion/animation respects reduced-motion preferences (n/a if no motion added)
+✓ Error messages programmatically associated with their fields
+
+## Return exactly
+
+```
+REVIEW ACCESSIBILITY — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/review-brand/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: review-brand
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal brand & copy review pass of the agentic-workflow review pack — composed
+  in-turn by review-change and product-audit; not a menu entry. Checks changed
+  user-facing copy against the project's brand doc: voice, terminology, and
+  honesty of claims — applies only to surfaces with user-facing text. Findings
+  only; never edits code.
+---
+
+# Review Brand & Copy (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+- ✓ Read the project's brand doc first (e.g. `docs/brand/BRAND.md`) — cite the
+  rule for every finding; n/a all items if the project has none and say so
+- ✓ Tone of changed copy matches the declared voice (cite the guideline violated)
+- ✓ Product/domain terms used consistently with the declared glossary (same
+  concept, same word, same capitalization)
+- ✓ No forbidden/deprecated phrases from the brand doc
+- ✓ Claims are honest: limits, restrictions, and reductions the code enforces
+  are disclosed in the copy (an undisclosed limitation is a major finding —
+  repo hard rule)
+- ✓ Error/empty-state copy is actionable (says what happened and what to do),
+  not blame-y
+- ✓ Consistency across the changed surface and its siblings (same action
+  labeled the same way everywhere)
+- ✓ Placeholder/lorem text absent from the diff
+
+## Return exactly
+
+```
+REVIEW BRAND — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.