bigpowers 2.82.3 → 2.83.0

package/.hermes/skills/audit-plan/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: audit-plan
+model: sonnet
+description: "Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase."
+---
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT_LATEST.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT_LATEST.md && grep -q 'Verdict' specs/PLAN-AUDIT_LATEST.md && echo OK || echo FAIL`

package/.hermes/skills/build-epic/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: build-epic
+model: sonnet
+description: "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work."
+---
+
+# story: e20s05
+
+# Build Epic
+
+Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.
+
+Orchestrates the **build** flow for a single epic: survey → plan tasks → kickoff → TDD → verify → audit → commit → release.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: build_epic` and `active_epic: eNN` before starting.
+>
+> **HARD GATE** — Not on `main`/`master` before step 3 (kickoff-branch).
+
+## Nine steps (`epic_cycle` in state.yaml)
+
+| Step | Skill / action |
+|------|----------------|
+| 0 | `security-review` — threat-model epic scope → `specs/security/epics/<id>/THREAT_MODEL.md` |
+| 1 | `survey-context` — confirm epic + story |
+| 2 | `plan-work` — flesh out story `tasks[]` in `specs/epics/eNN-slug/epic.yaml` |
+| 3 | `kickoff-branch` — feature branch + clean baseline |
+| 4 | `develop-tdd` — red-green per task |
+| 5 | `verify-work` — UAT + mechanical gates |
+| 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) |
+| 7 | `commit-message` — Conventional Commits draft |
+| 8 | `release-branch` — PR or solo land (supports `--squash-state`) | |
+
+## Process
+
+1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
+   - **On story start (step 1):** Write `started_at` ISO 8601 timestamp to `execution-status.yaml` under the story's key in the `stories:` section. The `bp-timing.sh` script already tracks skill-level timings — this is story-level.
+2. **Step 0 — Threat Model:** Run `security-review` against the epic's scope (read from the epic capsule). Output `specs/security/epics/<epic-id>/THREAT_MODEL.md` with surface area, vulnerability categories, risk level, and mitigation guidance.
+3. **Assess Impact (Step 2):** Before writing tasks, run `assess-impact --lightweight` on the proposed change. If the risk score exceeds 7, gate — require a `grill-me` session. Write the impact report to `specs/IMPACT-<epic>-<story>.md`. For net-new code with no existing dependents, skip.
+4. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
+5. **BCP Plus (Step 2, optional):** When the epic capsule carries a `bcp_plus_breakdown` (13-dimension sizing), also carry it into `state.yaml` as `epic_cycle.bcp_plus`. The breakdown maps each of the 13 dimensions to an integer count. NFR dimensions (11–13) that are N/A per the NFR Gate may be set to 0.
+6. If `epic_cycle.step` missing, set to `1`.
+6. Run **only the current step** (resume mode) unless user asked for full auto-run.
+7. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
+8. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
+   - **On story complete (step 8):** Write `completed_at` ISO 8601 timestamp to `execution-status.yaml` under the same story key. Format:
+
+     ```yaml
+     stories:
+       e01s01:
+         status: done
+         started_at: "2026-07-12T16:00:00-03:00"
+         completed_at: "2026-07-12T18:45:00-03:00"
+     ```
+9. **Traceability refresh:** Before step 8 (release-branch), run `bash scripts/trace-stories.sh` to regenerate `specs/traceability-matrix.json`, `specs/TRACEABILITY_LATEST.md`, and the `specs/codebase-wiki/` OKF bundle. Surface dark/orphan/stale findings for the just-built epic in your verify summary. If `scripts/trace-stories.sh` is missing or fails, note "trace skipped" and continue — trace failure must be visible, not silent (blocking is gate-trace's job, e38s06).
+
+9b. **OKF wiki refresh (e39s08):** Before step 8, run maintain-wiki INGEST to refresh the OKF wiki bundle:
+   ```bash
+   bash scripts/decompose-conventions.sh
+   bash scripts/generate-agent-guide.sh
+   ```
+   If any script is missing or fails, note "OKF wiki refresh skipped" and continue.
+   This is non-blocking — stale concepts are caught by LINT in verify-work Phase 3.
+
+### Step 6 — audit-code gate (non-optional)
+
+After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
+
+1. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
+2. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
+3. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
+4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
+5. **Enforce F.I.R.S.T:** After audit-code passes, run `enforce-first --quick` on new/modified tests. Append F.I.R.S.T violations (if any) to the audit report. Failing F.I.R.S.T criteria trigger the same loop-back to step 4.
+
+## --fast mode
+
+Coalesces read-and-report steps to reduce token overhead. Activate with `build-epic --fast`.
+
+| Normal | --fast | Change |
+|--------|--------|--------|
+| Step 1 (survey-context) | 1+2 together | survey + plan in one invocation |
+| Step 2 (plan-work) | (absorbed into 1) | — |
+| Step 3 (kickoff-branch) | Step 2 | unchanged, sequential |
+| Step 4 (develop-tdd) | Step 3 | unchanged, sequential |
+| Step 5 (verify-work) | Step 4 | unchanged, sequential |
+| Step 6 (audit-code) | 5+6 together | audit + commit-message in one invocation |
+| Step 7 (commit-message) | (absorbed into 6) | — |
+| Step 8 (release-branch) | Step 7 | unchanged, sequential |
+
+**Total invocations:** 8 → 6 per story.
+
+**Rules:**
+- Steps 3/4/5/8 (kickoff, develop, verify, release) still run sequentially — they require user interaction or branch state.
+- `--fast` does NOT skip any checklist items; it only coalesces steps that are pure read-and-report.
+- Record `epic_cycle.fast_mode: true` in `state.yaml` when this flag is active.
+
+## Handoff
+
+Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.
+
+## Verify
+
+→ verify: `test -f specs/state.yaml && test -f specs/execution-status.yaml && test -f specs/release-plan.yaml && test -d skills/assess-impact && test -d skills/audit-code && test -d skills/security-review && echo "OK: build-epic dependencies present" || echo "FAIL"`
+
+
+<!-- story: e38s02 -->

package/.hermes/skills/change-request/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: change-request
+model: sonnet
+description: "Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml and epic capsule directories. Modes Add and Reorder. Use when a new requirement arrives mid-release or the plan needs prioritization."
+---
+
+# story: e45s29
+# story: e20s01
+
+# Change Request
+
+> **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first.
+>
+> → verify: `[ -f specs/release-plan.yaml ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+
+Two modes. State which one you want or the skill will ask.
+
+## Mode A — Add
+
+Intake a new requirement mid-flight without disrupting work in progress.
+
+1. **Capture**: What is the change? What problem does it solve?
+2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace?
+3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29).
+4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`.
+5. **Score**: Compute WSJF; note if it outranks in-progress work.
+
+→ verify: `grep -c 'stories:' specs/epics/*/epic.yaml`
+
+## Mode B — Reorder
+
+Value-engineering pass over the full release using WSJF.
+
+See [REFERENCE.md](REFERENCE.md) for the full WSJF scoring rubric.
+
+1. **Score** each epic/story: BV + TC + RR / Job Size.
+2. **Re-sort** `release-plan.yaml` `epics[]` and per-epic `wsjf` fields.
+3. **Flag cut candidates**: WSJF < 1.5.
+4. **Update** `specs/release-plan.yaml` and epic `wsjf` keys with rationale.
+5. **Report** the delta.
+
+→ verify: `grep -c 'wsjf' specs/release-plan.yaml specs/epics/*/epic.yaml`
+
+## Conversational Mode
+
+If the user's request is in natural language and does not match the structured format of Mode A or Mode B, enter Conversational Mode to extract the change parameters through interactive dialogue.
+
+### 5-Step Flow
+
+1. **Capture**: Parse the natural-language request for what, why, and where. Ask at most 3 clarifying questions before drafting.
+2. **Locate**: Identify which epic or capability in `specs/epics/` the request affects or replaces.
+3. **Draft**: Present a structured draft of the proposed story and tasks for user confirmation.
+4. **Score**: Estimate the WSJF score and explain the calculation so the user understands the priority.
+5. **Place**: Confirm the final epic placement with the user before writing files.
+
+## After either mode
+
+Run `bash scripts/sync-status-from-epics.sh`. Suggest `plan-work` or `build-epic` for the top-ranked unstarted story.
+
+---
+
+# WSJF Scoring Reference
+
+Weighted Shortest Job First: **WSJF = (Business Value + Time Criticality + Risk Reduction) / Job Size**
+
+All dimensions scored 1–10 using a Fibonacci-like scale: 1, 2, 3, 5, 8, 10.
+
+## Business Value
+
+| Score | Meaning |
+|-------|---------|
+| 10 | Core revenue path, legal requirement, blocking launch |
+| 8  | Significant user value, major pain point removed |
+| 5  | Notable improvement, medium user segment affected |
+| 3  | Nice-to-have, minor convenience |
+| 1  | Cosmetic or speculative |
+
+## Time Criticality
+
+| Score | Meaning |
+|-------|---------|
+| 10 | Hard deadline (regulatory, contract, launch date) |
+| 8  | Competitive window closing, partner dependency |
+| 5  | Would delay next milestone if deferred |
+| 3  | Flexible, can slip one sprint |
+| 1  | No urgency |
+
+## Risk Reduction (or Opportunity Enablement)
+
+| Score | Meaning |
+|-------|---------|
+| 10 | Eliminates critical architectural risk or enables a new capability |
+| 8  | Reduces a known failure mode or unblocks high-value work |
+| 5  | Moderate risk mitigation or enablement |
+| 3  | Low risk reduction |
+| 1  | No risk relevance |
+
+## Job Size (effort denominator — larger = lower WSJF)
+
+| Score | Meaning |
+|-------|---------|
+| 1  | Hours |
+| 2  | 1 day |
+| 3  | 2–3 days |
+| 5  | 1 week |
+| 8  | 2 weeks |
+| 10 | 1 month+ |
+
+## Cut threshold
+
+Stories with WSJF < 1.5 are cut candidates: high effort, low combined value.
+
+## Example
+
+Story: "Add OAuth login"
+- Business Value: 8 (removes major sign-up friction)
+- Time Criticality: 5 (Q3 launch nice, not hard)
+- Risk Reduction: 3 (minor security improvement)
+- Job Size: 5 (one week)
+
+WSJF = (8 + 5 + 3) / 5 = **3.2** — healthy, implement early.

package/.hermes/skills/commit-message/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: commit-message
+model: haiku
+description: "Reviews working-tree changes, then drafts a Conventional Commits title/body and states the semantic-release version bump a single such commit would imply. Also notes which defensive-code categories were touched. Use when the user wants to commit recent work, prepare a Conventional Commits message, or asks for semantic-release / semver-consistent messaging before git commit."
+---
+
+# Commit Message
+> **HARD GATE** — **HARD GATE** — Commits must follow Conventional Commits spec (type(scope): description). Do NOT use vague messages like 'fix' or 'updates.' The message must explain the 'why,' not the 'what.'
+
+
+## Modes
+
+- Default: standard Conventional Commits message
+- --fix-type: Forces type=fix. Use when commit type is unambiguous.
+
+## What "last chat" means
+
+- **Primary source of truth:** `git status`, `git diff` (unstaged), and `git diff --cached` (staged). Run these in the repo root (or the paths the user changed).
+- **Context:** use the current conversation to summarize *intent* and to spot **breaking** API/behavior changes that diff alone may not show.
+- If the user tracks a session baseline (e.g. branch, tag, or `git stash create` at start), you may `git diff <baseline>..HEAD` plus uncommitted diffs; otherwise use only the index and working tree.
+
+## Quick workflow
+
+1. **Inventory** — List changed paths; group by feature vs chore vs docs vs test-only.
+2. **Decide commit shape** — One atomic commit is ideal. If the diff mixes unrelated concerns, recommend **multiple commits** (each with its own type/scope) before suggesting one message.
+3. **Classify for semantic release** — `fix` → patch, `feat` → minor, **breaking** → major.
+4. **Write the message** — `type(optional-scope)!: description` (see [REFERENCE.md](REFERENCE.md#message-format)). Use `!` or a `BREAKING CHANGE:` footer when behavior contracts change.
+5. **Note defensive-code categories touched** — from CONVENTIONS.md: Rate limit | Retry with backoff | Circuit breaker | Timeout | Graceful degradation
+6. **Note fix-ratio contribution** — Each `fix:` commit counts toward `metrics.commit_ratio.fix` in `specs/state.yaml`. After `release-branch`, `session-state` recalculates the ratio automatically. A high fix rate (>30%) triggers a deploy + smoke-test suggestion.
+7. **Deliver** — Output:
+   - Proposed **full commit message** (title + optional body + footers).
+   - **Release bump** this commit would drive: `patch` | `minor` | `major` | `none`.
+   - Optional `git add …` and `git commit -m` instructions; do **not** run destructive git commands unless the user asked.
+
+## Checklist before finalizing
+
+- [ ] Type matches the **dominant** user-visible outcome (`feat` vs `fix` vs `perf`, etc.).
+- [ ] **Scope** is a short noun in parentheses if it helps (e.g. `fix(api): …`).
+- [ ] Breaking changes are explicit (`!` and/or `BREAKING CHANGE:` in the body/footer).
+- [ ] Description is imperative, lowercase start after the prefix, no trailing period in the title line.
+- [ ] **NO `Co-authored-by` or `Co-Authored-By` footers** — P1 rule (CONVENTIONS.md § Git Attribution). All commits must appear as if authored solely by the human user. The git hook and `land-branch.sh` both block these.
+
+## When not to invent a bump
+
+If the repo uses a custom `@semantic-release/commit-analyzer` preset, note that your bump is **heuristic** and they should match `.releaserc` / `release.config.*`. See [REFERENCE.md](REFERENCE.md#custom-repositories).
+
+## Further reading
+
+- [REFERENCE.md](REFERENCE.md) — Message shape, footers, release mapping, squashing notes.
+
+
+
+## Handoff
+
+Gate: READY -> next: release-branch
+Writes: state.yaml handoff.next_skill = release-branch
+
+---
+
+# Conventional Commits + semantic-style release (reference)
+
+## Message format
+
+From [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/#specification):
+
+```text
+<type>[optional scope][optional !]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- **Scope:** parenthesized noun, e.g. `feat(parser): …`.
+- **Breaking:** `!` before `:` (e.g. `feat(api)!: …`) and/or footer `BREAKING CHANGE: description` (token must be uppercase per spec for that footer name).
+- **Description:** short summary; body explains *why* or migration steps.
+
+Common **types** (not exhaustive): `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore` — as in [Angular / commitlint conventions](https://github.com/conventional-changelog/commitlint).
+
+## Advanced Specification Patterns
+
+### Reverts
+If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body, it should say: `This reverts commit <hash>.`.
+
+```text
+revert: feat(api): add user endpoint
+
+This reverts commit 676104e.
+```
+
+### Breaking Changes
+A breaking change can be signaled by:
+1.  A **`BREAKING CHANGE:`** footer (must be uppercase, at the start of the footer). This is the **most compatible** way to trigger a Major release in `semantic-release` (Angular preset).
+2.  A **`!`** after the type/scope: `feat(api)!: change user response shape`.
+
+**Pro-tip:** For maximum compatibility with all tooling (older and newer), use BOTH the `!` and the `BREAKING CHANGE:` footer.
+
+### Footers (Tokens & Values)
+Footers follow the same `Token: value` pattern as Git Trailers. Common tokens:
+- `Refs: #123`
+- `See-also: docs/ADR-001.md`
+- `Signed-off-by: Name <email>`
+
+**Multi-line footers:** If a footer value spans multiple lines, each subsequent line must be indented.
+
+### Squashing & History
+When using `gh pr merge --squash`, the PR title is usually used as the commit subject. 
+- **PR Title:** MUST follow `<type>(<scope>): <description>`
+- **PR Body:** Content will be moved to the commit body.
+
+## Release Type Mapping (Default Angular Preset)
+
+This table reflects the **out-of-the-box** behavior of `semantic-release` using the `@semantic-release/commit-analyzer` default (Angular) rules.
+
+| Commit pattern | Release | Notes |
+|----------------|---------|-------|
+| `fix:` | **Patch** | Bug fixes |
+| `feat:` | **Minor** | New features |
+| `perf:` | **Patch** | Performance improvements |
+| `any type` + `BREAKING CHANGE:` footer | **Major** | **Mandatory** for Major version bumps in default configs. |
+| `any type!:` (exclamation mark) | **Major** | Supported by modern CC parsers, but use footer for max safety. |
+| `docs:`, `chore:`, `test:`, `ci:`, `refactor:`, `style:` | **None** | Does not trigger a new release by default. |
+
+> **Warning:** While `refactor:` and `style:` improve code, they do NOT trigger a release in the default Angular preset. Use `fix:` if a refactor also fixes a bug, or `feat:` if it adds new behavior.
+
+## Custom Repositories
+
+- Read `release.config.js`, `.releaserc`, or `package.json` → `release` / `semantic-release` config.
+- The **@semantic-release/commit-analyzer** preset may map types differently; prefer **their** rules when they conflict with this reference.
+
+## Squash and PR titles
+
+- If the team squashes on merge, the **PR title** often becomes the single squashed commit subject — it should still follow `type(scope): description` for tooling.
+- `revert:` type and `Refs:` footers are valid patterns; revert handling varies by [tooling](https://www.conventionalcommits.org/en/v1.0.0/#specification).
+
+## Links
+
+- [Conventional Commits — specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
+- [semantic-release — README (commit format & flow)](https://github.com/semantic-release/semantic-release#commit-message-format)
+- Fork pointer: [semantic-release-baby](https://github.com/danielvm-git/semantic-release-baby) (automation and docs align with upstream semantic-release)

package/.hermes/skills/compose-workflow/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: compose-workflow
+model: sonnet
+description: "Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. Use when a project repeats a non-standard skill sequence, or user wants a documented playbook beyond orchestrate-project modes."
+---
+
+# story: e09s01
+# story: e45s27
+# story: e21s04
+
+# Compose Workflow
+> **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified.
+
+
+## Process
+
+1. Interview: goal, phases, which skills, gates between steps.
+2. Write `specs/workflows/<name>.yaml`:
+   - `name`, `command`, `description`, `skills[]`, `verify`
+   - Optional: `args` for skill-specific arguments
+3. Register in state.yaml Active Decisions.
+4. Optional: reference from `orchestrate-project` Ad-Hoc mode.
+
+> **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-<name>.md` markdown format.
+> YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library.
+
+## Terminal-state taxonomy (e45s27)
+
+Every workflow step and `/loop` tick MUST exit with exactly one terminal state:
+
+| State | Meaning | Next action |
+|-------|---------|-------------|
+| `success` | Step verify passed; artifacts written | Advance to next skill in recipe |
+| `no-op` | Nothing to do (already green / already applied) | Skip step; advance |
+| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user |
+| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required |
+
+Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`.
+
+## Standard Recipe Library
+
+Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains.
+Reference them in AGENTS.md so `/command` directly invokes the matching recipe.
+
+| Command | Workflow | Skill chain |
+|---------|----------|-------------|
+| `/check-stack` | check-stack | survey-context → assess-impact → setup-environment |
+| `/ship` | ship | audit-code → commit-message → release-branch |
+| `/tdd` | tdd | develop-tdd → enforce-first |
+| `/code-review` | code-review | audit-code → request-review → respond-review |
+| `/security` | security | audit-code → request-review |
+| `/plan` | plan | survey-context → research-first → plan-work |
+| `/build-fix` | build-fix | investigate-bug → diagnose-root → develop-tdd → validate-fix |
+| `/e2e` | e2e | smoke-test → verify-work |
+
+Add to `AGENTS.md`:
+```
+/check-stack = compose-workflow check-stack
+/ship        = compose-workflow ship
+```
+
+## Verify
+
+→ verify: `ls specs/workflows/*.yaml 2>/dev/null | wc -l | awk '{if($1>=8) print "OK: " $1 " recipes"; else print "FAIL"}'`
+
+See [REFERENCE.md](REFERENCE.md) for template.
+
+---
+
+# Workflow template
+
+```markdown
+# WORKFLOW: <name>
+
+**Trigger:** Use when ...
+
+| Step | Skill | Output | verify |
+|------|-------|--------|--------|
+| 1 | survey-context | state.yaml handoff | ... |
+| 2 | research-first | Prior Art in SCOPE_LATEST.yaml | ... |
+| 3 | plan-work | epics/eNN-*.yaml tasks | ... |
+```

package/.hermes/skills/context7-mcp/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: context7-mcp
+model: haiku
+description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc."
+---
+
+# Context7 MCP
+
+> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data.
+>
+> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
+
+## When to Use
+
+- Setup/configuration questions ("How do I configure Next.js middleware?")
+- Code involving libraries ("Write a Prisma query for…")
+- API references ("What are the Supabase auth methods?")
+- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
+
+## Bounded Retry (max 3x)
+
+| Attempt | Action |
+|---------|--------|
+| 1 | `resolve-library-id` → pick best match |
+| 2 | `query-docs` with selected `libraryId` |
+| 3 | Retry `query-docs` once with refined query (narrower scope) |
+
+After 3 failures, stop and print:
+
+```
+CONTEXT7_UNAVAILABLE
+Reason: <quota|rate-limit|no-match|timeout>
+Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`.
+Do NOT substitute training-data answers without labeling them UNVERIFIED.
+```
+
+## Fetch Cache (ETag-revalidated)
+
+1. **Cache key:** `"<libraryId>:<normalized-query>"` (lowercase, trimmed).
+2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get "<key>"` — exit 0 → use cached body.
+3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`.
+4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it.
+
+`bts docs <lib>` shares the same cache helper when invoked from this skill.
+
+## Process
+
+1. `resolve-library-id` with `libraryName` + full user `query`.
+2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
+3. `query-docs` with `libraryId` + specific question (one concept per call).
+4. Answer using fetched docs; cite library/version when relevant.
+
+## Verify
+
+→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL`