bigpowers 1.0.0

package/orchestrate-project/REFERENCE.md

@@ -0,0 +1,89 @@
+# Orchestrate Reference: Phases, Modes, and Workflows
+
+Detailed documentation for the `orchestrate-project` meta-skill.
+
+## The 6-Phase Core Loop
+
+### PHASE 1: DISCOVER
+- **Goal**: Understand the problem completely and map existing context.
+- **Deliverables**: `PROJECT.md`, `CONTEXT.md`.
+- **Skills**: `survey-context`, `elaborate-spec`, `grill-me`.
+- **Gate**: Confirm ("Is the problem clear?").
+
+### PHASE 2: ELABORATE
+- **Goal**: Research solutions and lock architectural design.
+- **Deliverables**: `RESEARCH.md`, ADRs (Architecture Decision Records).
+- **Skills**: `model-domain`, `define-language`, `challenge-design`.
+- **Gate**: Quality ≥94% (via `request-review`) + Confirm ("Are decisions locked?").
+
+### PHASE 3: PLAN
+- **Goal**: Write a verifiable implementation plan with success criteria.
+- **Deliverables**: `PLAN.md` with `verify:` commands.
+- **Skills**: `scope-work`, `slice-tasks`, `define-success`, `plan-work`.
+- **Gate**: Quality (request-review ≥94%) + slopcheck [SUS]/[SLOP].
+
+### PHASE 4: BUILD
+- **Goal**: Execute the plan step-by-step using TDD and vertical slices.
+- **Deliverables**: Code, `SUMMARY.md`.
+- **Skills**: `kickoff-branch`, `develop-tdd`, `delegate-task`, `execute-plan`.
+- **Gate**: Integration tests PASS.
+
+### PHASE 5: VERIFY
+- **Goal**: Validate success criteria and ensure production readiness.
+- **Deliverables**: `VERIFICATION.md`, audit results.
+- **Skills**: `validate-fix`, `audit-code`, `request-review`.
+- **Gate**: Quality ≥94%, coverage ≥95%, audits ≥93%.
+
+### PHASE 6: RELEASE
+- **Goal**: Ship to production with full traceability.
+- **Deliverables**: Release tag (vX.Y.Z), release notes.
+- **Skills**: `commit-message`, `release-branch`.
+- **Gate**: Safety ("About to push to main. Confirm?").
+
+---
+
+## Orchestration Modes
+
+### Mode 1: Standard (Enforce All Gates)
+**Use Case**: New features, major refactors, architectural changes.
+**Behavior**:
+- All Confirm gates require explicit user approval.
+- All Quality gates are hard stops if threshold is not met.
+- No shortcuts or phase skipping.
+
+### Mode 2: Fast-Track (Skip Negotiable Gates)
+**Use Case**: Hotfixes, minor improvements, refactors on well-tested code.
+**Behavior**:
+- Skip Discover if `PROJECT.md` exists.
+- Skip Elaborate if design decisions are already locked.
+- Skip Verify if coverage ≥95% + all tests PASS.
+- Soft gates auto-approve if baseline conditions are met.
+
+### Mode 3: Ad-Hoc (Legacy, Warnings Only)
+**Use Case**: Exploration, prototyping, spikes (NOT for production).
+**Behavior**:
+- Gates emit warnings but do not block execution.
+- User can manually skip any phase.
+- No enforced quality thresholds.
+
+---
+
+## Gate & Checkpoint Types
+*See `docs/references/gates.md` and `docs/references/checkpoints.md` for full specs.*
+
+- **Confirm**: Requires human "yes/no" decision.
+- **Quality**: Automated threshold check (e.g., coverage, audit score).
+- **Safety**: Destructive actions require risk acknowledgment.
+- **Transition**: Mandatory artifact presence check.
+- **slopcheck**: Identification of [SUS] (Suspicious) or [SLOP] (High-risk) packages.
+
+---
+
+## Error Recovery & State
+Orchestrate maintains `specs/STATE.md` to track:
+- **Current Phase**: Position in the loop.
+- **Artifacts**: Checklist of completed deliverables.
+- **Decisions**: Audit trail of architectural choices.
+- **Risks**: Active project risks and mitigation status.
+
+In the event of a crash or exit, run `claude /orchestrate --resume` to pick up exactly where the session left off.

package/orchestrate-project/SKILL.md

@@ -0,0 +1,59 @@
+---
+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.
+---
+
+# Orchestrate
+
+The orchestrate skill coordinates projects through a prescriptive 6-phase core loop with hard gates, ensuring consistent quality and preventing scope creep.
+
+## Quick Start
+
+```bash
+# Start a new project (creates PROJECT.md and begins discover phase)
+claude /orchestrate --mode standard
+
+# Or resume an existing project at the current phase
+claude /orchestrate --mode standard --resume
+
+# For low-risk scenarios (hotfixes, refactors on well-tested code)
+claude /orchestrate --mode fast-track
+```
+
+## The 6-Phase Core Loop
+
+1. **DISCOVER** (3-6 hours): Understand problem. Deliverables: PROJECT.md, CONTEXT.md.
+2. **ELABORATE** (3-6 hours): Research solutions. Deliverables: RESEARCH.md.
+3. **PLAN** (2-4 hours): Write verifiable plan. Deliverables: PLAN.md.
+4. **BUILD** (1-8 hours): Execute plan. Deliverables: Code, SUMMARY.md.
+5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: VERIFICATION.md.
+6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag.
+
+See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
+
+## How Orchestrate Works
+
+1. **Maintains STATE.md** — Tracks current phase, artifacts, decisions, risks.
+2. **Spawns appropriate skills** — Calls survey-context, elaborate-spec, plan-work, etc.
+3. **Enforces gates** — Hard stops if success criteria not met.
+4. **The Gatekeeper** (v1.19.0) — Between every Story implementation in PHASE 4:
+   - READ `specs/RELEASE-PLAN.md` to verify completion.
+   - REQUIRE that the previous Story is marked `[x] Done`.
+   - REFUSE to call `update_topic` for a new Story until the previous one is physically evidenced as complete.
+5. **Pauses for confirmation** — After each phase, asks "Ready to proceed?".
+6. **Archives history** — Saves PLAN.md as specs/PLAN-vX.Y.Z.md.
+
+## Orchestration Modes
+
+- **Standard**: Enforce all gates. Use for new features and major refactors.
+- **Fast-Track**: Skip negotiable gates. Use for hotfixes and minor improvements.
+- **Ad-Hoc**: Warnings only. Use for prototyping and spikes (non-production).
+
+See [REFERENCE.md](REFERENCE.md) for full mode behaviors.
+
+## Verification
+
+All phases complete with artifacts:
+```bash
+verify: test -f specs/PROJECT.md && test -f specs/PLAN.md && test -f specs/VERIFICATION.md && echo "✅ All phases complete"
+```

package/organize-workspace/REFERENCE.md

