Release (1.1)

.agents/skills/automatic-code-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: automatic-code-review
+description: How to conduct and receive effective code reviews. Use when reviewing a PR, requesting review, or improving review quality.
+authors:
+  - Automatic
+---
+
+# Code Review
+
+Code review is a quality gate and a knowledge-sharing mechanism. Its purpose is to catch defects, surface design problems, and spread understanding — not to enforce style preferences or demonstrate superiority.
+
+## Mindset
+
+Review the code, not the person. Every comment should serve the goal of shipping better software. Assume good intent; ask questions before making accusations.
+
+---
+
+## What to Look For
+
+### Correctness (highest priority)
+- Does the code do what it claims to do?
+- Are there edge cases that are not handled? (null, empty, overflow, concurrency)
+- Are error states handled explicitly, or silently swallowed?
+- Does it match the requirements or specification?
+
+### Security
+- Is user input validated and sanitised before use?
+- Are secrets or credentials ever logged or exposed?
+- Are permissions and authorisation checks in the right place?
+- See the `security-review` skill for a full checklist
+
+### Design
+- Does the change fit the existing architecture, or does it introduce inconsistency?
+- Is responsibility correctly assigned — does each function/class do one thing?
+- Are dependencies pointing in the right direction?
+- Would a future maintainer understand this without asking the author?
+
+### Testability and tests
+- Is the new code covered by tests?
+- Do the tests verify behaviour, not implementation?
+- Would a failing test give a clear signal about what broke?
+
+### Performance
+- Are there obvious algorithmic issues (N+1 queries, O(n²) in a hot path)?
+- Are expensive operations cached where appropriate?
+- For critical paths, is there evidence of measurement rather than assumption?
+
+### Maintainability
+- Are names clear and specific?
+- Is duplication introduced that could be extracted?
+- Are there comments that explain *why*, not just *what*?
+- Is dead code removed?
+
+---
+
+## How to Comment
+
+**Be specific.** Vague comments waste everyone's time.
+
+```
+// Bad:  "This could be better"
+// Good: "This will execute a database query for every item in the list.
+//        Consider fetching all items in a single query before the loop."
+```
+
+**Label the severity.** Not all comments are blockers.
+
+- `[blocking]` — must be resolved before merge; correctness or security issue
+- `[suggestion]` — improvement worth discussing; not required
+- `[nit]` — minor style or preference; take it or leave it
+- `[question]` — asking for understanding, not requesting a change
+
+**Suggest, do not just criticise.** If you identify a problem, offer a direction for fixing it.
+
+---
+
+## Scope
+
+Review what was changed. Do not block a PR because of pre-existing issues in surrounding code — create a separate ticket for those. Do not add scope to a PR during review.
+
+---
+
+## For Authors
+
+Before requesting review:
+
+- [ ] Self-review the diff first — catch your own obvious mistakes
+- [ ] The PR description explains *why*, not just *what* changed
+- [ ] Tests are included and passing
+- [ ] No debug code, commented-out blocks, or TODOs left in without a ticket reference
+- [ ] The change is as small as possible — large PRs produce low-quality reviews
+
+When receiving feedback:
+
+- Respond to every comment — either with a change or a rationale for not changing
+- Do not silently resolve comments you disagree with; discuss them
+- `[nit]` comments are optional — you do not need to justify ignoring them
+
+---
+
+## What Code Review Is Not
+
+- A style guide enforcement tool (use a linter for that)
+- A place to redesign the entire system
+- A gatekeeping exercise
+- A substitute for automated testing

.agents/skills/automatic-debugging/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: automatic-debugging
+description: Systematic process for diagnosing and resolving defects. Use when debugging failures, investigating errors, or reproducing issues.
+authors:
+  - Automatic
+---
+
+# Systematic Debugging
+
+A disciplined process for diagnosing and resolving defects. Guessing wastes time. Systematic investigation finds root causes.
+
+## The Process
+
+### 1. Reproduce first
+Before touching code, confirm you can reproduce the failure consistently. A defect you cannot reproduce reliably cannot be safely fixed.
+
+- Identify the exact inputs, environment, and sequence that trigger the issue
+- Determine if it is deterministic or intermittent
+- Record the actual vs. expected behaviour precisely
+
+### 2. Understand before fixing
+Read the error message and stack trace fully. Do not skip lines. The first error is usually the cause; later errors are often consequences.
+
+- Locate the exact file, line, and call that failed
+- Read the surrounding code — not just the failing line
+- Check recent changes: `git log --oneline -20`, `git diff HEAD~5`
+
+### 3. Form a hypothesis
+State a specific, testable hypothesis: *"I believe X is happening because Y."* Do not proceed without one.
+
+- Hypotheses must be falsifiable — if you cannot test it, it is not a hypothesis
+- Start with the simplest explanation consistent with the evidence
+- Avoid hypothesising about multiple unrelated causes at once
+
+### 4. Gather evidence
+Prove or disprove the hypothesis with minimal, targeted changes.
+
+```bash
+# Add temporary logging at the point of failure
+# Check actual values, not assumed values
+# Use the debugger — step through, don't assume execution flow
+```
+
+- Add logging that reveals state, not just "got here" messages
+- Use the smallest possible test case that reproduces the issue
+- Check: inputs going in, outputs coming out, state at failure point
+
+### 5. Fix the cause, not the symptom
+Once the root cause is confirmed, fix it directly.
+
+- Removing an assertion to stop a test failing is not a fix
+- Adding a `null` guard around a crash is not a fix if the null should never occur
+- If the fix feels like a workaround, it probably is — keep investigating
+
+### 6. Verify and prevent regression
+- Confirm the fix resolves the original reproduction case
+- Add a test that would have caught this defect
+- Consider whether the same class of bug exists elsewhere
+
+---
+
+## Common Patterns
+
+### Intermittent failures
+- Likely causes: race conditions, timing dependencies, uninitialized state, external service variability
+- Strategy: add logging to capture state at the moment of failure; increase test runs; check for shared mutable state
+
+### "It works on my machine"
+- Likely causes: environment differences (OS, language version, dependencies, env vars, file paths, timezone)
+- Strategy: diff the environments explicitly; check `.env`, lock files, system dependencies; reproduce in a container
+
+### Regression (worked before, broken now)
+- Start with `git bisect` to isolate the breaking commit
+- Read that commit's diff with fresh eyes
+
+### Null / undefined errors
+- Find where the value is set, not where it is read
+- Ask: should this value ever be null? If not, find why it is
+
+### Performance degradation
+- Measure before you optimise — identify the actual bottleneck with profiling data, not intuition
+- See the `performance-profiling` skill
+
+---
+
+## What Not to Do
+
+- **Do not comment out failing code** to make tests pass
+- **Do not add `sleep` or retry loops** to hide timing issues
+- **Do not ignore warnings** — they are often early indicators of the real problem
+- **Do not fix multiple things at once** — you will not know which change resolved the issue
+- **Do not assume** — verify every assumption with evidence

