auth-yes/AGENTS.md

AGENTS.md — Auth-Yes System Guidelines & Operating Protocol

1. Project Context

Auth-Yes is a standalone, ultra-low-friction, zero-trust Identity and Access Management (IAM) fabric and WebAuthn Passkey authority.

• Runtime: Deno 2.x (TypeScript 5.x)
• Architecture: Modular Deno Workspace (sdk/, server/, ui/, spire_ffi/, infra/)
• Web API & SSR: Hono with pure Hono SSR JSX (Strictly React-free)
• Workload Mesh: ConnectRPC daemon + Rust SPIFFE/mTLS FFI crate (spire_ffi/)
• Data Layer: Dedicated PostgreSQL 18 + Valkey 8 (L1/L2 RESP3 Client Tracking)
• Cookie Scope: Wildcard .atyg.org domain scoping with host-collision sweep

2. Key Architecture Standards

1. Zero-Dependency SDK: @auth-yes/sdk must remain 100% free of backend/database imports. ConnectRPC contracts live in sdk/gen/.
2. Security: Session invalidation and revocation MUST always be handled server-side (deleteCookie across host and wildcard domains).
3. Quality Gates: Every PR must pass deno fmt, deno task lint, deno task check, and deno test.
4. Dual Remote & SDK Distribution: Development is tracked on GitHub (origin: git@github.com:mrteye/auth-yes.git). All commits and SDK changes must be mirrored to Gitea (gitea: git@git.atyg.org:tylerg/auth-yes.git) so that external agents (e.g. Jules) and unauthenticated local projects can consume raw SDK modules via https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts.

3. Strict Operating Protocol: Methodical Deliberation & Approval Gate

1. Read-Only First & Deep Context Preservation:
   • When asked to investigate, audit, analyze, critique, or report, NEVER make assumptions or jump directly into modifying files or pushing commits.
   • Spontaneous changes without team alignment break architecture and lose context. Always deliberate methodically across at least two levels of reasoning before proposing changes.
2. Mandatory Reporting & Options Presentation:
   • Inspect files and architecture using read-only tools.
   • Synthesize and present a structured markdown report detailing:
     • Exact state vs. master specification
     • Root causes of discrepancies or missing features
     • Proposed remediation options with trade-offs
3. Strict Gate on Code Modification:
   • Offer potential code changes clearly, but NEVER execute edits (write_to_file, replace_file_content) or git commits until the user explicitly reviews the proposal and confirms execution.
4. Standard Task Protocols (tasks/path.md):
   • Follow the standardized engineering lifecycle: tasks/plan.md \rightarrow tasks/audit-1.md \rightarrow tasks/do.md \rightarrow tasks/audit-2.md, with tasks/debug.md for hermetic root-cause analysis.
5. Agent Orchestration & Black-Box Delegation:
   • Autonomy over Tooling: When preparing prompts or tasks for external agents (e.g., Jules), NEVER micromanage their internal execution mechanics or tool choices (e.g. do not prohibit or mandate specific scripting languages).
   • Positive Final-State Delivery: Define strict terminal Acceptance Criteria (clean git working tree, formatted with deno fmt, all tests passing) rather than negative constraints on in-flight tools.
   • DRY Instructions: Rely on repository guideline documents (AGENTS.md, tasks/GUIDELINES.md) by reference rather than copy-pasting operational rules into prompts.

4. Hypermedia, Datastar & Vertical Feature Slicing Rules

1. Locality of Behavior (Vertical Slicing):
   • Co-locate all domain routes, queries, and UI view fragments in src/features/<domain>/.
   • Name template files fragments.tsx or views.tsx to reinforce the server-side hypermedia model.
2. Right-Sized Transport Selection:
   • Standard point-to-point user actions MUST return standard text/html JSX fragments.
   • SSE streams (text/event-stream) are STRICTLY reserved for multi-user broadcasts and live pub/sub updates.
   • Abstract SSE protocol strings behind a typed Datastar adapter/SDK. Never hand-roll raw SSE strings in route handlers.
3. Hypermedia Error Invariant & Mid-Stream Resilience:
   • Never return raw JSON error payloads to browser/Datastar callers.
   • All 4xx validation errors and 5xx server faults MUST return an HTML error fragment targeting #status-banner or .field-error.
   • If an error occurs mid-stream after an SSE connection is open (HTTP 200), the handler must yield an error toast fragment before closing cleanly.
4. Durable State vs. Transient Signals:
   • Database (PostgreSQL) and Cache (Valkey) are the SOLE authoritative sources of state.
   • Datastar data-signals must ONLY be used for transient presentation toggles (e.g. dropdown open/close). Never cache domain data or store auth secrets in client signals.
5. Vanilla JS Subtree Protection:
   • Any DOM element manipulated by native browser APIs (WebAuthn passkeys, clipboard copy feedback) MUST include data-ignore or data-ignore-morph to prevent Datastar reconciliation conflicts.
6. Payload & Rate Guardrails:
   • All interactive action endpoints must be bounded by rate-limiting and a strict 16KB request body ceiling.

5. AI-Optimized Code Organization & Engineering Principles

1. Strict 400-Line Ceiling & Concise Functions:
   • Target small, focused functions (4–20 lines) and keep all files bounded under a strict 400-line hard ceiling (aim for the 150–250 line sweet spot) so agents can read, reason, and edit full units in a single turn without context fragmentation or output truncation.
   • Subdivide by Sub-Feature, Not Just Type: When a feature slice grows, subdivide into focused, SRP-aligned sub-files within the feature directory (e.g., login_fragments.tsx, register_fragments.tsx, recovery_fragments.tsx instead of one massive monolithic file).
   • No Anti-Formatting Hacks: Never compress code onto single lines or use blind skip annotations to bypass line-count linters. All files must pass standard deno fmt and architectural linters without workarounds.
2. Strict Single Responsibility Principle (SRP):
   • Every module must do exactly one thing well. Independent modules allow agents to isolate and modify code without loading unrelated context.
3. Flat Call Chains Over Clever DRY Abstractions:
   • Prefer a flat, shallow 1–2 hop call chain over deep, multi-level abstraction hierarchies. Shallow boilerplate is vastly superior to a 5-file hop for AI reasoning.
4. Highly Distinctive, Searchable Naming:
   • Avoid generic identifiers (Manager, DataHandler, process()). Use explicit, searchable domain names (SessionPinRotator, streamGuestDrawerTelemetry, SessionHandoffCard).
5. Deterministic Tooling Enforcement:
   • All code quality and architectural standards must be enforced by automated tooling (deno fmt, deno task lint, deno task check, deno test). Architectural linters run as part of deno task lint to catch banned DOM APIs or missing data-ignore attributes immediately.
6. Legacy Code Quarantine:
   • During migration phases, legacy server/ and ui/ directories are strictly read-only reference. All new code, routes, queries, and fragments must be authored exclusively in src/.

6. History & Context Link

This repository was cleanly extracted from ed-droid.

• Reference Conversation: Auth-Yes Genesis Transcript (conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f)