bigpowers 2.83.4 → 2.84.0

package/.trae/skills/run-evals/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: run-evals
+model: sonnet
+description: "Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs."
+---
+
+# Run Evals
+
+> **HARD GATE** — Define evals before implementation. Code graders = runnable `verify:` commands; model graders = explicit rubric with pass/fail criteria.
+
+## Process
+
+1. Name the capability under test (one sentence).
+2. Write `specs/EVALS-<feature>.md` with:
+   - **Capability evals** (does it do the job?)
+   - **Regression evals** (did we break anything?)
+3. Assign grader type per eval: `code` (shell verify) or `model` (rubric).
+4. Assign **strictness tier** per eval (graduated promotion — e45s37):
+
+   | Tier | Meaning | Promotion rule |
+   |------|---------|------------------|
+   | `EXPERIMENTAL` | New eval, may flake | Not gating |
+   | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite |
+   | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge |
+
+   Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`.
+
+5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval.
+6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only.
+
+## Artefact
+
+`specs/verifications/eNNsYY-eval-report.md` — see [REFERENCE.md](REFERENCE.md) for template. Eval reports are stored alongside verification evidence in `specs/verifications/`, keyed by story ID for traceability.
+
+## Verify
+
+→ verify: `find specs/verifications -name "*-eval-report.md" | wc -l | awk '{if($1>0) print "OK: "$1" eval reports"; else print "MISSING"}'`
+
+
+<!-- story: e02s01 -->
+
+---
+
+# Run Evals — Reference
+
+## Strictness tiers (e45s37)
+
+Add a `tier:` column to each eval row:
+
+| Tier | Gate behaviour |
+|------|----------------|
+| `EXPERIMENTAL` | Log only — does not block |
+| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` |
+| `ALWAYS_PASSES` | Hard block on any failure |
+
+## EVALS template
+
+```markdown
+# EVALS: <feature>
+
+## Capability
+| ID | Eval | Grader | Tier | verify / rubric |
+|----|------|--------|------|-----------------|
+| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- <file>` |
+| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B |
+
+## Regression
+| ID | Eval | Grader | verify / rubric |
+|----|------|--------|-----------------|
+| R1 | Full suite passes | code | `verify: npm test` |
+
+## Results
+| Run | C1 | C2 | R1 | pass@k |
+|-----|----|----|-----|--------|
+| 1 | PASS | PASS | PASS | 3/3 |
+```
+
+## pass@k
+
+Run capability evals k times (default k=3). Ship when all k pass or document known flake in `specs/state.yaml` `handoff.open_decisions`.

package/.trae/skills/run-planning/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: run-planning
+model: sonnet
+description: "DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning-status.yaml) through survey-context → scope-work → research-first → elaborate-spec → plan-release → slice-tasks. NOT a duplicate of plan-work or the planning spine; it orchestrates the pre-coding discover phase only."
+---
+
+# story: e24s03
+
+# Run Planning
+
+> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
+>
+> **Role:** DISCOVER-PHASE ADVANCER — orchestrates the discover-phase sequence; hands off to the scope-work → slice-tasks → plan-work spine for implementation planning.
+
+Updates `specs/planning-status.yaml` as discover-phase skills complete. This is NOT a duplicate of plan-work — it orchestrates the *pre-coding* discovery phase only (Discover phase in the 6-phase PMBOK lifecycle), handing off to the planning spine for implementation detail.
+
+## When to use
+
+- Starting a brand-new feature or initiative with no prior planning artifacts
+- Returning to a stalled initiative and needing to resume the discovery workflow
+- After `orchestrate-project` hands off to the Discover phase
+- When a new epic emerges from `change-request` and needs to go through full discovery
+
+## Pre-flight
+
+- [ ] Does `specs/planning-status.yaml` exist? If not, create it with the default workflow keys.
+- [ ] Does `specs/state.yaml` have `active_flow: planning`? Set it if not already.
+- [ ] Is the epic identified in `release-plan.yaml`? The epic must exist before discovery begins.
+
+## Workflows (default keys)
+
+- `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
+
+Each key maps to a skill invocation. Optional keys can be skipped; required keys must complete before the phase advances.
+
+## Process
+
+1. **Read state** — Read `specs/planning-status.yaml` and `specs/state.yaml`. Understand where discovery stands: which workflow keys are `done`, which are `pending`, and which are `optional` (can be skipped).
+
+2. **Find next step** — Find the first workflow key with `status: pending`. If the key is `optional`, check if the user wants to run it. If not, mark it `skipped`.
+
+2a. **Context capsule check** — Before invoking `elaborate-spec`, check whether a fresh `specs/planning-context.yaml` exists:
+   ```bash
+   test -f specs/planning-context.yaml && python3 -c "
+import yaml, datetime
+d = yaml.safe_load(open('specs/planning-context.yaml'))
+written = d.get('written_at','')
+if written:
+    age = (datetime.datetime.now(datetime.timezone.utc) - datetime.datetime.fromisoformat(written)).total_seconds() / 3600
+    print(f'Context age: {age:.1f}h')
+" 2>/dev/null || echo "No context or no written_at"
+   ```
+   - If context is **< 24h old**, ask: `"Planning context from Xh ago exists for '<feature_name>'. Re-run elaborate-spec? [y/N]"`. Skip elaborate-spec on N.
+   - If context is **≥ 24h old** or absent, run elaborate-spec normally.
+   - On planning cycle completion (all required keys done), clear the capsule: delete `specs/planning-context.yaml` and set `planning-status.yaml` `context_capsule: null`.
+
+3. **Invoke the matching skill** — Run the skill that matches the workflow key:
+   - `survey-context` — where are we?
+   - `scope-work` — what's in and out?
+   - `research-first` — what already exists?
+   - `elaborate-spec` — refine the idea (optional)
+   - `plan-release` — sequence epics by WSJF
+   - `slice-tasks` — cut vertical slices
+
+4. **Update status** — On successful completion, set `status: done` for that workflow key in `planning-status.yaml`.
+
+5. **Advance** — Set `state.yaml` `active_flow: planning` while in this chain. When all required keys are done, set `handoff.next_skill` to `plan-work`.
+
+## Workflow Keys Schema
+
+In `specs/planning-status.yaml`:
+```yaml
+context_capsule:             # written by elaborate-spec; cleared on cycle completion
+  written_at: "2026-06-22T03:00:00Z"
+  written_by: elaborate-spec
+  feature_name: "add dark mode"
+workflows:
+  survey-context:
+    required: true
+    status: done
+  scope-work:
+    required: true
+    status: pending
+  research-first:
+    required: false
+    status: optional
+    note: "Skip if no external dependencies"
+  elaborate-spec:
+    required: false
+    status: optional
+  plan-release:
+    required: true
+    status: pending
+  slice-tasks:
+    required: true
+    status: pending
+```
+
+## Verify
+
+→ verify: `test -f specs/planning-status.yaml && grep -c 'status: done' specs/planning-status.yaml | awk '{if($1>=3) print "OK"; else print "INCOMPLETE"}'`

