bigpowers 2.49.0 → 2.51.0

package/skills/release-branch/REFERENCE.md

@@ -40,22 +40,65 @@ If `git worktree remove` fails due to uncommitted changes, ask: "There are uncom
 
 ## Cycle-time recording
 
-After landing the branch, record delivery metrics for this story:
-
-1. Write `metrics.story_end` (ISO 8601) to `specs/state.yaml`
-2. Compute `cycle_minutes`: `story_end` minus `story_start` in minutes
-3. Compute `bcp_per_hour`: `epic_cycle.story_bcps / (cycle_minutes / 60)`
-4. Append a row to `specs/metrics/cycle-times.yaml`:
-
-```yaml
-- id: e01s01
-  bcps: 3
-  start: "2026-06-10T09:45:00Z"
-  end: "2026-06-10T11:15:00Z"
-  cycle_minutes: 90
-  bcp_per_hour: 2.0
+After landing the branch, record delivery metrics using the git-derived,
+additive script (replaces hand-arithmetic):
+
+```bash
+bash scripts/record-cycle-time.sh append \
+  --story <story_id> --bcps <bcps> \
+  --range "$(git merge-base main HEAD)..HEAD" \
+  --file specs/metrics/cycle-times.yaml
 ```
 
+This appends a row to the cycle-times ledger with two separated metrics:
+
+- **effort_hours** — ADDITIVE. Idle-stripped estimated effort from git commit
+  history (git-hours model: 120-min session threshold, 120-min first-commit pad).
+  Sums exactly to whole-repo effort. NO hand-arithmetic, NO wall-clock includes.
+- **lead_time_minutes** — calendar latency from first commit to merge.
+  Median-aggregated across stories; NEVER summed.
+
+The script also runs an additivity self-check: Σ(story effort) == whole-repo effort
+within rounding tolerance.
+
+### Why not story_start minus story_end?
+
+The previous hand-arithmetic approach (survey-context writes `story_start`,
+release-branch writes `story_end`, agent hand-computes `cycle_minutes`) was
+retired because:
+
+1. It was **agent-self-reported** — trivially fabricated or mis-subtracted.
+2. Wall-clock included **overnight/weekend/UAT gaps** — calendar latency,
+   not coding effort.
+3. The `bcp_per_hour` metric was **computationally meaningless** (velocity
+   derived from a latency measurement).
+
+The new approach derives effort from commit history (objective, reproducible)
+and lead time from first commit → merge (honest calendar latency). See
+`docs/references/bcp.md` for BCP sizing context and
+`scripts/record-cycle-time.sh` for the full algorithm.
+
+---
+
+## CI verification
+
+The CI polling logic has been extracted to `scripts/wait-for-ci.sh`.
+See the script's `--help` for usage. Step 7b of the main SKILL.md invokes it directly:
+
+```bash
+bash scripts/wait-for-ci.sh --timeout 600 --interval 30
+```
+
+**Exit codes:**
+- **0** — all workflows green. Set `release.ci_verified: true` in state.yaml.
+- **1** — at least one workflow failed. Prints failure URLs. Set `handoff.next_skill = fix-bug`.
+- **2** — timeout. CI did not complete. Retry or investigate.
+- **0 with warning** — `gh` CLI not available, git-only fallback confirmed push landed but CI status unverified.
+
+The script handles: auto-discovery of all workflows for the current
+branch/commit, polling until completion, success/failure/timeout exit codes,
+and git-only fallback when `gh` CLI is unavailable.
+
 ---
 
 ## Solo-local fallback detail
@@ -96,43 +139,3 @@ git push origin "$DEFAULT_BRANCH"
 # Clean up local feature branch
 git branch -d "$FEATURE_BRANCH"
 ```
-
----
-
-## Reference block 2
-
-```bash
-echo "==> Polling CI for main branch..."
-TIMEOUT=600   # 10 minutes
-INTERVAL=30   # poll every 30 seconds
-ELAPSED=0
-
-while [ $ELAPSED -lt $TIMEOUT ]; do
-  CI_JSON=$(gh run list --limit 1 --branch main --workflow CI --json status,conclusion,headSha,databaseId 2>/dev/null)
-  CI_STATUS=$(echo "$CI_JSON" | jq -r '.[0].status // "unknown"')
-  CI_CONCLUSION=$(echo "$CI_JSON" | jq -r '.[0].conclusion // ""')
-  CI_SHA=$(echo "$CI_JSON" | jq -r '.[0].headSha // ""')
-  CI_ID=$(echo "$CI_JSON" | jq -r '.[0].databaseId // ""')
-
-  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "success" ]; then
-    echo "OK: CI passed for $(git rev-parse --short HEAD)"
-    bp-yaml-set.sh specs/state.yaml release.ci_verified true 2>/dev/null || \
-      echo "  (bp-yaml-set not available — manually set release.ci_verified: true in state.yaml)"
-    break
-  fi
-
-  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "failure" ]; then
-    echo "FAIL: CI failed for $(git rev-parse --short HEAD)"
-    echo "  Run URL: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$CI_ID"
-    echo "  Handoff to fix-bug with the failure URL above."
-    return 1
-  fi
-
-  sleep $INTERVAL
-  ELAPSED=$((ELAPSED + INTERVAL))
-  echo "  Waiting... (${ELAPSED}s / ${TIMEOUT}s)"
-done
-
-echo "FAIL: CI did not complete within ${TIMEOUT}s timeout"
-return 1
-```

