axiom-coding-agent-setup 1.0.11 → 1.1.0

package/.agents/CONTEXT-MANAGEMENT.md

@@ -0,0 +1,155 @@
+# Context Management
+
+## The Context Problem
+
+AI agents have limited context windows. Every token counts. Wasted context = degraded reasoning = worse output. Managing context is a core competency of a world-class agent.
+
+---
+
+## Context Budget Principles
+
+### The 50% Rule
+When context reaches ~50% of the window, proactively compact. Don't wait until you're forced to.
+
+### Every Token Must Earn Its Place
+Before including anything in context, ask:
+- Does this directly help solve the current task?
+- Can I summarize this instead of including it verbatim?
+- Is this already known from the conversation history?
+- Would a file reference suffice instead of the full content?
+
+### Read Before Claiming, But Don't Read Everything
+- Read files that are directly relevant to the current task
+- Use search tools (grep, ast-grep) to find specific patterns without reading entire files
+- Batch read multiple files when you know they're all needed
+- Stop reading once you have sufficient understanding
+
+---
+
+## Context Compaction Strategy
+
+### When to Compact
+- Context exceeds 50% of window
+- Starting a new sub-task within the same session
+- Switching from exploration to implementation
+- Before making a complex, multi-step change
+
+### How to Compact
+1. **Summarize conversation history** — Replace long exchanges with key decisions and current state
+2. **Remove completed work** — Move done items to a summary; keep only what's still open
+3. **Replace file contents with references** — "See `src/auth.ts` for implementation" vs. full file content
+4. **Use todo lists** — Track state externally (todo tool) instead of in conversation
+5. **Extract key findings** — Move exploration results into a concise summary
+
+### The Compact Format
+```
+## Session Summary
+- Task: [one-line description]
+- Status: [in progress / blocked / completed]
+- Key decisions: [bullet list]
+- Open items: [from todo list]
+- Relevant files: [file paths only, not contents]
+```
+
+---
+
+## Session Discipline
+
+### One Task Per Session
+Switching tasks mid-session degrades quality. Use `/clear` or start a new session when pivoting.
+
+### Session Lifecycle
+1. **Setup** — Load relevant skills, read initial files, clarify requirements
+2. **Exploration** — Search codebase, understand patterns, identify files to change
+3. **Implementation** — Make changes, verify, test
+4. **Verification** — Run tests, check for regressions, confirm requirements met
+5. **Handoff** — Summarize what changed, what's still open, what needs follow-up
+
+### Handoff Documentation
+When ending a session or passing to another agent:
+- What was completed
+- What is still in progress
+- What decisions were made and why
+- What blockers exist
+- What files were changed
+- What tests were run and their results
+
+---
+
+## Parallel Execution & Context
+
+### When to Parallelize
+- Multiple independent file reads
+- Multiple search queries
+- Multiple test runs
+- Independent implementation tasks
+
+### When NOT to Parallelize
+- Tasks that depend on each other's output
+- Tasks that modify the same files
+- Tasks that share mutable state
+
+### Context Isolation
+Each parallel agent/worker should receive:
+- The specific task it's responsible for
+- The minimal context needed for that task
+- Clear boundaries on what it should NOT touch
+
+---
+
+## Codebase Navigation Without Context Bloat
+
+### Grepping > Reading
+Use grep/ast-grep to find specific patterns without loading entire files into context.
+
+### Symbol Search > File Reading
+Use LSP symbol search to find where something is defined, then read only that definition.
+
+### References > Full Content
+When you've already read a file once, reference it by path. Don't re-read it unless you need to verify current state.
+
+### Tree > List
+Use `tree` with depth limits to understand structure without listing every file.
+
+---
+
+## Memory Management for Long Sessions
+
+### Progressive Disclosure
+1. Start with high-level overview (tree, key files)
+2. Read relevant files as needed
+3. Compact and summarize before diving deeper
+4. Reference, don't repeat
+
+### The Rule of Three
+If you find yourself re-reading the same file more than 3 times in a session, something is wrong:
+- You didn't understand it the first time (take notes)
+- You're working on too many things at once (narrow scope)
+- The file is too large and needs refactoring (flag it)
+
+### State Persistence
+Use external tools for state:
+- **Todo lists** — Track progress without consuming context
+- **File system** — Write summaries to temp files
+- **Session state** — Use session variables for cross-turn data
+
+---
+
+## Context Anti-Patterns
+
+| Anti-Pattern | Why It Hurts |
+|---|---|
+| **Including entire files** | Eats context budget; most of the file is irrelevant |
+| **Repeating history** | Every turn doesn't need full conversation replay |
+| **Loading unrelated skills** | Only load skills relevant to the current task |
+| **Parallelizing dependent tasks** | Results in conflicts, wasted work, context pollution |
+| **Never compacting** | Context degrades until the agent starts hallucinating or making mistakes |
+| **Over-reading** | Reading 20 files when 3 would suffice |
+
+---
+
+## The Ultimate Rule
+
+**Context is your most precious resource. Spend it wisely.**
+
+Every byte of context should directly contribute to producing correct, high-quality output. If it doesn't, remove it.

package/.agents/DEBUGGING.md

