Skip to content

HK-hub/AgentSkills / ax-audit

ax-audit

Verified

Audits 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.

FileKindSize
SKILL.mdskill md8.7 KB
references/agent-native-principles.mdmarkdown3.6 KB
references/ax-evolution-curve.mdmarkdown3.0 KB
references/feature-playbooks.mdmarkdown6.7 KB
references/output-format.mdmarkdown4.8 KB
references/ship-readiness.mdmarkdown5.5 KB
rules-arch/_sections.mdmarkdown1.8 KB
rules-arch/_template.mdmarkdown2.2 KB
rules-arch/comm-no-approval-gate.mdmarkdown3.2 KB
rules-arch/comm-no-completion-signal.mdmarkdown2.9 KB
rules-arch/comm-no-progress-visibility.mdmarkdown2.7 KB
rules-arch/context-no-checkpoint-resume.mdmarkdown2.8 KB
rules-arch/context-no-injection.mdmarkdown2.6 KB
rules-arch/context-starvation.mdmarkdown2.6 KB
rules-arch/granularity-static-api-mapping.mdmarkdown2.9 KB
rules-arch/granularity-workflow-shaped-tool.mdmarkdown2.8 KB
rules-arch/parity-crud-incomplete.mdmarkdown2.5 KB
rules-arch/parity-no-tool-parity.mdmarkdown2.3 KB
rules-arch/parity-orphan-ui-action.mdmarkdown2.4 KB
rules-ax/_sections.mdmarkdown2.9 KB
rules-ax/_template.mdmarkdown2.5 KB
rules-ax/comm-no-generative-momentum.mdmarkdown2.6 KB
rules-ax/comm-no-intent-handshake.mdmarkdown3.1 KB
rules-ax/comm-no-progress-signal.mdmarkdown2.8 KB
rules-ax/context-memory-not-visible.mdmarkdown3.0 KB
rules-ax/context-no-adaptive-canvas.mdmarkdown2.9 KB
rules-ax/context-under-contextual.mdmarkdown2.9 KB
rules-ax/control-no-approval-gate.mdmarkdown2.8 KB
rules-ax/control-no-escape-hatch.mdmarkdown2.7 KB
rules-ax/control-over-conversational.mdmarkdown2.3 KB
rules-ax/trust-no-confidence-cues.mdmarkdown2.5 KB
rules-ax/trust-no-escalation-path.mdmarkdown2.6 KB
rules-ax/trust-no-uncertainty-markers.mdmarkdown2.5 KB

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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall