# Repo Retro CLI Adoption Implementation Source

## Status

- Date: 2026-05-19
- Source type: discussion-to-implementation-doc
- Status: ready for implementation planning
- Intended next step: execute the sibling implementation plan.
- Recommended plan: docs/plans/repo-retro-cli-adoption/repo-retro-cli-adoption-plan.md
- Recommended execution state: docs/plans/repo-retro-cli-adoption/repo-retro-cli-adoption-execution-state.md

## Purpose

The current `weekly-retro` workflow name is too narrow. The capability is not
weekly-specific: it reviews implementation activity for a selected repository
and selected time window. The durable primitive should therefore be named
`repo-retro`, with weekly remaining only a default or common window.

The implementation should move deterministic data collection into `nils-cli` as
a released Homebrew-installed CLI named `repo-retro`, then return to
`agent-kit` and update the reporting skill to consume that installed CLI. The
agent-kit skill should be named `project-retro`, because it is the user-facing
project implementation review workflow. `agent-kit` keeps workflow judgment,
policy, and synthesis; `nils-cli` owns the stable command, JSON contract,
history writes, and local repo parsing.

## Source Material

- Existing agent-kit workflow:
  `skills/workflows/reporting/weekly-retro/SKILL.md`
- Existing agent-kit helper implementation:
  `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
- Existing agent-kit tests:
  `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- Target nils-cli primitive crate:
  `/Users/terry/Project/sympoies/nils-cli/crates/agent-workflow-primitives/`
- nils-cli workspace binary inventory:
  `/Users/terry/Project/sympoies/nils-cli/scripts/workspace-bins.sh`
- nils-cli CLI contract:
  `/Users/terry/Project/sympoies/nils-cli/docs/runbooks/new-cli-crate-development-standard.md`
- nils-cli release workflow:
  `/Users/terry/Project/sympoies/nils-cli/.agents/skills/nils-cli-bump-version-tag-release/SKILL.md`
- Homebrew tap:
  `/Users/terry/Project/sympoies/homebrew-tap/Formula/nils-cli.rb`

## Confirmed Facts

- `weekly-retro` currently supports arbitrary windows through current week,
  `--days N`, `--since YYYY-MM-DD`, and `--from/--to`; it is not limited to
  weekly reporting.
- Current output already summarizes repo identity, window metadata, local git
  commits, commit type mix, authors, hotspots, test signals, HEURISTIC_SYSTEM
  movement, explicit JSONL inputs, warnings, source commands, and optional
  history writes.
- The desired upgrade adds review modes, themes/outcomes, attention items,
  follow-up questions, richer validation signals, HEURISTIC_SYSTEM aging,
  expanded history comparison, and typed optional JSONL inputs.
- `nils-cli` already has a multi-binary `nils-agent-workflow-primitives` crate
  for deterministic local-first agent workflow primitives.
- `nils-cli` service-consumed commands should provide versioned JSON envelopes,
  stable exit codes, documented human output, and contract tests.
- The nils-cli release workflow can bump versions, tag the source repo, update
  the Homebrew tap, wait for release artifacts, upgrade the installed local
  formula, and verify the installed Homebrew version.

## Decisions

- Name the CLI binary `repo-retro`.
- Put the CLI in `nils-cli` under `crates/agent-workflow-primitives` unless
  implementation proves it needs a standalone crate.
- Use a command shape that leaves room for future subcommands:
  `repo-retro report --repo <path> --days 7 --mode team --format json`.
- Use review modes `personal`, `team`, and `maintainer`.
- Use an additive report result schema named `repo-retro.report.v1` and a
  nils-cli service envelope named `cli.repo-retro.report.v1`.
- Release `nils-cli`, update the Homebrew tap, and verify the local Homebrew
  installation before changing `agent-kit` to depend on `repo-retro`.
- Rename the agent-kit reporting workflow surface to `project-retro`; keep
  `weekly` wording only as an example window, not as the capability name. The
  installed CLI it consumes remains `repo-retro`.
- Remove or deprecate the repo-local Python helper after the installed
  `repo-retro` CLI is available and verified.

## Scope

- Implement `repo-retro` in nils-cli with git/window parsing, typed JSONL
  inputs, HEURISTIC_SYSTEM read-only summaries, derived review analysis,
  Markdown output, opt-in history writes, completion support, and tests.
- Update nils-cli docs, binary inventory/completion assets, changelog/release
  metadata, and validation evidence.