.agents/skills/automatic-documentation/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: automatic-documentation
+description: Principles for writing READMEs, API docs, ADRs, code comments, and changelogs. Use when creating or improving any technical documentation.
+authors:
+  - Automatic
+---
+
+# Technical Documentation
+
+Documentation is a product. It requires the same deliberateness as code. Outdated, incomplete, or misleading documentation is worse than none — it wastes time and creates false confidence.
+
+## Principles
+
+**Write for the reader, not the writer.** The author already knows how the system works. Documentation exists to transfer that understanding to someone who does not. Every sentence should serve that goal.
+
+**Document decisions, not just descriptions.** Code describes what the system does. Documentation should explain *why* it does it that way. The most valuable documentation captures constraints, trade-offs, and rejected alternatives.
+
+**Treat documentation as a deliverable.** A feature is not complete until it is documented. Documentation that is written later rarely gets written.
+
+---
+
+## Types of Documentation
+
+### README
+The entry point for any project. Must answer:
+- What does this project do?
+- How do I get it running locally?
+- How do I run the tests?
+- Where do I go for more information?
+
+Keep it short. Link to deeper documentation. It should take under 5 minutes to read.
+
+### API documentation
+Document every public interface: functions, REST endpoints, event schemas.
+
+For each item, include:
+- **Purpose** — what it does in one sentence
+- **Parameters / fields** — name, type, whether required, valid values or range, default
+- **Return value / response** — what is returned and under what conditions
+- **Errors** — what error conditions can occur and what they mean
+- **Example** — a concrete, working example
+
+### Architecture decision records (ADRs)
+Record significant technical decisions as short, dated documents:
+
+```markdown
+# ADR-042: Use PostgreSQL for primary data store
+
+**Status**: Accepted  
+**Date**: 2025-03-02
+
+## Context
+We needed a relational database that supports ...
+
+## Decision
+We will use PostgreSQL 16 because ...
+
+## Consequences
+- We gain: JSONB support, strong ACID guarantees, mature tooling
+- We accept: operational complexity vs. a managed service
+- We reject: MySQL (weaker JSON support), SQLite (no concurrent writes)
+```
+
+ADRs are permanent. Even superseded decisions should be marked "Superseded" and kept — the reasoning matters.
+
+### Code comments
+Comment *why*, not *what*. The code says what is happening; comments explain why it happens that way.
+
+```
+// Good: "Skip validation here — this path is only reachable from the
+//        internal job queue, which has already validated the payload."
+
+// Bad: "Skip validation"
+// Bad: "Call the validate function" (the next line says that)
+```
+
+Comment anything surprising, non-obvious, or that required a decision that is not evident from the code itself.
+
+### Changelogs
+Record what changed for users, not for developers.
+
+- Group by release version and date
+- Categorise: Added, Changed, Deprecated, Removed, Fixed, Security
+- Link to issues or PRs for context
+- Never use "Various bug fixes" — be specific about what was fixed
+
+---
+
+## Writing Style
+
+**Use plain English.** Avoid jargon where a simpler word exists. If jargon is necessary, define it on first use.
+
+**Short sentences.** Break long sentences into two. If a sentence requires re-reading, rewrite it.
+
+**Active voice.** "The server validates the token" not "The token is validated by the server."
+
+**Present tense.** "Returns the user object" not "Will return the user object."
+
+**Examples are mandatory.** Abstract descriptions without examples make readers do extra work. Show, then tell.
+
+---
+
+## Maintenance
+
+- Documentation lives alongside the code it describes — in the same repository
+- Documentation changes are part of the same PR as the code changes
+- Broken documentation is a bug — file it and fix it
+- Deprecate documented features explicitly; do not silently remove documentation