Add stack-agnostic project workflow agents: architect, planner, reviewer

[brs191]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services. (N/A — no paid services)
• My contribution adds a new agent file in the correct directory (agents/).
• The file follows the required naming convention (lowercase-with-hyphens .agent.md).
• The content is clearly structured and follows the example format.
• I have tested my agents with GitHub Copilot.
• I have run npm start and verified that README.md (docs/README.agents.md) is up to date.
• I am targeting the staged branch for this pull request.

Description

Three stack-agnostic agents that compose into a delivery workflow:

• Project Architect — system design, decomposition, ADRs, technology selection, brownfield evolution
• Project Planner — scoping, estimation, critical path, risk registers, replanning
• Project Reviewer — PR review, anti-pattern detection, security review, quality gates

Each encodes a decision discipline, not just a persona:

• Architect — "decompose at the force, not the noun," plus a modular-monolith-first gate (< 4 bounded contexts / < 3 teams / < 10K RPM).
• Planner — "the critical path governs the date, not the effort sum"; estimates are ranges with a stated basis.
• Reviewer — "every finding has a severity and a reason"; never cites a file:line it didn't inspect, and doesn't invent CVEs.

Not a duplicate of existing agents:

• Project Architect — project-architecture-planner is cloud-agnostic but bundles architecture + scalability roadmaps + cost analysis + diagram generation; arch and principal-software-engineer give general guidance. This agent is design-only — force-based decomposition, modular-monolith-first gate, brownfield migration paths — and hands planning and review to the other two.
• Project Planner — planner, task-planner, gem-planner, and implementation-plan are implementation planners (feature → coding steps). This is the only delivery planner: estimate ranges with a basis, critical-path-driven dates, plan-vs-commit-date split, a risk register, and replan/recovery triggers.
• Project Reviewer — gem-reviewer and wg-code-sentinel are security-focused. This adds a severity+evidence discipline (HARD/SOFT/NOTE) with stack-agnostic fast-grep signals across Go/Java/Python/TS.

Workflow: handoffs wire architect ⇄ planner, with a reviewer → architect escalation (VS Code only; on github.com the field is ignored, so each agent states the recommendation and the prompt to paste).

Type of Contribution

• New agent file.

Additional Notes

• AI-authored — 🤖🤖🤖 is in the PR title for fast-track per CONTRIBUTING.
• Frontmatter: each agent has a single-quoted description, name, model, tools, and a VS Code handoffs block. docs/README.agents.md regenerated via npm start; files are LF.
• Testing: Tested in VS Code with each agent's example prompts.

[github-actions]

🔍 Skill Validator Results

✅ All checks passed

Scope	Checked
Skills	0
Agents	3
Total	3

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	Found 3 agent(s)
ℹ️	Validated 3 agent(s)
ℹ️	✅ All checks passed (3 agent(s))

Full validator output

Found 3 agent(s)
Validated 3 agent(s)

✅ All checks passed (3 agent(s))

[brs191]

Note: The validator returned a non-zero exit code. Please review the findings above before merge.

The Skill Validator flagged the name field on all three agents (expects lowercase-hyphen matching the filename). That's the SKILL.md naming rule — for .agent.md files, instructions/agents.instructions.md specifies a human-readable display name, and every existing agent follows it (e.g. api-architect.agent.md → name: 'API Architect', project-architecture-planner.agent.md → name: 'Project Architecture Planner'). I kept that convention for consistency with the catalog and the rendered agents table. Happy to switch all three to lowercase (project-architect, etc.) if you'd prefer the validator clean — just say the word.

[aaronpowell]

GitHub Copilot already contains both a plan mode and rubber duck agent (reviewer) - how do you see these agents comparing against the built-in, and what features are the built-in's lacking that these agents are addressing?

[brs191]

GitHub Copilot already contains both a plan mode and rubber duck agent (reviewer) - how do you see these agents comparing against the built-in, and what features are the built-in's lacking that these agents are addressing?

These don't compete with the built-ins — they operate at a higher altitude and ship as portable files. Side by side:

	Built-in	This agent
Plan mode → Planner	Implementation planning: breaks a task into coding steps, refines as it codes. In-session, ephemeral.	Delivery planning: estimate ranges with a basis, critical-path-driven date, plan-date vs. commit-date split, risk register, replan triggers.
Rubber Duck → Reviewer	Inward self-critique: the agent calls a cross-family model mid-loop to improve its own work. Unstructured, behind /experimental.	Outward PR review for a human merge decision: graded findings (HARD/SOFT/NOTE) with evidence rules + stack-agnostic grep signals.

What the built-ins don't do, that these add:

1. Planning that produces a commitment, not a task list. Plan mode tells the agent how to build; it doesn't estimate, model a critical path, or track risk. Planner answers when can we commit and what could derail it — the project-management layer above the code.

2. Review you can trust and act on. Rubber Duck's critique is unstructured and tied to the live agent loop. Reviewer enforces a discipline a human reviewer can rely on: every finding has a severity and a reason, it never cites a file:line it didn't inspect, it won't invent CVEs, and it runs the same grep signals across Go/Java/Python/TS. You can point it at any diff and paste the output into a thread.

3. Portability + composition. Plain .agent.md that run on github.com, VS Code, and CLI — not gated behind experimental mode or a specific model picker — and wired as a workflow (architect ⇄ planner ⇄ reviewer) rather than separate modes.

Bottom line: complementary, not redundant. You could run Rubber Duck inside a session that's following these agents.