move skills source of truth to .agents/

.agents/skills/cleanup-commits/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: cleanup-commits
+description: Rebase and reorganize commits into clean, meaningful commits for easy PR review
+disable-model-invocation: true
+argument-hint: "[base-branch]"
+allowed-tools: Bash(git *), Read, Grep, Glob
+---
+
+# Cleanup Commits for PR Review
+
+Reorganize all commits on the current branch into clean, logical commits that are easy to review.
+
+## Arguments
+
+- `$0` - Base branch to rebase onto (default: `main`)
+
+## Process
+
+### 1. Preparation
+
+First, verify clean working state and identify the base:
+
+```bash
+git status --porcelain
+```
+
+If there are uncommitted changes, warn the user and stop.
+
+Get the base branch (use argument or default to `main`):
+
+- Base branch: `${0:-main}`
+
+### 2. Analyze Changes
+
+Get the full picture of what changed:
+
+```bash
+git log --oneline ${0:-main}..HEAD
+git diff --stat ${0:-main}..HEAD
+git diff ${0:-main}..HEAD
+```
+
+Also check the files changed to understand the scope:
+
+```bash
+git diff --name-only ${0:-main}..HEAD
+```
+
+### 3. Plan Commits
+
+Based on the diff analysis, identify logical groupings. Common patterns:
+
+- **Feature commits**: Group related functionality together
+- **Refactor commits**: Structural changes without behavior change
+- **Config/setup commits**: Dependencies, configs, tooling
+- **Test commits**: Test additions/changes
+- **Fix commits**: Bug fixes
+- **Docs commits**: Documentation updates
+
+Create a plan listing each commit with:
+
+- Clear subject line (imperative mood, <72 chars)
+- Which files go in each commit
+- Why this grouping makes sense
+
+**Show the plan to the user and ask for confirmation before proceeding.**
+
+### 4. Execute Rebase
+
+After user confirms the plan:
+
+```bash
+git reset --soft ${0:-main}
+git reset HEAD
+```
+
+This unstages everything while keeping all changes in working directory.
+
+### 5. Create Commits
+
+For each logical group in the plan:
+
+1. Stage the relevant files:
+
+   ```bash
+   git add <specific-files>
+   ```
+
+2. Create commit with descriptive message:
+
+   ```bash
+   git commit -m "type: concise description
+
+   - Detail 1
+   - Detail 2"
+   ```
+
+Use conventional commit prefixes:
+
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `refactor:` - Code restructuring
+- `test:` - Test changes
+- `docs:` - Documentation
+- `chore:` - Build, config, dependencies
+
+### 6. Verify Result
+
+Show the new commit history:
+
+```bash
+git log --oneline ${0:-main}..HEAD
+```
+
+Compare with original to ensure nothing was lost:
+
+```bash
+git diff ${0:-main}..HEAD --stat
+```
+
+## Important Notes
+
+- This is a **destructive operation** - it rewrites git history
+- Only use on branches that haven't been pushed, or be prepared to force push
+- Always verify the final diff matches the original diff
+- If something goes wrong, use `git reflog` to recover
+
+## Example Output
+
+Before:
+
+```
+abc1234 wip
+def5678 more stuff
+ghi9012 fix thing
+jkl3456 wip2
+```
+
+After:
+
+```
+aaa1111 feat: add user authentication flow
+bbb2222 refactor: extract validation helpers
+ccc3333 test: add auth integration tests
+```

.claude/skills/design-first-engineering/SKILL.md → .agents/skills/design-first-engineering/SKILL.md

@@ -19,8 +19,8 @@ Work through these steps **in order**. Complete and confirm each step with the u
 
 List the core requirements — what the system must accomplish from the user's perspective. Stay at the "what", not the "how". No implementation details, no technology choices, no component names.
 
-Good: "Users can search exercises by muscle group"
-Bad: "ElasticSearch index for exercise lookup via REST API"
+Good: "Users can search authors by creation date"
+Bad: "ElasticSearch index for authors lookup via REST API"
 
 Ask the user to confirm the capabilities list is complete and correct before proceeding. Push back if implementation details creep in — they belong in later steps.
 
@@ -72,4 +72,4 @@ Think about:
 - Use a clear "Step N complete, moving to Step N+1" transition
 - If a later step reveals a problem with an earlier one, go back and fix it — that's the whole point of designing first
 - Keep everything in a single evolving design document format
-- Do not write implementation code — pseudocode in contracts is fine, but no real code
+- Do not write implementation code — pseudocode in contracts is fine, but no real code

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

@@ -0,0 +1,11 @@
+---
+name: grill-me
+description: |
+  Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we
+reach a shared understanding. Walk down each branch of the design tree,
+resolving dependencies between decisions one by one.
+
+If a question can be answered by exploring codebase, explore the codebase instead.

.agents/skills/ralph-it/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ralph-it
+description: Pick and implement the next user story from a PRD GitHub issue. Analyzes merged PRs for prior work and findings, proposes a plan, implements it, and creates a PR linking back to the PRD. Use when user says "ralph it", "ralph-it", or wants to work through PRD user stories.
+---
+
+You are Ralph — a methodical implementer that works through PRD user stories one at a time.
+
+Input: a GitHub issue URL/number containing a PRD with User Stories. If not provided as an argument, ask for it.
+
+## Step 1: Gather Context
+
+1. Fetch the PRD issue from GitHub (use `gh` CLI).
+2. Parse all User Stories from the PRD.
+3. List all merged PRs in this repo. For each merged PR:
+   - Check if it references the PRD issue or any user story.
+   - Collect any findings, notes, or follow-up items mentioned in the PR body/comments.
+4. Determine which user stories are already done (linked to merged PRs or marked done in the issue).
+
+## Step 2: Pick Next User Story
+
+Based on:
+- What's already been implemented (from merged PRs)
+- Dependencies between user stories
+- Findings/notes from previous PRs that inform what to tackle next
+
+Present to the user:
+- Summary of what's done so far
+- Which user story you recommend next and why
+- Any relevant findings from previous PRs
+
+Wait for user confirmation before proceeding.
+
+## Step 3: Plan
+
+Propose an implementation plan for the chosen user story. Use Plan mode.
+
+Grill the user on any ambiguities — do NOT proceed with assumptions. Once the user is happy with the plan, move on.
+
+## Step 4: Implement
+
+Execute the plan. Run tests, typecheck, and verify the implementation works.
+
+## Step 5: Create PR & Close the Loop
+
+1. Create a new branch and commit all changes.
+2. Create a PR using `gh` CLI with:
+   - Title referencing the user story
+   - Body containing:
+     - Link to the original PRD issue
+     - Which user story this implements
+     - **Findings**: anything discovered during implementation that's relevant for follow-up work (edge cases, tech debt, design decisions, open questions)
+3. Update the PRD issue: mark the completed user story as done (edit the issue body, check the checkbox or strike it through).
+
+## Step 6: Loop
+
+After successfully creating the PR, tell user they should clear the context and loop again.