agentops
Enterprise guardrails, delivery lifecycle, and self-evolution for Claude Code. Wraps every session in 7 security layers (path validation, co
Open source Open in the app JSON README (API)
About
Enterprise guardrails, delivery lifecycle, and self-evolution for Claude Code. Wraps every session in 7 security layers (path validation, command validation, injection scanning, credential redaction, exfiltration detection), structures work with the STAR methodology, and orchestrates full project builds from vision to merged PR through an 8.5-phase lifecycle with TDD enforcement, wave-based parallel execution, and two-stage code review. Includes 37 commands, 44 hooks, 12 specialist agents, 49 templates, and 32+ feature flags.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- garethdaine
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 3
- Last push
- 2026-03-29T19:22:48Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
garethdaine/agentops/agentops
README
<p align="center">
<img src="assets/banner.png" alt="AgentOps Banner" width="100%"/>
</p>
# AgentOps — Enterprise Guardrails & Delivery Lifecycle for Claude Code
A plugin for [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) that wraps every session in 7 security layers, structures work with the STAR methodology, auto-pilots workflows, delegates to 12 specialist agents, learns from failures via self-evolution, and orchestrates full project builds from vision to merged PR.
40 slash commands | 44 hooks | 12 specialist agents | 49 templates | 33+ feature flags | real-time 3D dashboard
[](https://github.com/garethdaine/agentops/actions/workflows/tests.yml)
[](https://github.com/garethdaine/agentops/actions/workflows/lint.yml)
[](https://github.com/garethdaine/agentops/actions/workflows/security.yml)
[](https://www.npmjs.com/package/@garethdaine/agentops)
[](LICENSE)
---
## Quick Start
### Install via npm
```bash
npm install -g @garethdaine/agentops
# Run Claude Code with the plugin loaded
claude --plugin-dir $(npm root -g)/@garethdaine/agentops
```
### Or clone from GitHub
```bash
git clone https://github.com/garethdaine/agentops.git agentops-plugin
claude --plugin-dir ./agentops-plugin
```
On first session, the plugin auto-initializes `.agentops/` with default flags and budget.
---
## AgentOps vs GSD vs Superpowers
| Dimension | AgentOps | GSD (~31K stars) | Superpowers (~50K stars) |
|-----------|----------|-------------------|--------------------------|
| **Core identity** | Enterprise guardrailing + full delivery lifecycle | Spec-driven meta-prompting to beat context rot | Skills-based methodology with TDD enforcement |
| **Commands** | 40 | ~15 | ~10 (skill-based) |
| **Hooks** | 44 shell scripts across 7 lifecycle events | None (prompts only) | None (prompts only) |
| **Agents** | 12 specialist agents | 4 parallel researchers + planner | Code reviewer agent |
| **Security** | 7 layers (injection, exfiltration, supply-chain, Unicode, credential, path, env) | Minimal | None |
| **Self-evolution** | EvoSkill (failures → proposer → skill-builder → feedback loop) | KNOWLEDGE.md (manual) | Skill extraction (manual) |
| **TDD enforcement** | Mandatory RED→GREEN→REFACTOR + Nyquist rule (`<test>`/`<verify>`/`<done>` on every task); auto-test hook in sessions | Nyquist rule (verify required) | Code without tests = deleted |
| **Context strategy** | Fresh subagent per task (build_fresh_context) + session hooks | Fresh 200K context per subagent | Fresh context per subagent |
| **Parallel execution** | Wave-based with dependency graphs + 4 parallel researchers | Wave-based parallel execution | N/A |
| **Persuasion psychology** | 5 Cialdini techniques embedded in human gates | None | 5 Cialdini techniques |
| **Plan format** | STAR markdown + XML with Nyquist compliance (<test>/<verify>/<done>) | XML executable plans | Markdown plans |
| **Git workflow** | Configurable strategy (worktree / feature-branch / trunk-based); atomic commits per task, conventional commit format | Atomic commits, worktrees | Worktrees, atomic commits |
| **Review** | Two-stage: spec compliance (requirements mapping) + code quality (11 dimensions) | N/A | Two-stage review |
| **Feature flags** | 32+ independently toggleable with presets | Minimal settings | None |
| **Enterprise templates** | 49 templates (discovery → delivery → handover) | None | None |
| **Observability** | Audit logs, OTLP telemetry, file provenance, cost budgets | None | None |
| **Configurable autonomy** | guided / supervised / autonomous | N/A | N/A |
| **Linear integration** | Task sync (create, status update, close) | None | None |
| **Real-time dashboard** | 3D office scene (React Three Fiber) + 2D fallback, WebSocket relay | None | None |
### What AgentOps does that neither competitor does
1. **7-layer security system.** Injection scanning, exfiltration detection, Unicode/Glassworm defense, path traversal protection, credential redaction, env var guarding, and content trust — all running as hooks on every tool invocation.
2. **EvoSkill self-evolution.** The failure-collector → proposer → skill-builder → feedback-history pipeline auto-generates skills from failures. No manual intervention.
3. **Full observability.** Structured audit logs, OTLP telemetry export, file provenance tracking, and cost budgets with session-level granularity.
4. **8.5-phase build lifecycle.** From brainstorm to merged PR with state machine, resumability, human gates, parallel research, TDD enforcement, two-stage review, and Nyquist verification — all configurable via feature flags and autonomy levels.
5. **Real-time 3D agent dashboard.** A Next.js 16 + React Three Fiber office scene that visualizes agent activity live via WebSocket relay from telemetry JSONL, with 2D fallback for non-GPU environments.
---
## Architecture
The plugin integrates through four extension points:
| Extension Point | Location | Count | Purpose |
|-----------------|----------|-------|---------|
| **Hooks** | `hooks/hooks.json` | 44 | Intercept tool use at every lifecycle event |
| **Commands** | `commands/*.md` | 40 | User-facing slash commands (`/agentops:*`) |
| **Agents** | `agents/*.md` | 12 | Specialist subagents for analysis and execution |
| **Templates** | `templates/**/*.md` | 49 | Standards, architecture patterns, delivery docs |
Runtime state lives in `.agentops/` (auto-created, gitignored).
---
## The Build Command
`/agentops:build` is the master lifecycle command — it orchestrates a project from raw vision to merged, verified code.
### 8.5 Phases
| Phase | Name | What happens | Human gate? |
|-------|------|-------------|-------------|
| 1 | **BRAINSTORM** | Vision capture → 3 alternative framings → brief | Yes |
| 2 | **INTERROGATION** | 4 parallel researchers + exhaustive Q&A → requirements | Yes |
| 3 | **PLANNING** | STAR analysis → XML plan → 8-dimension validation | Yes |
| 4 | **TASK BREAKDOWN** | Parse XML → per-task TDD mini-plans → Linear sync | Yes |
| 4.5 | **SCAFFOLD** | Auto-scaffold new projects (conditional) | — |
| 5 | **EXECUTION** | Fresh subagent per task, wave-based parallelism, TDD enforced | Supervised only |
| 6 | **REVIEW** | Stage 1: spec compliance → Stage 2: code quality → fix wave | Yes |
| 7 | **VERIFICATION** | Nyquist audit + full test suite + E2E + compliance gates | Yes |
| 8 | **APPROVAL** | Summary → PR creation → Linear cleanup → lesson capture | Yes |
### Key features
- **Resumable state machine** — state saved to `.agentops/build-state.json` after each phase
- **Fresh context per task** — each execution task gets a fresh 200K-token subagent with full standards injection
- **Mandatory TDD** — RED→GREEN→REFACTOR enforced; no code without a failing test first
- **Nyquist compliance** — every task must have `<test>`, `<verify>`, and `<done>` in the XML plan
- **4 parallel researchers** — stack, architecture, features, pitfalls research runs concurrently
- **8-dimension plan validation** — completeness, dependency DAG, file ownership, task size, Nyquist, wave ordering, TDD ordering, commit quality
- **Two-stage review** — spec compliance reviewer maps every requirement to implementation; code quality reviewer checks 11 dimensions
- **Persuasion psychology** — Cialdini's 5 techniques (authority, commitment, scarcity, social proof, loss aversion) embedded in human gates
- **Quick mode** — `--quick` for brainstorm → plan → execute → verify (no interrogation, no PR)
---
## Security (7 Layers)
| Layer | Hook | What it blocks |
|-------|------|---------------|
| Command validation | `validate-command.sh` | `rm -rf /`, fork bombs, shell injection, destructive ops |
| Path validation | `validate-path.sh` | Path traversal, system dirs, sensitive dotfiles |
| Env protection | `validate-env.sh` | `PATH`/`HOME` reassignment, credential patterns |
| Injection detection | `injection-scan.sh` | Role-switching, authority markers, delimiter attacks |
| Exfiltration prevention | `exfiltration-check.sh` | `curl`/`wget` with sensitive files, base64+network combos |
| Credential redaction | `credential-redact.sh` | `.env`, `.pem`, `.key` access → audit + alert |
| Content trust | `content-trust.sh` | Flags external content as untrusted + optional LLM firewall |
Plus supply-chain defense: Unicode/Glassworm detection (`unicode-firewall.sh`), integrity verification (`integrity-verify.sh`), and lockfile auditing (`lockfile-audit.sh`).
---
## Commands (40)
### Core Commands
| Command | Purpose |
|---------|---------|
| `/agentops:build` | Master 8.5-phase project lifecycle — vision to merged PR |
| `/agentops:plan` | STAR-based implementation plan with checkable tasks |
| `/agentops:star` | Quick STAR analysis (lighter than plan) |
| `/agentops:interrogate` | Exhaustive requirements discovery — eliminates all assumptions |
| `/agentops:workflow` | 8-phase workflow mapping with YAML schemas and Mermaid diagrams |
| `/agentops:verify` | Verify task completion against STAR criteria |
| `/agentops:evolve` | Run EvoSkill self-improvement loop |
| `/agentops:code-field` | Code Field methodology (decompose, solve with confidence, verify) |
| `/agentops:code-analysis` | Structured code analysis on current project |
| `/agentops:lessons` | Display all captured lessons |
| `/agentops:lesson` | Capture a single lesson learned |
| `/agentops:compliance-check` | Run compliance gates manually |
| `/agentops:cost-report` | Session cost tracking and budget status |
| `/agentops:flags` | View or toggle feature flags |
| `/agentops:configure` | Unified configuration interface with presets |
| `/agentops:prune` | Clean up stale runtime state |
| `/agentops:supply-chain-scan` | Scan dependencies for supply-chain threats |
| `/agentops:unicode-scan` | Scan project for invisible Unicode characters |
### Enterprise Commands
| Command | Purpose |
|---------|---------|
| `/agentops:feature` | 6-phase structured feature build with configurable autonomy |
| `/agentops:scaffold` | Interactive project scaffolding with tech stack selection |
| `/agentops:review` | Unified code review (code-critic + security-reviewer agents) |
| `/agentops:test-gen` | AI-generated test suites with quality validation |
| `/agentops:reason` | Multi-step reasoning: Analyse → Design → Validate → Recommend |
| `/agentops:design` | Solution design — architecture proposals, risk assessment |
| `/agentops:adr` | Architecture Decision Records |
| `/agentops:brainstorm` | Structured brainstorming sessions |
| `/agentops:qa-check` | Pre-deployment QA: security, performance, accessibility |
| `/agentops:handover` | Client handover documentation and runbooks |
| `/agentops:onboard` | Generate onboarding guides from project structure |
| `/agentops:knowledge` | Search project knowledge base |
| `/agentops:status-report` | Client-facing status report from git history |
| `/agentops:tech-catalog` | Technology catalog and stack documentation |
| `/agentops:gap-analysis` | Gap analysis between current and desired state |
| `/agentops:dev-setup` | Developer environment setup guide |
| `/agentops:docker-dev` | Docker development environment configuration |
| `/agentops:e2e` | End-to-end test planning and execution |
| `/agentops:worklog` | Personal work log for tracking daily contributions |
| `/agentops:idea` | Structured idea proposals with development and export |
| `/agentops:search` | Unified search across work log, ideas, git history, and knowledge base |
| `/agentops:herd` | Multi-agent coordination for complex tasks |
---
## Specialist Agents (12)
### Core Agents
| Agent | Tools | Purpose |
|-------|-------|---------|
| `code-critic` | Read, Grep, Glob, Bash | 11-dimension code quality review |
| `security-reviewer` | Read, Grep, Glob, Bash, WebSearch | OWASP Top 10, CVE scanning, auth gaps |
| `interrogator` | Read, Grep, Glob, WebSearch | Requirements discovery and plan generation |
| `proposer` | Read, Grep, Glob | Failure analysis → skill proposals (EvoSkill) |
| `skill-builder` | Read, Grep, Glob, Bash | Materialize skill proposals into SKILL.md files |
| `delegation-router` | Read, Grep, Glob | Route tasks to appropriate specialist agents |
### Build Agents (Phase-specific)
| Agent | Phase | Tools | Purpose |
|-------|-------|-------|---------|
| `stack-researcher` | 2 | Read, Grep, Glob, WebSearch | Technology stack options with fit scores |
| `architecture-researcher` | 2 | Read, Grep, Glob, WebSearch | Architectural patterns and ADRs |
| `feature-researcher` | 2 | Read, Grep, Glob, WebSearch | MVP vs v2 scope, feature trade-offs |
| `pitfalls-researcher` | 2 | Read, Grep, Glob, WebSearch | Anti-patterns, failure modes, security pitfalls |
| `plan-validator` | 3 | Read, Grep, Glob | 8-dimension plan validation |
| `spec-compliance-reviewer` | 6 | Read, Grep, Glob, Bash | Requirement mapping + standards compliance |
---
## Hook System (44 hooks)
Hooks fire at 7 lifecycle events:
| Event | When | Example hooks |
|-------|------|---------------|
| `SessionStart` | Session begins | session-cleanup, star-preamble, code-field-preamble, lessons-check, budget-check, unicode-scan, integrity-verify, lockfile-audit |
| `PreToolUse` | Before tool executes | validate-command, validate-path, validate-env, injection-scan, exfiltration-check, star-gate, auto-plan, runtime-mode |
| `PostToolUse` | After tool completes | content-trust, unicode-firewall, integrity-verify, credential-redact, detect-test-run, standards-enforce, ai-guardrails, plan-gate, auto-test, auto-delegate, audit-log, telemetry |
| `PostToolUseFailure` | After tool fails | failure-collector, auto-lesson, evolve-gate, telemetry |
| `SubagentStart` | Subagent spawned | delegation-trust |
| `Stop` | Session ending | auto-verify, auto-evolve, compliance-gate |
| `SessionEnd` | Final cleanup | telemetry |
---
## EvoSkill Self-Evolution
```
Tool Failure → failure-collector.sh → failures.jsonl
↓
/agentops:evolve
↓
proposer agent (analyze failures,
check existing skills & feedback)
↓
Skill Proposal
↓
skill-builder agent (materialize SKILL.md)
↓
feedback-history.jsonl (record outcome)
```
Triggered automatically at session stop (if 2+ unprocessed failures exist) or manually via `/agentops:evolve`.
---
## Engineering Standards
The build system injects comprehensive engineering standards into every execution subagent:
- **SOLID** — all 5 principles with heuristics and code examples (SRP: ≤30 line functions, ≤200 line classes)
- **Clean Code** — naming, functions (≤3 params, command-query separation), error handling (typed hierarchy, correlation IDs)
- **DRY/KISS/YAGNI** — with clear thresholds (2+ locations = extract, 3+ uses before abstracting)
- **Design Patterns** — creational, structural, behavioral with selection heuristic ("name the problem it solves")
- **Action-Based Architecture** — single-purpose action classes for business logic
- **DDD** — aggregates, entities, value objects, domain services, ubiquitous language
- **Layered Architecture** — controller → service → domain → repository (no skipping, violations = CRITICAL)
- **Security** — injection prevention, secrets management, auth, input validation, data protection (all CRITICAL)
- **Testing** — Arrange-Act-Assert, red-first TDD, behaviour over implementation
Standards are enforced via `templates/standards/standards-checklist.md` during Phase 6 review.
---
## Feature Flags (33+)
All flags default to sensible values and are toggleable via `/agentops:flags` or `.agentops/flags.json`.
### Security flags
`command_validation_enabled`, `path_validation_enabled`, `env_validation_enabled`, `injection_scan_enabled`, `content_trust_enabled`, `exfiltration_detection_enabled`, `credential_redaction_enabled`, `llm_content_firewall_enabled`
### Workflow flags
`star_preamble_enabled`, `code_field_rules_enabled`, `plan_gate_enabled`, `verification_gate_enabled`, `test_gate_enabled`, `lessons_enabled`
### Automation flags
`auto_plan_enabled`, `auto_test_enabled`, `auto_verify_enabled`, `auto_lesson_enabled`, `auto_evolve_enabled`, `auto_delegate_enabled`
### Build lifecycle flags
`build_tdd_enforced`, `build_parallel_research`, `build_xml_plans`, `build_linear_sync`, `build_fresh_context`, `build_wave_parallel`, `build_nyquist_enforce`, `build_persuasion`, `build_quick_mode`, `build_scaffold_auto`, `build_standards_inject`, `standards_enforcement_mode`
### Dashboard flags
`dashboard_enabled`
### Enterprise flags
`enterprise_scaffold`, `ai_workflows`, `unified_review`, `architecture_guardrails`, `delivery_lifecycle`, `team_governance`, `client_comms`
### Autonomy levels
- **guided** (default) — all human gates active
- **supervised** — all human gates + step-level confirmation during execution
- **autonomous** — skip soft gates, only hard security gates remain
### Configuration presets
```bash
/agentops:configure preset minimal # Security only, no automation
/agentops:configure preset standard # Security + core automation
/agentops:configure preset enterprise # All features, guided autonomy
/agentops:configure preset autonomous # All features, minimal gates
```
---
## Observability
| System | File | Purpose |
|--------|------|---------|
| Audit log | `.agentops/audit.jsonl` | Every tool invocation with timestamp, session, tool, input |
| Telemetry | `.agentops/telemetry.jsonl` | Structured events with optional OTLP export |
| File provenance | `.agentops/provenance.jsonl` | Source and trust level of every file interaction |
| Cost tracking | `.agentops/budget.json` | Session budget with 80% warning threshold |
| Build execution | `.agentops/build-execution.jsonl` | Per-task execution log with TDD phase tracking |
| Failure log | `.agentops/failures.jsonl` | Tool failures for EvoSkill analysis |
| Integrity | `.agentops/integrity.jsonl` | SHA-256 manifest of agent-written files |
---
## Agent Office Dashboard
A real-time 3D visualization of agent activity, built with Next.js 16, React Three Fiber, and Shadcn UI.
### Features
| Feature | Description |
|---------|-------------|
| **3D office scene** | Workstations with lighting, agent avatars, and animations via React Three Fiber |
| **Real-time state** | WebSocket relay server streams agent activity from JSONL telemetry files |
| **2D fallback** | Activity table with WebGL detection for environments without GPU support |
| **Session registry** | Auto-registers sessions from incoming telemetry with stale detection |
| **Connection status** | Live indicator showing relay connection health |
| **Lifecycle management** | Proper Three.js disposal and resource cleanup |
### How it works
```
hooks/telemetry.sh → .agentops/telemetry.jsonl
↓
dashboard/server/file-watcher.ts (byte-offset tracking)
↓
dashboard/server/relay.ts (WebSocket with origin validation)
↓
dashboard/src/ (Zustand store → 3D scene / 2D table)
```
The dashboard launches automatically when `dashboard_enabled` is `true` in `.agentops/flags.json`. The `dashboard-launch.sh` hook starts the Next.js dev server and WebSocket relay on session start.
---
## Configuration
### Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `AGENTOPS_MODE` | `standard` | Runtime mode (`safe`, `standard`, `full`, `unrestricted`) |
| `AGENTOPS_BUDGET_USD` | `5` | Session cost budget in USD |
| `OTLP_ENDPOINT` | _(none)_ | OpenTelemetry endpoint for telemetry forwarding |
| `LINEAR_API_KEY` | _(none)_ | Linear API key for build task sync |
### Key Files
| File | Purpose |
|------|---------|
| `.claude-plugin/plugin.json` | Plugin metadata |
| `hooks/hooks.json` | Master hook registry |
| `settings.json` | Plugin permission defaults |
| `.agentops/flags.json` | Feature flag toggles (auto-created) |
| `.agentops/budget.json` | Cost tracking (auto-created) |
---
## Directory Structure
```
agentops-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── hooks/ # 44 shell scripts + hooks.json
│ ├── hooks.json # Master hook registry
│ ├── feature-flags.sh # Shared flag library (facade)
│ ├── flag-utils.sh # Core flag reading
│ ├── enforcement-lib.sh # Enforcement actions
│ ├── patterns-lib.sh # Shared patterns & thresholds
│ ├── redact-lib.sh # Secret redaction
│ ├── evolve-lib.sh # Failure tracking helpers
│ ├── unicode-lib.sh # Unicode detection library
│ └── *.sh # Security, automation, compliance hooks
├── commands/ # 37 slash commands
│ ├── build.md # /agentops:build (master lifecycle)
│ ├── plan.md # /agentops:plan (STAR planning)
│ ├── interrogate.md # /agentops:interrogate (requirements)
│ ├── workflow.md # /agentops:workflow (process mapping)
│ └── enterprise/ # 19 enterprise delivery commands
├── agents/ # 12 specialist agents
│ ├── code-critic.md # Code quality (11 dimensions)
│ ├── security-reviewer.md # Security (OWASP, CVEs)
│ ├── stack-researcher.md # Technology research (build Phase 2)
│ ├── architecture-researcher.md # Architecture research (build Phase 2)
│ ├── feature-researcher.md # Feature scoping (build Phase 2)
│ ├── pitfalls-researcher.md # Failure modes (build Phase 2)
│ ├── plan-validator.md # 8-dimension validation (build Phase 3)
│ └── spec-compliance-reviewer.md # Spec + standards review (build Phase 6)
├── templates/ # 49 templates
│ ├── standards/ # Engineering standards + checklist
│ ├── build/ # Brief, task-plan, summary templates
│ ├── architecture/ # 8 architecture pattern templates
│ ├── delivery/ # Discovery → deployment → handover
│ ├── communication/ # Stakeholder comms templates
│ ├── workflows/ # Feature, refactor, spike, bug workflows
│ └── scaffolds/ # Error handling, logging, health checks
├── dashboard/ # Agent Office Dashboard (Next.js 16)
│ ├── src/ # React components, stores, types
│ ├── server/ # WebSocket relay + JSONL file watcher
│ └── tests/ # Dashboard unit tests (Vitest)
├── tests/ # 20 BATS test files (security, automation, dashboard)
├── docs/ # Architecture docs
├── settings.json # Plugin permission defaults
├── LICENSE # MIT
└── .gitignore
```
---
## Testing
The plugin includes 20 BATS test files covering security hooks, automation hooks, and dashboard integration:
```bash
# Run all tests
bats tests/
# Security hooks
bats tests/validate-command.bats
bats tests/validate-path.bats
bats tests/validate-env.bats
bats tests/injection-scan.bats
bats tests/exfiltration-check.bats
bats tests/credential-redact.bats
bats tests/content-trust.bats
bats tests/feature-flags.bats
# Automation hooks
bats tests/auto-test.bats
bats tests/auto-plan.bats
bats tests/auto-verify.bats
bats tests/auto-lesson.bats
bats tests/auto-evolve.bats
bats tests/auto-delegate.bats
bats tests/failure-collector.bats
bats tests/evolve-gate.bats
# Dashboard
bats tests/dashboard-flag.bats
bats tests/dashboard-launch.bats
bats tests/session-registry.bats
bats tests/telemetry-pretool.bats
```
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to report bugs, suggest features, and submit PRs.
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
## Security
Found a vulnerability? See [.github/SECURITY.md](.github/SECURITY.md) for responsible disclosure instructions. Do not open a public issue.
## License
MIT License. See [LICENSE](LICENSE) for details.