bigpowers 2.84.0 → 2.85.0

package/.agents/skills/audit-code/SKILL.md

@@ -95,6 +95,10 @@ bash scripts/lib/parallel-review-worktrees.sh audit-code
 - [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable
 - [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)
 
+### Refactoring Smells (Fowler)
+
+Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.
+
 ### Code Style (CONVENTIONS.md)
 
 - [ ] Functions: 4–20 lines; split if longer
@@ -106,13 +110,6 @@ bash scripts/lib/parallel-review-worktrees.sh audit-code
 - [ ] Conditionals: expressed as positives (G29)
 - [ ] Comments explain WHY, not WHAT
 
-### Agent Readability (Akita's Lens)
-
-- [ ] Functions are small enough to fit in a standard context window (4–20 lines)
-- [ ] Names are unique and specific enough to be `grep`-able (grep returns < 5 hits)
-- [ ] Types are explicit (no `any`, no inferred return types for public APIs)
-- [ ] Code avoids deep nesting (max 2 levels) and uses early returns
-
 ### Red Flags
 
 Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.

package/.agents/skills/craft-skill/SKILL.md

@@ -6,7 +6,7 @@ description: "Create new bigpowers skills with proper structure, progressive dis
 
 # Craft Skill
 
-> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md.
+> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh`. Generated `.cursor/rules/` and `.gemini/` artifacts MUST match the source SKILL.md.
 
 ## CSO Description Discipline (e45s02)
 
@@ -21,11 +21,25 @@ The YAML `description` is the **Catalog Selection Object** — the only field ag
 
 Move process detail into the SKILL.md body or REFERENCE.md — never into `description`.
 
+## Agentic STE body discipline (e79s02)
+
+Skill-body instructional prose MUST follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md).
+
+| Rule | Limit |
+|------|-------|
+| Sentence length | ≤20 words per instruction sentence |
+| Voice | Imperative, active |
+| Directive terms | MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT |
+| Banned modals | should, might, could, may, consider, try, generally, typically |
+| Scope | SKILL.md body only — not YAML `description`, not `terse-mode` output |
+
+> **HARD GATE** — Do NOT merge a new or edited skill until `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` exits 0. Fix violations before `sync-skills.sh`.
+
 ## Process
 
 1. **Gather requirements** — ask user about:
    - What task/domain does the skill cover?
-   - What specific use cases should it handle?
+   - Which use cases must the skill handle?
    - Does it need executable scripts or just instructions?
    - Any reference materials to include?
    - What specs/ output does it produce (if any)?
@@ -41,7 +55,8 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
    - Additional reference files if content exceeds 100 lines
    - Utility scripts if deterministic operations needed
 
-   **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source.
+   **Auto-skill from library README:** When user provides a library README or API docs URL, extract triggers and HARD GATEs.
+   Draft verify commands and specs/ output into SKILL.md. Do NOT invent APIs not in the source.
 
 4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md).
 
@@ -50,10 +65,11 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
 5. **Review with user** — present draft and ask:
    - Does this cover your use cases?
    - Anything missing or unclear?
-   - Should any section be more/less detailed?
+   - Does any section need more or less detail?
 
 6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done:
    - Run `bash scripts/validate-skill-description.sh skills/<name>/SKILL.md` — must exit 0
+   - Run `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` — must exit 0 (e79s02)
    - Run `bash scripts/sync-skills.sh` — must complete without error
    - Run `bash scripts/run-skill-verify.sh <name>` if the skill defines a verify command
    - Show terminal output for each — narration without evidence is rejected
@@ -78,6 +94,7 @@ After drafting, verify:
 - [ ] Consistent terminology with CONVENTIONS.md
 - [ ] specs/ output documented if applicable
 - [ ] `validate-skill-description.sh` exits 0
+- [ ] `validate-agentic-ste.sh --strict` exits 0 (e79s02)
 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini
 - [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty)
 

package/.agents/skills/grill-me/SKILL.md

@@ -18,6 +18,14 @@ Interview relentlessly about every aspect of this plan until reaching shared und
 
 If a question can be answered by exploring the codebase, explore it instead.
 
+### Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by exploring the codebase, reading docs, or checking APIs. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the code, go find it. Only ask questions where the user's judgment is needed.
+
 ## Docs mode
 
 Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process.
@@ -29,6 +37,10 @@ Short form:
 4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
 5. Update the plan for each confirmed discrepancy.
 
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
 ---
 
 # Docs Mode — Full Process

package/.agents/skills/grill-with-docs/SKILL.md

@@ -23,6 +23,18 @@ description: "Doc-grounded variant of grill-me — stress-tests plan assumptions
 - If docs contradict the plan, plan loses until updated.
 - Prefer official docs over blog posts.
 
+## Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by reading docs, checking APIs, or exploring the codebase. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the docs, go fetch it. Only ask questions where the user's judgment is needed.
+
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
 ## Verify
 
 → verify: `grep -c 'https\?://' skills/grill-with-docs/SKILL.md | awk '{if($1>=2) print "OK"; else print "NEEDS DOCS"}'`

package/.agents/skills/request-review/SKILL.md

@@ -86,6 +86,7 @@ Review for:
 4. Design — are there simpler or more robust approaches?
 5. Edge cases — what inputs or states could cause failures?
 6. Security — any injection, auth, or data exposure risks?
+7. Refactoring smells — explicitly name any detected Fowler smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man
 
 For each finding, categorize as: must-fix / should-fix / consider.
 Run the verify command and report the result.

package/.agents/skills/seed-conventions/SKILL.md

@@ -9,6 +9,7 @@ description: "Generate CLAUDE.md and CONVENTIONS.md for a brand-new project thro
 # story: e10s02
 # story: e51s02
 # story: e45s21
+# story: e79s03
 
 
 # Seed Conventions
@@ -32,13 +33,25 @@ Ask the user these questions (one at a time, wait for each answer):
 2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
 2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
 3. **Commands** — "What commands do you use for: run, test, build, lint?"
-3b. **Preflight (optional)** — "What single command runs your full local green stack (test + lint + build)? If you don't have one, we'll chain your Test + Lint + Build answers into a **Preflight** row in the Commands table."
+3b. **Preflight (optional)** — "What command runs test, lint, and build together? If none, chain Test + Lint + Build into one **Preflight** row."
 4. **Architecture** — "Key modules and relationships in 1–2 sentences."
 5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
 6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
 7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
 8. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in).
 
+## Agentic STE for generated prose (e79s03)
+
+When writing instructional lines in `CLAUDE.md`, `AGENTS.md`, or `CONVENTIONS.md`, follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md):
+
+- Use directive vocabulary: MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT
+- Do NOT use hedge modals listed in AGENTIC-STE.md Rule 3
+- Cap each instruction sentence at 20 words
+- Write imperative, active-voice lines — one instruction per line
+- Do NOT apply Agentic STE to `terse-mode` (output compression is out of scope)
+
+After generation, run `bash scripts/validate-agentic-ste.sh --strict CLAUDE.md CONVENTIONS.md` when those files exist in the target project.
+
 ## Generate files
 
 After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
@@ -65,9 +78,11 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 
 **Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
 
-`specs/state.yaml` carries a top-level `workflow_mode` key (`team-pr` | `solo-git`, default `solo-git`). This is the **canonical integrate-mode signal** for all skills — set it once here and skills such as `release-branch` read it from this file instead of sniffing profile files.
+`specs/state.yaml` carries top-level `workflow_mode` (`team-pr` | `solo-git`, default `solo-git`).
+This is the **canonical integrate-mode signal** for all skills.
+Set it once here. Skills such as `release-branch` read this file instead of sniffing profiles.
 
-When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`).
+When generating `CLAUDE.md`, chain Test + Lint + Build into one **Preflight** row if the user named no Preflight command.
 
 ### Self-installing fenced markers (e45s21)
 
@@ -79,7 +94,9 @@ Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment
 <!-- END bigpowers:section-id -->
 ```
 
-**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file.
+**Merge rule:** On update, replace only content between matching `BEGIN`/`END` pairs.
+If a marker pair is missing, append a new fenced block at file end.
+Never rewrite the whole file.
 
 **Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
 

package/.agents/skills/stocktake-skills/SKILL.md

@@ -6,6 +6,7 @@ description: "Sequential subagent batch audit of the bigpowers skill catalog —
 
 # story: e09s01
 <!-- story: e45s12 -->
+<!-- story: e79s04 -->
 
 
 # Stocktake Skills
@@ -25,6 +26,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 ## Process
 
 0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
+0b. **Agentic STE audit (e79s04)** — run `bash scripts/validate-agentic-ste.sh --audit skills/`. Flag hedge words and sentences over 20 words per [AGENTIC-STE.md](../../docs/AGENTIC-STE.md). Record WARN lines in the stocktake report as **STE debt** — do NOT rewrite the full catalog in one pass. Route critical repeat offenders to `evolve-skill`.
 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
 2. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).