@@ -0,0 +1,124 @@
+# Debugging Methodology
+
+## The Golden Rule of Debugging
+
+**Never guess. Always observe.**
+
+Debugging is not about being smart — it's about being systematic. The fastest way to fix a bug is to understand it completely before touching code.
+
+---
+
+## The Debugging Protocol
+
+### Phase 1: Reproduction
+1. **Can you reproduce it consistently?** If not, find the pattern.
+2. **What are the exact steps?** Document them precisely.
+3. **What is the smallest input that triggers it?** Minimize the reproduction case.
+4. **When did it last work?** Use `git bisect` to find the offending commit.
+
+### Phase 2: Observation
+1. **Read the error message carefully** — not just the first line, the full stack trace
+2. **Check the obvious first** — null pointers, off-by-one, typos, recent changes
+3. **Inspect the state** — print/LOG variables at key points; don't assume you know their values
+4. **Trace the data flow** — where does the bad value come from?
+5. **Check boundaries** — empty collections, first/last items, zero, null, max values
+6. **Check the environment** — different OS, different Node version, different database state
+
+### Phase 3: Hypothesis
+1. **Form a specific, testable hypothesis** — "The bug is caused by X because Y"
+2. **Design an experiment to prove or disprove it** — a test, a log, a minimal change
+3. **If disproven, discard and form a new hypothesis** — don't cling to wrong theories
+4. **If proven, fix the root cause** — not the symptom
+
+### Phase 4: Fix & Verify
+1. **Fix the root cause, not the symptom** — suppressing the error message is not fixing the bug
+2. **Verify the fix** — run the reproduction case; it should pass
+3. **Verify you didn't break anything else** — run the full test suite
+4. **Add a regression test** — ensure this bug never returns
+5. **Document what you learned** — if it was tricky, save the next engineer the trouble
+
+---
+
+## Debugging Techniques
+
+### Binary Search (Divide and Conquer)
+When you don't know where the bug is:
+1. Add a check/log at the midpoint of the suspected code path
+2. Determine if the bug is before or after that point
+3. Repeat, halving the search space each time
+
+### Rubber Duck Debugging
+Explain the bug out loud (or in writing) to an inanimate object. Forcing yourself to articulate the problem often reveals the solution.
+
+### Git Bisect
+When you know it worked before:
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good-commit>
+# Git will checkout commits; test and mark good/bad until it finds the culprit
+```
+
+### Backwards from the Error
+Start at the crash/error and trace backwards:
+1. What function threw the error?
+2. What called that function?
+3. What data was passed?
+4. Where did that data come from?
+
+### Isolate Variables
+Change one thing at a time:
+- Does it fail on a different machine?
+- Does it fail with a different database?
+- Does it fail with different input?
+- Does it fail with the previous commit?
+
+---
+
+## Common Bug Categories & Patterns
+
+| Symptom | Likely Causes |
+|---|---|
+| Works on my machine | Environment differences, missing env vars, different versions |
+| Intermittent failure | Race condition, timing issue, external dependency flakiness |
+| Works after restart | Memory leak, state corruption, resource exhaustion |
+| Only fails with large data | Buffer overflow, timeout, memory limit, algorithmic complexity |
+| Works in tests, fails in prod | Different data, different config, different permissions |
+| Works in prod, fails in tests | Test isolation, mock mismatch, different environment setup |
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It Fails |
+|---|---|
+| **Shotgun debugging** | Randomly changing things hoping something works. You learn nothing and introduce new bugs. |
+| **Print-driven development** | Adding `console.log` everywhere instead of understanding the flow. Clutters code and output. |
+| **Commenting out code** | "Maybe if I disable this..." You hide the symptom without fixing the cause. |
+| **Blaming the compiler/framework** | It's almost never the compiler. Check your assumptions first. |
+| **Ignoring the stack trace** | The answer is usually in the stack trace. Read it fully. |
+| **Fixing without reproducing** | If you can't reproduce it, you can't verify your fix. |
+| **Not adding a regression test** | The same bug will come back. Guaranteed. |
+
+---
+
+## Debugging Tools
+
+- **Stack traces** — Read bottom-up: the error is at the bottom, the call chain above it
+- **Breakpoints** — Pause execution and inspect state (better than print statements)
+- **Diff tools** — Compare working vs broken state (files, configs, database dumps)
+- **Log aggregation** — Centralized logs for tracing requests across services
+- **Request tracing** — Trace IDs to follow a single request through multiple services
+
+---
+
+## When to Ask for Help
+
+Stop and escalate when:
+- You've spent 30+ minutes without progress
+- The bug involves a third-party library you don't control
+- It requires access to production data or systems you don't have
+- You're tempted to add a hack/workaround instead of a real fix
+- The fix would change security-critical code
+
+**Debugging is a skill. The more methodical you are, the faster you solve problems.**

package/.agents/{engineering.md → ENGINEERING.md}

@@ -122,6 +122,12 @@ Log what's surprising, not what's expected.
 | Untested happy paths | You find bugs in production, not staging |
 | Architecture by autocomplete | AI-generated structure without architectural judgment |
 | Dependency sprawl | Each dependency is a supply chain risk and a maintenance burden |
+| Blind retries | Same failed command in a loop; wastes time and obscures real issues. See WORKFLOW.md |
+| Suppressing type errors | `as any`, `@ts-ignore` hide real bugs; fix the root cause. See AGENTS.md |
+| Empty catch blocks | `catch(e) {}` swallows errors; log and handle or don't catch. See AGENTS.md |
+| Cargo-culting patterns | Copying solutions without understanding why; wrong tool for the job. See AGENTS.md |
+
+> **Domain-specific anti-patterns:** See DEBUGGING.md (debugging anti-patterns) and PERFORMANCE.md (performance anti-patterns) for detailed coverage.
 
 ---
 

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}

@@ -57,9 +57,12 @@ I apply this hierarchy before making any claim about a system:
 - 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
+- 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)
@@ -110,6 +113,9 @@ When presenting solutions, include:
 
 ## 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