HK-hub/AgentSkills / ax-audit
ax-audit
VerifiedAudits agentic applications for architecture and trust: tool parity, tool granularity, context injection, completion signals, approval gates, confidence cues, escape hatches, intent handshakes, memory visibility, and adaptive canvases. Produces a ship-readiness verdict plus an AX Relationship Summary. Use when reviewing agentic feature PRs or asking "is this agent-native", "AX review", "critique this AI feature", "does this earn user trust", or "audit this for AX". For traditional frontend UX use ui-audit.
references/agent-native-principles.md
View on GitHub# Agent-Native Principles (Condensed)
<!-- TOC -->
- [Core Principles](#core-principles)
- [Tool Design](#tool-design)
- [Context Patterns](#context-patterns)
- [Agent-UI Communication](#agent-ui-communication)
<!-- /TOC -->
## Core Principles
- **Parity:** every UI capability has a tool; if not, add one.
- **Granularity:** atomic primitives, one action per tool; decision logic lives in prompts, so behavior changes are prompt edits, not refactors.
- **Composability:** atomic tools plus parity make new features new prompts.
- **Emergent capability:** ship atomic tools, watch requests, add domain tools for common patterns.
- **Improvement over time:** context files plus refined prompts improve the app without code; self-modification needs audit logs and rollback.
## Tool Design
**Atomic primitives first.** Bash, file ops, storage; prove the architecture before domain tools.
**CRUD completeness.** Verify every entity has create, read, update, delete. Common failure: `create_note` + `read_notes` exist but `update_note` and `delete_note` are missing.
**Domain tools.** Add deliberately for vocabulary anchoring, guardrails (validation not left to judgment), or bundling a multi-step operation.
**Dynamic capability discovery.** Expose `list_available_types()` + `read_data(type)` over one-tool-per-endpoint, so capabilities are discovered at runtime. MCP standardizes discover + access; prefer MCP servers over hand-coded wrappers for external services.
**Graduation.** Hot paths can move to optimized code, but the agent still triggers them and falls back to primitives for edge cases.
## Context Patterns
**Entity-scoped directories.** `{entity_type}/{entity_id}/`; separate ephemeral (`AgentCheckpoints/`, `AgentLogs/`) from durable (`Research/`).
**The `context.md` pattern.** Read at session start, updated as state changes (agent identity, user knowledge, what exists, recent activity, current state). Portable working memory, no code changes.
**Context injection.** System prompts include three sections:
1. **Available resources**: what data exists, where
2. **Capabilities**: what the agent can do
3. **Recent activity**: what happened since last session
**Context engineering.** Long-running agents manage a finite window:
| Technique | When to use |
|-----------|-------------|
| **Compaction**: summarize old messages, drop raw history | Context >70% full |
| **Structured note-taking**: agent keeps `notes.md` of learnings and decisions | Multi-step research/planning |
| **Just-in-time retrieval**: load files/schemas only when the step needs them | Large data sets, many tools |
## Agent-UI Communication
**Completion signals.** Explicit via `stop_reason`, never heuristic: `tool_use` loops, `end_turn` stops. Orchestrators can add `pause`, `escalate`, `retry`.
**Partial completion tracking.** Per-task status (pending, in_progress, completed, failed, skipped); show `3/5 tasks complete (60%)` with error notes.
**Agent event types.** Emit typed events (`thinking`, `toolCall`, `toolResult`, `textResponse`, `statusChange`); an `ephemeralToolCalls` flag hides noisy internals.
**Shared workspace.** Agents and users share one data space, each building on the other's work. Sandbox only when security or data integrity requires it.
**Approval gates.** Match approval to stakes and reversibility:
| Stakes | Reversibility | Pattern |
|--------|--------------|---------|
| Low | Easy | Auto-apply |
| Low | Hard | Quick confirm |
| High | Easy | Suggest + apply (show diff) |
| High | Hard | Explicit approval |
An explicit user request is already approval. Self-modification always requires explicit approval + audit log + rollback.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |