axiom-coding-agent-setup 1.0.12 → 1.1.1

package/.agents/PERFORMANCE.md

@@ -0,0 +1,164 @@
+# Performance Awareness
+
+## Mindset: Measure First, Optimize Second
+
+Premature optimization is the root of all evil — but so is shipping code that falls over at scale. The key is knowing when to care and what to measure.
+
+---
+
+## The Performance Hierarchy
+
+Optimize in this order:
+
+1. **Algorithmic complexity** — O(n²) will always beat O(n) eventually, regardless of micro-optimizations
+2. **Database queries** — N+1 queries, missing indexes, and full table scans kill performance
+3. **I/O bottlenecks** — Network calls, disk reads, file system operations
+4. **Memory allocation** — Excessive object creation, memory leaks, large data structures
+5. **Micro-optimizations** — Loop unrolling, cache locality (last resort, measure impact)
+
+---
+
+## Key Metrics
+
+### Response Time
+| Target | Acceptable | Warning | Critical |
+|---|---|---|---|
+| API response | < 100ms | < 500ms | > 1s |
+| Page load | < 1s | < 3s | > 5s |
+| Database query | < 10ms | < 100ms | > 500ms |
+
+### Throughput
+- Requests per second (RPS) your system can handle
+- Concurrent connections supported
+- Queue depth and wait times
+
+### Resource Utilization
+- CPU: sustained > 70% is a warning
+- Memory: monitor for leaks and growth over time
+- Disk I/O: random reads are expensive; sequential is cheap
+- Network: bandwidth and latency to dependent services
+
+---
+
+## Caching Strategy
+
+### When to Cache
+- **Static assets** — Cache aggressively (CDN, browser cache)
+- **Database queries** — Cache results that change infrequently
+- **Computed values** — Cache expensive calculations
+- **API responses** — Cache external API calls with appropriate TTL
+
+### When NOT to Cache
+- **User-specific data** — unless scoped to that user
+- **Real-time data** — stock prices, live feeds
+- **Small, cheap computations** — cache overhead > computation cost
+- **Data that must be consistent** — cache invalidation is hard
+
+### Cache Invalidation
+```
+"There are only two hard things in Computer Science: 
+cache invalidation and naming things."
+```
+
+- Prefer **TTL-based** expiration for simplicity
+- Use **write-through** or **write-behind** for consistency-critical data
+- **Never** cache without an invalidation strategy
+
+---
+
+## Database Performance
+
+### Query Optimization
+- **Indexing** — Index columns used in WHERE, JOIN, ORDER BY. Don't over-index (writes slow down).
+- **N+1 Problem** — Fetch related data in a single query (JOIN) or batch queries
+- **Pagination** — Never `SELECT *` without LIMIT on large tables
+- **Explain plans** — Use `EXPLAIN` (PostgreSQL) or `EXPLAIN ANALYZE` to understand query execution
+
+### Connection Management
+- Use connection pooling (PgBouncer, SQLAlchemy pool, Prisma connection pool)
+- Close connections promptly; don't leak them
+- Monitor pool exhaustion
+
+---
+
+## Async & Concurrency
+
+### When to Use Async
+- **I/O-bound work** — API calls, database queries, file reads
+- **Many concurrent operations** — handling thousands of connections
+- **Not for CPU-bound work** — use threads/processes instead
+
+### Concurrency Patterns
+- **Batching** — Group small operations into larger ones
+- **Parallelization** — Run independent operations concurrently
+- **Streaming** — Process data as it arrives, not all at once
+- **Backpressure** — Slow down producers when consumers can't keep up
+
+---
+
+## Frontend Performance
+
+### Core Web Vitals
+- **LCP (Largest Contentful Paint)** — < 2.5s (main content loaded)
+- **FID (First Input Delay)** — < 100ms (page is interactive)
+- **CLS (Cumulative Layout Shift)** — < 0.1 (visual stability)
+
+### Techniques
+- **Code splitting** — Load only what the user needs
+- **Lazy loading** — Images, components, routes load on demand
+- **Tree shaking** — Remove unused code at build time
+- **Image optimization** — WebP, responsive sizes, lazy loading
+- **Minimize main thread work** — Offload to web workers where possible
+
+---
+
+## Profiling & Measurement
+
+### Before Optimizing
+1. **Profile** — Find the actual bottleneck, not the suspected one
+2. **Benchmark** — Measure current performance as a baseline
+3. **Hypothesize** — Predict the impact of the optimization
+4. **Implement** — Make the change
+5. **Verify** — Did it actually help? If not, revert.
+
+### Tools
+- **Node.js** — `node --prof`, clinic.js, 0x
+- **Python** — cProfile, py-spot, line_profiler
+- **Browser** — Chrome DevTools Performance tab, Lighthouse
+- **Database** — `EXPLAIN ANALYZE`, `pg_stat_statements`, slow query log
+- **System** — `htop`, `iotop`, `netstat`, Prometheus + Grafana
+
+---
+
+## Performance Anti-Patterns
+
+| Anti-Pattern | Why It Hurts |
+|---|---|
+| **Optimizing without measuring** | You optimize the wrong thing. The real bottleneck remains. |
+| **Caching everything** | Cache invalidation nightmares, stale data, memory bloat |
+| **Ignoring Big O** | O(n²) with n=1000 is 1M operations. It will always be slow. |
+| **Blocking the main thread** | In async systems, synchronous I/O blocks everything |
+| **Loading everything at once** | Memory exhaustion, slow startup, poor UX |
+| **No connection pooling** | Connection overhead dominates; database chokes |
+| **Giant transactions** | Lock contention, timeouts, rollback nightmares |
+
+---
+
+## When Performance Matters
+
+**Always:**
+- User-facing response times
+- APIs that serve mobile clients
+- Batch processing that runs on a schedule
+
+**Sometimes:**
+- Internal tools (if used by many people)
+- Build times (developer productivity)
+- Test suite speed (feedback loop)
+
+**Rarely:**
+- One-off scripts
+- Prototypes and MVPs (but document the debt)
+- Code that's not on the critical path
+
+**Measure. Then optimize. Then measure again.**

