Guidelines

Requirements use RFC 2119 keywords correctly, are independently testable, and describe behavior rather than implementation.

No section is empty without explanation, all gaps are tracked with NEEDS REVIEW, and edge cases and test vectors provide comprehensive coverage.

Recipe aligns with applicable cookbook guidelines and does not contradict platform-wide principles for security, accessibility, and error handling.

Naming, structure, and depth are consistent across sibling recipes so the cookbook reads as a coherent whole.

Recipe accurately captures what the source code does without invention, idealization, or omission of documented quirks.

Recipe follows the standard template structure with valid frontmatter and all required sections in correct order.

Comprehensive lint checklist for validating Claude Code agent structure, content quality, and best practices

Reference for Claude Code agent file format, frontmatter fields, tool access patterns, and permission modes

Best practices for creating Claude Code skills, agents, and rule files.

Comprehensive lint checklist for validating Claude Code rule file content quality, best practices, and optimization

Reference for Claude Code rule file format, quality criteria, optimization guidelines, and comparison with skills and agents

Comprehensive lint checklist for validating Claude Code skill structure, content quality, and best practices

Reference for Claude Code skill directory layout, frontmatter fields, string substitutions, and invocation control

Properties that test vectors in cookbook artifacts (ingredients, recipes) should exhibit — adapted from Kent Beck's Test Desiderata.

How to write test vectors in cookbook artifacts — use AAA structure, one concept per vector, descriptive names.

Canonical platform design sources that cookbook artifacts MUST reference when specifying UI behavior, spacing, and appearance.

All components MUST integrate with platform accessibility APIs from initial implementation:

Layouts MUST NOT break at larger text sizes. Use Dynamic Type throughout — avoid fixed font sizes. Custom fonts must ...

Layouts MUST NOT break at 2x font size. Check `Configuration.fontScale` and test with large font settings enabled.

Use MVVM with [CommunityToolkit.Mvvm](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/) — source-gener...

Deliver the full agreed scope. Don't silently mark work out of scope, declare done prematurely, or invoke YAGNI to skip required work.

Constructor injection via `Microsoft.Extensions.DependencyInjection`. Use interface types for dependencies, not concr...

Use `pathlib.Path`, not `os.path`. All path manipulation should go through `pathlib`.

Use Hilt with KSP and constructor injection for Android DI; scope bindings to the correct Hilt component and reserve @Singleton for app-scoped state.

All projects MUST have linting configured and passing before the first pull request.

- `PascalCase` for types, methods, properties, public fields, constants, namespaces

`roadmap_lib` uses the standard library only. Do not add PyYAML, requests, or other third-party packages to core libr...

