Guidelines

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.

All projects MUST include linting configured from initial generation:

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

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

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

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

Comprehensive SQLite reference covering schema design, performance tuning, device-to-server sync, and production operations

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...

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

All layouts MUST support right-to-left languages:

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

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

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

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

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

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

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

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

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

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.)...

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

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

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

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

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:

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

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

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.

1. [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines)

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 MVVM with [CommunityToolkit.Mvvm](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/) — source-gener...

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

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

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

- Use the single-project MSIX packaging model

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

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.

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

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.

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

1. [OWASP Top 10 (2021)](https://owasp.org/www-project-top-ten/)

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.

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.

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

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

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

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

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

Every generated artifact MUST be verified:

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

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

1. [Google SWE Book Ch. 11: Testing Overview](https://abseil.io/resources/swe-book/html/ch11.html)

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

**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:

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

When the UI is waiting on an async task:

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

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

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

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

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

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

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

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...

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

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