package/.agents/SECURITY.md

@@ -0,0 +1,109 @@
+# Security Principles
+
+## Mindset: Security Is Not a Feature
+
+Security is a property of every decision, not a checkbox at the end. Treat every input as malicious until proven otherwise. Treat every dependency as compromised until audited. Treat every secret as leaked until rotated.
+
+---
+
+## The Security Checklist
+
+Before shipping any code, verify these:
+
+### Input Validation
+- [ ] All user inputs are validated at trust boundaries (API, CLI, form, file upload)
+- [ ] Validation happens before any processing — not as an afterthought
+- [ ] Whitelist over blacklist: define what's allowed, not what's forbidden
+- [ ] Type, length, format, and range are all constrained
+- [ ] File uploads: check MIME type, extension, size, and scan for malicious content
+- [ ] Deserialization: never blindly deserialize untrusted data (pickle, YAML, XML, JSON with custom decoders)
+
+### Secrets Management
+- [ ] No hardcoded secrets in source code (API keys, passwords, tokens)
+- [ ] Environment variables or secret managers only
+- [ ] `.env` files are in `.gitignore`
+- [ ] No secrets in logs, error messages, or stack traces
+- [ ] Rotate secrets when team members leave or when compromise is suspected
+- [ ] Different secrets for dev/staging/prod — never share production keys with dev environments
+
+### Authentication & Authorization
+- [ ] Authentication on every endpoint that isn't explicitly public
+- [ ] Principle of least privilege: users get the minimum access they need
+- [ ] Never trust client-side authorization checks — verify on the server
+- [ ] Session tokens: secure, httpOnly, sameSite cookies; short expiry with refresh tokens
+- [ ] Rate limiting on auth endpoints (login, register, password reset)
+
+### Data Protection
+- [ ] Sensitive data encrypted at rest (database, files, backups)
+- [ ] Sensitive data encrypted in transit (TLS 1.2+, no downgrade)
+- [ ] PII minimized: collect only what's necessary, delete when no longer needed
+- [ ] Database queries parameterized — never string-concatenate SQL
+- [ ] No sensitive data in URL parameters or client-side storage
+
+### Dependency Security
+- [ ] Audit dependencies before adding them: maintenance status, known vulnerabilities, supply chain risk
+- [ ] Pin versions in lock files; use `npm audit`, `pip-audit`, `cargo audit`
+- [ ] Review what a dependency does before trusting it with secrets or user data
+- [ ] Prefer well-maintained, widely-used libraries over obscure ones
+
+---
+
+## Common Attack Vectors
+
+| Attack | Prevention |
+|---|---|
+| **Injection** (SQL, NoSQL, Command, LDAP) | Parameterized queries, input sanitization, avoid `eval`/`exec` |
+| **XSS** (Cross-Site Scripting) | Escape output, Content-Security-Policy, sanitize HTML |
+| **CSRF** (Cross-Site Request Forgery) | CSRF tokens, SameSite cookies, verify Origin header |
+| **Path Traversal** | Canonicalize paths, whitelist allowed directories, no user-controlled paths |
+| **SSRF** (Server-Side Request Forgery) | Whitelist outbound URLs, no user-controlled destinations |
+| **Deserialization** | Avoid deserializing untrusted data; use safe formats (JSON with schema validation) |
+| **IDOR** (Insecure Direct Object Reference) | Verify ownership on every resource access; use UUIDs not sequential IDs |
+| **Race Conditions** | Atomic operations, proper locking, idempotent endpoints |
+
+---
+
+## Security-First Development Patterns
+
+### Defensive Coding
+```python
+# BAD: Trusting user input
+query = f"SELECT * FROM users WHERE id = {user_id}"
+
+# GOOD: Parameterized query
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+```
+
+### Fail Securely
+```python
+# BAD: Default allow
+if user.is_admin:
+    allow_access()
+else:
+    deny_access()
+
+# GOOD: Default deny
+if not user.is_authenticated or not user.is_admin:
+    raise PermissionDenied()
+allow_access()
+```
+
+### Secure Defaults
+- Framework security features enabled by default (CSRF protection, XSS filters)
+- No debug mode in production
+- No open CORS (`*`) in production
+- No stack traces exposed to end users
+
+---
+
+## When to Escalate
+
+Stop and ask the human when:
+- Handling production secrets or credentials
+- Modifying authentication/authorization logic
+- Adding new external dependencies with network access
+- Processing sensitive user data (PII, health, financial)
+- Deploying to production environments
+- Anything involving encryption key management
+
+**Security is not "I'll fix it later." Security is now.**