package/skills/release-branch/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: release-branch
 model: haiku
+effort: standard
 description: Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says "release", "merge", or "open a PR".
 ---
 
@@ -100,11 +101,16 @@ mv specs/epics/eNN-slug specs/epics/archive/
 
 > **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
 
-After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
+After push (solo-local step 5 or team-pr step 7), run the CI polling script:
 
-See [REFERENCE.md](REFERENCE.md)
+```bash
+bash scripts/wait-for-ci.sh --timeout 600 --interval 30
+```
+
+The script auto-discovers workflow runs for the pushed commit and polls until completion.
+See [REFERENCE.md](REFERENCE.md) for exit code semantics and git-only fallback.
 
-- [ ] CI workflow passes after push
+- [ ] CI workflow passes after push (wait-for-ci.sh exit 0)
 - [ ] `release.ci_verified: true` documented in state.yaml
 - On failure: `handoff.next_skill = fix-bug` with the CI failure URL
 
@@ -118,7 +124,17 @@ git branch -d <branch-name>
 
 ### 8a. Cycle-time recording
 
-After landing, record delivery metrics. See [REFERENCE.md](REFERENCE.md) for fields and example row.
+After landing, record delivery metrics with the git-derived, additive script:
+
+```bash
+bash scripts/record-cycle-time.sh append \
+  --story <story_id> --bcps <bcps> \
+  --range "$(git merge-base main HEAD)..HEAD" \
+  --file specs/metrics/cycle-times.yaml
+```
+
+This replaces the previous hand-arithmetic approach (story_end minus story_start).
+See [REFERENCE.md](REFERENCE.md) for the git-hours model and field definitions.
 
 ### 9. Return to main
 

package/skills/request-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: request-review
 model: opus
+effort: standard
 description: Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review.
 ---
 

package/skills/research-first/SKILL.md

@@ -2,6 +2,7 @@
 name: research-first
 description: Look-before-build — search registries, repo, existing skills, and web for prior art before implementing. Appends Prior Art to the spec. Use after survey-context and before elaborate-spec, when adding dependencies, or when the task may already be solved.
 model: sonnet
+effort: standard
 ---
 
 # Research First

package/skills/reset-baseline/SKILL.md

@@ -2,6 +2,7 @@
 name: reset-baseline
 description: Restore the project to a known clean state between agent runs or experiments. Use between benchmark runs, after a failed spike, or when user wants a clean working tree.
 model: haiku
+effort: standard
 ---
 
 # Reset Baseline

package/skills/respond-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: respond-review
 model: sonnet
+effort: standard
 description: Act on a reviewer agent's feedback systematically — categorize findings, apply fixes, verify tests still pass. Use after request-review returns a report, or when user wants to work through code review findings.
 ---
 

package/skills/run-benchmark/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: run-benchmark
 model: haiku
+effort: standard
 description: Run skill quality benchmarks from specs/benchmarks/ definitions and write pass@k reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions.
 ---
 

package/skills/run-evals/SKILL.md

@@ -2,6 +2,7 @@
 name: run-evals
 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.
 model: sonnet
+effort: standard
 ---
 
 # Run Evals

package/skills/run-planning/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: run-planning
 model: sonnet
+effort: standard
 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."
 ---
 

package/skills/scope-work/SKILL.md

@@ -2,6 +2,7 @@
 name: scope-work
 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)."
 model: sonnet
+effort: standard
 ---
 
 # Scope Work

package/skills/search-skills/SKILL.md

@@ -2,6 +2,7 @@
 name: search-skills
 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.
 model: haiku
+effort: standard
 ---
 
 # Search Skills

package/skills/security-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: security-review
 model: sonnet
+effort: standard
 description: >
   AI-powered security analysis of code changes — traces data flow, detects
   injection, auth bypass, secrets exposure, and unsafe deserialization across

package/skills/seed-conventions/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: seed-conventions
 model: sonnet
+effort: standard
 description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory with evolved bigpowers structure (product/, tech-architecture/, verifications/, epics/archive/). Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet.
 ---
 

package/skills/session-state/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: session-state
 model: haiku
+effort: standard
 description: Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
 ---
 
@@ -10,6 +11,8 @@ description: Track implementation decisions and progress in specs/state.yaml to
 
 Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
 
+Session-state implements the **isolate** strategy from the context-engineering framework (docs/references/context-engineering.md): each agent gets exactly the context it needs — no more — by recording decisions so the next agent can cold-start without replaying history. The four strategies (write, select, compress, isolate) work together: session-state handles isolation, terse-mode handles compression, survey-context handles selection, and CONVENTIONS.md ensures token-efficient writing.
+
 ## Goal
 
 Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.

