opena2a harden-soul
Generate or improve governance files by adding missing ABGS (Agent Behavioral Governance Standard) sections.
Usage
opena2a harden-soul [options]Description
Analyzes the existing SOUL.md (or other governance file) and appends missing ABGS sections required for the specified agent profile and tier. Existing content is preserved; only missing sections are added. If no governance file exists, a new SOUL.md is generated from scratch with all required sections.
Use --dry-run to preview changes without modifying any files. Pair with scan-soul to verify improvements after hardening.
Requires hackmyagent to be installed. Install with npm install -g hackmyagent.
Flags
| Flag | Description |
|---|---|
--profile <type> | Agent profile: conversational, code-assistant, tool-agent, autonomous, orchestrator. |
--tier <tier> | Target tier: BASIC, TOOL-USING, AGENTIC, MULTI-AGENT. |
--dry-run | Preview changes without writing to disk. |
--format <text|json> | Output format. |
--ci | CI mode with deterministic output. |
--verbose | Show detailed section-by-section changes. |
Examples
opena2a harden-soul --profile tool-agent --tier TOOL-USINGopena2a harden-soul --dry-run --verboseopena2a harden-soul --profile autonomous --tier AGENTIC opena2a scan-soul --profile autonomous --tier AGENTIC
What SOUL.md Is
SOUL.md is the governance file for an AI agent. It defines the behavioral boundaries, capabilities, and policies that the agent must follow. Think of it as a constitution for the agent: it declares what the agent is allowed to do, what it must not do, how it handles data, and how it responds to edge cases. The file is human-readable Markdown and machine-parseable by security scanners.
The OASB (Open Agent Security Benchmark) v2 standard defines the sections that a well-governed agent should include. The harden-soul command generates these sections based on the agent profile and tier you specify.
Generated Sections
The number of sections generated depends on the target tier. A BASIC tier agent receives 27 controls across core domains, while a MULTI-AGENT orchestrator receives up to 68 controls. Generated sections include:
- Agent Identity and Purpose declaration
- Capability Scope and access boundaries
- Data Handling policies (PII, retention, storage)
- Tool Usage restrictions and confirmation requirements
- Communication and output formatting rules
- Safety and ethics guidelines
- Monitoring and audit trail requirements
- Escalation and incident response procedures
Expected Output
$ opena2a harden-soul --profile tool-agent --tier TOOL-USING Governance Hardening (ABGS) ============================ File: SOUL.md (existing, 12 sections) Profile: tool-agent Tier: TOOL-USING (54 controls) Analysis: Existing sections: 12 (preserved) Missing sections: 8 Controls covered: 34 -> 54 Added sections: + Data Handling: Retention policy + Data Handling: PII classification + Tool Usage: Confirmation requirements + Tool Usage: Resource limits + Safety: Bias mitigation + Monitoring: Audit trail format + Monitoring: Incident reporting + Communication: Error response policy SOUL.md updated. Run 'opena2a scan-soul' to verify.
Customization
Generated sections use template content that you should customize for your specific agent. The templates include placeholder values marked with brackets (e.g., [specify retention period]) to indicate where agent-specific details are needed. After hardening, review the generated sections and replace placeholders with actual policies. The --dry-run flag lets you preview all changes before they are written to disk, which is useful for reviewing the generated content before committing.
Error Handling
If hackmyagent is not installed, the command prints installation instructions and exits. If the governance file is read-only, the command reports a permission error. The--dry-run flag always succeeds regardless of file permissions since it does not write to disk. When no --profile or --tier is specified, the command auto-detects based on the project structure.