Tyler Gillispie
42b336173e
- Add Section 3.5 to AGENTS.md for agent orchestration and tool autonomy - Add Section E to tasks/GUIDELINES.md with pre-review summary gate - Update tasks/do.md dispatch template with DRY positive acceptance criteria - Align task lifecycle state machine to keep in-flight work in tasks/new/
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# 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. History & Context Link
|
|
|
|
This repository was cleanly extracted from `ed-droid`.
|
|
|
|
- **Reference Conversation:**
|
|
[Auth-Yes Genesis Transcript](conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f)
|
|
(`conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f`)
|