package/skills/setup-environment/SKILL.md

@@ -2,6 +2,7 @@
 name: setup-environment
 description: Pre-install dependencies and configure tools before development work begins. Use at session start on a fresh clone, before kickoff-branch, or when user says setup environment or install deps.
 model: haiku
+effort: standard
 ---
 
 # Setup Environment

package/skills/simulate-agents/SKILL.md

@@ -2,6 +2,7 @@
 name: simulate-agents
 description: Run Mock User and Auditor agents against a feature in fresh contexts before human review. Use after verify-work, before request-review, when user wants pre-review simulation.
 model: sonnet
+effort: standard
 ---
 
 # Simulate Agents

package/skills/slice-tasks/SKILL.md

@@ -2,6 +2,7 @@
 name: slice-tasks
 description: "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical-slice stories in specs/epics/. Use after scope-work (step 1), before plan-work (step 3). Not a substitute for scope-work or plan-work."
 model: sonnet
+effort: standard
 ---
 
 # Slice Tasks

package/skills/smoke-test/SKILL.md

@@ -2,6 +2,7 @@
 name: smoke-test
 description: "Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill."
 model: sonnet
+effort: standard
 ---
 
 # Smoke Test

package/skills/spike-prototype/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spike-prototype
 model: sonnet
+effort: standard
 description: Throw-away prototype for unknown problem spaces. Output is learning notes in specs/archive/spikes/SPIKE-<name>.md, not production code. Use when the domain or technology is unexplored, when estimates are impossible without experimentation, or when user says "spike", "prototype", or "proof of concept".
 ---
 

package/skills/stocktake-skills/SKILL.md

@@ -2,6 +2,7 @@
 name: stocktake-skills
 description: Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.
 model: sonnet
+effort: standard
 ---
 
 # Stocktake Skills

package/skills/survey-context/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: survey-context
 model: haiku
+effort: standard
 description: Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first.
 ---
 
@@ -114,7 +115,7 @@ Report blockers first, before recommendations.
 
 ### 8. Record story start timestamp
 
-At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` for cycle-time tracking.
+At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` as an **informational progress marker only** — not a measurement input. Cycle-time metrics are now derived from git commit history via `scripts/record-cycle-time.sh` (see `skills/release-branch/REFERENCE.md` §Cycle-time recording).
 
 ## Utility outputs
 

package/skills/terse-mode/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: terse-mode
 model: haiku
+effort: standard
 description: Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use ONLY when context is critically long and compressing output is necessary to continue. Not a strategy — token discipline comes from code shape (small functions, unique names, headless tests), not terser prompts. Use when user says "caveman mode", "terse mode", "less tokens", "be brief", or invokes /terse-mode.
 ---
 

package/skills/trace-requirement/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: trace-requirement
 model: haiku
+effort: standard
 description: Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
 ---
 

package/skills/using-bigpowers/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: using-bigpowers
 model: sonnet
+effort: standard
 description: One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks "where do I start?", or when the skills system needs to be explained.
 ---
 

package/skills/validate-contracts/SKILL.md

@@ -2,6 +2,7 @@
 name: validate-contracts
 description: "Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy."
 model: sonnet
+effort: standard
 ---
 
 # Validate Contracts

package/skills/validate-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: validate-fix
 model: haiku
+effort: standard
 description: Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says "is this fixed?", or before closing an investigation.
 ---
 

package/skills/verify-work/SKILL.md

@@ -2,6 +2,7 @@
 name: verify-work
 description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.
 model: haiku
+effort: standard
 ---
 
 # Verify Work

package/skills/visual-dashboard/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: visual-dashboard
 model: sonnet
+effort: standard
 description: Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Persists artifacts in .bigpowers/dashboard/. Reads specs/state.yaml, release-plan.yaml, epics, and planning-status via HTTP API or opencode panel.
 ---
 

package/skills/wire-ci/SKILL.md

@@ -2,6 +2,7 @@
 name: wire-ci
 description: "CI pipeline setup with pre-built templates and local validation. Generates GitHub Actions workflows, validates YAML syntax and permissions, supports dry-run via act/gh. The CI equivalent of wire-observability."
 model: sonnet
+effort: standard
 ---
 
 # Wire CI

package/skills/wire-observability/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wire-observability
 model: sonnet
+effort: standard
 description: Add structured JSON logging, observability commands, and idempotent setup scripts to a project. Use when a project needs production-readiness instrumentation, when user wants structured logging, or as a production-readiness gate at any phase of development.
 ---
 

package/skills/write-document/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: write-document
 model: sonnet
+effort: standard
 description: Write, organize, and sync high-integrity technical documents using the BMAD methodology. Ensures every document is Bold, Minimal, Actionable, and Durable. Use when creating architectural docs, technical guides, or organizing the specs/ directory.
 ---