Initialize

Author: MelbourneDeveloper

.claude/skills/ci-prep/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ci-prep
+description: Prepares the current branch for CI by running the exact same steps locally and fixing issues. If CI is already failing, fetches the GH Actions logs first to diagnose. Use before pushing, when CI is red, or when the user says "fix ci".
+argument-hint: "[--failing] [optional job name to focus on]"
+---
+<!-- agent-pmo:d58c330 -->
+
+# CI Prep
+
+Prepare the current state for CI. If CI is already failing, fetch and analyze the logs first.
+
+## Arguments
+
+- `--failing` -- Indicates a GitHub Actions run is already failing. When present, you MUST execute **Step 1** before doing anything else.
+- Any other argument is treated as a job name to focus on (but all failures are still reported).
+
+If `--failing` is NOT passed, skip directly to **Step 2**.
+
+## Step 1 -- Fetch failed CI logs (only when `--failing`)
+
+You MUST do this before any other work.
+
+```bash
+BRANCH=$(git branch --show-current)
+PR_JSON=$(gh pr list --head "$BRANCH" --state open --json number,title,url --limit 1)
+```
+
+If the JSON array is empty, **stop immediately**:
+> No open PR found for branch `$BRANCH`. Create a PR first.
+
+Otherwise fetch the logs:
+
+```bash
+PR_NUMBER=$(echo "$PR_JSON" | jq -r '.[0].number')
+gh pr checks "$PR_NUMBER"
+RUN_ID=$(gh run list --branch "$BRANCH" --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run view "$RUN_ID"
+gh run view "$RUN_ID" --log-failed
+```
+
+Read **every line** of `--log-failed` output. For each failure note the exact file, line, and error message. If a job name argument was provided, prioritize that job but still report all failures.
+
+## Step 2 -- Analyze the CI workflow
+
+1. Find the CI workflow file. Look in `.github/workflows/` for `ci.yml`, `build.yml`, `test.yml`, `checks.yml`, `main.yml`, `pull_request.yml`, or any workflow triggered on `pull_request` or `push`.
+2. Read the workflow file completely. Parse every job and every step.
+3. Extract the ordered list of commands the CI actually runs (e.g., `make lint`, `make fmt-check`, `make test`, `make coverage-check`, `make build`, or whatever the workflow specifies -- it may use `npm`, `cargo`, `dotnet`, raw shell commands, or anything else).
+4. Note any environment variables, matrix strategies, or conditional steps that affect execution.
+
+**Do NOT assume the steps are `make lint`, `make test`, `make coverage-check`, `make build`.** The actual CI may run different commands, in a different order, with different targets. Extract what the CI *actually does*.
+
+## Step 3 -- Run each CI step locally, in order
+
+Work through failures in this priority order:
+
+1. **Formatting** -- run auto-formatters first to clear noise
+2. **Compilation errors** -- must compile before lint/test
+3. **Lint violations** -- fix the code pattern
+4. **Runtime / test failures** -- fix source code to satisfy the test
+
+For each command extracted from the CI workflow:
+
+1. Run the command exactly as CI would run it (adjusting only for local environment differences like not needing `actions/checkout`).
+2. If the step fails, **stop and fix the issues** before continuing to the next step.
+3. After fixing, re-run the same step to confirm it passes.
+4. Move to the next step only after the current one succeeds.
+
+### Hard constraints
+
+- **NEVER modify test files** -- fix the source code, not the tests
+- **NEVER add suppressions** (`#pragma warning disable`, `// eslint-disable`, `#[allow(...)]`)
+- **NEVER delete or ignore failing tests**
+- **NEVER remove assertions**
+
+If stuck on the same failure after 5 attempts, ask the user for help.
+
+## Step 4 -- Report
+
+- List every step that was run and its result (pass/fail/fixed).
+- If any step could not be fixed, report what failed and why.
+- Confirm whether the branch is ready to push.
+
+## Step 5 -- Commit/Push (only when `--failing`)
+
+Once all CI steps pass locally:
+
+1. Commit, but DO NOT MARK THE COMMIT WITH YOU AS AN AUTHOR!!! Only the user authors the commit!
+2. Push
+3. Monitor until completion or failure
+4. Upon failure, go back to Step 1
+
+## Rules
+
+- **Always read the CI workflow first.** Never assume what commands CI runs.
+- Do not push if any step fails (unless `--failing` and all steps now pass)
+- Fix issues found in each step before moving to the next
+- Never skip steps or suppress errors
+- If the CI workflow has multiple jobs, run all of them (respecting dependency order)
+- Skip steps that are CI-infrastructure-only (checkout, setup-node/python/rust actions, cache steps, artifact uploads) -- focus on the actual build/test/lint commands
+
+## Success criteria
+
+- Every command that CI runs has been executed locally and passed
+- All fixes are applied to the working tree
+- The CI passes successfully (if you are correcting an existing failure)

