bigpowers 2.4.0 → 2.5.0

package/.pi/skills/investigate-bug/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: investigate-bug
-description: "Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions "triage", or wants to plan a fix."
+description: "Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions \"triage\", or wants to plan a fix."
+model: sonnet
 ---
 
 

package/.pi/skills/kickoff-branch/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: kickoff-branch
-description: "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions "start a branch" or "new worktree"."
+description: "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions \"start a branch\" or \"new worktree\"."
+model: haiku
 ---
 
 

package/.pi/skills/map-codebase/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: map-codebase
-description: ""Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does.""
+description: "\"Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does.\""
+model: sonnet
 ---
 
 

package/.pi/skills/migrate-spec/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: migrate-spec
 description: "Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers YAML layout (state.yaml, release-plan.yaml, epics/, requirements/, plans/, ADRs). Use when migrating foreign spec docs."
+model: sonnet
 ---
 
 

package/.pi/skills/model-domain/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: model-domain
 description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates specs/tech-architecture/tech-stack.md and specs/adr/ inline as decisions crystallise. Use when user wants to stress-test a plan against their project's domain language and documented decisions."
+model: sonnet
 ---
 
 

package/.pi/skills/orchestrate-project/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: orchestrate-project
 description: "Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan → build → verify → release) with hard gates. Use to coordinate multi-phase projects with guaranteed quality checkpoints. One-time command for the entire project lifecycle."
+model: sonnet
 ---
 
 

package/.pi/skills/organize-workspace/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: organize-workspace
-description: "Scans the active workspace for disposable artifacts—logs, caches, stale build output, and stray draft markdown—and proposes consolidation of scattered assets. Produces a reviewable list, asks for explicit confirmation before any delete or move, and optionally revises .gitignore. Use when the user says "clean my room", "organize workspace", "workspace cleanup", "remove temp files", "organize assets", "gitignore", or wants a safe tidy pass."
+description: "Scans the active workspace for disposable artifacts—logs, caches, stale build output, and stray draft markdown—and proposes consolidation of scattered assets. Produces a reviewable list, asks for explicit confirmation before any delete or move, and optionally revises .gitignore. Use when the user says \"clean my room\", \"organize workspace\", \"workspace cleanup\", \"remove temp files\", \"organize assets\", \"gitignore\", or wants a safe tidy pass."
+model: haiku
 ---
 
 

package/.pi/skills/plan-refactor/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plan-refactor
 description: "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps."
+model: sonnet
 ---
 
 

package/.pi/skills/plan-release/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plan-release
-description: ""RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics.""
+description: "\"RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics.\""
+model: sonnet
 ---
 
 

package/.pi/skills/plan-work/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plan-work
-description: ""PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2).""
+description: "\"PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2).\""
+model: opus
 ---
 
 

package/.pi/skills/release-branch/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: release-branch
-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"."
+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\"."
+model: haiku
 ---
 
 

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

@@ -1,6 +1,7 @@
 ---
 name: request-review
 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."
+model: opus
 ---
 
 

package/.pi/skills/research-first/SKILL.md

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/reset-baseline/SKILL.md

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/respond-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: respond-review
 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."
+model: sonnet
 ---
 
 

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

@@ -1,6 +1,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"
+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
 ---
 
 

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

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

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

@@ -1,6 +1,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"
+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
 ---
 
 

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

@@ -1,6 +1,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"
+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
 ---
 
 

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

@@ -1,6 +1,7 @@
 ---
 name: seed-conventions
 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."
+model: sonnet
 ---
 
 

package/.pi/skills/session-state/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: session-state
 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."
+model: haiku
 ---
 
 

package/.pi/skills/setup-environment/SKILL.md

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/simulate-agents/SKILL.md

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/slice-tasks/SKILL.md

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/spike-prototype/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spike-prototype
-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"."
+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\"."
+model: sonnet
 ---
 
 

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

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/survey-context/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: survey-context
 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."
+model: haiku
 ---
 
 

