Skip to content

AGENT_FRIENDLINESS_REPORT.md

Latest commit

 

History

History
134 lines (101 loc) · 4.44 KB

AGENT_FRIENDLINESS_REPORT.md

File metadata and controls

134 lines (101 loc) · 4.44 KB
Raw

Agent-Friendliness Report: Process Triage (pt)

Bead ID: bd-2r7 Date: 2026-01-25 Agent: Claude Opus 4.5

Executive Summary

Status: HIGH AGENT-FRIENDLINESS MATURITY

Process Triage (pt) is exceptionally well-optimized for AI coding agent usage:

  • TOON output fully integrated (--format toon)
  • Comprehensive JSON output with multiple format options
  • Token-efficient output with field selection and max-token budgets
  • Extensive robot/agent mode support

1. Current State Assessment

1.1 Robot Mode Support

Feature Status Details
--format flag YES json, toon, md, jsonl, summary, metrics, slack, exitcode, prose
--robot flag YES Non-interactive mode for automation
--json flag YES Alias for --format json
PT_OUTPUT_FORMAT env YES Set default format via environment
--fields flag YES Select specific output fields
--compact flag YES Enable minified output
--max-tokens flag YES Limit output token budget
--estimate-tokens flag YES Get token count without full output

1.2 Output Formats

Format Description
json Token-efficient structured JSON (default)
toon Token-Optimized Object Notation
md Human-readable Markdown
jsonl Streaming JSON Lines for progress
summary One-line summary for quick checks
metrics Key=value pairs for monitoring
slack Human-friendly narrative
exitcode Minimal output (exit code only)
prose Natural language for agent-to-user

1.3 Commands with JSON/TOON Support

Command JSON TOON Notes
pt-core agent plan YES YES Full Bayesian inference plan
pt-core agent explain YES YES Evidence breakdown per-process
pt-core agent apply YES YES Action execution results
pt-core agent capabilities YES YES System capabilities
pt-core agent sessions YES YES Session history
pt-core config show YES YES Configuration values
pt-core signature list YES YES Process signatures
pt-core signature stats YES YES Match statistics

1.4 Token-Efficient Output Pipeline

The TokenEfficientOutput system provides:

--fields minimal|standard|full     // Select output fields
--compact                          // Short keys, minified JSON
--max-tokens N                     // Token budget with truncation
--estimate-tokens                  // Get token estimate

This is highly advanced agent-friendly output control.

2. Documentation Assessment

2.1 AGENTS.md

Status: EXISTS and comprehensive (548 lines)

Contains:

  • Multi-agent coordination guidelines
  • Beads/bv/br workflow instructions
  • MCP Agent Mail integration
  • Exit code semantics
  • UBS integration

2.2 Robot Mode Documentation

Documented extensively in --help output and source code.

3. Scorecard

Dimension Score (1-5) Notes
Documentation 5 Comprehensive AGENTS.md
CLI Ergonomics 5 Excellent subcommand structure
Robot Mode 5 --format, --robot, --fields, --max-tokens
Error Handling 4 Structured errors with categories
Consistency 5 OutputFormat enum standardized
Zero-shot Usability 4 Good --help, needs QUICKSTART
Overall 4.7 Excellent maturity

4. TOON Integration Status

Status: FULLY INTEGRATED

TOON is available via:

  • --format toon flag
  • toon_rust = { path = "../toon_rust" } workspace dependency
  • OutputFormat::Toon enum variant in pt_common
  • encode_toon_value() function in pt_core::output

5. Recommendations

5.1 High Priority (P1)

None - pt is already highly agent-friendly

5.2 Medium Priority (P2)

  1. Add docs/agent/QUICKSTART.md for 30-second onboarding
  2. Add --schema flag for JSON Schema emission

5.3 Low Priority (P3)

  1. Consider adding --capabilities command
  2. Document error taxonomy formally

6. Conclusion

Process Triage (pt) is among the most agent-friendly tools in the suite with:

  • Full TOON integration
  • Advanced token-efficient output system
  • Comprehensive robot mode support
  • Excellent documentation

Score: 4.7/5 - Excellent maturity, minimal improvements needed.

Generated by Claude Opus 4.5 during bd-2r7 execution