package/.trae/skills/scope-work/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: scope-work
+model: sonnet
+description: "PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in and out of scope and save as specs/product/SCOPE_LATEST.yaml. Use before slice-tasks or plan-release on any new initiative. Not a substitute for slice-tasks (step 2) or plan-work (step 3)."
+---
+
+# story: e03s01
+# story: e24s02
+
+# Scope Work
+
+> **Spine position:** Step 1 — scope-work → slice-tasks → plan-work.
+
+Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`. Without a scope boundary, implementation drifts — stories expand, estimates blow up, and "done" becomes undefined.
+
+## Pre-flight
+
+- [ ] Do you have a clear user need or problem statement? If not, run `elaborate-spec` first.
+- [ ] Does `specs/product/VISION_LATEST.yaml` exist? If yes, read it for north-star alignment.
+- [ ] Is there an existing `SCOPE_LATEST.yaml`? If yes, you're refining, not creating from scratch.
+
+## Process
+
+0. **Read planning-context.yaml** — If `specs/planning-context.yaml` exists, read it before doing anything else:
+   ```bash
+   test -f specs/planning-context.yaml && echo "Context found" || echo "No context — starting fresh"
+   ```
+   Pre-populate `feature_name`, `constraints`, and `out_of_scope` from the file. Skip re-asking questions already answered by elaborate-spec. If the file is absent, proceed normally.
+
+1. **Gather context** — Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any). Understand what the project is building and why.
+
+2. **Interview (if needed)** — Clarify: What is the goal? Who are the users? What is definitely in scope? What is explicitly out of scope? What constraints exist (time, budget, tech)? How will success be measured?
+
+3. **Write `specs/product/SCOPE_LATEST.yaml`** with these fields:
+   - `core_value` — one-sentence value proposition
+   - `summary` — 2-3 paragraph scope overview
+   - `in_scope[]` — list of what this initiative covers (each maps to an epic/story)
+   - `out_of_scope[]` — explicit exclusions (prevents scope creep)
+   - `constraints` — tech, time, resource boundaries
+   - `success_criteria` — observable outcomes that prove the scope is delivered
+   - `references` — links to related specs, ADRs, or documents
+
+4. **Lightweight trade-off analysis** — For each `out_of_scope` item, note *why* it's excluded (deferred, not valuable, too risky, depends on external factor). This protects against "what about X?" questions later.
+
+5. **Run `research-first`** if external dependencies are proposed — verify the dependency exists, is maintained, and fits the scope before committing to it.
+
+> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`. If an item can't be mapped, the scope is too vague — refine before proceeding.
+
+> **HARD GATE** — Do NOT include implementation details in SCOPE_LATEST.yaml. Scope is *what* and *why*, not *how*. Implementation detail belongs in epic capsules and slice-tasks.
+
+## Common Anti-Patterns
+
+- **"Everything is in scope"** — If nothing is out of scope, you haven't defined a scope. You've described a universe. Cut aggressively.
+- **"We'll figure it out later"** — Ambiguity in scope propagates to every downstream decision. Resolve now or explicitly defer in writing.
+- **Scope as architecture** — Saying "we need a PostgreSQL database" is architecture, not scope. Scope says "we need to store user profiles and transaction history."
+
+## Output
+
+`specs/product/SCOPE_LATEST.yaml` — the bounded PRD. Subsequent skills (`slice-tasks`, `plan-work`) reference this as the source of truth for what to build.
+
+## Verify
+
+→ verify: `test -f specs/product/SCOPE_LATEST.yaml && grep -c 'out_of_scope' specs/product/SCOPE_LATEST.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`

package/.trae/skills/search-skills/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: search-skills
+model: haiku
+description: "Find the right bigpowers skill from natural-language intent using a local lexical index over SKILL.md frontmatter. Use when unsure which skill to invoke, or at start of research-first."
+---
+
+# story: e09s01
+# story: e21s01
+
+# Search Skills
+
+> **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
+>
+> **HARD GATE** — Do NOT use external embedding APIs or AI-based semantic search. This is a lexical-only index (ADR: zero external dependency).
+
+Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX_LATEST.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
+
+## When to use
+
+- You're unsure which skill to invoke for a user's request
+- At the start of `research-first` to find pre-existing skills that might solve the problem
+- When a user asks "is there a skill for X?"
+- Before calling a skill by name, to confirm it's the right one
+
+## Pre-flight
+
+- [ ] Does `specs/SKILL-SEARCH-INDEX_LATEST.md` exist? If not, run `bash scripts/build-skill-index.sh`.
+- [ ] Is the index fresh? Check its timestamp — if > 24 hours old or after any SKILL.md change, regenerate.
+
+## Process
+
+1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX_LATEST.md` doesn't exist or was modified before the last SKILL.md change.
+
+2. **Search the index** — Use ripgrep on the lexical index:
+   ```
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX_LATEST.md
+   ```
+   The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
+
+3. **Rank results** — Read the top 3 matches. Evaluate by:
+   - **Exactness** — Does the description literally match the user's intent?
+   - **Phase fit** — Is the skill designed for the current lifecycle phase?
+   - **Trigger phrases** — Does the skill's "Use when" section match the situation?
+
+4. **Recommend one skill** — Select the single best-matching skill. Provide:
+   - The skill name
+   - Why it's the best match (citing the description or trigger phrase)
+   - What it produces (artifact, dialogue, or state change)
+
+5. **Invoke** — Call the skill directly or through the orchestrator. If no match found, suggest the closest phase-appropriate skill or `using-bigpowers` as a general entry point.
+
+## Index Format
+
+`specs/SKILL-SEARCH-INDEX_LATEST.md` contains one section per skill:
+```markdown
+## <skill-name>
+- **Description:** <from frontmatter>
+- **Phase:** <lifecycle phase>
+- **Triggers:** <key phrases from description>
+- **Keywords:** <extracted terms>
+```
+
+## Why Not Semantic Search?
+
+- Zero network dependency — works fully offline
+- Zero cost — no API keys, no usage limits
+- Instant — ripgrep on a local file is sub-second
+- Deterministic — same query always returns same results
+- Auditable — you can read the full index
+
+## Verify
+
+→ verify: `test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK)`