Skip to content

RUNBOOK_AI.md

Latest commit

 

History

History
116 lines (77 loc) · 3.44 KB

RUNBOOK_AI.md

File metadata and controls

116 lines (77 loc) · 3.44 KB

AI Runbook — retort

Operational runbook for AI agent workflows. Covers common scenarios, troubleshooting, and recovery procedures.

Table of Contents

  1. Quick Reference
  2. Common Workflows
  3. Troubleshooting
  4. Recovery Procedures

Quick Reference

Command Purpose
retort sync Regenerate all AI tool configs from spec
retort validate Check config integrity and security
agentkit discover Scan repo and detect tech stacks
retort init Initialize a new repo overlay
/orchestrate Run multi-team coordination workflow
/check Run quality gates locally
/review Request code review from relevant teams

Common Workflows

First-time Setup

  1. Clone the repository
  2. Run retort init --repoName <name> to create overlay
  3. Edit .agentkit/overlays/<name>/settings.yaml as needed
  4. Run retort sync to generate all configs
  5. Commit the generated files

Adding a New Team Member (AI Agent)

  1. Add agent definition to .agentkit/spec/agents.yaml
  2. Run retort sync to regenerate agent files
  3. Verify with retort validate

Updating Permissions

  1. Edit .agentkit/overlays/<repo>/settings.yaml
  2. Add entries to permissions.allow or permissions.deny
  3. Run retort sync — deny entries always win over allow
  4. Verify with retort validate

Customizing Team Commands

  1. Edit .agentkit/overlays/<repo>/commands.yaml
  2. Add command overrides (merged at file level with base spec)
  3. Run retort sync

Troubleshooting

Sync produces unexpected output

  • Run DEBUG=1 retort sync for verbose logging
  • Check for unresolved placeholder warnings (mustache-style {{key}} tokens)
  • Verify overlay directory matches .agentkit-repo marker

Validate reports permission issues

  • Review settings.yaml — deny entries override all matching allow entries
  • Ensure no secrets appear in allow lists
  • Check that tool patterns match the expected format

Generated files show as modified after clean sync

  • This indicates drift — someone edited a generated file directly
  • Run retort sync to overwrite with canonical version
  • Commit the regenerated files

Hook scripts fail

  • Verify .sh scripts have executable permissions (chmod +x)
  • Check that the hook reads JSON from stdin correctly
  • Test with: echo '{"tool":"Write"}' | .claude/hooks/protect-sensitive.sh

Recovery Procedures

Restore from bad sync

Generated files include a backup-aware atomic write. If sync fails mid-write:

  1. Check for leftover .tmp/ directory in agentkit root
  2. If present, delete it: rm -rf .agentkit/.tmp
  3. Re-run retort sync

Reset to clean state

  1. Delete all generated files (those with GENERATED by Retort header)
  2. Run retort sync to regenerate everything
  3. Use git diff to verify the output

State file corruption

If .claude/state/orchestrator.json becomes corrupted:

  1. Delete the file
  2. The orchestrator will recreate it on next /orchestrate invocation
  3. Active session data will be lost — check git history for recovery

This runbook is maintained by Retort. Run pnpm --dir .agentkit retort:sync to regenerate.