Enable `<Nullable>enable</Nullable>` in all projects. Treat warnings as design signals — `string` means non-null, `st...

Only modify what was requested. State the goal before starting. Note but do not fix adjacent issues.

Shell script `main()` functions must only call other functions — no inline logic. Keep scripts composable and testable.

One logical change per commit. A change may touch multiple files if they are part of the same concept. Commits should...

Type hints are welcome but not required. Maintain Python 3.9 compatibility — use `from __future__ import annotations`...

Set strict: true on every new TypeScript project and adopt the stricter index/module flags incrementally.

Use functions from `roadmap_lib` for all roadmap operations (reading state, parsing frontmatter, finding steps, etc.)...

Wrap domain primitives that carry invariants in small immutable value objects so validation lives in one place and invalid instances cannot be constructed.

Give every agent a runnable pass/fail check it can run on itself, and enforce correctness through deterministic gates rather than prompt text.

Favor explicit, greppable, locally-readable code so AI agents can find and modify behavior on the first pass — without sacrificing human readability.

Parse YAML frontmatter with the built-in frontmatter parser in `roadmap_lib`. Do not add a PyYAML dependency. The par...

Migrate to Swift 6 data-race safety module by module, making every type that crosses an isolation boundary Sendable.

Mutable shared state is the root cause of most concurrency bugs. Default to immutable values; introduce mutability on...

Expose UI state as StateFlow via stateIn and collect it lifecycle-aware, injecting dispatchers for testability.

All lengthy work must run on background threads/tasks using platform async primitives:

Rules for analyzing query access patterns to drive schema and index decisions, covering read-heavy vs write-heavy tradeoffs, designing for WHERE/JOIN/ORDER BY, identifying missing indexes, and sync-specific batch sizing and transaction patterns.

Match the Postgres index type to the access pattern, build on live tables with CONCURRENTLY, and validate with EXPLAIN ANALYZE.

How to choose the right clock system for distributed sync: physical clocks, Lamport timestamps, vector clocks, Hybrid Logical Clocks, and server-assigned monotonic versions.

How to choose and implement a conflict resolution strategy for sync: LWW, server-wins, field-level merge, CRDTs, Operational Transformation, and manual conflict queues.

Front Postgres with a transaction-mode pooler for serverless or many-instance backends, and never depend on session-scoped state.

CHECK constraints for SQLite: evaluation rules, enum-like constraints, boolean enforcement, range and pattern validation, NULL truthiness, and limitations.

Define a retention schedule per data category and automate deletion or anonymization that cascades to every derived store.

SQLite type affinity rules, the STRING gotcha, STRICT tables, and type mapping between SQLite and PostgreSQL for cross-database compatibility.

Use SQLite with WAL mode for concurrent read access. No ORM — use direct SQL via the `sqlite3` standard library module.

Prescriptive rules for SQLite backup methods, corruption prevention, integrity checking, recovery procedures, VACUUM strategy, and database size management.

Snake_case naming rules for tables, columns, primary keys, foreign keys, indexes, constraints, and triggers — including reserved word avoidance.

Always use the roadmap file's own UUID from its YAML frontmatter. Never generate random UUIDs. IDs must be determinis...

Enabling and declaring foreign keys in SQLite, ON DELETE/UPDATE actions, deferred constraints, indexing FK columns, and common pitfalls.

Rules for creating effective indexes in SQLite and PostgreSQL, covering B-tree fundamentals, composite ordering, covering indexes, partial and expression indexes, sync metadata indexes, and when not to index.

JSON storage and extraction in SQLite, json_each for array iteration, generated columns for indexing JSON fields, and when JSON is a schema design smell.

Start normalized (3NF), denormalize only measured hotspots. SQLite-specific tradeoffs and sync-safe denormalization guidance.

Design rules for offline-first apps: WAL as the foundation, operation queues, optimistic UI updates, rollback on rejection, offline schema migrations, data expiry, and connectivity-aware sync scheduling.

Choosing between INTEGER PRIMARY KEY, AUTOINCREMENT, UUID, and WITHOUT ROWID — including sync compatibility and cross-database PK design.

Rules for writing efficient SQLite and PostgreSQL queries, including query planner behavior, anti-patterns that cause full table scans, JSON query performance, subquery elimination, and CTE vs subquery tradeoffs.

One-to-many, many-to-many, polymorphic FKs, self-referential tables, and tree hierarchy patterns with tradeoffs and SQLite-specific guidance.

Use Room with KSP, Flow-returning observable reads, suspend writes, and @Transaction-wrapped multi-step operations on Android.

Migration strategies for SQLite: PRAGMA user_version, ALTER TABLE limitations, the 12-step recreate procedure, and sync-compatible migration rules.

Comparison and selection guide for SQLite sync tools: Session Extension, cr-sqlite, Litestream, ElectricSQL, PowerSync, Turso/libSQL, and sqlite-sync — with a decision matrix and selection criteria.

How to design a client-side sync engine: layered architecture, entity-agnostic Syncable interface, the six-step sync cycle, scheduling strategies, snapshot rebuilding, and error handling with circuit breakers.

Rules for designing the sync protocol between client and server: push/pull direction, full vs incremental sync, change tracking, batching, idempotency, the outbox pattern, and retry with backoff.

Schema design rules for databases that sync across devices: UUID primary keys, timestamp columns, soft deletes, dirty tracking, version columns, and sync metadata tables.

Partition large tables only when a measured size or retention need justifies the operational cost, and apply time-series patterns deliberately.

Choose an isolation level per transaction and retry serialization failures with bounded, idempotent backoff.

Rules for transaction management and concurrency in SQLite, covering WAL mode, journal mode selection, BEGIN IMMEDIATE vs DEFERRED, connection strategies, busy_timeout, PRAGMA tuning, and WAL benefits for sync workloads.

Migrate a live database with expand-and-contract: every step backward-compatible with the running app, indexes built concurrently.

Features that may need experimentation SHOULD support variant assignment via an `ExperimentProvider` interface (`vari...

Apps MUST include a debug-only configuration panel (not in release builds):

All features MUST be gated behind feature flags from initial implementation. Define a `FeatureFlagProvider` interface...

Build small, secure container images with multi-stage builds, pinned slim bases, non-root users, cache-ordered layers, and no baked-in secrets.

Externalize Kubernetes config via ConfigMaps and treat Secrets as unencrypted base64 — encrypt at rest, tighten RBAC, and prefer external secret managers.

Run Kubernetes workloads with explicit resource requests/limits, health probes, hardened pod security, and safe rollout strategies.

Read config that varies between deploys from the environment and promote one immutable build artifact unchanged across every environment.

All user-facing strings MUST be localizable — no hardcoded strings:

All layouts MUST support right-to-left languages:

AI API calls cost $0.01-$0.10+ each. Systems MUST treat AI calls as a managed resource with budgets, caching, and fallback strategies.

Use REST with consistent conventions. Follow the platform API guidelines (Microsoft, Google,

Parse protocol and API inputs strictly, reject violations loudly, and actively co-evolve spec and implementation instead of tolerating drift.

Use HTTP caching headers. The server controls cache policy; the client honors it.

Use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) format with

Use ETags with If-None-Match for efficient reads and If-Match for optimistic concurrency on writes to prevent lost updates.

Accept a client-supplied Idempotency-Key on write endpoints so retries are safe, and reject key reuse with different parameters.

Design MCP servers by choosing the right primitive and giving each tool a precise name, output schema, and annotations.

For apps that must work offline, design for local-first with background sync.

Prefer **cursor pagination** for most APIs — stable under concurrent mutations, consistent

Respect server rate limits. Handle 429 responses gracefully.

Choose the simplest technique that meets your needs.

Not every failure is permanent. Retry transient failures with exponential backoff and jitter.

Always set both connection and read timeouts. Never use infinite timeouts.

Use Flask for web services. The dashboard service runs on Flask with a REST API and SSE/polling for live updates.

Every call to an AI provider API MUST be logged with structured metadata for cost attribution, debugging, and performance monitoring.

All significant user actions MUST be instrumented via an `AnalyticsProvider` interface (`track(event, properties)`). ...

Adopt always-on, low-overhead production profiling correlated with traces only when measured perf/cost debugging justifies the pipeline.

Propagate W3C trace context across every service hop and async boundary, and correlate logs/metrics/traces via a shared trace_id.

Every component and flow must be instrumented with structured logging using the platform's best-in-class framework:

Instrument services with RED metrics and resources with USE so signals correlate and feed SLIs/SLOs.

Define user-centric SLIs, set SLOs, derive an error budget, and alert on multi-window burn rate rather than resource thresholds.

Expose key app actions and data as App Intents so Siri, Shortcuts, Spotlight, widgets, and the system can invoke them.

Apps that sync data, process uploads, or maintain state SHOULD use platform background execution APIs rather than relying on foreground presence.

All significant feature points and views MUST be deep linkable using the platform's native URL/deep link mechanism:

Apps available on multiple devices SHOULD support continuity features so users can start work on one device and resume on another.

Apps SHOULD use the platform notification system for timely, actionable alerts that respect user preferences.

Components and flows SHOULD be scriptable where the platform supports it:

App content SHOULD be discoverable through the platform's system search, enabling users to find content without opening the app.

Apps SHOULD participate in the platform's share and inter-app data exchange mechanisms to integrate with other apps and workflows.

Use AppKit (macOS) and UIKit (iOS) for all UI. Use SwiftUI only where Apple requires it.

Apps with time-sensitive or frequently checked data SHOULD provide widgets and glanceable surfaces on platforms that support them.

Wrap agents in deterministic input/output guardrails, least-privilege tool access, human confirmation for irreversible actions, and a kill switch.

Use OAuth 2.0 / OpenID Connect with PKCE for all public clients. The Implicit flow is

**Server-side authorization is the only real authorization.** Client-side checks (hiding

Capture granular, versioned, withdrawable consent in an auditable log and gate all non-essential processing on it.

Prevent XSS and injection with a strict CSP. Web apps only.

Cross-Origin Resource Sharing — get it right or don't enable it.

Architect every personal-data store to be enumerable, exportable, and deletable by subject id so DSARs are satisfied within the legal SLA.

Your dependencies are your attack surface. Manage them actively.

**Never trust client input.** Client-side validation is a UX feature, not a security control.

Treat all model output as untrusted, defend against direct and indirect prompt injection, and constrain tool agency.

Harden MCP servers against tool poisoning, rug-pulls, token passthrough, confused-deputy, session hijacking, and SSRF.

Treat every MCP tool argument as untrusted model-supplied input: schema-validate, authorize per call, and bound resource access.

Implement phishing-resistant passwordless auth with passkeys/WebAuthn, prefer them over passwords and SMS-OTP, and plan recovery.

Classify PII at the schema level, minimize collection, encrypt at rest and in transit, and never write it to logs.

Collect only what is needed. Prefer on-device processing.

Tokens, credentials, and any sensitive data MUST use platform secure storage. Never store secrets in plaintext config...

Every web application should set these response headers:

Bind access tokens to the client with DPoP or mTLS so a stolen token cannot be replayed by another party.

Minimize what you collect, encrypt what you keep, never log what you shouldn't.

Short-lived (5-15 min). Include only necessary claims — no PII in JWTs

**TLS 1.2 minimum**, prefer TLS 1.3. Disable TLS 1.0 and 1.1 entirely.

Reference for Claude Code agent file format, frontmatter fields, tool access patterns, and permission modes

Best practices for creating Claude Code skills, agents, and rule files.

Treat context as a finite budget you curate: prune aggressively, isolate large subtasks to subagents, and persist what must survive across sessions.

Optimize Claude Code extensions for speed and token efficiency through shell scripts, model selection, and progressive disclosure.

Reference for Claude Code rule file format, quality criteria, optimization guidelines, and comparison with skills and agents

Reference for Claude Code skill directory layout, frontmatter fields, string substitutions, and invocation control

Prioritize unit tests over integration tests. Test state transitions, edge cases, serialization round-trips. Every im...

When to use: parsers, serializers, data transformers, encoders/decoders, validators — anything

Use Swift Testing (@Test, #expect/#require, parameterized arguments, suites, traits) for new Swift unit tests.

**Construct what you need, per test.** Large shared fixture files SHOULD be avoided.

Use [Martin Fowler's taxonomy](https://martinfowler.com/bliki/TestDouble.html):

**Structure — Arrange, Act, Assert (AAA):**

When the UI is waiting on an async task:

Render Android apps edge-to-edge and consume WindowInsets so content is never hidden behind the status bar, navigation bar, or IME.

Use type-safe Navigation Compose with serializable routes, single-activity architecture, and hoisted nav state.

Migrate off deprecated back handling to OnBackPressedDispatcher and support the predictive back gesture with progress-driven animations.

Motion should be purposeful — guide attention, show spatial relationships, and provide

Adopt the system Apple design language and materials over custom chrome, and version-gate brand-new design APIs like Liquid Glass.

Use color with intention — never as the sole means of conveying information.

Target LCP <= 2.5s, INP <= 200ms, CLS <= 0.1 at field p75, and enforce a performance budget in CI.

Share one semantic token source across platforms, then render values in each platform's native units, type scale, and idioms.

The dashboard service is a generic API and UI layer. It has no knowledge of git, files, or roadmap structure. Agents ...

Choose the right pattern for the content type and user task.

Generate per-platform token artifacts from one source via a build step; never hand-edit the generated outputs.

- Use `d:DataContext` and `d:DesignInstance` for XAML designer preview data

Every user action should have visible feedback. The weight of the feedback should match

Use built-in WinUI 3 controls — they implement Fluent 2 natively. Never custom-draw what a standard control can do.

Forms are where users do real work. Reduce friction at every step.

XAML layout uses effective pixels (epx) — scaling is automatic for all XAML-rendered content.

Icons supplement text — they do not replace it (except for universally understood symbols

Minimize Compose recomposition with stable types, deferred state reads, lazy-list keys, and release-build measurement.

Run side effects through the correct keyed Compose effect API, never directly inside composition.

Hoist UI state to its lowest common owner or the ViewModel, keep composables stateless, and enforce state-down/events-up unidirectional flow.

Design for the content, not a fixed screen size. Layouts should adapt gracefully from

Theme Compose UIs with Material 3 color roles, ColorScheme, type and shape scales, and full dark support.

Adopt modern interoperable CSS features (container queries, @layer, :has(), subgrid, nesting, view transitions) gated on Baseline status with fallbacks.

Defer to these canonical sources before applying the defaults in this file:

All UI components MUST include preview declarations for rapid visual verification during development. Previews should...

Ship a Web App Manifest plus a service worker with an explicit caching strategy, and account for iOS install/push/storage limits.

Use a consistent spatial scale based on a **4px base unit** (8px primary grid). All spacing,

Every view that loads data or can be empty must handle all four states explicitly. Never

WinUI 3 supports tri-state theming: Light, Dark, and High Contrast.

Implement themes as alternate value sets for the same semantic tokens; swap the active set, never the component code.

Interactive elements MUST be large enough to tap or click accurately. Defer to the platform

Use the platform's system font. Establish a type scale with clear roles — don't invent

Establish clear importance through size, weight, color, and spacing. Every screen should

Apply Mica as the backdrop of long-lived windows and Acrylic for transient surfaces, honoring user theme and system settings.

Ship a lean machine-targeted instruction file at the repo root that states build/test/run commands, conventions, and what is out of scope.

Characterize the computational profile of each candidate scope group by identifying dominant algorithms, data structures, and complexity characteristics.

Characterize how components communicate within the application — delegation, pub/sub, shared state, and other in-process coordination patterns.

Use MVVM with [CommunityToolkit.Mvvm](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/) — source-gener...

Pick a .NET target framework from the documented support cadence: LTS for apps, multi-target libraries, pin the SDK.

Decide a Windows UI framework and deployment model deliberately and early; package identity is mandatory for notifications and background tasks.

Distinguish concerns that span all scope groups (cross-cutting — do not isolate) from shared infrastructure that is itself a coherent group.

Identify scope groups by measuring internal coupling density versus external coupling — files that import each other heavily belong together.

Separate the irreducible complexity of the problem from incidental complexity, then spend agents on the incidental and design review on the essential.

Identify the architectural patterns imposed by the chosen framework and use those conventional units as primary scope group candidates.

Group files by their shared public API surface — types, protocols, and exported symbols that define a coherent contract.

Share domain and data logic broadly across platforms with KMP; choose shared vs native UI per platform maturity.

Identify scope group boundaries by finding groups of objects that are created, owned, and destroyed together as a unit.

Identify scope group candidates by locating explicit build targets, package manifests, and declared module boundaries.

Classify every file by its primary reason for existing, and verify that each candidate scope group has a single coherent purpose.

Identify permissions, entitlements, environment checks, and configuration prerequisites that constrain when and where code can execute.

Only modify what was requested. State the goal before starting. Note but do not fix adjacent issues.

Before writing new code, check the platform, your existing dependencies, your own codebases, and proven open source — and verify any candidate dependency is real.

For non-trivial agent work, write a self-contained spec before code, separating planning from execution and ending with a verification step.

Characterize which external libraries, OS frameworks, and system services the code reaches for, and what that implies about scope boundaries.

Characterize how the code communicates with the operating system — IPC, lifecycle callbacks, background execution, and OS-level integration points.

Rules for analyzing query access patterns to drive schema and index decisions, covering read-heavy vs write-heavy tradeoffs, designing for WHERE/JOIN/ORDER BY, identifying missing indexes, and sync-specific batch sizing and transaction patterns.

Pick SwiftData or Core Data for Apple persistence by OS-version floor, model complexity, and migration needs — not by novelty.

Default to a relational database for a server backend; adopt a specialist store only for a concrete, measured requirement.

How to choose the right clock system for distributed sync: physical clocks, Lamport timestamps, vector clocks, Hybrid Logical Clocks, and server-assigned monotonic versions.

How to choose and implement a conflict resolution strategy for sync: LWW, server-wins, field-level merge, CRDTs, Operational Transformation, and manual conflict queues.

Adopt CQRS or event sourcing ONLY when audit/replay or independent read/write scaling justifies their substantial complexity cost.

Use SQLite with WAL mode for concurrent read access. No ORM — use direct SQL via the `sqlite3` standard library module.

Rules for creating effective indexes in SQLite and PostgreSQL, covering B-tree fundamentals, composite ordering, covering indexes, partial and expression indexes, sync metadata indexes, and when not to index.

JSON storage and extraction in SQLite, json_each for array iteration, generated columns for indexing JSON fields, and when JSON is a schema design smell.

Start normalized (3NF), denormalize only measured hotspots. SQLite-specific tradeoffs and sync-safe denormalization guidance.

Design rules for offline-first apps: WAL as the foundation, operation queues, optimistic UI updates, rollback on rejection, offline schema migrations, data expiry, and connectivity-aware sync scheduling.

Choosing between INTEGER PRIMARY KEY, AUTOINCREMENT, UUID, and WITHOUT ROWID — including sync compatibility and cross-database PK design.

One-to-many, many-to-many, polymorphic FKs, self-referential tables, and tree hierarchy patterns with tradeoffs and SQLite-specific guidance.

Comparison and selection guide for SQLite sync tools: Session Extension, cr-sqlite, Litestream, ElectricSQL, PowerSync, Turso/libSQL, and sqlite-sync — with a decision matrix and selection criteria.

How to design a client-side sync engine: layered architecture, entity-agnostic Syncable interface, the six-step sync cycle, scheduling strategies, snapshot rebuilding, and error handling with circuit breakers.

Rules for designing the sync protocol between client and server: push/pull direction, full vs incremental sync, change tracking, batching, idempotency, the outbox pattern, and retry with backoff.

Schema design rules for databases that sync across devices: UUID primary keys, timestamp columns, soft deletes, dirty tracking, version columns, and sync metadata tables.

Rules for transaction management and concurrency in SQLite, covering WAL mode, journal mode selection, BEGIN IMMEDIATE vs DEFERRED, connection strategies, busy_timeout, PRAGMA tuning, and WAL benefits for sync workloads.

Plan RAG retrieval on pgvector with an HNSW index and hybrid dense+lexical+rerank scoring before reaching for a dedicated vector DB.

Plan for feature flag architecture from the start: define a FeatureFlagProvider interface, choose storage backend, and identify which features need gating.

Never mutate running servers in place; build a versioned image artifact and replace instances to deploy or roll back.

Define infrastructure declaratively in version control and apply it through a reviewed plan, never by hand.

Use REST with consistent conventions. Follow the platform API guidelines (Microsoft, Google,

Evolve APIs additively; when versioning is unavoidable pick one scheme and run a header-driven deprecation lifecycle.

Use HTTP caching headers. The server controls cache policy; the client honors it.

Select an API style from consumer needs and traffic shape: REST for resource CRUD, gRPC for internal RPC, GraphQL for client-driven aggregation.

Author the OpenAPI document before implementing endpoints and treat it as the linted, machine-readable contract.

For apps that must work offline, design for local-first with background sync.

Prefer **cursor pagination** for most APIs — stable under concurrent mutations, consistent

Choose the simplest technique that meets your needs.

Use OAuth 2.0 / OpenID Connect with PKCE for all public clients. The Implicit flow is

Identify the privacy regimes that apply and confirm a lawful basis before collecting any personal data.

Collect only what is needed. Prefer on-device processing.

Map personal-data flows, minimize collection, default to the most private setting, and run a DPIA before building high-risk processing.

Model trust boundaries and ask the four Manifesto questions before building so point security controls trace to a why.

Projects SHOULD follow the Google SWE Book ratio: **80% unit / 15% integration / 5% E2E**.

Pick a rendering strategy per route to minimize how much JavaScript reaches the client and when, treating it as an architecture decision not a framework mandate.

The dashboard service is a generic API and UI layer. It has no knowledge of git, files, or roadmap structure. Agents ...

Choose the right pattern for the content type and user task.

Express UI design decisions once as named, tiered design tokens in one platform-agnostic source; reference semantic tokens, never raw values.

Defer to these canonical sources before applying the defaults in this file:

Keep remote server state in a query/cache layer and UI client state in lightweight local state; never hand-cache server data in a global store.

All components MUST integrate with platform accessibility APIs from initial implementation:

After any operation touching 5+ files, run a verification pass for stale references before marking complete.

When you replace or refactor code, delete what it supersedes. Leave no dead code, orphaned files, or commented-out blocks behind.

Constructor injection via `Microsoft.Extensions.DependencyInjection`. Use interface types for dependencies, not concr...

Use `pathlib.Path`, not `os.path`. All path manipulation should go through `pathlib`.

Talk only to immediate collaborators and tell objects to act rather than asking for their internals, except across documented boundary, builder, and pipeline cases.

- `PascalCase` for types, methods, properties, public fields, constants, namespaces

`roadmap_lib` uses the standard library only. Do not add PyYAML, requests, or other third-party packages to core libr...

Only modify what was requested. State the goal before starting. Note but do not fix adjacent issues.

Shell script `main()` functions must only call other functions — no inline logic. Keep scripts composable and testable.

Type hints are welcome but not required. Maintain Python 3.9 compatibility — use `from __future__ import annotations`...

Use functions from `roadmap_lib` for all roadmap operations (reading state, parsing frontmatter, finding steps, etc.)...

Parse YAML frontmatter with the built-in frontmatter parser in `roadmap_lib`. Do not add a PyYAML dependency. The par...

Query review checklist: anti-patterns to flag, EXPLAIN QUERY PLAN red flags, and common performance issues in SQLite queries.

Scan, pin, sign, and slim container images so they ship without known-exploited vulnerabilities, embedded secrets, or root runtimes.

All user-facing strings MUST be localizable — no hardcoded strings:

All layouts MUST support right-to-left languages:

Treat every observable behavior of an interface as a contract a consumer may depend on: document guarantees, constrain incidental behavior, and never depend on the unspecified.

Pre-merge checklist a reviewer runs over an MCP server's primitive design, tool contracts, and authorization.

Respect server rate limits. Handle 429 responses gracefully.

Always set both connection and read timeouts. Never use infinite timeouts.

All significant user actions MUST be instrumented via an `AnalyticsProvider` interface (`track(event, properties)`). ...

Every component and flow must be instrumented with structured logging using the platform's best-in-class framework:

All significant feature points and views MUST be deep linkable using the platform's native URL/deep link mechanism:

Use AppKit (macOS) and UIKit (iOS) for all UI. Use SwiftUI only where Apple requires it.

Use OAuth 2.0 / OpenID Connect with PKCE for all public clients. The Implicit flow is

**Server-side authorization is the only real authorization.** Client-side checks (hiding

Prevent XSS and injection with a strict CSP. Web apps only.

Cross-Origin Resource Sharing — get it right or don't enable it.

Your dependencies are your attack surface. Manage them actively.

**Never trust client input.** Client-side validation is a UX feature, not a security control.

Adversarially test LLM and agent systems against the OWASP LLM Top 10 and gate releases on a tracked attack-success-rate threshold.

Collect only what is needed. Prefer on-device processing.

Tokens, credentials, and any sensitive data MUST use platform secure storage. Never store secrets in plaintext config...

Every web application should set these response headers:

Minimize what you collect, encrypt what you keep, never log what you shouldn't.

Short-lived (5-15 min). Include only necessary claims — no PII in JWTs

**TLS 1.2 minimum**, prefer TLS 1.3. Disable TLS 1.0 and 1.1 entirely.

Triage CVEs by exploitability — CISA KEV and high EPSS first, deprioritize unreachable transitive findings — not raw CVSS.

Comprehensive lint checklist for validating Claude Code agent structure, content quality, and best practices

Optimize Claude Code extensions for speed and token efficiency through shell scripts, model selection, and progressive disclosure.

Comprehensive lint checklist for validating Claude Code rule file content quality, best practices, and optimization

Comprehensive lint checklist for validating Claude Code skill structure, content quality, and best practices

Flaky tests destroy confidence. Quarantine them immediately — fix or delete, never ignore.

Every generated artifact MUST be verified:

Run security scans as part of post-generation verification (agenticdevelopercookbook://guidelines/testing/post-generation-verification). These a...

Use color with intention — never as the sole means of conveying information.

Interactive elements MUST be large enough to tap or click accurately. Defer to the platform

Pre-ship A/B test verification: ensure experiment variants are configured, defaults are safe, and the debug panel override works.

After any operation touching 5+ files, run a verification pass for stale references before marking complete.

Keep main always releasable via an automated build-test-deploy pipeline; releasing is a business decision, not a manual scramble.

Pre-deployment backup verification: ensure backups run before migrations, WAL files are handled during restore, and integrity checks pass before shipping.

Your dependencies are your attack surface. Manage them actively.

Provision a disposable per-PR environment from IaC, seed it with throwaway data, test against it, and auto-destroy on merge or close.

Pre-ship feature flag verification: ensure all new features are gated, defaults are correct, and flag keys are documented.

Run production incidents with defined command roles and severity tiers, then close them with blameless, tracked-to-completion postmortems.

- Use the single-project MSIX packaging model

Decouple deploy from release and limit blast radius with canary, rings, blue-green, flags, and health-based automated rollback.

Pre-deploy migration verification: ensure version tracking, idempotency, sync compatibility, and rollback strategy before shipping schema changes.

Ship a PrivacyInfo.xcprivacy manifest declaring data collection and required-reason API usage, or App Store submission is rejected.

One logical change per commit. A change may touch multiple files if they are part of the same concept. Commits should...

Emit an SBOM and signed SLSA provenance per build, then verify both signatures and provenance at deploy time.

Pre-deploy transport security verification: TLS 1.2+, HSTS enabled, cipher suites audited, certificate pinning validated.

Integrate to one shared trunk in small daily increments behind feature flags, keeping trunk releasable instead of trading rigor for long branches.

Ship native ARM64 builds for Windows on ARM; adopt Native AOT and trimming only when a measured need justifies their constraints.

Gate every agent/LLM release on two checks: a quality eval gate and a safety gate, both run in CI on every model and prompt change.

Prioritize unit tests over integration tests. Test state transitions, edge cases, serialization round-trips. Every im...

Verify that independently deployed services agree on the shape of their interactions before they ship.

Prescriptive rules for testing SQLite-backed code: in-memory vs file-based databases, test isolation strategies, migration testing, sync logic testing, and conflict resolution testing.

Use design-time data contexts for visual preview testing — verify UI renders correctly without running the app.

When the unit under test is agent or LLM behavior, build a calibrated eval harness instead of relying on ordinary unit tests.

Flaky tests destroy confidence. Quarantine them immediately — fix or delete, never ignore.

Detect, quarantine with an owner and deadline, fix the root cause, then return flaky tests to the gating suite.

Fuzz untrusted-input parsing surfaces — especially in memory-unsafe code — with coverage-guided fuzzers; adopt elsewhere only on measured need.

Evaluate RAG groundedness with verified citations, calibrated LLM judges, and retrieval metrics, and abstain when context is insufficient.

Run linting as part of your automated test and verification suite — it catches bugs that unit tests miss.

Mutation testing validates that your tests actually catch bugs — not just achieve coverage.

Every generated artifact MUST be verified:

All UI components MUST include preview declarations for rapid visual verification during development. Previews should...

From Kent Beck's Test Desiderata — tests should be:

When to use: parsers, serializers, data transformers, encoders/decoders, validators — anything

Run security scans as part of post-generation verification (agenticdevelopercookbook://guidelines/testing/post-generation-verification). These a...

Keep snapshots small and deterministic, and deliberately review every snapshot diff before accepting it.

**Construct what you need, per test.** Large shared fixture files SHOULD be avoided.

Use [Martin Fowler's taxonomy](https://martinfowler.com/bliki/TestDouble.html):

Projects SHOULD follow the Google SWE Book ratio: **80% unit / 15% integration / 5% E2E**.

The recommended Claude Code testing workflow, combining all tools:

Evaluate agent tool use for selection, argument correctness, ordering, and stopping against a fixed trajectory suite with error-recovery cases.

**Structure — Arrange, Act, Assert (AAA):**