- Release nils-cli end to end through source tag, Homebrew tap update, tap CI,
  and local Homebrew install/upgrade verification.
- Update agent-kit after the Homebrew-installed `repo-retro` is available:
  `project-retro` skill rename/adoption, docs/catalog/tests/changelog, and
  removal or deprecation of the old local helper.

## Non-Scope

- Do not add remote GitHub, GitLab, or CI enrichment to `repo-retro` by default.
- Do not search `$HOME`, memory, telemetry, or hidden project state for inputs.
- Do not mutate HEURISTIC_SYSTEM records from repo-retro.
- Do not keep generated retro outputs in tracked source by default.
- Do not make agent-kit depend on an unreleased local nils-cli checkout.
- Do not leave `weekly-retro` or `repo-retro` as the primary agent-kit skill
  name; `repo-retro` is the CLI name.

## Requirements

- `repo-retro report` must work for arbitrary selected windows.
- Default output should be human-readable unless nils-cli conventions for this
  binary choose JSON as a documented service mode; `--format json` must be
  service-consumable.
- JSON output must include a versioned nils-cli envelope and a stable result
  report schema.
- The result must include source commands and warnings so agent-kit can cite
  what was read.
- `repo-retro` must support explicit typed JSONL inputs for timeline, learnings,
  validation, review, incidents, and decisions.
- History writes must require explicit `--history-dir <dir> --write`.
- Agent-kit must not switch to `repo-retro` until Homebrew installation verifies
  `repo-retro --version`, `repo-retro --help`, and a real report command.
- Agent-kit should keep synthesis and workflow framing in the skill; nils-cli
  should own deterministic parsing and output contracts.
- The primary agent-kit skill should be `project-retro`, and it should call the
  installed `repo-retro` CLI.

## Acceptance Criteria

- `repo-retro` appears in `bash scripts/workspace-bins.sh` after nils-cli
  implementation.
- `repo-retro completion zsh` and `repo-retro completion bash` work and assets
  pass nils-cli completion audits.
- `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode team --format json`
  emits `cli.repo-retro.report.v1` with `repo-retro.report.v1` result content.
- nils-cli full required checks pass before release.
- nils-cli release workflow publishes the source tag, updates Homebrew tap, and
  verifies installed Homebrew `nils-cli` includes `repo-retro`.
- agent-kit `project-retro` skill consumes installed `repo-retro`, no longer
  depends on the old Python helper for report generation, and passes agent-kit
  checks.

## Validation Plan

- nils-cli implementation checks:
  `NILS_CLI_TEST_RUNNER=nextest bash scripts/ci/nils-cli-checks-entrypoint.sh`
- nils-cli pre-release checks:
  `NILS_CLI_TEST_RUNNER=nextest bash scripts/ci/nils-cli-checks-entrypoint.sh --with-coverage`
- nils-cli release:
  `.agents/scripts/release.sh --version "$NILS_CLI_NEXT_VERSION" --tap-dir /Users/terry/Project/sympoies/homebrew-tap`
- Homebrew install verification:
  `brew list --versions nils-cli`
  `command -v repo-retro`
  `repo-retro --version`
  `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode team --format json`
- agent-kit adoption checks:
  `scripts/check.sh --tests -- -k project_retro`
  `scripts/check.sh --docs`
  `scripts/check.sh --markdown`
  `scripts/check.sh --all`

## Risks And Guardrails

- Cross-repo execution can blur ownership. Complete and release nils-cli first;
  only then change agent-kit.
- Homebrew release state is time-sensitive. Verify source release artifacts, tap
  release, and local install from live commands during execution.
- Renaming from `weekly-retro` to agent-kit `project-retro` plus nils-cli
  `repo-retro` can break references. Update catalogs, tests, script specs, and
  changelog together.
- The report should stay deterministic. Keep model synthesis out of nils-cli and
  in the agent-kit skill.
- Older report history may use `weekly-retro.report.v1`. Add compatibility
  parsing or explicit migration warnings instead of failing history comparison.

## Execution

- Recommended plan: docs/plans/repo-retro-cli-adoption/repo-retro-cli-adoption-plan.md
- Recommended execution state: docs/plans/repo-retro-cli-adoption/repo-retro-cli-adoption-execution-state.md
- Retention intent: cross-repo coordination artifact; keep at least until both
  nils-cli release and agent-kit adoption are complete.

## Open Questions

- None for planning. The implementation can choose the next nils-cli version at
  release time by inspecting the current workspace and tag state.
