docs: add integration patterns guide and benchmark scope documentation

[kevglynn]

Summary

Two new documentation files based on findings from an independent evaluation:

• docs/integration-patterns.md — How to use ponytail as "one voice among many" in multi-agent workflows
• docs/benchmark-scope.md — Task-type dependency, model-specific cost behavior, and evaluation methodology

Motivation

Ponytail's README covers installation for 16+ hosts but not integration patterns for projects with existing review systems or test frameworks. The benchmark results are honest about limitations (issue #126 response, agentic limitations), but scope and model-specific behavior deserve dedicated documentation.

Key content

Integration patterns:

• On-demand profile (skills without SessionStart hooks)
• Anti-patterns: double injection, ultra as routine council member, standalone review as QA gate
• Multi-agent review integration: enhance existing lens, don't add a 4th

Benchmark scope:

• Over-build-trap wins vs irreducible CRUD convergence
• Claude-specific cost savings; OpenAI reasoning model cost increase (26-39%)
• Independent evaluation methodology and findings

Test plan

• npm test passes (1 pre-existing failure in csv correctness test, unrelated to docs)
• No changes to code or skills — docs only

Made with Cursor