opena2a scan-soul

Governance file scanner. Evaluates agent behavioral governance against OASB v2 controls.

Usage

opena2a scan-soul [options]

Description

Scans governance files (SOUL.md, system-prompt.md, CLAUDE.md, .cursorrules, agent-config.yaml) against the OASB v2 Agent Behavioral Governance Standard. The number of applicable controls depends on the agent tier. Results include a compliance score, missing controls, and specific remediation steps. Exits with code 1 if the score falls below 60.

Agent Tiers

Tier	Controls	Description
`BASIC`	27	Conversational agents with no tool access.
`TOOL-USING`	54	Agents that invoke external tools or APIs.
`AGENTIC`	65	Autonomous agents with multi-step reasoning.
`MULTI-AGENT`	68	Orchestrators managing multiple sub-agents.

Auto-Detected Files

SOUL.md, system-prompt.md, CLAUDE.md
.cursorrules, agent-config.yaml

Flags

Flag	Description
`--profile <type>`	Agent profile: conversational, code-assistant, tool-agent, autonomous, orchestrator.
`--tier <tier>`	Override auto-detected tier: BASIC, TOOL-USING, AGENTIC, MULTI-AGENT.
`--deep`	Enable deep analysis with semantic matching of control coverage.
`--format <text\|json>`	Output format.
`--ci`	CI mode with exit code 1 if score < 60.
`--verbose`	Show detailed per-control results.

Requires hackmyagent to be installed. Install with npm install -g hackmyagent.

Examples

# Scan governance files in current directory

opena2a scan-soul

# Scan as autonomous agent with deep analysis

opena2a scan-soul --profile autonomous --deep

# CI gate with JSON output

opena2a scan-soul --ci --format json --tier AGENTIC

Control Domains

The OASB v2 standard organizes behavioral controls into domains. The scanner checks each governance file for coverage across these domains:

Domain	What It Covers
Identity & Authentication	Agent identity declaration, capability scoping, access control boundaries.
Data Handling	PII handling, data retention, storage and transmission policies.
Tool Usage	Tool access restrictions, confirmation requirements, resource limits.
Communication	Output formatting, disclosure obligations, error response behavior.
Safety & Ethics	Harm prevention, bias mitigation, escalation procedures.
Monitoring & Audit	Logging requirements, audit trail, incident reporting.

Grading

The compliance score is calculated as the percentage of applicable controls that are covered in the governance files. The score uses a forward-looking scale that shows the path to improvement:

90-100 -- Comprehensive governance coverage
70-89 -- Good coverage with minor gaps
60-69 -- Adequate coverage, some domains need attention
Below 60 -- Significant gaps (CI gate fails at this threshold)

Expected Output

$ opena2a scan-soul --profile autonomous --tier AGENTIC

Governance Scanner (OASB v2)
=============================
Files:   SOUL.md, .cursorrules
Profile: autonomous
Tier:    AGENTIC (65 controls)

Results: 48/65 controls covered (73%)

Missing controls:
  DATA-003  No data retention policy specified
  TOOL-007  No tool confirmation requirement for destructive actions
  TOOL-009  No resource usage limits defined
  SAFE-002  No bias mitigation policy
  ...       (13 more, use --verbose for full list)

Score: 73/100 (recoverable to 93 by adding 13 missing sections)
Run 'opena2a harden-soul --profile autonomous --tier AGENTIC' to generate missing sections.

Error Handling

If no governance file is found in the target directory, the command reports that no files were detected and suggests running opena2a harden-soul to generate a SOUL.md from scratch. In CI mode, the command exits with code 1 when the score falls below 60. The --deepflag uses semantic matching which may take longer for large governance files.

Related Commands

harden-soul scan benchmark OASB docs