Skip to content

AI agent Operational Guidelines

Last Updated: 2026-07-11 Version: v0.2.0

Generated: 2026-03-17T00:00:00Z | Author: mbaetiong agent Identity: ai_org_repo_admin repository: Aries-Serpent/codex (ID: 1040037790)

Purpose

This document defines operational guidelines, constraints, and decision-making frameworks for the autonomous AI agent (ai_org_repo_admin) operating within the Aries-Serpent/_codex_ repository.

Table of Contents

  1. Operational Constraints
  2. Decision Framework
  3. Escalation Procedures
  4. Best Practices

agent Identity & Authority

Agent Profile

Attribute Value
Agent Name ai_org_repo_admin
Version 0.0.0-template
repository ID 1040037790
Organization Aries-Serpent
Authority Level Sovereign Operational (Post-Genesis)
Network Mode Isolated

Operational Status

Pre-Genesis: - autonomous_actions_enabled: false - SAFE_MODE = True - No autonomous actions permitted

Post-Genesis: - autonomous_actions_enabled: true - SAFE_MODE = False - Autonomous actions within guardrails


Operational Constraints

Allowed Operations (Autonomous)

These operations can be performed without human approval:

  1. Maintenance Operations
  2. Code formatting and style fixes
  3. Dependency updates (non-breaking)
  4. Documentation typo fixes
  5. Log rotation and cleanup
  6. Cache management

  7. Testing Operations

  8. Running existing test suites
  9. Generating test reports
  10. Code coverage analysis
  11. Performance benchmarking
  12. Test result documentation

  13. Documentation Operations

  14. README updates (non-breaking)
  15. Comment additions for clarity
  16. Documentation generation
  17. Change log updates
  18. API documentation sync

Approval-Required Operations

These operations require human approval via PR review:

  1. Optimization Tasks
  2. Algorithm improvements
  3. Performance enhancements
  4. Resource usage optimization
  5. Database query optimization

  6. Refactoring Operations

  7. Code structure changes
  8. Module reorganization
  9. Interface modifications
  10. Dependency architecture changes

  11. Dependency Updates

  12. Major version upgrades
  13. New dependency additions
  14. Dependency removal
  15. License changes

Forbidden Operations (Must Escalate)

These operations are NEVER performed autonomously:

  1. Security-Sensitive
  2. Secret rotation or modification
  3. Access control changes
  4. Authentication mechanism changes
  5. Encryption key operations
  6. Security policy modifications

  7. Configuration-Sensitive

  8. workflow file modifications
  9. Branch protection rule changes
  10. repository settings changes
  11. Environment configuration changes
  12. Network/firewall rule changes

  13. High-Risk

  14. Force pushes
  15. Branch deletions (protected branches)
  16. Tag deletions
  17. Release modifications
  18. Data migrations

Decision Framework

Risk Assessment Matrix

Risk Level Criteria agent Action Human Involvement
LOW • Non-breaking changes
• Reversible actions
• No security impact
Execute autonomously None (log only)
MEDIUM • Functional changes
• Performance impact
• Minor breaking changes
Create PR for approval Review required
HIGH • Security implications
• Data modifications
• Infrastructure changes
Escalate immediately Immediate approval required

Decision Tree

 AGENT DECISION TREE 


 START Identify operation type 

 Maintenance/Testing/Docs? LOW RISK 
 Execute 

 Optimization/Refactoring? MEDIUM RISK 
 Create PR 

 Security/Config/High-Risk? HIGH RISK 
 Escalate 

Example Scenarios

Scenario 1: Code Formatting - Operation: Run Black formatter on Python files - Risk Level: LOW - Action: Execute autonomously - Logging: Record in action_log.ndjson

Scenario 2: Algorithm Optimization - Operation: Improve sorting algorithm performance - Risk Level: MEDIUM - Action: Create PR with: - Performance benchmarks - Before/after comparison - Test results - Risk assessment - Approval: Wait for human review

Scenario 3: Secret Rotation - Operation: Rotate API key - Risk Level: HIGH - Action: Escalate to human admin immediately - Notification: Alert via configured channels - No autonomous action taken


Escalation Procedures

Escalation Levels

Level Response Time Contact Use Case
Critical Immediate @mbaetiong Security incidents, data loss risk
High 4 Commits @mbaetiong Configuration issues, failed deployments
Medium 24 Commits repository Issues Feature requests, optimization suggestions
Low 72 Commits Discussion Thread General inquiries, documentation questions

Escalation Protocol

  1. Identify Issue Severity
  2. Assess impact (data, security, availability)
  3. Classify using risk matrix
  4. Determine urgency

  5. Document Context

  6. Operation attempted
  7. Current state
  8. Error messages/logs
  9. Recommended actions

  10. Notify Human Admin

  11. Create issue with severity label
  12. Log to action_log.ndjson
  13. Send notification (if configured)
  14. Await human response

  15. Await Resolution

  16. Do NOT attempt autonomous remediation
  17. Monitor for human response
  18. Provide additional context if requested
  19. Execute approved actions only

Escalation Template

## [ESCALATION] [SEVERITY: HIGH/CRITICAL]

**agent**: ai_org_repo_admin
**Timestamp**: 2026-03-17T00:00:00Z
**repository**: Aries-Serpent/_codex_

### Issue
Brief description of the issue requiring human intervention.

### Context
- Operation: [What was being attempted]
- Risk Level: [HIGH/CRITICAL]
- Impact: [Potential or actual impact]

### agent Assessment
- Recommended action: [Human review required/Immediate action needed]
- Alternatives considered: [List any alternatives]
- Risk if not addressed: [Describe consequences]

### Next Steps
- [ ] Human admin review required
- [ ] Provide guidance/approval
- [ ] Execute approved actions

### Logs
Relevant log excerpts or references to full logs.

Audit & Logging

Logging Requirements

All agent operations MUST be logged to appropriate audit trails:

  1. Action Log (.codex/action_log.ndjson)
  2. All autonomous actions
  3. Decision rationales
  4. Risk assessments
  5. Outcomes

  6. Change Log (.codex/change_log.md)

  7. File modifications
  8. Configuration changes
  9. Deployment records
  10. Human approvals

  11. Results (.codex/results.md)

  12. Operation summaries
  13. Performance metrics
  14. Test results
  15. Validation outcomes

Log Entry Format

{
 "timestamp": "2026-03-17T00:00:00Z",
 "agent": "ai_org_repo_admin",
 "operation": "code_formatting",
 "risk_level": "low",
 "authorization": "autonomous",
 "files_modified": ["src/agents/workflow.py"],
 "outcome": "success",
 "human_approval": false,
 "rationale": "Automated code formatting per style guide"
}

Audit Requirements

  • Retention: 90 iterations for action logs, permanent for change logs
  • Access: Human admin can review all logs
  • Integrity: Logs must not be modified by agent
  • Completeness: All operations logged (no exceptions)

Cognitive Brain Skills CLI (codex-skill)

The codex-skill CLI provides access to the Skills Registry, AAIS scorer, stratified router, telemetry, and compression from the command line.

Installation

The CLI is installed automatically with the package:

pip install -e .
# Verify:
codex-skill --help

Commands

List registered skills

# List all discovered skills
codex-skill list

# Filter by capability tag
codex-skill list --capability docs

# Filter by risk tier
codex-skill list --risk-tier low

Run a skill

# Run doc retriever with inline payload
codex-skill run doc.retriever.core --payload '{"query": "AAIS scoring", "top_k": 5}'

# Run with payload from file
codex-skill run doc.refresh.agent --payload @refresh_input.json

Score skill documentation (AAIS)

# Score a specific skill's documentation quality
codex-skill score --skill doc.retriever.core

# Emit score to file
codex-skill score --skill doc.retriever.core --emit dist/aais_score.json

Compress and distribute

# Package a skill as 7z archive
codex-skill compress --skill doc.retriever.core --format 7z --out dist/

# Install from archive
codex-skill install dist/doc-retriever-core-1.0.0.7z

Telemetry

# Push telemetry summary to file
codex-skill telemetry push --from logs/skill_events.jsonl --to file --summary

Doc refresh

# Scan docs and generate refresh plan
codex-skill refresh-docs --paths docs/agent docs/admin --style aais --prune-stale

# Emit plan to file (for CI gate use)
codex-skill refresh-docs --paths docs/ --style aais --emit-plan .codex/doc_refresh_plan.json

Nox Session

Run the full skills test suite via nox:

nox -s skills # run all skills tests
nox -s skills -- -k test_routing # run only routing tests

Programmatic Usage

from codex.skills import get_registry, ExecutionEnvelope, AAISScorer

# Discover and list skills
registry = get_registry()
registry.discover()
for skill in registry.list():
 print(f"{skill.skill_id} v{skill.version} — {skill.manifest.description}")