.claude/skills/code-dedup/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: code-dedup
+description: Searches for duplicate code, duplicate tests, and dead code, then safely merges or removes them. Use when the user says "deduplicate", "find duplicates", "remove dead code", "DRY up", or "code dedup". Requires test coverage -- refuses to touch untested code.
+---
+<!-- agent-pmo:d58c330 -->
+
+# Code Dedup
+
+Carefully search for duplicate code, duplicate tests, and dead code across the repo. Merge duplicates and delete dead code -- but only when test coverage proves the change is safe.
+
+## Prerequisites -- hard gate
+
+Before touching ANY code, verify these conditions. If any fail, stop and report why.
+
+1. Run `make test` -- all tests must pass. If tests fail, stop. Do not dedup a broken codebase.
+2. Run `make coverage-check` -- coverage must meet the repo's threshold. If it doesn't, stop.
+3. This is a C# repo with static typing -- proceed.
+
+## Steps
+
+Copy this checklist and track progress:
+
+```
+Dedup Progress:
+- [ ] Step 1: Prerequisites passed (tests green, coverage met, typed)
+- [ ] Step 2: Dead code scan complete
+- [ ] Step 3: Duplicate code scan complete
+- [ ] Step 4: Duplicate test scan complete
+- [ ] Step 5: Changes applied
+- [ ] Step 6: Verification passed (tests green, coverage stable)
+```
+
+### Step 1 -- Inventory test coverage
+
+1. Run `make test` and `make coverage-check` to confirm green baseline
+2. Note the current coverage percentage -- this is the floor. It must not drop.
+3. Identify which files/modules have coverage and which do not. Only files WITH coverage are candidates for dedup.
+
+### Step 2 -- Scan for dead code
+
+1. Look for unused exports, unused functions, unused classes, unused variables
+2. C# analyzer warnings for unused members -- check `make lint` output
+3. For each candidate: **grep the entire codebase** for references. Only mark as dead if truly zero references.
+4. List all dead code found with file paths and line numbers. Do NOT delete yet.
+
+### Step 3 -- Scan for duplicate code
+
+1. Look for functions/methods with identical or near-identical logic
+2. Look for copy-pasted blocks (same structure, maybe different variable names)
+3. Look for multiple implementations of the same algorithm or pattern
+4. Check across module boundaries -- duplicates often hide in different projects
+5. For each duplicate pair: note both locations, what they do, and how they differ
+6. List all duplicates found. Do NOT merge yet.
+
+### Step 4 -- Scan for duplicate tests
+
+1. Look for test functions with identical assertions against the same code paths
+2. Look for test fixtures/helpers that are duplicated across test files
+3. Look for integration tests that fully cover what a unit test also covers (keep the integration test)
+4. List all duplicate tests found. Do NOT delete yet.
+
+### Step 5 -- Apply changes (one at a time)
+
+For each change: **change -> test -> verify coverage -> continue or revert**.
+
+#### 5a. Remove dead code
+- After each deletion: run `make test` and `make coverage-check`
+- If tests fail or coverage drops: **revert immediately**
+
+#### 5b. Merge duplicate code
+- Extract shared logic into a single function/module, update all call sites
+- After each merge: run `make test` and `make coverage-check`
+- If tests fail: **revert immediately**
+
+#### 5c. Remove duplicate tests
+- Delete the redundant test (keep the more thorough one)
+- After each deletion: run `make coverage-check`
+- If coverage drops: **revert immediately**
+
+### Step 6 -- Final verification
+
+1. Run `make test` -- all tests must still pass
+2. Run `make coverage-check` -- coverage must be >= the baseline from Step 1
+3. Run `make lint` and `make fmt-check` -- code must be clean
+4. Report: what was removed, what was merged, final coverage vs baseline
+
+## Rules
+
+- **No test coverage = do not touch.** If a file has no tests covering it, leave it alone entirely.
+- **Coverage must not drop.** The coverage floor from Step 1 is sacred.
+- **One change at a time.** Never batch multiple dedup changes before testing.
+- **When in doubt, leave it.**
+- **Preserve public API surface.**
+- **Three similar lines is fine.** Only dedup when shared logic is substantial (>10 lines) or 3+ copies.

.claude/skills/spec-check/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: spec-check
+description: Audit spec/plan documents against the codebase. Ensures every spec section has implementing code, tests, and matching logic. Use when the user says "check specs", "spec audit", or "verify specs".
+argument-hint: "[optional spec ID or filename filter]"
+---
+<!-- agent-pmo:d58c330 -->
+
+# spec-check
+
+> **Portable skill.** This skill adapts to the current repository. The agent MUST inspect the repo structure and use judgment to apply these instructions appropriately.
+
+Audit spec/plan documents against the codebase. Ensures every spec section has implementing code, tests, and that the code logic matches the spec.
+
+## Arguments
+
+- `$ARGUMENTS` -- optional spec name or ID to check (e.g., `AUTH-TOKEN-VERIFY` or `repo-standards`). If empty, check ALL specs. Spec IDs are descriptive slugs, NEVER numbered (see Step 1).
+
+## Instructions
+
+Follow these steps exactly. Be strict and pedantic. Stop on the first failure.
+
+---
+
+### Step 1: Validate spec ID structure
+
+Before checking code/test references, verify that the specs themselves are well-formed.
+
+1. Find all spec documents (see locations in Step 2).
+2. Extract every section ID using the regex `\[([A-Z][A-Z0-9]*(-[A-Z0-9]+)+)\]`.
+3. **Flag invalid IDs:**
+   - Numbered IDs (`[SPEC-001]`, `[REQ-003]`, `[CI-004]`) -- must be renamed to descriptive hierarchical slugs.
+   - Single-word IDs (`[TIMEOUT]`) -- must have a group prefix.
+   - IDs with trailing numbers (`[FEAT-AUTH-01]`) -- the number is meaningless, remove it.
+4. **Check group clustering:** The first word of each ID is its group. All sections in the same group MUST appear together (adjacent) in the document. If they're scattered, flag it.
+5. **Check for missing IDs:** Any heading that defines a requirement or behavior should have an ID. Flag headings in spec files that look like they define behavior but lack an ID.
+
+If any ID violations are found, report them all and **STOP**.
+
+If all IDs are valid, proceed to Step 2.
+
+---
+
+### Step 2: Find all spec/plan documents
+
+Search for markdown files that contain spec sections with IDs. Look in these locations:
+
+- `docs/*.md`
+- `docs/**/*.md`
+- `SPEC.md`
+- `PLAN.md`
+- `specs/*.md`
+
+Use Glob to find candidate files, then use Grep to confirm they contain spec IDs.
+
+**Spec ID patterns** -- IDs appear in square brackets, typically at the start of a heading or section line. Match this regex pattern:
+
+```
+\[([A-Z][A-Z0-9]*(-[A-Z0-9]+)+)\]
+```
+
+Spec IDs are **hierarchical descriptive slugs, NEVER numbered.** The format is `[GROUP-TOPIC]` or `[GROUP-TOPIC-DETAIL]`.
+
+For each file, extract every spec ID and its associated section title and full section content.
+
+---
+
+### Step 3: Filter specs
+
+- If `$ARGUMENTS` is non-empty, filter the discovered specs.
+- If `$ARGUMENTS` is empty, process ALL discovered specs.
+
+---
+
+### Step 4: Check each spec section
+
+For EACH spec section that has an ID, perform checks A, B, and C below. **Stop on the first failure.**
+
+#### Check A: Code references the spec ID
+
+Search the entire codebase for the spec ID string, **excluding** `docs/`, `node_modules/`, `.git/`, and `*.md` files.
+
+Any comment containing the exact spec ID string counts as a valid code reference.
+
+**If NO code files reference the spec ID:**
+
+```
+SPEC VIOLATION: [ID] "Section Title" has no implementing code.
+
+ACTION REQUIRED: Add a comment referencing [ID] in the file(s) that implement
+this spec section, then re-run spec-check.
+```
+
+**STOP HERE.**
+
+#### Check B: Tests reference the spec ID
+
+Search test files (`**/*.Tests/**`, `**/*Tests.*`, `**/*Test.*`) for the literal spec ID string.
+
+**If NO test files reference the spec ID:**
+
+```
+SPEC VIOLATION: [ID] "Section Title" has no tests.
+
+ACTION REQUIRED: Add tests for [ID] with a comment or test name containing
+the spec ID, then re-run spec-check.
+```
+
+**STOP HERE.**
+
+#### Check C: Code logic matches the spec
+
+1. Read the spec section content carefully.
+2. Read the implementing code.
+3. Compare spec vs. code. Be SENSITIVE and PEDANTIC. Check for ordering violations, missing conditions, wrong logic, missing steps, wrong defaults.
+4. If the code deviates from the spec, report a detailed error with quotes from both spec and code.
+
+**STOP HERE on any deviation.**
+
+5. If the code matches the spec, this check passes. Move to the next spec.
+
+---
+
+### Step 5: Report results
+
+On failure: output ONLY the first violation found.
+
+On success: output a summary table of all specs checked.
+
+## Key principles
+
+- **Fail fast.** Stop on the first violation. One fix at a time.
+- **Be pedantic.** If the spec says it, the code must do it.
+- **Quote everything.** Always quote the spec text and the code in error messages.
+- **Be actionable.** Every error must tell the developer what file to change and what to do.
+- **No numbered IDs.** Spec IDs are hierarchical descriptive slugs, NEVER sequential numbers.

.claude/skills/submit-pr/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: submit-pr
+description: Creates a pull request with a well-structured description after verifying CI passes. Use when the user asks to submit, create, or open a pull request.
+disable-model-invocation: true
+---
+<!-- agent-pmo:d58c330 -->
+
+# Submit PR
+
+Create a pull request for the current branch with a well-structured description.
+
+## Steps
+
+1. Run `make ci` -- must pass completely before creating PR
+2. **Generate the diff against main.** Run `git diff main...HEAD > /tmp/pr-diff.txt` to capture the full diff between the current branch and the head of main. This is the ONLY source of truth for what the PR contains. **Warning:** the diff can be very large. If the diff file exceeds context limits, process it in chunks (e.g., read sections with `head`/`tail` or split by file) rather than trying to load it all at once.
+3. **Derive the PR title and description SOLELY from the diff.** Read the diff output and summarize what changed. Ignore commit messages, branch names, and any other metadata -- only the actual code/content diff matters.
+4. Write PR body using the template in `.github/pull_request_template.md`
+5. Fill in (based on the diff analysis from step 3):
+   - TLDR: one sentence
+   - What Was Added: new files, features, deps
+   - What Was Changed/Deleted: modified behaviour
+   - How Tests Prove It Works: specific test names or output
+   - Spec/Doc Changes: if any
+   - Breaking Changes: yes/no + description
+6. Use `gh pr create` with the filled template
+
+## Rules
+
+- Never create a PR if `make ci` fails
+- PR description must be specific and tight -- no vague placeholders
+- Link to the relevant GitHub issue if one exists
+
+## Success criteria
+
+- `make ci` passed
+- PR created with `gh pr create`
+- PR URL returned to user