self-improving-intent-security-agent

Documentation-first skill and workflow toolkit for intent-based security. Provides templates, examples, and local helper scripts for capturing intent, reviewing actions, documenting rollbacks, and recording learnings. Use when: (1) designing or prototyping intent validation workflows, (2) documenting high-risk operations, (3) creating audit trails and rollback records, (4) building your own runtime enforcement layer.

# Self-Improving Intent Security Agent

## Install

```bash
npx skills add nishantapatil3/self-improving-intent-security-agent
```

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:

```bash
mkdir -p .agent/{intents,violations,learnings,audit}
```

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:

```bash
./scripts/scaffold-run.sh examples/my-demo customer_feedback medium
```

This creates:
- `conversation.md` for the user/agent transcript
- `report.md` 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:

```markdown
## [INT-YYYYMMDD-XXX] task_name

**Created**: ISO-8601 timestamp
**Risk Level**: low | medium | high
**Status**: active | completed | violated

### Goal
What you want to achieve (single clear objective)

### Constraints
- Boundary 1 (e.g., "Only modify files in ./src")
- Boundary 2 (e.g., "Do not make network calls")
- Boundary 3 (e.g., "Preserve existing test coverage")

### Expected Behavior
- Pattern 1 (e.g., "Read files before modifying")
- Pattern 2 (e.g., "Run tests after changes")
- Pattern 3 (e.g., "Create backups of modified files")

### Context
- Relevant files: path/to/file.ext
- Environment: development | staging | production
- Previous attempts: INT-20250115-001 (if retry)

---
```

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. Capture the user request in `conversation.md`
2. Translate it into a structured intent in `.agent/intents/`
3. Record allowed and blocked actions in `.agent/audit/`
4. Log suspicious behavior in `.agent/violations/ANOMALIES.md`
5. Log hard validation failures in `.agent/violations/`
6. Record recovery steps in `.agent/audit/ROLLBACKS.md`
7. Extract reusable learnings in `.agent/learnings/`
8. Promote stable improvements into `.agent/learnings/STRATEGIES.md`
9. Summarize the run in `report.md`

### 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. **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

```yaml
Intent: "Process customer feedback files"
Constraints: ["Only read ./feedback", "No file modifications"]

Action: "delete ./feedback/temp.txt"
Validation:
  - Goal Alignment: ❌ Deleting isn't "processing"
  - Constraint Check: ❌ Violates "no modifications"
  - Behavior Match: ❌ Not expected for this task
  - Authorization: ✓ (but blocked by other checks)

Result: BLOCKED → Log violation → Consider rollback
```

## Logging Violations

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

```markdown
## [VIO-YYYYMMDD-XXX] violation_type

**Logged**: ISO-8601 timestamp
**Severity**: low | medium | high | critical
**Intent**: INT-20250115-001
**Status**: pending_review

### What Happened
Action that was attempted

### Validation Failures
- Goal Alignment: [reason]
- Constraint Check: [which constraint violated]
- Behavior Match: [how it deviated]

### Action Taken
- [ ] Action blocked
- [ ] Checkpoint rollback
- [ ] Alert sent
- [ ] Execution halted

### Root Cause
Why the agent attempted this (if analyzable)

### Prevention
How to prevent this in the future

### Metadata
- Related Intent: INT-20250115-001
- Action Type: file_delete | api_call | command_execution
- Risk Level: high
- See Also: VIO-20250110-002 (if recurring)

---
```

## 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`:

```markdown
## [ANO-YYYYMMDD-XXX] anomaly_type

**Detected**: ISO-8601 timestamp
**Severity**: low | medium | high
**Intent**: INT-20250115-001

### Anomaly Details
What unusual behavior was detected

### Evidence
- Metric that triggered alert
- Baseline vs. actual values
- Timeline of deviation

### Assessment
Why this is anomalous

### Response Taken
- [ ] Continued with monitoring
- [ ] Applied constraints
- [ ] Rolled back
- [ ] Halted execution

---
```

## Learning Workflow

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

```markdown
## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Intent**: INT-20250115-001
**Outcome**: success | failure | partial

### What Was Learned
Pattern or insight discovered

### Evidence
- Success rate: 95%
- Execution time: 2.3s
- Actions taken: 15
- Checkpoints: 3

### Strategy Impact
How this affects future executions

### Application Scope
- Tasks: file_processing, data_transformation
- Risk Levels: low, medium
- Conditions: when X and Y are true

### Safety Check
- Complexity: low | medium | high
- Performance: baseline_comparison
- Risk: assessment

### Metadata
- Category: pattern | optimization | error_handling | security
- Confidence: low | medium | high
- Sample Size: N tasks observed
- Pattern-Key: file.batch_processing (if recurring)

---
```

## Rollback Operations

### Creating Checkpoints

Before risky operations:

```typescript
const checkpoint = await agent.checkpoint.create({
  intent: currentIntent,
  reason: "Before bulk file operations"
});
```

### Rollback on Violation

Automatic rollback when intent violated:

```typescript
// Happens automatically, but can also trigger manually:
await agent