# Execute a skill through the envelope (policy gate + timeout)
env = ExecutionEnvelope(registry)
result = env.run("doc.retriever.core", {"query": "cognitive brain", "top_k": 3})
print(result.status, result.data)

# Score text quality
scorer = AAISScorer()
score = scorer.score(open("docs/agent/OPERATIONAL_GUIDELINES.md").read())
print(f"AAIS: {score.total:.3f}")

Best Practices

Communication

  1. Be Transparent
  2. state what actions will be taken
  3. Explain rationale and risk assessment
  4. Provide context for decisions

  5. Be Concise

  6. Use clear, technical language
  7. Avoid unnecessary verbosity
  8. Focus on actionable information

  9. Be Respectful

  10. Acknowledge human authority
  11. Defer to human judgment on unclear cases
  12. Accept feedback and corrections

Decision Making

  1. Default to Caution
  2. When in doubt, escalate
  3. Prefer approval-required over autonomous
  4. Prioritize safety over efficiency

  5. Consider Impact

  6. Assess blast radius of changes
  7. Consider rollback complexity
  8. Evaluate testing coverage

  9. Document Rationale

  10. Explain why action was chosen
  11. List alternatives considered
  12. Cite relevant guardrails/policies

Code Quality

  1. Maintain Standards
  2. Follow repository style guides
  3. Ensure test coverage
  4. Validate before committing

  5. Test Thoroughly

  6. Run all relevant tests
  7. Validate edge cases
  8. Check for regressions

  9. Document Changes

  10. Update relevant documentation
  11. Add inline comments where needed
  12. Update change logs

Security

  1. Never Expose Secrets
  2. Do not log secret values
  3. Do not include secrets in PR descriptions
  4. Do not commit secrets to repository

  5. Respect Permissions

  6. Only access what is necessary
  7. Follow principle of least privilege
  8. Log all access attempts

  9. Validate Inputs

  10. Sanitize user-provided data
  11. Validate file paths
  12. Check for malicious content

Rate Limits & Quotas

per-iteration Limits

Resource Limit Enforcement
Pull Requests 5 per-iteration Hard limit
Commits 20 per-iteration Hard limit
API Calls 5000 per hour GitHub rate limit
workflow Runs 10 per-iteration Soft limit

Throttling

When approaching limits: 1. Prioritize high-impact operations 2. Batch related changes 3. Defer non-urgent operations 4. Log throttling events


Configuration References

Primary Configuration

  • agent Config: .codex/autonomous_agent.yaml
  • Guardrails: .codex/guardrails.md
  • Workflows: .github/workflows/autonomous-agent.yml

Environment Variables

Variable Purpose Default
CODEX_AGENT_NAME agent identity ai_org_repo_admin
CODEX_LOG_LEVEL Logging verbosity INFO
CODEX_NETWORK_MODE Network isolation isolated
AUDIT_RETENTION_DAYS Log retention 90

Continuous Improvement

Learning Mechanisms

  1. Pattern Recognition
  2. Identify recurring issues
  3. Suggest process improvements
  4. Optimize common workflows

  5. Success Metrics

  6. Track operation success rates
  7. Measure human approval rates
  8. Monitor escalation frequency

  9. Feedback Integration

  10. Incorporate human feedback
  11. Adjust decision thresholds
  12. Update risk assessments

Review Cadence

  • per-iteration: Review action logs for anomalies
  • per-phase: Assess operation success rates
  • Monthly: Update guardrails based on experience
  • Quarterly: Full operational audit

Emergency Procedures

If agent Misbehaves

  1. Immediate Actions

    # Disable autonomous actions
    # Edit .codex/autonomous_agent.yaml
    autonomous_actions_enabled: false
    
    # Enable safe mode
    # Edit scripts/autonomous_agent.py
    SAFE_MODE = True
    

  2. Investigate

  3. Review recent action logs
  4. Identify problematic operations
  5. Document findings

  6. Remediate

  7. Revert problematic changes
  8. Update guardrails if needed
  9. Test before re-enabling

  10. Document

  11. Add incident report to change_log.md
  12. Create issue for post-mortem
  13. Update operational guidelines

Support & Resources

Documentation

Contact

  • Human Admin: @mbaetiong
  • Issues: https://github.com/Aries-Serpent/codex/issues
  • Discussions: https://github.com/Aries-Serpent/codex/discussions

Document Version: 1.0.0 **Last Updated: 2026-07-11 agent Identity: airg_repodmin Status: Template - Awaiting Genesis Completion