@@ -0,0 +1,80 @@
+# clean-my-room — reference patterns
+
+Optional commands for the agent. Adapt paths; **dry-run** before bulk delete.
+
+## Discover large top-level entries
+
+```sh
+du -sh ./* .[!.]* 2>/dev/null | sort -hr | head -30
+```
+
+## Find common logs (respect `.gitignore` when using fd)
+
+```sh
+fd -t f '\.log$' . 2>/dev/null
+fd 'npm-debug' . 2>/dev/null
+```
+
+## Find build-like dirs (review list before `rm -rf`)
+
+```sh
+fd -t d '^(dist|build|out|target|\.next|coverage)$' . --max-depth 3 2>/dev/null
+```
+
+## Stray markdown at repo root (heuristic)
+
+```sh
+ls -1 ./*.md 2>/dev/null
+fd -t f '^(draft|scratch|untitled|TODO|notes)' . --max-depth 1 2>/dev/null
+```
+
+## Git-safe moves
+
+```sh
+git status -sb
+git check-ignore -v <path>   # was ignored?
+# Tracked: git mv old new
+# Untracked: mkdir -p … && mv old new
+```
+
+## `.gitignore` revision (after cleanup)
+
+**Goal:** stop regenerated junk from polluting `git status`, without hiding real source.
+
+1. **Read** root `.gitignore` and, in monorepos, `apps/*/.gitignore` / `packages/*/.gitignore` as needed. Check **`.git/info/exclude`** for machine-only rules that should *not* be committed (keep personal noise there; don’t copy into shared `.gitignore` unless the team agrees).
+2. **Per-path checks** (last match wins; shows which file defined the rule):
+
+   ```sh
+   git check-ignore -v path/to/artifact
+   git status -u --ignored    # optional: see ignored names (noisy)
+   ```
+
+3. **Pattern style**
+   - Leading `/` = relative to the `.gitignore`’s directory (e.g. `/dist/` = only that folder at that level, not all nested `dist` unless intended).
+   - `**` for deep trees, e.g. `**/*.log`, when noise appears at many depths.
+   - **Negation** (`!`) is tricky: later rules, parent dirs, and `git add -f` interact—prefer narrow positive ignores over `!` unless you already use negation in that file.
+4. **Do not** add rules that would ignore: application source, small JSON/YAML config the repo tracks, or `!important` assets. When unsure, run `git check-ignore -v` on a *known good* file that must stay tracked.
+5. **Tracked but should be ignored** (user already committed `build/` once): this skill does not silently fix history; flag `git rm -r --cached <path>` + `.gitignore` as a **separate** explicit step the user must approve.
+6. **Global excludes** (optional heads-up for “why is this still ignored?”):
+
+   ```sh
+   git config --get core.excludesfile
+   ```
+
+## Safety: never pass through these in automated deletes
+
+- `.git/`, `.svn/`, `.hg/`
+- `node_modules/`, `vendor/`, `venv/`, `.venv/`, `__pypackages__/`
+- Files matching `.env`, `.env.*` (except `.env.example` if intentional)
+- `~/.ssh`, `id_rsa*`, `*.pem` inside project trees
+
+## Post-deploy / server-ish extras (name buckets to stack)
+
+- Docker: dangling images/volumes (only if user asked for Docker cleanup; requires `docker` context).
+- CI: `*.log` under `build/`, artifact dirs from previous runs.
+- K8s: local `*.kube`, tmp kubeconfigs—list only; do not delete without confirmation.
+
+## Inspiration
+
+- Same **inventory → plan → confirm → act** flow as [post-deploy environment cleanup](https://mcpmarket.com/tools/skills/post-deploy-environment-cleanup) style workflows.
+- [Agent template public](https://github.com/matsuni-kk/agent_template_public): honor **Flow** (draft) vs **Stock** (stable); do not “clean” user drafts from Flow without explicit approval.

package/organize-workspace/SKILL.md

@@ -0,0 +1,74 @@
+---
+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.
+---
+
+# Organize Workspace
+
+## Principles
+
+- **Read-only first**: inventory and size (`du`, `ls -la`) before any change.
+- **Never delete or move** without a numbered list and **explicit user approval** (item-level or "approve all").
+- **Prefer `fd` / `ripgrep` / `find`** in that order; avoid blind `rm -rf` on vague globs.
+- **Do not** touch `.git/`, `node_modules/`, `venv/`, `.env*`, or SSH keys; flag them only if the user asked about them.
+- Confirm prompts in the **user's language** if they are not writing in English.
+
+## 1. Establish scope
+
+- Default: **current project root** (where the user is working) or the path they name.
+- Record OS (macOS vs Linux) for ignore patterns (e.g. `.DS_Store`).
+
+## 2. Classify candidates (scan)
+
+Group findings under these **buckets**:
+
+| Bucket | Examples | Typical action |
+|--------|----------|----------------|
+| **Logs & temp** | `*.log`, `logs/`, `tmp/`, `temp/`, `*.pid` | Delete after confirm |
+| **Build / cache** | `dist/`, `build/`, `.next/`, `coverage/`, `.turbo/` | Delete if rebuildable |
+| **Package caches** | root `.cache/`, `__pycache__/` | Offer delete |
+| **Stray drafts** | root-level `*.md` named `draft`, `scratch`, `temp` | User picks: delete, move to `specs/`, or keep |
+| **Duplicate / dump dirs** | `old/`, `backup/`, `copy/`, `*_backup` | List + ask |
+
+Use quick size hints: `du -sh` per top-level dir; sort large items first.
+
+## 3. Assets & data (organize, not only delete)
+
+If the user wants **organization**:
+
+1. Propose a **single convention**, e.g.:
+   - `assets/` — images, fonts, static media
+   - `data/` — JSON, CSV, fixtures, samples
+   - `specs/` — all planning and domain documents
+2. For each cluster of loose files, suggest **one target path** and a short rationale.
+3. Use **git-aware moves** when in a repo: `git mv` if tracked; otherwise `mv` and report.
+4. Never move secrets or production DB dumps into `docs/` or public `assets/`.
+
+## 4. Present the plan
+
+Output a table or numbered list:
+
+- Path
+- Kind (log / build / draft / asset / other)
+- Approx size
+- Proposed action: **delete** | **move to …** | **keep**
+
+Ask: *"Delete items 1–3? Move 4–5? Skip 6?"*
+
+## 5. Execute after approval
+
+- Deletes: on macOS, prefer a Trash-capable tool (e.g. `trash` from Homebrew) if installed; else `rm` with paths echoed back.
+- Moves: create dirs with `mkdir -p` first; one batch at a time.
+- **Verify**: re-run listing on affected parents; if anything failed, report stderr.
+
+## 6. Post-cleanup and `.gitignore` revision
+
+Do this when the repo is under Git and the cleanup surfaced **untracked** noise:
+
+1. **Inventory ignore sources**: root `.gitignore`, `.git/info/exclude`, any subpackage `.gitignore` files.
+2. **Map findings to rules**: for each deleted or recurring artifact class, check whether a pattern already exists; note gaps.
+3. **Propose a patch**: list only **concrete** changes — `+` add / `-` remove / `~` reword — with one-line why.
+4. **User must approve** the exact diff before editing the file.
+5. **Verify**: run `git check-ignore -v <path>` on 2–3 representative paths.
+
+See [REFERENCE.md](REFERENCE.md) for shell patterns, `.gitignore` mechanics, and safety checks.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "bigpowers",
+  "version": "1.0.0",
+  "description": "44 agent skills for spec-driven, test-first software development by solo developers",
+  "main": "index.js",
+  "scripts": {
+    "sync": "bash scripts/sync-skills.sh",
+    "install": "bash scripts/install.sh",
+    "postinstall": "bash scripts/sync-skills.sh && bash scripts/install.sh",
+    "release": "semantic-release"
+  },
+  "keywords": [
+    "skills",
+    "agents",
+    "claude",
+    "development",
+    "spec-driven",
+    "test-first"
+  ],
+  "author": "Daniel",
+  "license": "MIT",
+  "homepage": "https://github.com/danielvm-git/bigpowers#readme",
+  "bugs": {
+    "url": "https://github.com/danielvm-git/bigpowers/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielvm-git/bigpowers.git"
+  },
+  "bin": {
+    "bigpowers": "./bin/bigpowers.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "^11.0.3",
+    "@semantic-release/release-notes-generator": "^12.1.0",
+    "semantic-release": "^22.0.12"
+  }
+}

package/plan-refactor/SKILL.md

@@ -0,0 +1,75 @@
+---
+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.
+---
+
+# Plan Refactor
+
+Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR.md`.
+
+## Steps
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice: "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Save the refactor plan to `specs/REFACTOR.md`. Create the `specs/` directory if it doesn't exist.
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+Each commit entry follows this format:
+```
+N. <commit description> → verify: <runnable command>
+```
+
+## Decision Document
+
+A list of implementation decisions that were made:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes, API contracts, specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>
+
+After writing `specs/REFACTOR.md`, suggest running `kickoff-branch` next to create a refactor branch.

package/plan-release/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: plan-release
+description: Convert elaborated specs into a structured release plan with Gherkin acceptance criteria and WSJF-sorted epics. Produces specs/RELEASE-PLAN.md. Use when a spec is clear and ready to plan, after elaborate-spec, or when the user wants a release plan broken into epics and stories.
+---
+
+# Plan Release
+
+> **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.
+
+Synthesize the conversation context into `specs/RELEASE-PLAN.md`. No new interview — only clarify if something is genuinely ambiguous.
+
+## Process
+
+### 1. Draft epics and stories
+
+From the conversation context, define:
+- **Epics** — major capability areas (Priority: P1/P2/P3 | Value: High/Med/Low | Effort: S/M/L)
+- **Stories** — "As a [actor], I want [feature] so that [benefit]"
+
+WSJF-sort epics: score = (Business Value + Time Criticality + Risk Reduction) / Job Size. Highest score first.
+
+### 2. Write acceptance criteria (Gherkin)
+
+For each story, write at least one happy-path and one edge-case scenario:
+
+```
+Acceptance Criteria:
+  Feature: [name]
+    Scenario: [happy path]
+      Given [initial state]
+      When  [user action]
+      Then  [observable outcome]
+    Scenario: [edge case]
+      Given ...
+      When  ...
+      Then  ...
+```
+
+### 3. Write tasks with verify commands
+
+Under each story, list implementation tasks:
+
+```
+Tasks:
+  - [ ] Write failing test for scenario 1 → verify: <cmd>
+  - [ ] Implement [module/function]       → verify: <cmd>
+  - [ ] Integrate and smoke-test          → verify: <cmd>
+```
+
+Every task must have a `verify:` command. No verify command = not a task.
+
+### 4. Save specs/RELEASE-PLAN.md
+
+```
+## Epic 1: [Name]
+Priority: P1 | Value: High | Effort: M | WSJF: [score]
+
+### Story 1.1: As a [actor], I want [feature] so that [benefit]
+Status: [ ] Not started
+
+Acceptance Criteria:
+  Feature: ...
+    Scenario: ...
+
+Tasks:
+  - [ ] ... → verify: <cmd>
+```
+
+→ verify: `grep -c "Scenario:" specs/RELEASE-PLAN.md`
+
+### 5. Suggest next steps
+
+- Run `assess-impact` before `plan-work` for any story touching existing modules.
+- Run `plan-work` per story to produce the detailed step-by-step plan.
+- Run `change-request` if a new requirement arrives mid-flight.

package/plan-work/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: plan-work
+description: Write a detailed implementation plan to specs/RELEASE-PLAN.md. Every step must include a runnable verify command (Karpathy verification template). Use when user has a task to implement and needs a step-by-step plan with evidence checkpoints, or after plan-release produces specs/RELEASE-PLAN.md.
+---
+
+# Plan Work
+
+Produce a detailed, verifiable implementation plan in `specs/RELEASE-PLAN.md`. Every step must be paired with a runnable verify command — "I think it works" is not a step.
+
+> **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
+>
+> **RECURSIVE DISCIPLINE** — This lifecycle apply to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+
+## Pre-flight
+
+Before writing the plan, check if `define-success` has been run. If the task's success criteria are unclear, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
+
+Read any existing `specs/` files: RELEASE-PLAN.md, SCOPE.md, TASKS.md, CONTEXT.md, UBIQUITOUS_LANGUAGE.md.
+
+> **ZOOM-OUT MANDATE** (v1.17.0 Guardrails) — If this plan modifies an existing module, function, or behavior:
+> 1. State the module's **purpose** — what is it responsible for?
+> 2. Name the **callers** — who depends on it?
+> 3. List the **contracts** — what invariants or interfaces must be preserved?
+> 
+> If you cannot answer all three without deep code archaeology, the scope is misunderstood. Stop and clarify with the user before writing steps.
+
+If this plan touches an existing module or symbol, run `assess-impact` first to understand the blast radius before writing steps.
+
+> **DISCOVERY MANDATE** (v1.18.0 Guardrails) — For any step involving external API integration (e.g., macOS CGEventTap, AWS SDK, Third-party libraries):
+> 1. You MUST perform a `google_web_search` or `grep_search` of local documentation to verify the API signature and constraints.
+> 2. You MUST quote at least one technical detail (method name, parameter, or error case) from your discovery in the step's context.
+> 
+> Plans that skip discovery for complex integrations are [SUS] and should be rejected.
+
+> **MULTIPLE INTERPRETATIONS (HARD GATE)** — If the task statement admits ≥2 valid interpretations, you must list them and get a decision from the user before drafting any steps. Do not assume intent.
+
+> **COMPLEXITY PUSHBACK (HARD GATE)** — Every step introducing a new abstraction (class, interface, helper, layer) MUST include a one-sentence "Reason for Depth": _"This abstraction is needed because [forcing function]..."_. If the sentence cannot be filled with a non-trivial reason, the abstraction is premature. Delete it and use inline code instead.
+
+## Process
+
+### 1. Explore the codebase
+
+Use the Agent tool with subagent_type=Explore to understand:
+- Affected modules and their current interfaces
+- Existing test patterns to follow
+- Any similar features already implemented (prior art)
+- Dependencies that will be needed
+
+### 2. Draft steps
+
+Break the implementation into the smallest possible steps where each step:
+- Leaves the codebase in a working state (tests pass)
+- Has exactly one observable outcome
+- Can be verified with a single runnable command
+
+**Red-flag check**: before moving to Step 3, name any rationalization you caught yourself making — skipping a gate, adding out-of-scope steps, omitting a verify command. Write them out; do not suppress them.
+
+### 3. Write specs/RELEASE-PLAN.md
+
+Append the detailed steps under the relevant story in `specs/RELEASE-PLAN.md`. Create the `specs/` directory if it doesn't exist.
+
+<plan-template>
+
+### Story [X.Y]: [title] — Implementation Steps
+
+**Context**: [One paragraph: what this story implements and why]
+
+## Steps
+
+1. [Step description] → verify: `<runnable command>`
+
+2. [Step description] → verify: `<runnable command>`
+
+3. [Step description] → verify: `<runnable command>`
+
+...
+
+## Verification Script (Step-by-Step)
+
+[A human-readable, step-by-step script for the user to verify the story's outcome. Focus on user-observable behavior.]
+
+1. [Action 1: e.g. Start the server]
+2. [Action 2: e.g. Open browser to http://localhost:3000]
+3. [Action 3: e.g. Click 'Login']
+4. [Observation: e.g. Verify that the login modal appears]
+
+## Out of scope
+
+- [Explicit exclusions]
+
+## Risks
+
+- [Anything that could go wrong and how to detect it early]
+
+</plan-template>
+
+### 4. Verify step format rules
+
+Every step MUST follow this exact format:
+```
+N. <What to do> → verify: <runnable command that proves it worked>
+```
+
+Good examples:
+```
+1. Add User model with email and name fields → verify: npm test -- user.test.ts
+2. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
+3. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts
+```
+
+Bad examples (no verify command):
+```
+1. Implement the user creation flow
+2. Write tests for the API
+```
+
+### 5. Review with user
+
+Before finalizing, confirm:
+- Does the step order make sense?
+- Is the granularity right (not too coarse, not too fine)?
+- Are the verify commands actually runnable in this project?
+
+After writing `specs/RELEASE-PLAN.md`, suggest `kickoff-branch` (if not already on a feature branch) then `execute-plan` or `develop-tdd`.

package/playwright.config.ts

@@ -0,0 +1,56 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './tests/e2e',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: [
+    ['list'],
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }]
+  ],
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  // webServer: {
+  //   command: 'npm run start',
+  //   url: 'http://127.0.0.1:3000',
+  //   reuseExistingServer: !process.env.CI,
+  // },
+
+  expect: {
+    timeout: 10000,
+  },
+
+  timeout: 60000,
+});