package/.pi/skills/terse-mode/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: terse-mode
-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."
+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."
+model: haiku
 ---
 
 

package/.pi/skills/trace-requirement/SKILL.md

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

package/.pi/skills/using-bigpowers/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: using-bigpowers
-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."
+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."
+model: sonnet
 ---
 
 

package/.pi/skills/validate-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: validate-fix
-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."
+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."
+model: haiku
 ---
 
 

package/.pi/skills/verify-work/SKILL.md

@@ -1,6 +1,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"
+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
 ---
 
 

package/.pi/skills/visual-dashboard/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: visual-dashboard
 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."
+model: sonnet
 ---
 
 

package/.pi/skills/wire-observability/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wire-observability
 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."
+model: sonnet
 ---
 
 

package/.pi/skills/write-document/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: write-document
 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."
+model: sonnet
 ---
 
 

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.5.0](https://github.com/danielvm-git/bigpowers/compare/v2.4.1...v2.5.0) (2026-06-18)
+
+
+### Features
+
+* add align-grid skill and orchestration reference docs ([359c823](https://github.com/danielvm-git/bigpowers/commit/359c82381d0d124ef849ca15bd1d3ee91d218766))
+
+## [2.4.1](https://github.com/danielvm-git/bigpowers/compare/v2.4.0...v2.4.1) (2026-06-18)
+
+
+### Bug Fixes
+
+* **scripts:** sync-skills.sh — escape YAML quotes, preserve model key, add validation guard ([#19](https://github.com/danielvm-git/bigpowers/issues/19)) ([b77bf12](https://github.com/danielvm-git/bigpowers/commit/b77bf1269f4824703d69d2a0d890a0a13c2f3aeb))
+
 # [2.4.0](https://github.com/danielvm-git/bigpowers/compare/v2.3.0...v2.4.0) (2026-06-18)
 
 

package/SKILL-INDEX.md

@@ -19,13 +19,13 @@
 | **Initiate** | 4 | kickoff-branch, guard-git, hook-commits, seed-conventions |
 | **Build** | 8 | develop-tdd, enforce-first, delegate-task, dispatch-agents, execute-plan, build-epic, run-planning, fix-bug |
 | **Harden** | 1 | wire-observability |
-| **Verify** | 2 | verify-work, run-evals |
+| **Verify** | 3 | verify-work, run-evals, align-grid |
 | **Bug** | 3 | investigate-bug, diagnose-root, validate-fix |
 | **Review** | 4 | audit-code, request-review, respond-review, trace-requirement |
 | **Integrate** | 2 | commit-message, release-branch |
 | **Sustain** | 4 | inspect-quality, organize-workspace, stocktake-skills, evolve-skill |
 | **Utility** | 12 | terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard, write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents |
-| **TOTAL** | **61** | |
+| **TOTAL** | **62** | |
 
 ---
 
@@ -66,36 +66,37 @@
 | 31 | Harden | `wire-observability` | Structured logging + observability | src/, CLAUDE.md | ✅ Active |
 | 32 | Verify | `verify-work` | Multi-phase UAT; loop on gaps; absorbs cold-start-smoke, gaps-loop, verify-work-smoke | (dialogue) | ✅ Active |
 | 33 | Verify | `run-evals` | EDD capability + regression evals | EVALS-<feature>.md | ✅ Active |
-| 34 | Bug | `investigate-bug` | Investigate bug → diagnosis | bugs/BUG-*.md | ✅ Active |
-| 35 | Bug | `diagnose-root` | 4-phase root cause analysis | bugs/BUG-*.md | ✅ Active |
-| 36 | Bug | `validate-fix` | Prove fix works | (verify) | ✅ Active |
-| 37 | Review | `audit-code` | Self-review checklist; absorbs audit-code-quick | (checklist) | ✅ Active |
-| 38 | Review | `request-review` | Fresh reviewer agent | review-report | ✅ Active |
-| 39 | Review | `respond-review` | Act on reviewer feedback | src/ | ✅ Active |
-| 40 | Review | `trace-requirement` | Story ID → code/tests | TRACEABILITY.md | ✅ Active |
-| 41 | Integrate | `commit-message` | Conventional Commits + semver; absorbs commit-message-fix | (git message) | ✅ Active |
-| 42 | Integrate | `release-branch` | Merge/PR decision + cleanup; absorbs release-branch-hotfix | (git PR) | ✅ Active |
-| 43 | Sustain | `inspect-quality` | Structured QA session | BUG-LOG.md | ✅ Active |
-| 44 | Sustain | `organize-workspace` | Safe workspace cleanup | (filesystem) | ✅ Active |
-| 45 | Sustain | `stocktake-skills` | Batch audit of skill catalog | specs/ audit report | ✅ Active |
-| 46 | Sustain | `evolve-skill` | Benchmark-gated skill evolution | ADR, STATE.md | ✅ Active |
-| 47 | Utility | `terse-mode` | Ultra-terse output (fallback) | (prompt) | ✅ Active |
-| 48 | Utility | `craft-skill` | Build new bigpowers skill | skills/<name>/SKILL.md | ✅ Active |
-| 49 | Utility | `edit-document` | Edit documents in specs/ | specs/<name>.md | ✅ Active |
-| 50 | Utility | `session-state` | Track decisions in state.yaml; absorbs show-state, reset-state, compact-state, list-epics, check-gates | state.yaml | ✅ Active |
-| 51 | Utility | `migrate-spec` | Migrate foreign spec formats | specs/ | ✅ Active |
-| 52 | Utility | `visual-dashboard` | Browser dashboard (HTTP cockpit) | `npm run visual-dashboard` → GET /cockpit.html | ✅ Active |
-| 53 | Utility | `write-document` | BMAD technical documents | specs/<name>.md | ✅ Active |
-| 54 | Utility | `setup-environment` | Pre-install deps before work | (.env, packages) | ✅ Active |
-| 55 | Utility | `reset-baseline` | Restore clean known state | (clean tree) | ✅ Active |
-| 56 | Utility | `search-skills` | Natural language → right skill | SKILL-SEARCH-INDEX.md | ✅ Active |
-| 57 | Utility | `compose-workflow` | Chain skills into workflow recipe | WORKFLOW-<name>.md | ✅ Active |
-| 58 | Utility | `simulate-agents` | Mock User + Auditor simulation | SIMULATION-<feature>.md | ✅ Active |
-| 59 | Build | `build-epic` | Eight-step epic build cycle | state.yaml, epics/ | ✅ Active |
-| 60 | Build | `run-planning` | Discover-phase workflow tracker | planning-status.yaml | ✅ Active |
-| 61 | Bug | `fix-bug` | Bug fix orchestrator | bugs/BUG-*.md | ✅ Active |
-
-**Total: 61 active skills.** 18 sub-op concepts (zoom-out, slopcheck, red-phase, green-phase, refactor-phase, cold-start-smoke, gaps-loop, plan-work-fast, commit-message-fix, release-branch-hotfix, audit-code-quick, verify-work-smoke, show-state, reset-state, compact-state, list-epics, check-gates) are documented as sub-sections within parent SKILL.md files; none were standalone SKILL.md directories, so the count remains 61.
+| 34 | Verify | `align-grid` | Müller-Brockmann modular grid layout alignment and verification harness | (code / config) | ✅ Active |
+| 35 | Bug | `investigate-bug` | Investigate bug → diagnosis | bugs/BUG-*.md | ✅ Active |
+| 36 | Bug | `diagnose-root` | 4-phase root cause analysis | bugs/BUG-*.md | ✅ Active |
+| 37 | Bug | `validate-fix` | Prove fix works | (verify) | ✅ Active |
+| 38 | Review | `audit-code` | Self-review checklist; absorbs audit-code-quick | (checklist) | ✅ Active |
+| 39 | Review | `request-review` | Fresh reviewer agent | review-report | ✅ Active |
+| 40 | Review | `respond-review` | Act on reviewer feedback | src/ | ✅ Active |
+| 41 | Review | `trace-requirement` | Story ID → code/tests | TRACEABILITY.md | ✅ Active |
+| 42 | Integrate | `commit-message` | Conventional Commits + semver; absorbs commit-message-fix | (git message) | ✅ Active |
+| 43 | Integrate | `release-branch` | Merge/PR decision + cleanup; absorbs release-branch-hotfix | (git PR) | ✅ Active |
+| 44 | Sustain | `inspect-quality` | Structured QA session | BUG-LOG.md | ✅ Active |
+| 45 | Sustain | `organize-workspace` | Safe workspace cleanup | (filesystem) | ✅ Active |
+| 46 | Sustain | `stocktake-skills` | Batch audit of skill catalog | specs/ audit report | ✅ Active |
+| 47 | Sustain | `evolve-skill` | Benchmark-gated skill evolution | ADR, STATE.md | ✅ Active |
+| 48 | Utility | `terse-mode` | Ultra-terse output (fallback) | (prompt) | ✅ Active |
+| 49 | Utility | `craft-skill` | Build new bigpowers skill | skills/<name>/SKILL.md | ✅ Active |
+| 50 | Utility | `edit-document` | Edit documents in specs/ | specs/<name>.md | ✅ Active |
+| 51 | Utility | `session-state` | Track decisions in state.yaml; absorbs show-state, reset-state, compact-state, list-epics, check-gates | state.yaml | ✅ Active |
+| 52 | Utility | `migrate-spec` | Migrate foreign spec formats | specs/ | ✅ Active |
+| 53 | Utility | `visual-dashboard` | Browser dashboard (HTTP cockpit) | `npm run visual-dashboard` → GET /cockpit.html | ✅ Active |
+| 54 | Utility | `write-document` | BMAD technical documents | specs/<name>.md | ✅ Active |
+| 55 | Utility | `setup-environment` | Pre-install deps before work | (.env, packages) | ✅ Active |
+| 56 | Utility | `reset-baseline` | Restore clean known state | (clean tree) | ✅ Active |
+| 57 | Utility | `search-skills` | Natural language → right skill | SKILL-SEARCH-INDEX.md | ✅ Active |
+| 58 | Utility | `compose-workflow` | Chain skills into workflow recipe | WORKFLOW-<name>.md | ✅ Active |
+| 59 | Utility | `simulate-agents` | Mock User + Auditor simulation | SIMULATION-<feature>.md | ✅ Active |
+| 60 | Build | `build-epic` | Eight-step epic build cycle | state.yaml, epics/ | ✅ Active |
+| 61 | Build | `run-planning` | Discover-phase workflow tracker | planning-status.yaml | ✅ Active |
+| 62 | Bug | `fix-bug` | Bug fix orchestrator | bugs/BUG-*.md | ✅ Active |
+
+**Total: 62 active skills.** 18 sub-op concepts (zoom-out, slopcheck, red-phase, green-phase, refactor-phase, cold-start-smoke, gaps-loop, plan-work-fast, commit-message-fix, release-branch-hotfix, audit-code-quick, verify-work-smoke, show-state, reset-state, compact-state, list-epics, check-gates) are documented as sub-sections within parent SKILL.md files; none were standalone SKILL.md directories, so the count remains 62.
 
 ---
 
@@ -121,7 +122,7 @@ survey-context → research-first → elaborate-spec → map-codebase
                          ↓
         wire-observability (production-readiness gate, any phase)
                          ↓
-              ★ VERIFY ★  run-evals → verify-work  (prove it works)
+              ★ VERIFY ★  run-evals → verify-work → align-grid  (prove it works)
                          ↓
     fix-bug → investigate-bug → diagnose-root → validate-fix
                          ↓

package/align-grid/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: align-grid
+description: "Build editorial/magazine/report webpages on a GENUINE Müller-Brockmann modular grid (International Typographic Style) — not a decorative one. Encodes the discipline (columns + modules + baseline, grotesque type, flush-left, restrained black/white/red palette) AND the hard-won front-end engineering to make the grid real, visible, and verified: one CSS-variable source of truth, an interactive grid-toggle overlay that lives in the SAME content box as the content, subgrid \"bands\" so every element snaps to a column line, an 8px baseline lock, and runtime OPTICAL ALIGNMENT that puts display type's ink (not its box) on the line. Ships with a scaffold generator and a Puppeteer verification harness that proves 0px adherence."
+model: sonnet
+---
+
+# Müller-Brockmann Grid Systems — built real, visible, and verified
+
+Josef Müller-Brockmann (1914–1996), Zurich; *Grid Systems in Graphic Design* (1981) is the corpus. The grid is treated as an ethic, not decoration: **"The grid system is an aid, not a guarantee. It permits a number of possible uses and each designer can look for a solution appropriate to his personal style. But one must learn how to use the grid; it is an art that requires practice."** This skill encodes that discipline AND — the part most attempts get wrong — the front-end engineering to make the grid genuinely load-bearing on the web, plus a harness that PROVES it.
+
+> Two real review notes this skill exists to prevent:
+> 1. *"the grid is just slapped on top and misaligned"* → the overlay wasn't in the same content box as the content (see §2.2).
+> 2. *"the H in the headline is off the grid"* → the headline's BOX was on the grid but its INK wasn't; large glyphs carry a side-bearing (see §2.6). **Box-on-grid ≠ ink-on-grid.**
+
+---
+
+## PART 1 — THE DISCIPLINE (decide before drawing)
+- **Objective order.** The grid brings "constructive thought," legibility, and "objective and functional" design. Restraint is the point; the system, not the ego, organizes the page.
+- **Modular grid.** Divide the type area into a field of **modules** — columns AND rows — separated by consistent **gutters**, inside defined **margins**. Text and images occupy whole modules. Müller-Brockmann specimens common field counts (8 / 20 / 32 fields). For the web, a **12-column grid + 8px baseline** is a robust general default; a **6×6 or 4×8 modular field grid** when you want visible rows too.
+- **Baseline grid.** Vertical rhythm is sacred: **leading = a whole multiple of the baseline unit**, and every element snaps to it. This is what makes facing columns and images line up across the page.
+- **Typography.** A **grotesque sans** (Akzidenz-Grotesk / Helvetica; on the web Inter, Helvetica Now, Archivo). **Flush-left, ragged-right.** Few sizes, large jumps in **scale** for hierarchy; objective, not expressive. Big **numerals/data set large** is a signature move.
+- **Palette.** Pure white paper, near-black ink, **one accent — red is canonical**. Avoid the warm-cream "Claude look"; **never blue/purple gradients** (hard house rule).
+- **White space + asymmetry.** Generous margins; asymmetric compositions held in tension by the grid.
+
+---
+
+## PART 2 — MAKE THE GRID REAL ON THE WEB (the load-bearing engineering)
+`grid_tokens.py` emits this whole scaffold correctly; the rules below are why it's built the way it is.
+
+### 2.1 One source of truth
+Put every grid parameter in `:root` CSS variables — `--cols, --gutter, --margin, --bl (baseline), --lh (leading=3×bl), --maxw`. **Content and the overlay both read these same variables.** Never hand-author the overlay separately or it will drift.
+
+### 2.2 The overlay MUST live in the SAME content box as the content  ← #1 bug
+Failure mode: content sits in a centered `max-width` container while the overlay is a **full-width sibling** of the section. On any viewport wider than `--maxw`, the centered content and the full-width overlay no longer share column positions → "slapped on top / misaligned."
+**Fix:** put `.guides` *inside* the same `.wrap`, and draw the column guides with `left/right = var(--margin)` and the **same** `repeat(var(--cols),1fr)` + `column-gap:var(--gutter)`. Then the overlay columns **are** the content columns at every width. Add left/right margin lines at `var(--margin)`.
+
+### 2.3 Place every element by column LINE via subgrid bands
+Don't eyeball spans. Each horizontal **band** spans all columns and re-exposes them:
+```css
+.band{grid-column:1 / -1; display:grid; grid-template-columns:subgrid; column-gap:var(--gutter); align-items:start;}
+@supports not (grid-template-columns:subgrid){ .band{grid-template-columns:repeat(var(--cols),1fr);} }
+```
+Children place with `grid-column: <startline> / <endline>` (e.g. `1 / 6`, `6 / 13`). Every headline, paragraph, photo, caption now snaps to identical lines.
+
+### 2.4 Lock vertical rhythm to the baseline
+- Leading = `--lh` (e.g. 24px = 3×8). **Every line-height a multiple of the baseline, in px (not unitless) for display type** — unitless line-heights on large type push the box off the grid.
+- Every margin/padding a multiple of the baseline. Spread top/bottom padding a multiple too, so content starts on a line.
+- **Media heights = multiples of the leading** (e.g. 240/360/432/480px) so a photo's top AND bottom both land on lines.
+- Hairline rules sit inside a baseline-height band, not free-floating.
+
+### 2.5 The toggle (sizzle within the sizzle)
+A control (button **+ `G` key**) toggles `body.grid-on`; overlay fades 0→1. Overlay draws: translucent **numbered column fields**, the **baseline** (major line every `--lh`, faint minor every `--bl`), and **margin lines**. Showing the real grid the page is built on IS the demo.
+
+### 2.6 OPTICAL ALIGNMENT — display ink, not its box  ← the subtle bug
+A 180px headline whose layout box is exactly on line 1 still looks misaligned against body text, because the letterform's **ink** is inset by its **left side-bearing**. Cure at runtime:
+```js
+// after document.fonts.ready and on resize:
+var cvs=document.createElement('canvas'),ctx=cvs.getContext('2d');
+document.querySelectorAll('.masthead,.numeral,.shead h2,.h2b').forEach(function(el){
+  el.style.marginLeft='0px';
+  var cs=getComputedStyle(el),ch=(el.textContent||'').trim()[0]; if(!ch) return;
+  if(cs.textTransform==='uppercase') ch=ch.toUpperCase();
+  ctx.font=cs.fontStyle+' '+cs.fontWeight+' '+cs.fontSize+' '+cs.fontFamily; ctx.textAlign='left';
+  var abl=ctx.measureText(ch).actualBoundingBoxLeft;     // +ve = ink overhangs left of box
+  if(isFinite(abl)) el.style.marginLeft=abl.toFixed(2)+'px'; // shift box so INK lands on the line
+});
+```
+Apply to the masthead, big numerals, and section headlines. It scales with fluid type (re-runs on resize) and uses the **actually-loaded** font, so it's correct in the user's browser.
+**CRITICAL measurement caveat:** side-bearing is **font-specific**. If you measure with the wrong font you get the wrong nudge. Headless/sandbox Chrome usually lacks the webfont, so canvas falls back to a different grotesque (measured **−16px on the fallback vs −7px on real Inter** for the same `H`). To verify optics offline you must **embed the real webfont** via `@font-face` (local TTF). In production the runtime JS measures the loaded font and is correct.
+
+---
+
+## PART 3 — VERIFY (don't trust, measure)  → `verify_grid.js`
+Render with headless Chrome (Puppeteer) and assert, at **several widths including > and < `--maxw`** (to catch centered-container drift, e.g. 1440 / 1180 / 900):
+1. **Column adherence** — every placed `.band > *` left snaps to a column START and right to a column END (~0px). **Exclude the optically-aligned display elements** from this box check (their box is intentionally side-bearing-offset; they're validated in step 4). **Gotcha:** build BOTH the column-start set and the column-end set — a grid item spanning "to line N" ends at the *far* side of the gutter, so single-edge math falsely reports a one-gutter error.
+2. **Overlay match** — each `.guides .col` rect equals the computed column rect (~0px).
+3. **Baseline** — text tops modulo the baseline ≈ 0 (tolerance ≈ half a baseline; the box-top is a proxy — the leading does the real work).
+4. **Optical ink** — each display element's ink-left (box − `actualBoundingBoxLeft`, real font) equals **its own** column line (nearest column-start to its box), not always line 1.
+
+Sandbox Chrome flags that work: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`. `file://` works for non-ES-module pages; the CLI `--screenshot` can hang on tall pages — drive via Puppeteer and screenshot per viewport. Read PNGs back with the image-capable Read tool to eyeball a **zoom crop of the top-left corner** (masthead vs body vs column line) — the fastest human check.
+
+A clean run looks like: `col=0px overlay=0px baseline≤4px ink=0px` → `GRID VERIFY: PASS`.
+
+---
+
+## PART 4 — CRAFT DEFAULTS (so it looks excellent, not just aligned)
+- **Palette:** white `#fff`, ink `#111`, one accent (Swiss red `#e4002b`). No warm-cream Claude look; no blue/purple gradients.
+- **Type:** a real grotesque webfont (Inter / Helvetica Now / Archivo) for display + body; a **mono** (Space Mono / IBM Plex Mono) for folios, captions, grid annotations — reinforces the technical register. Non-Latin via Noto Sans JP etc.
+- **Hierarchy** through scale + weight + white space, not color. Treat key data as **large numerals**. Kicker labels in mono caps. Per-spread folios.
+- **Real photography.** Ground real subjects in real photos (`SearchImages`). **Host each image via `PublishFilePublicly` and embed the `pub.hyperagent.com` URL** — a `PublishWebpage` artifact runs in a sandboxed iframe that can't authenticate thread-scoped `/api/files/...` URLs (broken-image trap).
+- **Type fidelity if you ever rasterize art** (cairosvg / headless screenshots / image-gen reference): a `Helvetica`/`Arial` CSS stack silently falls back to **Noto Sans** (reads like Calibri). Render in **Liberation Sans** or an embedded Helvetica/Arimo TTF before trusting it. (Same trap as the optical-measurement caveat: wrong font in → wrong result out.)
+- **Spread model:** full-width sections, each its own per-spread `.grid` + `.guides`, consistent margins/folios.
+
+---
+
+## PART 5 — WORKFLOW
+1. Pick the subject; gather real photos; host them publicly.
+2. Generate the scaffold: `python3 grid_tokens.py` (or `--scaffold` for a full page; `--cols/--baseline/--gutter/--margin/--maxw/--accent` to taste; it warns if gutter/margin aren't baseline multiples).
+3. Build spreads as **subgrid bands**; place everything by **column line**; lock spacing/line-heights/media heights to the **baseline**.
+4. Add the overlay (same content box) + toggle + optical-alignment JS (already in the scaffold; point its selector list at your display elements).
+5. Publish, then **verify**: `CHROME=… PUP=… node verify_grid.js <file-or-url> --widths=1440,1180,900`. Eyeball a top-left zoom crop. Fix, republish.
+
+## SCRIPTS
+- **`grid_tokens.py`** — deterministic scaffold generator. Emits the `:root` tokens, `.grid`/`.band` (subgrid) scaffold, `.guides` overlay CSS, toggle JS, and the optical-alignment JS — all wired to one source of truth. `--scaffold` emits a full minimal HTML page. No network/credentials.
+- **`verify_grid.js`** — Puppeteer harness implementing all four checks above with the corrected both-edges column math, the optical-exclusion, per-element column-line ink targeting, and PASS/FAIL output at multiple widths. Env: `CHROME` (chrome binary), `PUP` (puppeteer-core module path).
+
+## CREED
+A grid you can't toggle on and measure is a mood board, not a system. Build it from one source of truth, prove it at 0px, and align the **ink**.