Self-Improving Intent Security Agent

Install

CODEBLOCK0

Use this skill to structure and document intent validation workflows. It does not ship a production runtime engine that automatically intercepts agent actions; instead, it provides templates, examples, and local scripts that help you build, simulate, or document that workflow.

Scope Clarification

• - This package includes markdown templates, examples, and helper shell scripts
• The helper shell scripts operate on local files only
• Automatic enforcement, anomaly detection, rollback execution, and learning application must be implemented by the host agent or surrounding system

Quick Reference

Situation	Action
Starting autonomous task	Capture intent specification (goal, constraints, expected behavior)
Before each action

Validate against intent, check authorization | | Action violates intent | Document the violation and follow the rollback workflow | | Unusual behavior detected | Log an anomaly, assess severity, and decide whether to halt or roll back | | Task completes | Analyze outcome, extract patterns, update strategies | | High-risk operation | Require human approval before execution | | Need transparency | Review audit log with full action history | | Strategy improves | A/B test new approach, adopt if better | | Recurring violation | Promote to permanent constraint in CLAUDE.md |

Setup

Create .agent/ directory in project root:

CODEBLOCK1

Copy templates from assets/ or create files with headers. Review the included shell scripts before running them if you want to understand exactly what they do.

For a complete conversation-driven working folder, scaffold a run pack:

CODEBLOCK2

This creates:

• - conversation.md for the user/agent transcript
• INLINECODE3 for the final summary
• a local .agent/ tree with intent, audit, violation, rollback, learning, and strategy files

Intent Specification Format

Before executing autonomous tasks, capture structured intent:

CODEBLOCK3

Save to .agent/intents/INT-YYYYMMDD-XXX.md.

Validation Workflow

Conversation-Driven Workflow

Use this when you want the skill to document not just the intent, but the full user and agent interaction over time.

Recommended Sequence

1. 1. Capture the user request in INLINECODE6
2. Translate it into a structured intent in INLINECODE7
3. Record allowed and blocked actions in INLINECODE8
4. Log suspicious behavior in INLINECODE9
5. Log hard validation failures in INLINECODE10
6. Record recovery steps in INLINECODE11
7. Extract reusable learnings in INLINECODE12
8. Promote stable improvements into INLINECODE13
9. Summarize the run in INLINECODE14

Good Fit

• - High-risk or privacy-sensitive tasks
• Tasks where you need a human-readable transcript
• Demos and evaluations
• Incident reviews and postmortems

Example

See examples/customer-feedback-demo/ for a full run showing:

• - intent capture
• per-action validation
• anomaly detection
• blocked violation
• rollback
• learning promotion

Pre-Execution Validation

Before each action, validate:

1. 1. Goal Alignment: Does this action serve the stated goal?
2. Constraint Check: Does it respect all boundaries?
3. Behavior Match: Does it fit expected patterns?
4. Authorization: Do we have permission for this?

If ANY check fails → block action, log violation.

Example Validation

CODEBLOCK4

Logging Violations

When validation fails, log to .agent/violations/:

CODEBLOCK5

Anomaly Detection

Monitor execution for behavioral anomalies:

Anomaly Types

Type	Description	Response
Goal Drift	Actions diverging from stated goal	Halt, request clarification
Capability Misuse

Using tools inappropriately | Rollback to checkpoint | | Side Effects | Unexpected consequences detected | Log warning, continue with monitoring | | Resource Exceeded | CPU/memory/time limits breached | Throttle or halt | | Pattern Deviation | Behavior differs from expected | Log for analysis |

Anomaly Logging

Log to .agent/violations/ANOMALIES.md:

CODEBLOCK6

Learning Workflow

After task completion, log learnings to .agent/learnings/:

CODEBLOCK7

Rollback Operations

Creating Checkpoints

Before risky operations:

CODEBLOCK8

Rollback on Violation

Automatic rollback when intent violated:

CODEBLOCK9

Rollback Log

Track in .agent/audit/ROLLBACKS.md:

CODEBLOCK10

Strategy Evolution

When agent learns better approaches:

A/B Testing

1. 1. Baseline: Current strategy (90% of tasks)
2. Candidate: New strategy (10% of tasks)
3. Measure: Compare success rate, time, resource usage
4. Validate: Safety checks pass
5. Adopt: Roll out if candidate is 10%+ better
6. Rollback: Revert if candidate degrades performance

Strategy Log

Track in .agent/learnings/STRATEGIES.md:

CODEBLOCK11

Promoting to Permanent Memory

When learnings are broadly applicable, promote to project files:

Promotion Targets

Target	What Belongs There
INLINECODE21	Intent patterns, common constraints for this project
INLINECODE22

Agent-specific workflows, validation rules | | .github/copilot-instructions.md | Security guidelines, constraint templates | | SECURITY.md | Security-critical constraints and validation rules |

When to Promote

Promote when:

• - Violation occurs 3+ times (recurring constraint)
• Learning applies across multiple task types
• Strategy is adopted and proven (success rate 90%+)
• Security pattern prevents entire class of violations

Promotion Examples

Violation (recurring):

VIO-20250115-001: Attempted to modify files outside ./src

VIO-20250118-002: Attempted to modify files outside ./src

VIO-20250120-003: Attempted to modify files outside ./src

Promote to CLAUDE.md:
CODEBLOCK12

Learning (proven strategy):

LRN-20250115-005: Batch processing with checkpoints every 10 files

Results: 95% success, 40% faster, easy rollback on failures

Promote to AGENTS.md:
CODEBLOCK13

Configuration

Environment Variables

Important: All environment variables are optional. The skill works with sensible defaults without any configuration.

Security Note: This skill does NOT require any credentials or secrets. All data stays local in the .agent/ directory. No data is transmitted externally.

CODEBLOCK14

Configuration File

Create .agent/config.json:

CODEBLOCK15

ID Generation

Format: TYPE-YYYYMMDD-XXX

• - INT: Intent specification
• INLINECODE29: Violation (failed validation)
• INLINECODE30: Anomaly (behavioral deviation)
• INLINECODE31: Learning (insight from execution)
• INLINECODE32: Strategy (new approach)
• INLINECODE33: Rollback operation
• INLINECODE34: Checkpoint

Examples: INT-20250115-001, VIO-20250115-A3F, INLINECODE37

Priority Guidelines

Priority/Severity	When to Use
INLINECODE38	Immediate security risk, data loss, system compromise
INLINECODE39

Intent violation, unauthorized action, goal drift | | medium | Anomaly detected, suboptimal strategy, warning condition | | low | Minor deviation, optimization opportunity, observation |

Best Practices

Intent Specification

1. 1. Be specific - Vague goals lead to validation failures
2. List all constraints - Implicit boundaries often get violated
3. Define expected behavior - Helps catch deviations early
4. Set correct risk level - Triggers appropriate approval gates

Validation

1. 1. Validate early - Before execution, not after
2. Fail safe - Block on doubt, don't assume permission
3. Log all violations - Even if they seem minor
4. Review regularly - Patterns emerge over time

Learning

1. 1. Let it learn - Requires sample size to be effective
2. Monitor A/B tests - Don't adopt blindly
3. Safety first - Reject strategies that reduce safety
4. Promote proven patterns - Turn learnings into permanent rules

Audit

1. 1. Keep detailed logs - Debugging requires context
2. Archive old logs - Retention policies prevent bloat
3. Review anomalies - Often reveal edge cases
4. Share learnings - Team benefits from documented patterns

Detection Triggers

Automatically apply intent security when:

High-Risk Operations:

• - File deletion or bulk modifications
• API calls with write permissions
• Command execution with elevated privileges
• Database modifications
• Deployment operations

Autonomous Workflows:

• - Multi-step task sequences
• Background job execution
• Scheduled automation
• Agent-initiated operations

Learning Opportunities:

• - Task completes successfully
• Failure with identifiable cause
• User provides correction
• Better approach discovered

Hook Integration (Optional)

Enable automatic intent validation through agent hooks.

Setup (Claude Code / Codex)

Create .claude/settings.json:

CODEBLOCK16

Available Hook Scripts

Script	Hook Type	Purpose
INLINECODE43	UserPromptSubmit	Prompts for intent specification
INLINECODE44

PostToolUse | Validates actions against intent | | scripts/learning-capture.sh | TaskComplete | Captures learnings after tasks |

See references/hooks-setup.md for detailed configuration.

Quick Commands

CODEBLOCK17

Examples

See examples/README.md for detailed usage examples:

• - Basic intent specification and validation
• Handling violations and rollbacks
• Learning from task outcomes
• Strategy evolution through A/B testing
• Security monitoring and anomaly detection

References

• - Architecture - System design and components
• Intent Security - Validation and authorization
• Self-Improvement - Learning mechanisms
• Hooks Setup - Automation configuration
• API Reference - Programmatic usage

Multi-Agent Support

Works with Claude Code, Codex CLI, GitHub Copilot, and OpenClaw. See references/multi-agent.md for agent-specific configurations.

Safety Guarantees

✓ Intent Alignment - Every action validated against goal
✓ Permission Boundaries - Cannot exceed authorized scope
✓ Reversibility - Checkpoint-based rollback
✓ Auditability - Complete action history
✓ Bounded Learning - Safety-constrained improvements
✓ Human Oversight - Approval gates for high-risk operations

License

MIT

---

Note: This skill provides strong safety mechanisms but requires proper configuration and usage. Always:

• - Define clear, specific intents
• Review violation logs regularly
• Monitor learning effectiveness
• Keep approval gates enabled for high-risk operations
• Test in non-production environments first

Intent-based security is a powerful approach, but human judgment remains essential.