feat: add composite actions, command files, and docs (Phase 1)

.claude/commands/.markdownlint.yaml

@@ -0,0 +1,7 @@
+# Command files are prompts, not documents — the first line is an instruction,
+# not a heading.
+MD041: false
+
+# Inherit root line-length setting
+MD013:
+  line_length: 120

.claude/commands/code-review.md

@@ -0,0 +1,20 @@
+Review the current PR for code quality, security, and convention adherence.
+
+Read CLAUDE.md for project conventions.
+
+## Context
+
+- !`gh pr view --json title,body,baseRefName,headRefName,additions,deletions`
+- !`gh pr diff`
+
+## Review Checklist
+
+- Correctness and edge cases
+- Type safety (no unnecessary `any`, non-null assertions justified)
+- Security implications (injection, secrets, auth)
+- Convention adherence per CLAUDE.md
+- Test coverage for changed code paths
+- Performance considerations
+
+Post specific findings as inline comments. Post a summary comment covering overall
+assessment, key changes, and any concerns.

.claude/commands/dependency-audit.md

@@ -0,0 +1,27 @@
+Audit project dependencies for security vulnerabilities and maintenance concerns.
+
+## Context
+
+- !`cat package.json | head -5` (detect package manager)
+
+## Steps
+
+1. Run the appropriate audit command (`pnpm audit`, `npm audit`, `pip audit`, etc.)
+2. Check for known CVEs in the dependency tree
+3. Identify unmaintained dependencies (no release in >1 year, archived repo)
+4. Check for dependencies with restrictive or changed licenses
+5. Review transitive dependency tree depth for supply chain risk
+
+## Assessment Criteria
+
+For each finding, assess:
+
+- **Severity:** CRITICAL / HIGH / MEDIUM / LOW
+- **Exploitability:** Is this reachable from our code?
+- **Fix available:** Is there a patched version?
+
+## Output
+
+- If vulnerabilities found: create GitHub issue with `security` and `dependencies`
+  labels, listing all findings with remediation steps
+- If clean: comment on the most recent commit or output to stdout

.claude/commands/docs-drift.md

@@ -0,0 +1,14 @@
+Verify all documentation is current and accurate. $ARGUMENTS
+
+## Steps
+
+1. Read all documentation files (README.md, docs/, content/ if applicable)
+2. For each documented feature/API/pattern, verify the code still matches
+3. Check for undocumented public exports, new features, or changed behaviour
+4. Verify code examples in docs actually compile/run
+5. Check for broken internal links
+
+## Output
+
+- If drift found: create branch `docs/drift-fix-YYYY-MM-DD`, fix issues, open PR
+- If clean: output confirmation to stdout

.claude/commands/docs-sync.md

@@ -0,0 +1,17 @@
+Check if documentation is still accurate after the changes in this PR. $ARGUMENTS
+
+## Context
+
+- !`gh pr diff --name-only`
+- !`gh pr diff`
+
+## Steps
+
+1. Identify changed source files that have corresponding documentation
+   (README, JSDoc, inline docs, content/ files)
+2. Check if the documentation still accurately describes the code
+3. Update any documentation that has drifted
+4. If the PR adds new public API, exports, or features — check if they need documenting
+
+Commit documentation updates on the PR branch with message:
+`docs: update documentation for [changed area]`

.claude/commands/quality-audit.md

@@ -0,0 +1,39 @@
+Perform a comprehensive code quality audit of this repository.
+
+Read CLAUDE.md for project conventions.
+
+## Stale Annotations
+
+Find TODO, FIXME, HACK comments. Use `git log --follow -p` to check age. Flag items:
+
+- Referencing closed issues
+- Describing completed work
+- Present >6 months with no activity
+
+## Dead Code
+
+- Exported functions/components/types never imported elsewhere
+- Unreferenced files in source directories
+- Unused CSS classes in component files
+
+Skip: content files, public assets, config files, type declarations.
+
+## Accessibility
+
+Review components for: missing ARIA, non-semantic HTML, missing keyboard handlers,
+images without alt, form inputs without labels.
+
+## Code Patterns
+
+- Simplification opportunities
+- Type safety gaps (any casts, unjustified non-null assertions)
+- Potential bugs or edge cases
+- Convention drift from CLAUDE.md
+
+## Output
+
+1. Close any open PRs with `code-quality-audit` label (superseded)
+2. Create branch `chore/code-quality-audit-YYYY-MM-DD`
+3. Fix auto-fixable issues, commit each category separately
+4. Open PR with findings summary, linking individual items
+5. For non-auto-fixable issues, create GitHub issues with `code-quality` label

.claude/commands/release-notes.md

@@ -0,0 +1,19 @@
+Generate release notes for the latest release (or tag $ARGUMENTS if specified).
+
+## Context
+
+- !`gh release view --json tagName,name,isDraft,isPrerelease 2>/dev/null || echo "No release context"`
+- !`git log $(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "HEAD~20")..HEAD --oneline --no-merges`
+
+## Commit Categories
+
+- **Features** — `feat:` commits, new capabilities
+- **Fixes** — `fix:` commits, bug fixes
+- **Breaking Changes** — commits with `BREAKING CHANGE` or `!:` suffix
+- **Other** — `chore:`, `docs:`, `refactor:`, `perf:`, `test:` (group by type)
+
+Write user-facing release notes — translate commit messages into plain language.
+Skip internal refactors unless they affect behaviour.
+
+If this is running in CI on a release event, update the release body using
+`gh release edit`. If running locally, output the notes to stdout.

.claude/commands/renovate-review.md

@@ -0,0 +1,24 @@
+Review this Renovate dependency update PR.
+
+$ARGUMENTS
+
+## Context
+
+- !`gh pr view --json title,body,labels`
+- !`gh pr diff`
+
+## Steps
+
+1. Read the PR body for upgrade details and release notes
+2. Check if CI has passed — if still running, note that
+3. Assess risk level:
+   - Patch: Low risk, check for known issues in release notes
+   - Minor: Review changelog for breaking changes despite semver
+   - Major: Detailed breaking change analysis required
+4. For low-risk updates (patch/minor with green CI): approve with a brief comment
+   summarising your assessment
+5. For risky updates: comment with specific concerns, do NOT approve
+6. If CI fails: analyse the failure, attempt a fix on the branch, push, and comment
+
+Use `gh pr review --approve` for approvals. Do NOT enable auto-merge — the human
+reviews and merges manually.

.claude/commands/respond.md

@@ -0,0 +1,4 @@
+Respond to a mention or comment. The raw comment text is passed as $ARGUMENTS.
+This command is intentionally minimal — CLAUDE.md provides project context.
+
+$ARGUMENTS

.claude/commands/security-review.md

@@ -0,0 +1,23 @@
+Perform a security-focused review of the current PR.
+
+Read CLAUDE.md for project context.
+
+## Context
+
+- !`gh pr diff`
+- !`gh pr view --json title,body,changedFiles`
+
+## OWASP-Aligned Review Checklist
+
+- **Injection:** SQL, XSS, command injection, template injection
+- **Authentication/Authorisation:** Access control changes, session handling
+- **Data exposure:** Secrets in code, PII handling, error messages leaking internals
+- **Configuration:** Security headers, CORS, CSP changes
+- **Dependencies:** New dependencies with known vulnerabilities
+- **Cryptography:** Weak algorithms, hardcoded keys, insecure random
+- **Input validation:** Missing or inadequate validation on user input
+
+Rate each finding: CRITICAL / HIGH / MEDIUM / LOW / INFO
+
+Post findings as inline comments with severity tags. Post a summary comment with
+overall security assessment.

.claude/commands/test-gen.md

@@ -0,0 +1,24 @@
+Find source files changed in this PR that lack adequate test coverage. $ARGUMENTS
+
+## Context
+
+- !`gh pr diff --name-only`
+
+## Steps
+
+For each changed source file:
+
+1. Check if a co-located test file exists (e.g., `foo.test.ts` next to `foo.ts`)
+2. If no test file exists, or existing tests don't cover the changes, generate tests
+3. Follow project testing patterns — read existing test files for conventions
+
+## Testing Conventions
+
+- Co-locate tests next to source files
+- Use the project's test framework (check package.json)
+- Test behaviour, not implementation
+- Cover edge cases and error paths
+- Use descriptive test names
+
+Commit generated tests on the PR branch with message:
+`test: add tests for [component/module]`

.claude/commands/triage.md

@@ -0,0 +1,16 @@
+Triage the current issue (or issue $ARGUMENTS if specified).
+
+## Context
+
+- !`gh issue view --json title,body,labels,author`
+- !`gh issue list --state open --limit 20 --json title,number,labels`
+
+## Steps
+
+1. Categorise: bug / feature / question / improvement / docs
+2. Assess priority: critical / high / medium / low
+3. Check for duplicates — compare against open issues listed above
+4. Add appropriate labels using `gh issue edit --add-label`
+5. If duplicate found: comment linking to the original and close with `gh issue close`
+6. Post a triage comment summarising: category, priority, related issues, suggested
+   next steps