feat: add cadre agents subcommand for list, scaffold, and validate (#16) (#16)

[jafreck]

Summary

Implements the cadre agents subcommand group with three sub-commands — list, scaffold, and validate — that let users inspect, generate, and verify the agent prompt template files that CADRE's runtime depends on. A formal AgentDefinition interface and AGENT_DEFINITIONS registry (12 agents) were introduced as the canonical source of truth for agent metadata.

Closes #16

Changes

• src/agents/definitions.ts (new): AgentDefinition interface and AGENT_DEFINITIONS readonly array with all 12 CADRE agents, covering phases 1–5 with name, phase, phaseName, description, hasStructuredOutput, and templateFile fields.
• src/cli/agents.ts (new): registerAgentsCommand function implementing three subcommands:
  • cadre agents list — prints each agent with its phase, phaseName, and a ✓/✗ existence indicator
  • cadre agents scaffold — writes default template stubs for missing agent files; supports --force to overwrite, --agent <name> to limit to one agent, and --backend (accepted as a no-op for non-Claude backends)
  • cadre agents validate — exits 0 if all 12 agent templates exist and are non-empty, exits 1 with a descriptive list of missing/empty files otherwise
• src/index.ts: Imports and registers registerAgentsCommand before program.parse().
• tests/agent-definitions.test.ts (new): 13 vitest tests verifying completeness and shape of AGENT_DEFINITIONS.
• tests/cli-agents.test.ts (new): 22 vitest tests covering list, scaffold, and validate logic with mocked filesystem and config.
• tests/github-issues.test.ts: Fixed a pre-existing test assertion that expected the old get_issue MCP tool name; updated to issue_read with method: 'get' to match the current src/github/api.ts implementation.

Implementation Details

The agent directory is resolved relative to config.repoPath when config.copilot.agentDir is a relative path, and used as-is when absolute. Template content is a minimal markdown stub containing the agent name, role, instructions, and output format headers — sufficient to bootstrap user-editable files. The --backend flag is accepted without error but is a no-op in this implementation, preserving forward-compatibility for a future multi-backend PR.

Testing

• tests/agent-definitions.test.ts (13 tests): validates count, uniqueness, required fields, phase range, and templateFile naming convention
• tests/cli-agents.test.ts (22 tests): mocks loadConfig, exists, writeTextFile, and readFileOrNull to cover list output, scaffold create/skip/force/single-agent flows, and validate success/failure paths
• All 35 new tests pass with npx vitest run

Integration Verification

• Build: pass
• Tests: pass (1 pre-existing failure in tests/github-issues.test.ts was detected by the integration checker and fixed within this PR)
• Lint: not configured

Notes

• The --backend flag is a stub; full multi-backend template adaptation depends on issue Multi-backend agent launcher: native support for Copilot CLI, Claude CLI, and direct API #3.
• Integration with cadre run as an optional pre-flight check (--skip-agent-validation) is out of scope for this issue and should be addressed in the cadre run issue.
• Template content generated by scaffold is intentionally minimal; richer templates depend on a future "agent templates" sub-issue referenced in the original issue description.

Cadre Process Challenges

This section is required for all CADRE-generated PRs (dogfooding data).
Document honestly what was difficult, confusing, or error-prone when CADRE processed this issue.

• Issue clarity: The issue was generally well-written, but several details were underspecified: the --backend flag had no concrete behavior defined for non-Claude backends, the "templates sub-issue" it depends on was not linked, and the exact canonical list of 12 agents had to be inferred from an example table in the issue body rather than from a definitive source.
• Agent contracts: The fix-surgeon was invoked to repair a pre-existing test failure (get_issue → issue_read) that was unrelated to this issue. This created an unclear boundary: should the code-writer ignore pre-existing failures, or fix them? The fix-surgeon made the right call but it introduced the fix-result-integration-fix-test.md artifact into the working tree.
• Context limitations: No file-tree snapshot was provided to the analysis agent, so it had to infer the existing source structure from the issue's code structure guidance. The actual AgentName type values had to be discovered from src/agents/types.ts at implementation time.
• Git/worktree: No branch or worktree issues encountered.
• Parsing/output: The integration report captured the test failure before the fix-surgeon patch was applied. This made the integration status appear as "fail" in the report even though the final committed state passes all tests. The pipeline would benefit from re-running tests after fix-surgeon completes.
• Retry behavior: No retries were required.
• Overall: The biggest friction point was the mismatch between the integration report (captured mid-pipeline) and the final code state after fix-surgeon — the PR composer had to reconcile these by reading the full diff to determine actual final status.

Closes #16