Context: Agent-Safe CLI Fallbacks in /Users/pfleidi/entire/cli

Goal: Add guidance so future CLI features and code reviews catch commands whose useful output is only reachable through a TUI, terminal selector, wizard, confirmation dialog, or stdin question. Plain text output is acceptable; the problem is requiring an interactive terminal to reach the useful information.

Full instructions to add to README.md / AGENTS.md:

Agent-Safe CLI Fallbacks

When building CLI features, do not make useful output available only through a TUI, picker, wizard, terminal selection menu, confirmation dialog, or stdin question. Agents must be able to complete the same read-only workflow from a non-interactive terminal.

Plain text output is acceptable when it contains the full information needed for the workflow. JSON is preferred for structured data, following existing patterns such as --json on status, agent-help, sessions, search, and trail finding commands. Long human-readable output may use a pager in TTY mode, but must provide a bypass like the existing --no-pager pattern on explain.

For interactive browsing flows, provide one of these non-interactive shapes:

• a list command that prints stable identifiers, plus a show/detail command that accepts an identifier
• a flag or positional argument that selects the item directly
• a complete text or JSON fallback when stdout is not a terminal, like existing static/text fallbacks for TUI-backed commands

When reviewing CLI changes, inspect terminal-gated paths such as IsTerminalWriter, CanPromptInteractively, Bubble Tea, huh, direct stdin reads, terminal selection menus, confirmation dialogs, and wizard flows. Flag the change if a non-interactive agent can only see a menu, preview, truncated summary, or cannot select the item whose details matter.

Tests for interactive CLI features should cover the non-interactive path. Prefer the repo's existing subprocess pattern, execx.NonInteractive, when testing a real entire command.

Existing good patterns:

• entire investigate --findings prints a complete plain-text list and includes view: entire investigate show <run-id> hints.
• entire investigate show <run-id> prints the saved investigation summary and findings without needing a TUI.
• entire repo clone /gh/... prompts only when several clusters are possible; without a TTY it asks for --cluster.
• entire experts --tui is safe because the TUI is opt-in and non-TTY output falls back to deterministic plain text.
• entire explain --no-pager is the local pattern for avoiding pager-only long text output.
• entire status --json, entire agent-help --json, entire sessions list --json, and trail finding commands show the local --json convention.

Low-hanging code issues found:

1. cmd/entire/cli/review/fix.go

   • runReviewFindings opens an interactive picker in TTY mode.
   • Non-TTY fallback calls printReviewFindingsList, which only prints labels and truncated previews.
   • Agents can discover that findings exist but cannot get the full findings body.
   • Suggested fix: mirror the investigate shape. Print stable handles and a view: command, and add a non-interactive detail path that accepts a handle or session id.

2. cmd/entire/cli/rewind.go

   • Bare entire rewind opens an interactive checkpoint selector.
   • The pieces already exist: --list prints JSON and --to <id> selects a target non-interactively.
   • Suggested fix: if no flags are passed and there is no interactive terminal, print guidance or run the list view: entire rewind --list, then entire rewind --to <id>.

3. cmd/entire/cli/sessions.go

   • Bare entire sessions stop opens a multi-select when multiple sessions are active.
   • Explicit forms exist: <session-id>, --all, and --force.
   • Suggested fix: in non-TTY mode, refuse with active session IDs and tell the caller to pass <session-id> or --all --force.

4. cmd/entire/cli/clean.go

   • clean has good explicit controls: --dry-run, --force, --session, and --all.
   • Confirmation forms are opened without an obvious non-TTY guard.
   • Suggested fix: non-TTY without --force should refuse after printing the preview, with guidance to rerun --dry-run or --force.

Important nuance: Do not require JSON everywhere. Human-readable text is fine if it contains the complete information an agent needs. The failure mode is requiring an interactive terminal to select something or reveal details.

Let's apply both and see what's flagged in reviews.

Can you ask me the same question again? I wanted to submit something else and didn't get a good look at the options

Conitnue

Can you commit the changes separately?

Base directory for this skill: /Users/pfleidi/.agents/skills/pfleidi/skills/review

Code Review

1. Determine Diff Against origin/main

Always review changes against origin/main directly. Do not use local main, git merge-base, a PR base branch, or a user-specified alternate base.

Get the CURRENT diff — never use cached results from earlier in the conversation. Include both committed and uncommitted changes (staged + unstaged):

Note: git diff origin/main (not origin/main...HEAD) diffs origin/main against the working tree, capturing committed changes, staged changes, and unstaged changes in one pass.

Show the user the file list and total count. If there are 0 changed files, report that to the user and stop — there is nothing to review. Otherwise, immediately proceed to the review agents. Do NOT wait for confirmation.

Before launching agents, build a concise review context and pass it to every agent. Show the context as a table before launching agents so assumptions are visible:

• The user's request and any implementation plan, design notes, or acceptance criteria provided in the conversation.
• Branch commit messages from git log --oneline origin/main..HEAD.
• PR title/body when a PR exists for the branch.
• The changed-file list and any obvious intended behavior changes inferred from commits, tests, docs, or user-facing text.

Treat this context as the statement of intent. If no implementation plan or PR context exists, say that intent is inferred from the diff and commits only.

2. Spawn Parallel Review Agents

Review Philosophy

Pass these rules to every agent:

• It is OK to find nothing. A clean review is a valid outcome. Do NOT manufacture findings to justify the review. Only flag issues you are confident are real problems.
• Be opinionated and consistent. If a pattern is acceptable, don't flag it. If you flag something, commit to that position — don't suggest the opposite approach on a re-review.
• Don't flag trade-offs with no clear winner. If there are two reasonable approaches and neither is clearly better, don't flag it. The author already made a choice.
• High confidence only. Every finding must pass the bar: "I am confident this is a problem, and I can explain specifically what goes wrong if it's not fixed." Vague unease is not a finding.
• Permission-friendly reads. Avoid shell pipelines, command separators, subshells, and output filters for read-only investigation because they create extra permission prompts and block background review agents. Do not run commands like git show HEAD:path | sed -n '10,40p'. Use workspace file range reads, rg with path limits, path-scoped git diff $BASE -- <path>, or one standalone git show <rev>:<path> only when the output is acceptably small.
• Intent-aware review. Review changed code against the review context, not against the old behavior alone. Do not classify an intentional behavior change as Required merely because it differs from origin/main. A Required finding must either contradict stated intent, break an existing contract that the intent did not change, introduce a concrete bug/security issue, or leave the intended behavior unverified in a way that would likely fail.

Launch four baseline sub-agents in parallel using the Agent tool. Pass each agent origin/main as the base ref, the full list of changed files, the review context, and the review philosophy above.

When the repository is a Go project and the diff includes Go-related files (*.go, go.mod, or go.sum), also launch Agent 5 in the same batch. Do not run the Go-specific agent for non-Go diffs.

Agent 1: Security & Adversarial

Review git diff $BASE with fresh eyes for:

• Injection — command injection, SQL injection, path traversal
• TOCTOU and race conditions — check-then-act patterns, concurrent access without synchronization
• Unvalidated input at system boundaries — user input, API parameters, external data
• Auth/authz gaps — missing permission checks, privilege escalation paths
• Secrets or credentials — hardcoded tokens, leaked keys, credentials in code or config

For EACH finding: read the actual source file and trace whether the code path is reachable in production. Discard any finding you cannot confirm with a concrete code reference.

Agent 2: Correctness & Quality

Review git diff $BASE for:

• Logic errors — off-by-one, wrong comparison, inverted conditions
• Nil/null handling — unchecked nil dereferences, missing error checks (especially unchecked errors in Go)
• Edge cases in concurrency — goroutine leaks, missing locks, channel misuse, deferred unlock ordering
• Redundant state — state that duplicates existing state, cached values that could be derived
• Production test seams — mutable function variables, package-wide settings, reset hooks, or exported knobs added only so tests can swap behavior instead of using dependency injection or a higher-scope test
• Parameter sprawl — adding new parameters instead of restructuring
• Leaky abstractions — exposing internal details, breaking existing abstraction boundaries
• Stringly-typed code — using raw strings where constants or typed values already exist in the codebase
• Test coverage and scope gaps — changed behavior, edge cases, or error paths not exercised by meaningful tests; tests that prove implementation details instead of behavior; or unit tests used where integration/e2e coverage is the right confidence boundary
• Test helper over-abstraction — helpers that hide the behavior, expected values, or assertions and make the test harder to understand than a small amount of duplication

For EACH finding: verify the claim by reading the source. Check call sites to confirm the issue is real, not hypothetical.

Agent 3: Simplification & Efficiency

Review git diff $BASE for:

• Dead code — unreachable branches, unused functions, struct fields that are never read
• Code reuse — search for existing utilities and helpers that could replace newly written code; flag duplicated functionality
• Copy-paste with variation — near-duplicate blocks that should be unified
• Unnecessary abstractions — wrapper types, indirection, or overly defensive fallbacks that mask errors
• Unnecessary work — redundant computations, repeated file reads, duplicate API calls, N+1 patterns
• Missed concurrency — independent operations run sequentially when they could be parallel
• Hot-path bloat — blocking work added to startup or per-request paths
• Unnecessary existence checks — pre-checking file/resource existence before operating (TOCTOU anti-pattern); operate directly and handle the error
• Unnecessary comments — comments explaining WHAT the code does (well-named identifiers already do that); keep only non-obvious WHY

For EACH suggestion: verify it does not break existing behavior by checking call sites and usages. Discard cosmetic-only suggestions (renames, formatting).

Agent 4: Readability & Go Idioms

Review git diff $BASE for code that is hard to read, maintain, or reason about:

• Poor factoring — functions doing multiple jobs, tangled control flow, or missing helper extraction where a small local helper would clarify behavior
• Mixed abstraction levels — high-level orchestration mixed with low-level IO, parsing, protocol, or data-structure details; low-level helpers that also make workflow or policy decisions
• Generated-code smell — repetitive pasted logic, shallow wrappers, generic names, or code that reads like it was assembled without domain intent
• Data-flow opacity — values transformed across too many steps, unclear ownership, hidden mutation, pass-through helper chains, or state threaded through unrelated code
• Control-flow complexity — deeply nested conditionals, boolean flag plumbing, early returns used inconsistently, or error paths that obscure the main path
• Naming clarity — names that hide domain meaning or force callers to inspect implementation to understand usage
• Go API readability — ambiguous (result, bool) returns outside clear comma-ok/presence checks, oversized interfaces, unnecessary pointer indirection, or cleverness where explicit Go would be clearer
• Error readability — errors that lose operation/context, wrap inconsistently, or make call sites branch on strings/booleans instead of clear errors or typed status

For EACH finding: explain the readability cost in concrete maintenance terms. Prefer small, local refactor suggestions. Discard formatting-only, gofmt-only, or personal taste comments.

Agent 5: Clean Go & Modern Go (Go diffs only)

Use the local pfleidi:clean-go skill as the source of truth: skills/pfleidi/clean-go/SKILL.md.

Review only changed Go code plus surrounding source, tests, interfaces, and call sites needed to verify findings. Apply the skill's Clean Go checks and version-gated Modern Go checks. This includes the modern-go guidance incorporated from JetBrains' use-modern-go skill: detect the relevant go.mod target version, only suggest features available for that version, and do not perform blanket modernization.

Focus on concrete changed-code findings around composable functions, abstraction level, function size/signatures, errors, pointers, small interfaces, any/interface{}, testing guidance from skills/pfleidi/testing/SKILL.md, and modern standard-library helpers. Discard findings that would merely restyle existing code or require a broad rewrite unrelated to the current diff.

Second-Pass Coverage Sweep

After the first-pass agents complete, run a second independent review pass before synthesis. The goal is recall: catch high-confidence findings that the lens-specific agents may have missed.

Launch one fresh coverage agent with origin/main as the base ref, the full list of changed files, the review context, and the review philosophy above. Do not pass the first-pass findings to this agent.

Ask the coverage agent to:

• Re-read the changed files and the surrounding code needed to understand each changed path.
• Trace changed behavior through callers, callees, tests, configuration, migrations, generated interfaces, and user/API entry points where relevant.
• Search the repository for related patterns, duplicated logic, and existing helpers that affect the changed code.
• Look across all lenses together: security, correctness, tests, simplification, readability, performance, and Go cleanliness when applicable.
• Prioritize missed Required findings over optional improvements.
• Return only high-confidence findings with concrete file:line evidence and a short explanation of the traced path.

Then compare the second-pass findings with the first-pass findings. Deduplicate overlaps, verify any new claim by reading source yourself, and discard anything that cannot be confirmed.

3. Synthesize Report

After all launched agents complete:

1. Collect findings from both the first-pass agents and the second-pass coverage sweep
2. Deduplicate — merge findings from different agents that point to the same underlying issue
3. Verify — for any finding where the agent did not cite a specific file:line with evidence, read the source and confirm or discard it
4. Group by file
5. Sort by severity within each file: Critical > High > Medium > Low

Severity Definitions

• Critical — Must fix before merge. Bugs, security vulnerabilities, data loss risk, race conditions with observable impact.
• High — Should fix before merge. Missing error handling, meaningful test gaps, performance issues on hot paths.
• Medium — Worth fixing. Code reuse opportunities, unnecessary complexity, readability problems that make future changes error-prone, minor efficiency improvements.
• Low — Optional. Minor readability improvements or cosmetic suggestions.

Relevance Classification

For each finding, classify as:

• Required — The change does not work correctly without this fix in light of the review context. Bugs, missing error handling that causes failures, security vulnerabilities, race conditions, contradictions of stated intent, or missing tests for intended behavior that would likely fail. The branch should not merge without addressing these.
• Improvement — Valid finding, but the change works correctly without it. Better factoring, clearer Go APIs, using existing helpers, code reuse, unnecessary complexity, style. Worth addressing in a follow-up, not in this branch.

Autofix Eligibility

Mark each Required finding as Autofix eligible or Needs decision:

• Autofix eligible — source-backed, high confidence, minimal fix is clear, no new dependencies, no shared/public interface change, no product/design choice, no broad refactor, and the directly related verification path is clear.
• Needs decision — any Required finding that fails one of the autofix checks, including intentional behavior questions, API shape changes, cross-cutting refactors, or fixes where multiple reasonable approaches exist.

Present findings as compact tables, not prose blocks. Use one summary table for scanning and one details table for evidence and fixes.

Summary table format:

Details table format:

Keep table cells short and scannable. Put the smallest useful quote or evidence in the table rather than full paragraphs. Escape | characters inside code or text so the table remains valid Markdown. Use n/a for Autofix on Improvements. The Sources column lists the agents that independently found or confirmed the issue, such as security, correctness, readability, clean-go, or coverage.

If no findings exist at a severity level, omit that section.

If there are 0 findings across all agents, report that the review is clean and stop.

4. Present Report and Proceed With Default Fixes

Present findings in two sections:

Required

Table of findings classified as Required, sorted by severity. Include the Autofix value for each finding. Follow it with the details table for those same Required findings.

Improvements (follow-up)

Table of findings classified as Improvement, continuing the numbering. These are presented for awareness but are NOT included in the fix cycle by default. Follow it with the details table for those same Improvement findings.

End with a one-paragraph summary: total required vs improvement findings, overall merge-readiness assessment, and any patterns across files.

Before editing, present a planned-autofix table for Autofix eligible Required findings:

Do not ask the user to choose a mode. Immediately proceed to Step 5 for Autofix eligible Required findings after showing the planned-autofix table. Do not fix Improvements by default.

If there are Required findings but none are Autofix eligible, stop after the report and list the exact decisions needed.

5. Fix Cycle

Scope Rules

• Make the MINIMAL change that addresses the finding
• Keep the diff limited to files and lines directly required by the finding
• First decide whether the finding is local or systemic. Fix at the narrowest correct level; do not add a local workaround that hides a shared/root-cause bug.
• If the finding requires a behavior-changing code fix, add or update the directly related test in the same fix step. Prefer TDD, but complete the focused red-to-green cycle before stopping: write/update the failing test, confirm it fails, implement the fix, confirm the focused test passes. Do not stop after only adding the failing test unless the user explicitly asks.
• Do NOT rename variables, reformat code, or touch lines outside the finding scope
• Do NOT refactor adjacent code, even if it looks related
• Do NOT create any git commits — code changes only

Default Batched Fixes

Fix all Autofix eligible Required findings in report order by default. Do not ask which findings to fix.

Choose an artifact directory using the AGENTS.md temporary artifact rule with agent name pfleidi-review:

• Use ./tmp/pfleidi-review/ only when ./tmp/ already exists and is already ignored.
• If no project-local artifact directory is available, do not create file artifacts by default; keep ledger/log/cache information in the response and mark file paths n/a. Ask before using /tmp/pfleidi-review/ or modifying ignore files.

When an artifact directory is available, create a temporary fix ledger at <artifact-dir>/review-<repo-name>-<timestamp>.md before editing. If no artifact directory is available, keep the same ledger fields in the final summary table instead. Update the ledger after each finding with:

• Finding number, status, and source location.
• Files touched.
• What changed and why.
• Related tests or verification commands.
• Rollback notes sufficient for the user to understand how to revert the finding-specific change manually.

For each Autofix eligible finding:

• Read the relevant code to confirm the fix approach
• Re-check eligibility before editing; if the fix is no longer clearly eligible, mark it Needs decision and continue to the next finding
• Implement the fix — ONLY the code changes for that single finding
• Add or update the directly related test in the same diff when the fix changes behavior; if using TDD, complete red-to-green before moving on; if no test is added, state why
• Keep the diff limited to files and lines directly required by that finding
• If a fix would require changing a function signature in a shared interface, adding a dependency, expanding scope outside the finding, or making an ambiguous product/design choice, skip that finding as Needs decision and continue
• Track the exact files changed, what changed, and why the change addresses the finding

If a skipped finding has partial edits, remove only your own partial edits for that finding before continuing. If you cannot safely isolate those partial edits, stop and explain the conflict.

After all eligible fixes are applied, proceed directly to Step 6 (Verify Fixes). Do NOT show a diff yet.

6. Verify Fixes

Run the project's compile/build, lint, and test commands scoped to only the changed files and their directly related tests. Use safe background batches for independent validators instead of running every command sequentially.

When selecting verification commands, reuse <artifact-dir>/verification-<repo-name>.md if an artifact directory is available and the cache is fresh under the cache rules from pfleidi:pr; otherwise discover the smallest relevant lint/test/build commands. Update the cache only when an artifact directory is available.

• Build / compile — run a relevant compile/build command when one is discoverable for the changed production code.
• Lint / static analysis — run the project's documented lint task, scoped to the files that were modified by the fixes when the task supports scoping. Prefer lint-specific task wrappers such as make lint or mise run lint over invoking linter binaries directly. Do not use aggregate check, ci, or verify tasks unless you have confirmed they only run lint/static analysis. If the documented lint task cannot be scoped, run the smallest relevant project lint task.
• Tests — run only the test files that cover the modified code (same package, same module, co-located test files). Do NOT run the full test suite.

If no compile/build command or project lint task exists, state that explicitly instead of assuming an unavailable command.

Run formatters, generators, snapshot updates, or other mutating commands alone before validators that depend on their output. Run independent read-only validators concurrently when they do not require the same exclusive service, port, database, fixture directory, or generated output. Keep integration/e2e/service-backed commands separate unless the project documents that they are parallel-safe.

For each background batch, start every command from the same working-tree state, capture stdout/stderr/exit status from the tool, do not edit files while the batch is running, and wait for every command to finish. Run each selected validator directly, for example mise run lint, go test ..., or npm test -- .... Do not wrap validators in sh -c, shell redirection, tee, command separators, or pipelines solely to write logs; that defeats command-prefix approvals and causes extra permission prompts. If an artifact directory is available and file logs can be written after the command completes without rerunning through a shell wrapper, save them under <artifact-dir>/logs-<repo-name>-<timestamp>/; otherwise mark the full-log path as n/a. If files change after a failed batch, none of that batch's successful results count as current verification.

Show verification as a compact table:

For failures or short outputs, show complete output in the relevant-output column or immediately below the table. For long successful outputs, show the relevant excerpt and log path.

On Failure: Auto-Fix

If compile/build, lint, or tests fail due to issues introduced by the review fixes:

1. Read the error output and identify every failure
2. Fix all issues — apply the minimal changes needed
3. Re-run the failing commands using the same safe batching rules
4. Show the complete output again

Cap at 2 fix attempts. If still failing after 2 rounds, present the remaining failures to the user with full output. Do not describe the work as done or commit-ready while compile/build status is failing or unknown for changed production code.

7. Present Results

Once verification passes (or the user has seen the remaining failures), present a summary table. If compile/build did not pass for code changes, say the work is not commit-ready before the table. Do NOT show a diff — the Edit tool already showed each change inline.

Also present a rollback/traceability table and the ledger path:

Ledger: <artifact-dir>/review-<repo-name>-<timestamp>.md, or n/a when no project-local artifact directory was available.

STOP and wait. The user decides what to commit.

8. Post-Fix

• If the user asks for changes, apply them
• If the user asks to revert specific fixes, revert ONLY those changes using surgical git checkout of the affected lines
• Do NOT commit. The user handles commits on their own terms.

Apply the findings

commit the changes