unsorry

Protocols

These protocols must be followed when using plan mode. They are non-negotiable.

1. Architecture Decision Records (ADRs)

Always create or update an ADR when a decision is made.

• Every architectural, technical, or significant design decision must be captured as an ADR in /docs/adrs/
• ADRs follow the enhanced WH(Y) format as defined in ADR-001
• ADRs are immutable once approved — create a new ADR to supersede a previous one rather than modifying it
• Include rejected alternatives and the rationale for rejecting them
• Track dependencies between ADRs

2. Specifications

Always create or update a spec that links/references an ADR or ADRs.

• Every ADR that involves implementation details must have a corresponding specification in /docs/adrs/specs/
• Specs are the living documents — they evolve with the implementation
• ADRs remain stable decision records; specs capture the “how”
• Spec filenames follow the pattern: SPEC-{ADR-number}-{letter}-{Title}.md
• Each spec must reference the ADR(s) it implements

3. Test-Driven Development (TDD)

Always follow TDD.

• Write tests before writing implementation code
• Red → Green → Refactor cycle for every feature and bug fix
• Tests must cover the acceptance criteria defined in the relevant spec
• No code is merged without passing tests
• Test coverage must not decrease with any change

4. Feature Branches

Always create a new feature branch for any changes.

• Branch from main for every change, no matter how small
• Branch naming convention: feature/{description}, fix/{description}, docs/{description}
• No direct commits to main
• Each branch corresponds to a single logical change
• Clean up branches after merge

5. Changelog

Maintain a changelog with versions.

• Maintain CHANGELOG.md in the project root following Keep a Changelog format
• Every user-facing change must be recorded under the appropriate category (Added, Changed, Deprecated, Removed, Fixed, Security)
• Unreleased changes go under an [Unreleased] heading
• Version numbers follow Semantic Versioning

6. Releases

Release versions as appropriate when changes are made.

• Tag releases with semantic version numbers
• Move unreleased changelog entries to the new version heading
• Each release must pass all tests and quality checks
• Release notes reference the relevant ADRs and specs
• Always publish releases after they are tagged.

7. Context7 MCP for Language Research

Use the Context7 MCP to research appropriate language syntax and usage.

• Before writing code in an unfamiliar library, framework, or API, use the Context7 MCP to fetch current documentation
• Append “use context7” to prompts when you need up-to-date syntax, API signatures, or usage patterns
• This ensures code follows the latest conventions and avoids deprecated patterns
• Applies to every library, framework, and API used in the project

8. Production-Ready Code Only

No mocks, stubs, or placeholder implementations. Only fully working production-ready code.

• Every line of code written must be real, functional, and production-ready
• No mock implementations, fake data layers, placeholder functions, or “TODO: implement later” stubs
• If a dependency is not yet built, wait for it — do not mock it
• Tests use proper test fixtures and factories, not mocks of the system under test
• External dependencies (e.g., database, filesystem) may use test doubles in tests only — never in application code
• If something cannot be fully implemented yet, do not write it at all — defer it to the appropriate phase

9. Claude Agent Teams

Use Claude agent teams where suitable to get work done efficiently.

• When tasks can be parallelised, use Claude sub-agents (Task tool) to work on independent items concurrently
• Use specialised agents (Explore, Plan, general-purpose) matched to the task type
• Research and exploration tasks should use Explore agents to avoid polluting the main context window
• Independent code changes across different files or modules can be delegated to parallel agents working in isolated worktrees
• Agent results should be verified before integration — trust but verify

10. Latest Stable Dependencies

Always check for the latest available stable dependency and use that.

• When adding any new dependency to the project (backend or frontend), check for the latest stable release before installing
• Do not assume pinned versions from documentation or examples are current — verify against the package registry (PyPI, npm)
• Use stable releases only — no alpha, beta, release candidate, or pre-release versions unless explicitly approved
• When updating existing dependencies, prefer the latest stable version compatible with the project’s constraints
• Document the version chosen and the date it was verified in the relevant commit message

11. README Accuracy

The README must be kept up to date and must accurately reflect the implementation.

• Every feature described in the README must exist in the codebase — no aspirational claims
• When a feature is added, changed, or removed, update the README in the same branch
• Technical descriptions (algorithms, libraries, architecture) must match the actual implementation
• If a capability is planned but not yet implemented, it must not appear in the README
• README review is part of every release checklist

12. Don’t Repeat Yourself (DRY)

Eliminate duplication — every piece of knowledge must have a single, authoritative representation.

• Before writing new code, check for existing implementations that solve the same problem — reuse rather than duplicate
• Extract shared logic into functions, utilities, or modules when the same pattern appears in more than one place
• Shared constants, types, and configuration values must be defined once and imported everywhere they are used
• When fixing a bug or changing behaviour, identify all locations where the same logic exists — fix them all or extract the common code
• Components with identical or near-identical structure should be refactored into a single parameterised component
• Backend and frontend must not independently re-implement the same validation rules — share the source of truth or derive one from the other
• Test helpers and fixtures used across multiple test files must live in shared modules, not be copy-pasted
• Duplication in ADRs and specs is acceptable — documentation may restate for clarity, but code must not

13. Published GitHub Releases

Ensure every change includes a published release in GitHub.

• Every completed change or version bump must culminate in an official published GitHub release
• The release tag must precisely match the semantic version number specified in the codebase and CHANGELOG.md
• Include descriptive release notes that clear summary details of the specific updates, fixes, or enhancements contained within the change
• No workflow or feature deployment is considered officially complete until the corresponding GitHub release is live

---

Optional Protocols

The protocols below are conditional. Apply them only when the listed condition is met.

14. Frontend Security — {@html} Protocol (Svelte projects only)

Applies when: the project uses Svelte or SvelteKit. Skip this protocol entirely for non-Svelte projects.

Never use Svelte’s {@html} directive without DOMPurify sanitisation.

• Svelte escapes HTML by default in {expressions} — this is the safe default
• {@html} renders raw HTML and bypasses Svelte’s escaping — this is a stored XSS vector
• Any use of {@html} must pass content through DOMPurify (or equivalent sanitisation library) before rendering
• This applies to all user-generated content: entity names, descriptions, comments, model metadata, search results
• Code review must flag any {@html} usage without a corresponding sanitisation call
• Content Security Policy (CSP) headers must be configured to block inline script execution as a defence-in-depth measure
• This protocol addresses NZISM control 14.5.6.C.01 (web content security) and 14.5.8.C.01 (web application security)

This site is open source. Improve this page.