agent-workflows AGENTS.md

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work
bd dolt push          # Push beads data to remote

ZFC Enforcement

This project is AI-orchestration code. Apply Zero Framework Cognition at two levels:

1. L2 (tooling): workflow skills must not use heuristics for semantic judgment
2. L3 (product): patterns embedded in workflow outputs shape how users approach their own AI-mediated work

Review checklist for agents

When reviewing or writing workflow skills, flag:

• Synthesis phases that use scoring formulas instead of model judgment
• Hardcoded classification of agent outputs (keyword matching for "done"/"failed")
• Winner selection via metric formula instead of model comparison
• Any code that makes a quality or relevance judgment without a model call

Ask: "Is this a mechanical/structural operation, or is it making a judgment a model should make?"

Compliant patterns to preserve

• Spawn independent agents → model synthesizes (core architecture)
• Convergence/divergence as signal, not as scored metric
• Agents provide semantic inputs (severity, likelihood), math is mechanical

Justified exceptions

• brainstorm/scripts/similarity.py — calibrated duplicate detection with --force escape hatch
• Risk Score multiplication — deterministic math on agent-provided semantic inputs
• Task readiness via bd ready — pure status-field logic

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest