axiom-coding-agent-setup 1.0.12 → 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

package/AGENTS.md

@@ -12,9 +12,13 @@ I write code that survives contact with reality.
 
 ## Core Documents
 
-- @/.agents/engineering.md — Principles, decision framework, anti-patterns, code standards
-- @/.agents/stack.md — Technology knowledge: languages, frameworks, infrastructure, AI/ML
-- @/.agents/workflow.md — Work protocol, verification rules, git discipline, communication
+- @/.agents/ENGINEERING.md — Principles, decision framework, anti-patterns, code standards
+- @/.agents/STACK.md — Technology knowledge: languages, frameworks, infrastructure, AI/ML
+- @/.agents/WORKFLOW.md — Work protocol, verification rules, git discipline, communication
+- @/.agents/SECURITY.md — Security-first principles, checklist, attack vectors
+- @/.agents/DEBUGGING.md — Systematic debugging methodology and anti-patterns
+- @/.agents/PERFORMANCE.md — Performance awareness, measurement, optimization hierarchy
+- @/.agents/CONTEXT-MANAGEMENT.md — Context budget, compaction strategy, session discipline
 - @/.agents/templates/ — Project-type specific conventions and setup guides
 - @/.agents/skills/ — Domain-specific skills for specialized tasks
 
@@ -36,5 +40,65 @@ I write code that survives contact with reality.
 - NEVER declare "it works" without verification
 - NEVER add dependencies without checking if built-ins suffice
 - NEVER over-engineer for a scale that doesn't exist yet
-- ALWAYS ask: "Does this solve the actual problem?"
+- ALWAYS ask: "Does this solve the actual problem?".
 - **ALWAYS reference the current date/time**: Today is {Month} {Year}. You search the current date in your operations and always remember that. When performing web searches or any time-sensitive queries, explicitly use the current year to avoid retrieving outdated results from previous years like 2024 or 2025.
+- **ALWAYS analyze the current terminal/shell before running commands** — never mix syntax from different shells (e.g., `set` with `&&` in PowerShell, or `$env:` in CMD). See Terminal Awareness below.
+- **NEVER retry the same failed command blindly** — if a command fails, stop, analyze the error, fix the root cause, then retry. Never enter infinite retry loops.
+- **ALWAYS stop and ask when blocked** — if you've spent 3+ attempts on the same problem without progress, escalate to the human with: what you tried, what failed, and what you need.
+- **NEVER suppress type errors or lint warnings** — `as any`, `@ts-ignore`, `@ts-expect-error`, and empty catch blocks are forbidden. Fix the root cause instead.
+- **ALWAYS verify empirically** — read files before claiming contents, run tests before declaring success, observe before describing. Abstract thinking illuminates paths; empirical observation confirms arrival.
+- **NEVER modify security-critical code without explicit approval** — authentication, authorization, secret handling, encryption. Stop and ask.
+- **ALWAYS think before coding** — for any non-trivial change, pause and reason through: what does the user actually want? What could go wrong? What's the simplest correct approach?
+- **NEVER leave code in a broken state** — if you can't finish, revert to last known working state and explain what's blocked.
+- **ALWAYS match existing patterns** — read 2–3 similar files in the codebase before writing new code. Consistency > novelty.
+- **NEVER delete failing tests to "pass"** — a deleted test is a hidden bug. Fix the code or the test, never delete to green.
+
+---
+
+## Terminal Awareness
+
+Before executing any shell command, identify the active terminal and use its correct syntax. **Never assume** — check the environment context. Mixing shell syntax produces cryptic errors and wasted retry loops.
+
+### Common Shells & Their Syntax
+
+| Shell                    | Environment Variables | Command Chaining       | Example                             |
+| ------------------------ | --------------------- | ---------------------- | ----------------------------------- |
+| **PowerShell**           | `$env:VAR = "value"`  | `;` (or `&&` in PS 7+) | `$env:CI="true"; git diff --stat`   |
+| **CMD / Command Prompt** | `set VAR=value`       | `&&`                   | `set CI=true && git diff --stat`    |
+| **Bash / Sh / Zsh**      | `export VAR=value`    | `&&` or `;`            | `export CI=true && git diff --stat` |
+| **Fish**                 | `set -x VAR value`    | `;` or `and`           | `set -x CI true; git diff --stat`   |
+
+### Why This Matters
+
+- **PowerShell** does not recognize `set` or `&&` from CMD. Using them results in `"set" is not recognized` or `The token '&&' is not a valid statement separator`.
+- **CMD** does not recognize `$env:` syntax. Using it results in `'$env:' is not recognized`.
+- **Bash/Sh** use `export`, not `set` (which is a built-in with different behavior) and not `$env:`.
+
+### Practical Rule
+
+1. **Detect the shell** before constructing a command string.
+2. **Use the correct syntax** for that shell exclusively.
+3. **If unsure**, prefer the most universal form for the detected shell rather than guessing.
+4. **Never chain incompatible syntax** — it will fail, and retrying the same broken command wastes time.
+
+### Example: What NOT to Do
+
+```powershell
+# WRONG: Mixing CMD 'set' and '&&' in PowerShell
+$ set CI="true" && set GIT_TERMINAL_PROMPT="0" && git diff --stat .
+# Result: "set" is not recognized... && is not valid...
+
+# CORRECT: Pure PowerShell syntax
+$ $env:CI="true"; $env:GIT_TERMINAL_PROMPT="0"; git diff --stat
+```
+
+```bash
+# WRONG: Using PowerShell syntax in Bash
+$ $env:CI="true"; git diff --stat
+# Result: command not found: $env:CI=true
+
+# CORRECT: Pure Bash syntax
+$ export CI="true" && git diff --stat
+```
+
+---

package/README.md

@@ -23,9 +23,13 @@ This command downloads the following files from the [axiom-coding-agent-setup](h
 - `AGENTS.md` — Main agent instructions
 - `opencode.json` — OpenCode IDE configuration (MCP servers, plugins)
 - `.env.axiom` — Environment variables template for AXIOM credentials
-- `.agents/engineering.md` — Engineering principles & code standards
-- `.agents/stack.md` — Technology stack knowledge
-- `.agents/workflow.md` — Workflow guidelines & verification protocol
+- `.agents/ENGINEERING.md` — Engineering principles & code standards
+- `.agents/STACK.md` — Technology stack knowledge
+- `.agents/WORKFLOW.md` — Workflow guidelines & verification protocol
+- `.agents/SECURITY.md` — Security-first principles & attack vector checklist
+- `.agents/DEBUGGING.md` — Systematic debugging methodology & anti-patterns
+- `.agents/PERFORMANCE.md` — Performance awareness & optimization hierarchy
+- `.agents/CONTEXT-MANAGEMENT.md` — Context budget & session discipline
 - `.agents/templates/` — Project-type specific conventions
 - `.agents/skills/` — Domain-specific skills for specialized tasks
 
@@ -40,7 +44,7 @@ OpenCode IDE configuration including:
 - Plugin configuration
 - Environment variable references for secure credential management
 
-### .agents/engineering.md
+### .agents/ENGINEERING.md
 Core engineering principles including:
 - KISS, YAGNI, DRY principles
 - Decision framework for code reviews
@@ -48,7 +52,7 @@ Core engineering principles including:
 - Anti-patterns to avoid
 - AI-assisted development ground rules
 
-### .agents/stack.md
+### .agents/STACK.md
 Technology stack knowledge covering:
 - Languages (TypeScript, Python, Go, Rust, SQL)
 - Frontend (React, Next.js, Tailwind, shadcn/ui)
@@ -57,13 +61,44 @@ Technology stack knowledge covering:
 - AI/ML stack (LLM APIs, orchestration, observability)
 - Infrastructure & DevOps
 
-### .agents/workflow.md
+### .agents/WORKFLOW.md
 Workflow guidelines including:
 - Verification protocol (read files before claiming, test before declaring done)
 - Git discipline
 - Communication style
 - Code review stance
 - Context management for agentic sessions
+- Error recovery & anti-loop patterns
+
+### .agents/SECURITY.md
+Security-first principles including:
+- Input validation & secrets management checklist
+- Authentication & authorization patterns
+- Common attack vectors & prevention
+- When to escalate security decisions to humans
+
+### .agents/DEBUGGING.md
+Systematic debugging methodology including:
+- The 4-phase debugging protocol (Reproduction → Observation → Hypothesis → Fix)
+- Debugging techniques (binary search, git bisect, rubber duck)
+- Common bug categories & symptoms
+- Anti-patterns to avoid (shotgun debugging, print-driven development)
+
+### .agents/PERFORMANCE.md
+Performance awareness including:
+- The performance hierarchy (algorithm → database → I/O → memory → micro)
+- Caching strategies & when (not) to cache
+- Database query optimization
+- Frontend Core Web Vitals
+- Profiling & measurement tools
+
+### .agents/CONTEXT-MANAGEMENT.md
+Context management discipline including:
+- The 50% rule for context compaction
+- Session lifecycle & handoff documentation
+- Parallel execution & context isolation
+- Codebase navigation without context bloat
+- Context anti-patterns
 
 ### .agents/templates/
 Project-type specific convention files:

package/bin/cli.js

@@ -23,9 +23,13 @@ const FILES_TO_DOWNLOAD = [
   // Environment variables template
   '.env.axiom',
   // Core agent documents
-  '.agents/engineering.md',
-  '.agents/stack.md',
-  '.agents/workflow.md',
+  '.agents/ENGINEERING.md',
+  '.agents/STACK.md',
+  '.agents/WORKFLOW.md',
+  '.agents/SECURITY.md',
+  '.agents/DEBUGGING.md',
+  '.agents/PERFORMANCE.md',
+  '.agents/CONTEXT-MANAGEMENT.md',
   // Templates (project-type conventions)
   '.agents/templates/ai-engineering-python.md',
   '.agents/templates/fullstack-ai-nextjs.md',
@@ -138,9 +142,13 @@ async function main() {
     log('  - AGENTS.md                          → Main agent instructions', 'cyan');
     log('  - opencode.json                      → OpenCode IDE configuration', 'cyan');
     log('  - .env.axiom                         → Environment variables template', 'cyan');
-    log('  - .agents/engineering.md             → Engineering principles', 'cyan');
-    log('  - .agents/stack.md                   → Tech stack knowledge', 'cyan');
-    log('  - .agents/workflow.md                → Workflow guidelines', 'cyan');
+    log('  - .agents/ENGINEERING.md             → Engineering principles', 'cyan');
+    log('  - .agents/STACK.md                   → Tech stack knowledge', 'cyan');
+    log('  - .agents/WORKFLOW.md                → Workflow guidelines', 'cyan');
+    log('  - .agents/SECURITY.md                → Security principles & checklist', 'cyan');
+    log('  - .agents/DEBUGGING.md               → Systematic debugging methodology', 'cyan');
+    log('  - .agents/PERFORMANCE.md             → Performance awareness & optimization', 'cyan');
+    log('  - .agents/CONTEXT-MANAGEMENT.md      → Context budget & session discipline', 'cyan');
     log('  - .agents/templates/                 → Project-type conventions', 'cyan');
     log('  - .agents/skills/                    → Domain-specific skills\n', 'cyan');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axiom-coding-agent-setup",
-  "version": "1.0.12",
+  "version": "1.1.0",
   "description": "CLI tool to download AXIOM coding agent setup files into your project",
   "main": "bin/cli.js",
   "bin": {