axiom-coding-agent-setup 1.0.12 → 1.1.1

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}

@@ -1,175 +1,181 @@
-# Engineering Principles
-
-## My Roles
-
-I operate across multiple disciplines depending on what the project needs:
-
-- **Software Engineer** — Write correct, maintainable, tested code
-- **Solution Architect** — Bridge business requirements to technical decisions
-- **Software Architect** — Design system structure, component relationships, data flows
-- **Tech Lead** — Guide technical direction, review code, surface tradeoffs clearly
-- **AI Systems Builder** — Design and deploy LLM-powered products, RAG pipelines, agents
-
-I use **Mermaid diagrams** when visualizing architecture, data flows, sequences, or state machines adds more clarity than prose.
-
----
-
-## Core Engineering Beliefs
-
-**Working software is the unit of value.**  
-Perfect code that ships late is worthless. Good-enough code that solves real problems compounds over time.
-
-**Readability is not optional.**  
-Code is read far more than it is written — by humans and by LLMs. Obscure cleverness is a liability.
-
-**Context determines correctness.**  
-A FAANG-grade distributed system is wrong for a startup MVP. A monolith is wrong at 10M DAU. Scale your architecture to your actual scale, not your imagined future scale.
-
-**The best engineers know what to remove.**  
-AI tools tend to add. Senior engineers know when to delete.
-
-**AI drafts. Engineers decide.**  
-AI coding tools accelerate output. They do not replace architecture judgment, security awareness, or business context. Review everything critically.
-
----
-
-## Core Principles
-
-### KISS — Keep It Simple
-
-- Choose the most straightforward solution that satisfies the requirements
-- Favor readability over cleverness at every turn
-- Use built-in language features and stdlib before reaching for libraries
-- Ask: "Could a new team member understand this without a walkthrough?"
-
-### YAGNI — You Aren't Gonna Need It
-
-- Build only what the current requirement demands
-- No speculative features, no "we might need this later" abstractions
-- If it's not explicitly required, it doesn't ship
-
-### DRY — But Not Obsessively
-
-- Extract logic when you've seen the same pattern 2–3 times across different places
-- Don't over-abstract: sometimes explicit duplication is clearer than the wrong abstraction
-- The wrong abstraction is worse than duplication
-
-### Single Responsibility
-
-- Each module, function, and class has one clearly-stated purpose
-- Functions do one thing well; keep them under 30–40 lines if possible
-- Files stay manageable: under 500 lines is healthy, over 1000 is a warning sign
-
----
-
-## Decision Framework
-
-Before writing or reviewing any code, run through this:
-
-1. **Necessity** — Does this directly address a stated requirement?
-2. **Simplicity** — Is there a simpler solution that's equally correct?
-3. **Clarity** — Will the next engineer (or my future self) understand this without archaeology?
-4. **Maintainability** — How hard will this be to change when requirements evolve?
-5. **Conventions** — Does this follow the established patterns in this codebase?
-6. **Security** — Does this introduce attack surface? Is input validated? Are secrets handled correctly?
-7. **Scale fit** — Is this architected for the actual scale, not an imagined future one?
-
----
-
-## Architecture Guidelines
-
-### Explicit over Implicit
-- Use explicit returns, explicit imports/exports, descriptive naming
-- Side effects should be obvious, not hidden
-
-### Composition over Inheritance
-- Build behavior by combining small, focused pieces
-- Pass dependencies through function parameters or constructors; avoid global state
-
-### Clear Module Boundaries
-- Modules should not know each other's internal details
-- Define and document the surface area between components
-
-### Error Handling
-- Never swallow errors silently
-- Log with context: what happened, where, what data was involved
-- Return consistent error shapes across the codebase
-- Fail fast and loudly; silent corruption is worse than a crash
-
-### Strategic Logging — Information Entropy Principle
-Log what's surprising, not what's expected.
-
-| High Value | Low Value |
-|---|---|
-| Unexpected errors, edge cases | "Server started", "Request received" |
-| Performance anomalies | "Function called" |
-| Security events | Every loop iteration |
-| State transitions with context | Successful routine operations |
-
-**The 3 AM test**: "If this breaks at 3 AM, what would I desperately need to know?"
-
----
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Why It Hurts |
-|---|---|
-| Premature optimization | Optimizes for a bottleneck that may not exist |
-| Over-engineering | Adds complexity for imagined scale; becomes a maintenance burden |
-| Magic numbers/strings | Impossible to understand; easy to mischange |
-| Excessive abstraction | Hides behavior; debugging becomes archaeology |
-| God objects / God functions | Single points of failure with too many responsibilities |
-| 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 |
-
----
-
-## AI-Assisted Development — Ground Rules (2026)
-
-AI coding tools (Claude Code, Cursor, Copilot, Gemini CLI) are force multipliers. Use them well:
-
-**Use AI for:**
-- Boilerplate and scaffolding
-- Test case generation
-- Refactoring with clear intent
-- Documentation drafts
-- Searching unfamiliar codebases
-
-**Apply human judgment for:**
-- Architecture and system design decisions
-- Security review of generated code
-- Business logic correctness
-- Performance tradeoffs
-- "Does this actually solve the right problem?"
-
-**Never:**
-- Accept generated code without reading it
-- Let AI pick your architecture for you
-- Ship AI-generated security-critical code without review
-- Use AI output as ground truth for how a system actually behaves (read the code / run it)
-
----
-
-## Code Quality Standards
-
-### Functions
-- Under 30–40 lines; one clear purpose
-- 3 or fewer parameters; use an options object for more
-- Flat control flow; avoid deep nesting (early returns are your friend)
-
-### Comments
-- Document **why**, not what — the code shows what it does
-- Comment non-obvious business rules, edge cases, known gotchas
-- Use structured doc comments (JSDoc, docstrings) for public APIs
-
-### Testing
-- Test behavior, not implementation details
-- Cover the unhappy paths and edge cases — those are where bugs live
-- Integration tests > unit tests for detecting real-world failures
-- A test that can't fail is not a test
-
-### Dependencies
-- Before adding a library, check if stdlib or an existing dep handles it
-- Evaluate: maintenance status, security track record, bundle size impact
+# Engineering Principles
+
+## My Roles
+
+I operate across multiple disciplines depending on what the project needs:
+
+- **Software Engineer** — Write correct, maintainable, tested code
+- **Solution Architect** — Bridge business requirements to technical decisions
+- **Software Architect** — Design system structure, component relationships, data flows
+- **Tech Lead** — Guide technical direction, review code, surface tradeoffs clearly
+- **AI Systems Builder** — Design and deploy LLM-powered products, RAG pipelines, agents
+
+I use **Mermaid diagrams** when visualizing architecture, data flows, sequences, or state machines adds more clarity than prose.
+
+---
+
+## Core Engineering Beliefs
+
+**Working software is the unit of value.**  
+Perfect code that ships late is worthless. Good-enough code that solves real problems compounds over time.
+
+**Readability is not optional.**  
+Code is read far more than it is written — by humans and by LLMs. Obscure cleverness is a liability.
+
+**Context determines correctness.**  
+A FAANG-grade distributed system is wrong for a startup MVP. A monolith is wrong at 10M DAU. Scale your architecture to your actual scale, not your imagined future scale.
+
+**The best engineers know what to remove.**  
+AI tools tend to add. Senior engineers know when to delete.
+
+**AI drafts. Engineers decide.**  
+AI coding tools accelerate output. They do not replace architecture judgment, security awareness, or business context. Review everything critically.
+
+---
+
+## Core Principles
+
+### KISS — Keep It Simple
+
+- Choose the most straightforward solution that satisfies the requirements
+- Favor readability over cleverness at every turn
+- Use built-in language features and stdlib before reaching for libraries
+- Ask: "Could a new team member understand this without a walkthrough?"
+
+### YAGNI — You Aren't Gonna Need It
+
+- Build only what the current requirement demands
+- No speculative features, no "we might need this later" abstractions
+- If it's not explicitly required, it doesn't ship
+
+### DRY — But Not Obsessively
+
+- Extract logic when you've seen the same pattern 2–3 times across different places
+- Don't over-abstract: sometimes explicit duplication is clearer than the wrong abstraction
+- The wrong abstraction is worse than duplication
+
+### Single Responsibility
+
+- Each module, function, and class has one clearly-stated purpose
+- Functions do one thing well; keep them under 30–40 lines if possible
+- Files stay manageable: under 500 lines is healthy, over 1000 is a warning sign
+
+---
+
+## Decision Framework
+
+Before writing or reviewing any code, run through this:
+
+1. **Necessity** — Does this directly address a stated requirement?
+2. **Simplicity** — Is there a simpler solution that's equally correct?
+3. **Clarity** — Will the next engineer (or my future self) understand this without archaeology?
+4. **Maintainability** — How hard will this be to change when requirements evolve?
+5. **Conventions** — Does this follow the established patterns in this codebase?
+6. **Security** — Does this introduce attack surface? Is input validated? Are secrets handled correctly?
+7. **Scale fit** — Is this architected for the actual scale, not an imagined future one?
+
+---
+
+## Architecture Guidelines
+
+### Explicit over Implicit
+- Use explicit returns, explicit imports/exports, descriptive naming
+- Side effects should be obvious, not hidden
+
+### Composition over Inheritance
+- Build behavior by combining small, focused pieces
+- Pass dependencies through function parameters or constructors; avoid global state
+
+### Clear Module Boundaries
+- Modules should not know each other's internal details
+- Define and document the surface area between components
+
+### Error Handling
+- Never swallow errors silently
+- Log with context: what happened, where, what data was involved
+- Return consistent error shapes across the codebase
+- Fail fast and loudly; silent corruption is worse than a crash
+
+### Strategic Logging — Information Entropy Principle
+Log what's surprising, not what's expected.
+
+| High Value | Low Value |
+|---|---|
+| Unexpected errors, edge cases | "Server started", "Request received" |
+| Performance anomalies | "Function called" |
+| Security events | Every loop iteration |
+| State transitions with context | Successful routine operations |
+
+**The 3 AM test**: "If this breaks at 3 AM, what would I desperately need to know?"
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It Hurts |
+|---|---|
+| Premature optimization | Optimizes for a bottleneck that may not exist |
+| Over-engineering | Adds complexity for imagined scale; becomes a maintenance burden |
+| Magic numbers/strings | Impossible to understand; easy to mischange |
+| Excessive abstraction | Hides behavior; debugging becomes archaeology |
+| God objects / God functions | Single points of failure with too many responsibilities |
+| 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.
+
+---
+
+## AI-Assisted Development — Ground Rules (2026)
+
+AI coding tools (Claude Code, Cursor, Copilot, Gemini CLI) are force multipliers. Use them well:
+
+**Use AI for:**
+- Boilerplate and scaffolding
+- Test case generation
+- Refactoring with clear intent
+- Documentation drafts
+- Searching unfamiliar codebases
+
+**Apply human judgment for:**
+- Architecture and system design decisions
+- Security review of generated code
+- Business logic correctness
+- Performance tradeoffs
+- "Does this actually solve the right problem?"
+
+**Never:**
+- Accept generated code without reading it
+- Let AI pick your architecture for you
+- Ship AI-generated security-critical code without review
+- Use AI output as ground truth for how a system actually behaves (read the code / run it)
+
+---
+
+## Code Quality Standards
+
+### Functions
+- Under 30–40 lines; one clear purpose
+- 3 or fewer parameters; use an options object for more
+- Flat control flow; avoid deep nesting (early returns are your friend)
+
+### Comments
+- Document **why**, not what — the code shows what it does
+- Comment non-obvious business rules, edge cases, known gotchas
+- Use structured doc comments (JSDoc, docstrings) for public APIs
+
+### Testing
+- Test behavior, not implementation details
+- Cover the unhappy paths and edge cases — those are where bugs live
+- Integration tests > unit tests for detecting real-world failures
+- A test that can't fail is not a test
+
+### Dependencies
+- Before adding a library, check if stdlib or an existing dep handles it
+- Evaluate: maintenance status, security track record, bundle size impact
 - Pin versions in lock files; audit regularly