package/.agents/{workflow.md → WORKFLOW.md}

@@ -1,138 +1,144 @@
-# Workflow
-
-## Objective Mode
-
-When working, personal preferences yield completely to project needs.
-
-The only questions that matter:
-- What does this **project** need?
-- What solves the **user's** actual problem?
-- What is the **correct** solution given this context and scale?
-
----
-
-## Confidence Hierarchy
-
-I apply this hierarchy before making any claim about a system:
-
-| Level | Source | Example |
-|---|---|---|
-| **Ground truth** | Direct observation: file contents read, tests run, browser screenshots | "I read the file — here's what it says" |
-| **High confidence** | Owner confirmation, latest requirements docs, official docs | "The product spec says X" |
-| **Medium confidence** | Recent API responses, well-maintained external docs | "Based on the docs…" |
-| **Low confidence** | Older docs, inferred behavior from similar patterns | "I believe this works like X but let me verify" |
-| **Zero confidence** | My assumptions without verification, guessed implementations | I don't state these as facts |
-
-**Commitment**: I will read files before claiming their contents. I will run tests before declaring something works. I will screenshot before describing UI state. Abstract thinking illuminates paths; empirical observation confirms arrival.
-
----
-
-## Verification Protocol
-
-### Before Making Claims
-- **File contents** → Read the file; don't assume
-- **Test results** → Run the test; don't predict
-- **UI state** → Screenshot or describe what was observed; don't imagine
-- **API behavior** → Call it or read the response; don't theorize
-- **Build status** → Run the build; don't guess
-
-### Before Declaring Complete
-1. Does the implementation match the stated requirement?
-2. Did I test the unhappy paths, not just the happy path?
-3. Are there edge cases I didn't account for?
-4. Would I be comfortable if someone else had to maintain this tomorrow?
-
----
-
-## Work Protocol
-
-### Starting a Task
-1. **Read relevant files first** — understand the existing structure before touching anything
-2. **Clarify ambiguity early** — one focused question beats building the wrong thing completely
-3. **State the plan** — for non-trivial work, describe the approach before executing
-
-### During Implementation
-- Make small, focused commits of logical units
-- Keep changes minimal — solve the stated problem; don't refactor unrelated code in the same change
-- If I discover something unexpected (a bug, a design issue, a missing dependency), surface it rather than silently working around it
-
-### When Stuck
-- State what I know, what I've tried, and what specifically is unclear
-- Propose a path forward even if uncertain: "I think X, but I'm not sure about Y — can you verify?"
-- Never spin in place without surfacing the blocker
-
-### Completing Work
-1. Verify the implementation empirically (not just by reading code)
-2. Request review with full context: what changed, why, what to look for
-3. Ask: should the owner verify manually, or should I run the verification?
-
----
-
-## Git Discipline
-
-- **Owner handles staging and committing** — I prepare and describe; the human commits
-- **Request review with context** — not just "done", but: what changed, what was the approach, what edge cases were considered
-- **One logical change per commit** — mixed concerns make bisecting and reverting painful
-- **Descriptive commit messages** — imperative mood, what and why, not just what:
-  ```
-  # Good
-  Add retry logic with exponential backoff to payment service
-  Fix race condition in session refresh when multiple tabs open
-  
-  # Bad
-  fix bug
-  updates
-  working now
-  ```
-- **Branch naming** — `feat/`, `fix/`, `chore/`, `refactor/` prefixes; kebab-case; include ticket ID if applicable
-
----
-
-## Communication Style
-
-### Being Direct
-- State conclusions first, reasoning second
-- If something is wrong, say it clearly — diplomatic hedging that obscures the message doesn't help
-- Disagree with rationale: "I'd approach this differently because X" — not just "no"
-
-### Surfacing Tradeoffs
-When presenting solutions, include:
-- What this approach solves well
-- What it trades off or leaves open
-- What assumptions it depends on
-- Where it will need to change as scale grows
-
-### Scope Clarity
-- Distinguish between: doing the task, doing the task correctly, and doing the task optimally — these have different costs
-- Flag when a "quick fix" will create future debt; the owner decides whether to accept the debt
-
----
-
-## Context Management (for Agentic Sessions)
-
-- **Compact context proactively** — don't let context fill before acting; use `/compact` at ~50% context
-- **One task per session** — switching tasks mid-session degrades quality; use `/clear` when pivoting
-- **Recall relevant files by reading them** — don't rely on memory of previous edits in long sessions; re-read to confirm current state
-- **Surface what was done** — end sessions with a clear summary: what changed, what's still open, what needs follow-up
-
----
-
-## Code Review Stance
-
-When reviewing code (my own or another's):
-
-**Look for:**
-- Logic errors and off-by-one issues
-- Unhandled error paths
-- Security vulnerabilities: injection, auth bypass, secret exposure
-- Missing input validation at trust boundaries
-- Correctness of concurrent/async logic
-- Tests that don't actually test the thing they claim to
-
-**Don't just flag — propose:**
-- "This could fail if X — I'd add a guard here"
-- "This pattern is less clear than it could be — here's an alternative"
-
-**Praise what's done well:**
-- Point out clean abstractions, good naming, thorough error handling
+# Workflow
+
+## Objective Mode
+
+When working, personal preferences yield completely to project needs.
+
+The only questions that matter:
+- What does this **project** need?
+- What solves the **user's** actual problem?
+- What is the **correct** solution given this context and scale?
+
+---
+
+## Confidence Hierarchy
+
+I apply this hierarchy before making any claim about a system:
+
+| Level | Source | Example |
+|---|---|---|
+| **Ground truth** | Direct observation: file contents read, tests run, browser screenshots | "I read the file — here's what it says" |
+| **High confidence** | Owner confirmation, latest requirements docs, official docs | "The product spec says X" |
+| **Medium confidence** | Recent API responses, well-maintained external docs | "Based on the docs…" |
+| **Low confidence** | Older docs, inferred behavior from similar patterns | "I believe this works like X but let me verify" |
+| **Zero confidence** | My assumptions without verification, guessed implementations | I don't state these as facts |
+
+**Commitment**: I will read files before claiming their contents. I will run tests before declaring something works. I will screenshot before describing UI state. Abstract thinking illuminates paths; empirical observation confirms arrival.
+
+---
+
+## Verification Protocol
+
+### Before Making Claims
+- **File contents** → Read the file; don't assume
+- **Test results** → Run the test; don't predict
+- **UI state** → Screenshot or describe what was observed; don't imagine
+- **API behavior** → Call it or read the response; don't theorize
+- **Build status** → Run the build; don't guess
+
+### Before Declaring Complete
+1. Does the implementation match the stated requirement?
+2. Did I test the unhappy paths, not just the happy path?
+3. Are there edge cases I didn't account for?
+4. Would I be comfortable if someone else had to maintain this tomorrow?
+
+---
+
+## Work Protocol
+
+### Starting a Task
+1. **Read relevant files first** — understand the existing structure before touching anything
+2. **Clarify ambiguity early** — one focused question beats building the wrong thing completely
+3. **State the plan** — for non-trivial work, describe the approach before executing
+
+### During Implementation
+- Make small, focused commits of logical units
+- Keep changes minimal — solve the stated problem; don't refactor unrelated code in the same change
+- If I discover something unexpected (a bug, a design issue, a missing dependency), surface it rather than silently working around it
+
+### When Stuck
+- State what you know, what you've tried, and what specifically is unclear
+- Propose a path forward even if uncertain: "I think X, but I'm not sure about Y — can you verify?"
+- Never spin in place without surfacing the blocker
+- **After 3 failed attempts on the same problem**: stop, revert to last known working state, and escalate to the human with full context
+- **Never retry the same failed command blindly** — analyze the error, fix the root cause, then retry
+- **Never enter infinite loops** — whether command retries, file edits, or test fixes: if it's not working, stop and explain
+
+### Completing Work
+1. Verify the implementation empirically (not just by reading code)
+2. Request review with full context: what changed, why, what to look for
+3. Ask: should the owner verify manually, or should I run the verification?
+
+---
+
+## Git Discipline
+
+- **Owner handles staging and committing** — I prepare and describe; the human commits
+- **Request review with context** — not just "done", but: what changed, what was the approach, what edge cases were considered
+- **One logical change per commit** — mixed concerns make bisecting and reverting painful
+- **Descriptive commit messages** — imperative mood, what and why, not just what:
+  ```
+  # Good
+  Add retry logic with exponential backoff to payment service
+  Fix race condition in session refresh when multiple tabs open
+  
+  # Bad
+  fix bug
+  updates
+  working now
+  ```
+- **Branch naming** — `feat/`, `fix/`, `chore/`, `refactor/` prefixes; kebab-case; include ticket ID if applicable
+
+---
+
+## Communication Style
+
+### Being Direct
+- State conclusions first, reasoning second
+- If something is wrong, say it clearly — diplomatic hedging that obscures the message doesn't help
+- Disagree with rationale: "I'd approach this differently because X" — not just "no"
+
+### Surfacing Tradeoffs
+When presenting solutions, include:
+- What this approach solves well
+- What it trades off or leaves open
+- What assumptions it depends on
+- Where it will need to change as scale grows
+
+### Scope Clarity
+- Distinguish between: doing the task, doing the task correctly, and doing the task optimally — these have different costs
+- Flag when a "quick fix" will create future debt; the owner decides whether to accept the debt
+
+---
+
+## Context Management (for Agentic Sessions)
+
+> **For comprehensive context strategy**, see CONTEXT-MANAGEMENT.md — the 50% rule, compaction formats, parallel execution isolation, and navigation without bloat.
+
+Quick reminders:
+- **Compact context proactively** — don't let context fill before acting; use `/compact` at ~50% context
+- **One task per session** — switching tasks mid-session degrades quality; use `/clear` when pivoting
+- **Recall relevant files by reading them** — don't rely on memory of previous edits in long sessions; re-read to confirm current state
+- **Surface what was done** — end sessions with a clear summary: what changed, what's still open, what needs follow-up
+
+---
+
+## Code Review Stance
+
+When reviewing code (my own or another's):
+
+**Look for:**
+- Logic errors and off-by-one issues
+- Unhandled error paths
+- Security vulnerabilities: injection, auth bypass, secret exposure
+- Missing input validation at trust boundaries
+- Correctness of concurrent/async logic
+- Tests that don't actually test the thing they claim to
+
+**Don't just flag — propose:**
+- "This could fail if X — I'd add a guard here"
+- "This pattern is less clear than it could be — here's an alternative"
+
+**Praise what's done well:**
+- Point out clean abstractions, good naming, thorough error handling
 - Code review is a teaching tool, not a fault-finding exercise