claude-engineering-plugin/docs/plans/2026-03-30-001-feat-cli-readiness-review-persona-plan.md

title, type, status, date, origin

title	type	status	date	origin
feat: Add CLI agent-readiness conditional persona to ce:review	feat	active	2026-03-30	docs/brainstorms/2026-03-30-cli-readiness-review-persona-requirements.md

Add CLI Agent-Readiness Conditional Persona to ce:review

Overview

Create a lightweight review persona that evaluates CLI code for agent readiness during ce:review. The persona distills the standalone cli-agent-readiness-reviewer agent's 7 principles into a compact, diff-focused reviewer that produces structured JSON findings -- matching the pattern of every other conditional persona (security-reviewer, performance-reviewer, etc.).

Problem Frame

The cli-agent-readiness-reviewer agent exists but only fires when someone knows to invoke it. CLI code that passes through ce:review gets no agent-readiness feedback. Adding a conditional persona makes this automatic. (see origin: docs/brainstorms/2026-03-30-cli-readiness-review-persona-requirements.md)

Requirements Trace

• R1. Conditional selection by orchestrator based on diff analysis
• R2. Activation on CLI command definitions, argument parsing, CLI framework usage
• R3. Non-overlapping scope with agent-native-reviewer
• R4. Self-scoping: framework detection and command identification from diff
• R5. Standard JSON findings schema output
• R6. Severity mapping: Blocker->P1, Friction->P2, Optimization->P3 (never P0 -- CLI readiness issues don't crash or corrupt)
• R7. Autofix class: manual or advisory with owner human
• R8. Framework-idiomatic recommendations in suggested_fix
• R9. New persona agent file + persona catalog entry
• R10. Standalone agent unchanged

Scope Boundaries

• Does not modify the standalone cli-agent-readiness-reviewer agent
• Does not add CLI awareness to ce:brainstorm or ce:plan
• Does not introduce autofix for CLI readiness findings

Context & Research

Relevant Code and Patterns

• Persona agent pattern: plugins/compound-engineering/agents/review/ce-security-reviewer.agent.md (3.4 KB), performance-reviewer.md (3.0 KB) -- exact structure to follow
• Persona catalog: plugins/compound-engineering/skills/ce-review/references/persona-catalog.md -- cross-cutting conditional section
• Subagent template: plugins/compound-engineering/skills/ce-review/references/subagent-template.md -- provides output schema, scope rules, PR context (persona does not need to include these)
• Standalone agent: plugins/compound-engineering/agents/review/ce-cli-agent-readiness-reviewer.agent.md (24.3 KB) -- source of the 7 principles to distill
• Agent-native-reviewer: plugins/compound-engineering/agents/review/ce-agent-native-reviewer.agent.md -- non-overlapping domain reference

Institutional Learnings

• Conditional personas are 3.0-5.7 KB with a fixed structure: frontmatter, identity paragraph, hunting patterns, confidence calibration, suppress list, output format
• The subagent template injects the findings schema, scope rules, and PR context -- the persona file only needs domain-specific content
• Activation is orchestrator judgment (not keyword matching) -- the catalog describes the conceptual domain

Key Technical Decisions

• Distill, don't reproduce: The 7 principles become ~8 hunting pattern bullets. No Framework Idioms Reference in the persona -- the model uses its general knowledge of detected frameworks for suggested_fix specificity. Keeps the persona under 5 KB. (see origin: Key Decisions -- "New persona agent file")
• All 7 principles, weighted by command type: Evaluate all principles on every dispatch, but include a condensed command-type priority table so the persona weights findings appropriately (e.g., structured output matters most for read/query commands, idempotency matters most for mutating commands). Cap at ~5-7 findings to avoid flooding. (Resolves deferred question from origin)
• Severity ceiling is P1: CLI readiness issues never reach P0. Blocker->P1, Friction->P2, Optimization->P3. (see origin: Key Decisions)
• No autofix: All findings use manual or advisory autofix_class with human owner. CLI readiness findings require design judgment. (see origin: Key Decisions)
• Framework detection as a behavior instruction: Rather than embedding framework-specific patterns, instruct the persona to "detect the CLI framework from imports in the diff and provide framework-idiomatic recommendations in suggested_fix." This keeps the file small while satisfying R8.

Open Questions

Resolved During Planning

• How much content from the standalone agent? Distill the 7 principles into hunting pattern bullets (~1 sentence each). Include a condensed command-type priority table. No Framework Idioms Reference, no step-by-step methodology, no examples section. Target ~4 KB.
• All principles or prioritize? All 7, weighted by command type. The persona detects command types from the diff and adjusts which principles get the most attention. Cap at 5-7 findings per review.

Deferred to Implementation

• Exact wording of hunting pattern bullets -- will be refined when writing the agent file, using the standalone agent's principle descriptions as source material

Implementation Units

• Unit 1: Create the persona agent file

Goal: Create cli-readiness-reviewer.md in the review agents directory, following the exact structure of existing conditional personas.

Requirements: R4, R5, R6, R7, R8

Dependencies: None

Files:

• Create: plugins/compound-engineering/agents/review/ce-cli-readiness-reviewer.agent.md

Approach:

• Follow the exact structure of security-reviewer.md and performance-reviewer.md: frontmatter, identity paragraph, hunting patterns, confidence calibration, suppress list, output format
• Frontmatter: name: cli-readiness-reviewer, description in the standard conditional persona format, model: inherit, tools: Read, Grep, Glob, Bash, color: blue
• Identity paragraph: establishes the persona's lens -- evaluating CLI code for how well it serves autonomous agents, not just human users
• "What you're hunting for" section: distill the 7 principles into ~8 bullets. Each bullet names the issue pattern and why it matters for agents. Include a condensed command-type priority note
• "Confidence calibration": high (0.80+) for issues directly visible in the diff (missing --json flag, prompt without bypass); moderate (0.60-0.79) for issues that depend on context beyond the diff (whether other commands already have structured output); low (<0.60) suppress
• "What you don't flag": agent-native parity concerns (that's agent-native-reviewer's domain), non-CLI code, framework choice itself, test files, documentation-only changes
• "Output format": standard JSON template with severity capped at P1, autofix_class restricted to manual/advisory, owner always human
• Include severity mapping guidance: Blocker->P1, Friction->P2, Optimization->P3
• Include framework detection instruction: "Detect the CLI framework from imports in the diff. Reference framework-idiomatic patterns in suggested_fix (e.g., Click decorators, Cobra persistent flags, clap derive macros)."

Patterns to follow:

• plugins/compound-engineering/agents/review/ce-security-reviewer.agent.md -- structure, sections, size
• plugins/compound-engineering/agents/review/ce-performance-reviewer.agent.md -- structure, brevity
• plugins/compound-engineering/agents/review/ce-cli-agent-readiness-reviewer.agent.md -- source of the 7 principles to distill (Principles 1-7, lines 94-252)

Test scenarios:

• Happy path: persona file parses valid YAML frontmatter with all required fields (name, description, model, tools, color)
• Happy path: persona content follows the 6-section structure (identity, hunting patterns, calibration, suppress, output format)
• Edge case: persona file size is within the 3-5.7 KB range of existing personas (not bloated with framework reference material)

Verification:

• File exists at the expected path with valid frontmatter
• File follows the exact 6-section structure of existing conditional personas
• File size is under 6 KB
• All 7 CLI readiness principles are represented in hunting patterns
• Severity guidance caps at P1
• Autofix class restricted to manual/advisory
• No Framework Idioms Reference reproduced from the standalone agent

---

• Unit 2: Add persona to the catalog

Goal: Register the new persona in the ce:review persona catalog so the orchestrator knows when to dispatch it.

Requirements: R1, R2, R3, R9

Dependencies: Unit 1

Files:

• Modify: plugins/compound-engineering/skills/ce-review/references/persona-catalog.md
• Modify: plugins/compound-engineering/README.md

Approach:

• Add a row in the cross-cutting conditional personas table
• Persona name: cli-readiness
• Agent reference: compound-engineering:review:cli-readiness-reviewer
• Activation: "CLI command definitions, argument parsing, CLI framework usage, command handler implementations"
• Use domain description style (not framework names) consistent with other conditional personas
• Place after the existing conditional personas, before the stack-specific section
• Update the persona catalog section header from "Conditional (7 personas)" to "Conditional (8 personas)"
• Update the total persona count from 16 to 17 in persona-catalog.md header and ce-review SKILL.md
• Add cli-readiness-reviewer to the Review agents table in plugins/compound-engineering/README.md and verify the agent count

Patterns to follow:

• Existing conditional persona entries in persona-catalog.md (security, performance, api-contract, etc.)

Test scenarios:

• Happy path: bun test passes (no frontmatter or parsing regressions)
• Happy path: catalog entry follows the same column format as other conditional personas
• Edge case: activation description uses domain language, not specific framework names

Verification:

• The catalog has a new row for cli-readiness in the cross-cutting conditional section
• The agent reference uses the fully-qualified namespace
• The activation description is domain-level, not keyword-level

System-Wide Impact

• Interaction graph: ce:review's orchestrator reads the diff, decides to dispatch cli-readiness-reviewer alongside other conditional personas. Findings flow through the standard merge/dedup pipeline (Stage 5) into the review report
• API surface parity: agent-native-reviewer covers UI/agent parity; cli-readiness-reviewer covers CLI agent-friendliness. Both may activate on the same diff -- their findings are complementary and handled by ce:review's existing dedup fingerprinting
• Unchanged invariants: The standalone cli-agent-readiness-reviewer agent is untouched. Direct invocations continue to work exactly as before

Risks & Dependencies

Risk	Mitigation
Persona too large if principles aren't distilled enough	Target 4 KB, use security-reviewer as size benchmark. If over 6 KB, trim framework guidance
Persona findings flood the review with low-signal items	Cap at 5-7 findings via confidence calibration. Optimization-level items get P3 severity (user's discretion)

Sources & References

• Origin document: docs/brainstorms/2026-03-30-cli-readiness-review-persona-requirements.md
• Related code: plugins/compound-engineering/agents/review/ce-security-reviewer.agent.md, performance-reviewer.md
• Related code: plugins/compound-engineering/agents/review/ce-cli-agent-readiness-reviewer.agent.md (source of 7 principles)
• Related code: plugins/compound-engineering/skills/ce-review/references/persona-catalog.md