feat(agents): new agent templates, behaviors, and issue-creator guidance

[nsheaps]

Summary

Refreshed 2026-05-28 by Alex — original branch was 3+ months stale and conflicted on 162 commits worth of root-repo refactor. Strategy: reset onto origin/main, cherry-pick only the substantive commits, drop superseded ones.

KEEP (6 commits, 9 content files modified/added + ~89 pr-reviews deleted):

• 42d5f01 docs(agents): add github-issue-creator guidance to 5 agent definitions
• 13223a0 feat(agents): add technical-project-manager (Porky Pig) and product-manager (Pepé Le Pew)
• f46d68d docs: add version-prompt-tracking behavior
• d04653e fix(agents): address P2 findings in PM/TPM templates (QA 92/100)
• df2b862 delete .claude/pr-reviews/ cruft
• ff84aca style: prettier-format on version-prompt-tracking
• f595310 fix(behaviors): remove hardcoded /Users/... path + correct cchistory reference to docs/research/cchistory.md

DROP (commits superseded by main):

• 6203bcf fix(ci): skip non-shell files — superseded; bin/* shell-lint step no longer exists, mise run format replaced it
• fbd01cd chore: add agent-config utility scripts — would clobber current agent files
• c65a335 style: format markdown — superseded by re-running mise run format on the new tree

Triage Detail

Full report at [docs/research/](attached separately to Alex's session) — KEEP/MOVE/DROP per file, conflict resolution log, convention fixes applied.

Test Plan

• Verify agent definitions load correctly in Claude Code
• Confirm product-manager.md and technical-project-manager.md match templates/teams/looney-toons/personas/ conventions (file lives in .claude/agents/, not the looney-toons template — confirm intent)
• Validate version-prompt-tracking.md is correctly referenced from skill docs

Open Questions

1. version-prompt-tracking.md hardcodes /Users/nathan.heaps/src/nsheaps/agent-team and references .claude/skills/cchistory.md which actually lives at docs/research/cchistory.md on main. Resolved in f595310 (2026-05-28) per Nate's direction.
2. technical-project-manager.md sits alongside existing project-manager.md — both coexist as complementary roles per the original PR description. Confirm that's the intent.
3. STRIKE-ONE: not merging without explicit ack.

🤖 Refreshed with Claude Code (Alex)

[nsheaps]

QA Review: 91/100 ✅ — Ready to merge

Reviewer: Daffy D (qa)

Scope

This PR adds:

• 2 new agent templates: technical-project-manager.md (Porky Pig), product-manager.md (Pepé Le Pew)
• github-issue-creator guidance to 5 existing agents (ai-agent-eng, ops-eng, project-manager, quality-assurance, software-eng)
• 1 new behavior: version-prompt-tracking.md for AI Agent Eng

Category Scores

Category	Score	Status
Simplicity	92	✅
Flexibility	88	✅
Usability	90	✅
Documentation	92	✅
Security	90	✅
Pattern Matching	92	✅
Best Practices	90	✅
General QA	88	✅

Findings

qa-1 (P3): github-issue-creator guidance incomplete — 5 of 10 existing agents missing

Team rule #11 states "All teammates must file GitHub issues through the github-issue-creator sub-agent." The PR adds guidance to 5 agents but does not add it to: deep-researcher, designer, docs-writer, exec-assist, orchestrator. At minimum, docs-writer (may discover documentation gaps worth tracking) and orchestrator (coordinates issue creation) should have it. Non-blocking — can be a follow-up.

qa-2 (P3): version-prompt-tracking.md hardcodes absolute path

File: .claude/behaviors/version-prompt-tracking.md:408-409

The behavior hardcodes /Users/nathan.heaps/src/nsheaps/agent-team as the working directory for cchistory. This breaks portability if the repo is cloned elsewhere. Should use a relative reference or $PWD.

qa-3 (P4): Relative path in behavior references

File: .claude/behaviors/version-prompt-tracking.md:447

The reference ./../skills/cchistory.md works from .claude/behaviors/ but the .. prefix is fragile if the file is moved. Minor — informational only.

qa-4 (P4): Product PM uses "PRD" as primary term

File: product-manager.md:122

Project conventions use "spec" as the unified term. The product PM section header says "Writing a PRD / Spec" and uses "PRD" throughout. Not blocking but creates minor terminology inconsistency with other agents who use "spec" exclusively.

Verified Correct

New agent templates:

• Frontmatter format matches all existing agents (name, description with 3 examples, color, prompt_mode, base_prompt, framework, model, permission_mode, display_name, tools, disallowed_tools)
• product-manager.md color: indigo — unique, no conflict with existing agents
• technical-project-manager.md color: cyan — unique
• Display names follow "First L (role)" pattern: Porky P (tpm), Pepé L (product-mgr)
• Tool lists appropriate: TPM is read-only + tasks + messaging; Product PM has Write/Edit for spec authoring + tasks
• Both have disallowed_tools blocks (TPM: Edit/Write/Bash; Product PM: Bash)
• Both have <system-message> block, Persona reference, Session Start, References, Edge Cases
• Role differentiation clear: PM (task list) vs TPM (technical roadmap) vs Product PM (what to build and why) — no overlap
• Both reference github-issue-creator in Quality Standards
• SendMessage silent success warning present in TPM edge cases

github-issue-creator additions:

• Consistent wording pattern across all 5 agents: "consider using the github-issue-creator sub-agent to file them as GitHub issues rather than running gh issue create directly"
• Placement is contextually appropriate: in Quality Standards for most, in Filing Issues subsection for project-manager

version-prompt-tracking behavior:

• Well-structured: trigger conditions, process steps, output locations, rationale
• References cchistory skill and research docs
• Diff output correctly goes to .claude/tmp/ (disposable)
• Analysis output correctly goes to docs/research/ (permanent)

Summary

Clean PR. Two new agent templates are well-crafted with clear role boundaries. The github-issue-creator guidance is a good standardization pass. The version-prompt-tracking behavior formalizes an existing informal process. P3 findings are non-blocking follow-ups.

Ready to merge.