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

[DietrichGebert]

Thanks for putting this together. A lot of it leans on an outside evaluation and points people at an on-demand setup and a ponytail-playbook skill that do not match how ponytail actually works, so I would rather not ship it as official docs. Really appreciate the effort though.

[kevglynn]

Not gonna lie, this was an agent-gone-wild and shouldn't have made it to PR. Personal experiments in what I thought was an isolated env :-D SORRY!

I'm going to look over the other PRs to make sure nothing else rogue snuck in. Again... sorry!

[kevglynn]

For more context... I have used the concepts from ponytail to alter/update/tailor-fit some of my own skills, rules, plugins; hence the bleed-over.