# Plan: Repo Retro CLI Adoption

## Overview

Move the project implementation retrospective engine out of agent-kit and into
`nils-cli` as a released `repo-retro` binary, then update agent-kit with a
`project-retro` skill that consumes the Homebrew-installed CLI. The nils-cli
side owns deterministic repo parsing, JSON/Markdown output, opt-in history
writes, typed evidence inputs, completions, and release packaging. The agent-kit
side owns workflow naming, policy, synthesis, and user-facing review guidance
after `repo-retro` is available from the installed Homebrew formula.

## Read First

- Primary source: docs/plans/repo-retro-cli-adoption/repo-retro-cli-adoption-discussion-source.md
- Source type: discussion-to-implementation-doc
- Execution state: docs/plans/repo-retro-cli-adoption/repo-retro-cli-adoption-execution-state.md
- Open questions carried into execution: none

## Scope

- In scope: nils-cli `repo-retro` binary in
  `/Users/terry/Project/sympoies/nils-cli`, completion/assets/docs/tests,
  nils-cli release to source tag and Homebrew tap, local Homebrew install
  verification, and agent-kit migration from `weekly-retro` helper to
  `project-retro` skill backed by installed `repo-retro`.
- Out of scope: remote provider enrichment by default, telemetry, hidden home or
  memory lookup, HEURISTIC_SYSTEM mutation, generated report commits by default,
  and switching agent-kit to an unreleased local nils-cli checkout.

## Assumptions

1. `repo-retro` belongs in the existing nils-cli
   `nils-agent-workflow-primitives` crate unless implementation discovers a
   concrete standalone-crate need.
2. nils-cli implementation happens first, including release and Homebrew local
   install verification, before agent-kit starts depending on the new command.
3. The CLI should use `repo-retro report` as the primary command so future
   subcommands can be added without renaming the binary.
4. The JSON service envelope should follow nils-cli convention:
   `cli.repo-retro.report.v1`; the result payload can carry
   `repo-retro.report.v1`.
5. Agent-kit should rename the workflow surface to `project-retro`; any
   `weekly-retro` compatibility should be transitional and not the primary
   public name. The CLI consumed by the skill remains `repo-retro`.

## Sprint 1: nils-cli Repo-Retro Primitive

**Goal**: Add the `repo-retro` CLI contract and deterministic report engine in
nils-cli.
**Demo/Validation**:

- Command(s): `cargo test -p nils-agent-workflow-primitives repo_retro`,
  `cargo run -p nils-agent-workflow-primitives --bin repo-retro -- report --repo "$HOME/.config/agent-kit" --days 7 --mode team --format json`
- Verify: JSON has the nils-cli envelope, local repo data, review analysis, and
  no default writes.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 1.1: Add the `repo-retro` binary surface

- **Location**:
  - `nils-cli/crates/agent-workflow-primitives/Cargo.toml`
  - `nils-cli/crates/agent-workflow-primitives/src/bin/repo-retro.rs`
  - `nils-cli/crates/agent-workflow-primitives/src/lib.rs`
  - `nils-cli/crates/agent-workflow-primitives/src/repo_retro.rs`
  - `nils-cli/crates/agent-workflow-primitives/tests/integration/cli.rs`
- **Description**: Register the `repo-retro` binary and define the clap command
  contract with `report` and `completion <bash|zsh>`.
- **Dependencies**:
  - none
- **Complexity**: 4
- **Acceptance criteria**:
  - `repo-retro --help`, `repo-retro --version`, and
    `repo-retro report --help` work.
  - `repo-retro completion zsh` and `repo-retro completion bash` emit
    completion output.
  - Usage errors return nils-cli's documented usage exit code.
  - The binary is visible from `cargo metadata` and can be discovered by
    `scripts/workspace-bins.sh`.
- **Validation**:
  - `cargo test -p nils-agent-workflow-primitives repo_retro`
  - `cargo run -p nils-agent-workflow-primitives --bin repo-retro -- --help`

### Task 1.2: Port deterministic report collection to Rust

- **Location**:
  - `nils-cli/crates/agent-workflow-primitives/src/repo_retro.rs`
  - `nils-cli/crates/agent-workflow-primitives/tests/integration/cli.rs`
  - `nils-cli/crates/agent-workflow-primitives/docs/README.md`
- **Description**: Port the existing agent-kit Python helper behavior into a
  nils-cli Rust implementation for local git windows, commit classification,
  authors, file hotspots, test signals, HEURISTIC_SYSTEM movement, warnings, and
  source commands.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 7
- **Acceptance criteria**:
  - Supported windows include current week, `--days N`, `--since YYYY-MM-DD`,
    and `--from YYYY-MM-DD --to YYYY-MM-DD`.
  - The report reads only local git and explicitly provided file paths.
  - No-commit windows produce a valid report with a warning.
  - Missing HEURISTIC_SYSTEM directories are reported as `not_present`.
  - Source commands are included in JSON so agent-kit can cite them.
- **Validation**:
  - `cargo test -p nils-agent-workflow-primitives repo_retro`
  - `cargo run -p nils-agent-workflow-primitives --bin repo-retro -- report --repo /Users/terry/.config/agent-kit --days 7 --format json`

### Task 1.3: Add review modes, derived analysis, typed inputs, and history

- **Location**:
  - `nils-cli/crates/agent-workflow-primitives/src/repo_retro.rs`
  - `nils-cli/crates/agent-workflow-primitives/tests/integration/cli.rs`
  - `nils-cli/crates/agent-workflow-primitives/docs/README.md`
- **Description**: Implement the upgraded report capabilities directly in
  nils-cli: modes, themes, attention items, follow-up questions, validation
  signals, HEURISTIC_SYSTEM aging, expanded history comparison, typed JSONL
  inputs, and Markdown rendering.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 8
- **Acceptance criteria**:
  - `--mode personal|team|maintainer` affects review framing without changing
    data collection.
  - JSON uses envelope `cli.repo-retro.report.v1` and result schema
    `repo-retro.report.v1`.
  - `analysis.themes`, `analysis.attentionItems`,
    `analysis.followUpQuestions`, `analysis.validationSignals`,
    `analysis.heuristicSystemReview`, and `analysis.historyComparison` are
    populated when source signals exist.
  - Explicit JSONL inputs cover timeline, learnings, validation, review,
    incidents, and decisions.
  - `--history-dir <dir> --write` writes Markdown, raw JSON, and `index.jsonl`;
    `--history-dir` without `--write` reports intended paths only.
  - Markdown output is useful as a personal/team/maintainer review agenda.
- **Validation**:
  - `cargo test -p nils-agent-workflow-primitives repo_retro`
  - `cargo run -p nils-agent-workflow-primitives --bin repo-retro -- report --repo . --mode maintainer --format markdown`

## Sprint 2: nils-cli Integration, Docs, And Release Readiness

**Goal**: Make `repo-retro` a normal nils-cli binary with docs, completions,
tests, and required checks ready for release.
**Demo/Validation**:

- Command(s): `bash scripts/workspace-bins.sh`,
  `NILS_CLI_TEST_RUNNER=nextest bash scripts/ci/nils-cli-checks-entrypoint.sh --with-coverage`
- Verify: `repo-retro` appears in the workspace binary list and the repo is
  release-ready.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 2.1: Wire binary inventory, wrappers, and completions

- **Location**:
  - `nils-cli/wrappers/repo-retro`
  - `nils-cli/completions/zsh/_repo-retro`
  - `nils-cli/completions/bash/repo-retro`
  - `nils-cli/completions/zsh/aliases.zsh`
  - `nils-cli/completions/bash/aliases.bash`
  - `nils-cli/docs/specs/completion-coverage-matrix-v1.md`
- **Description**: Add the normal nils-cli wrapper/completion surface for the
  new binary and update completion coverage.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 4
- **Acceptance criteria**:
  - `bash scripts/workspace-bins.sh` includes `repo-retro`.
  - Completion files are generated through the clap-first path.
  - Completion audits and shell syntax checks pass.
  - Optional aliases, if added, do not conflict with existing commands.
- **Validation**:
  - `bash scripts/workspace-bins.sh`
  - `zsh -n completions/zsh/_repo-retro`
  - `bash -n completions/bash/repo-retro`
  - `bash scripts/ci/completion-asset-audit.sh --strict`
  - `bash scripts/ci/completion-flag-parity-audit.sh --strict`

### Task 2.2: Update nils-cli docs and release metadata

- **Location**:
  - `nils-cli/README.md`
  - `nils-cli/crates/agent-workflow-primitives/README.md`
  - `nils-cli/crates/agent-workflow-primitives/docs/README.md`
  - `nils-cli/BINARY_DEPENDENCIES.md`
  - `nils-cli/THIRD_PARTY_LICENSES.md`
  - `nils-cli/THIRD_PARTY_NOTICES.md`
- **Description**: Document `repo-retro` as an agent workflow primitive and
  refresh third-party artifacts if new dependencies are introduced.
- **Dependencies**:
  - Task 1.3
  - Task 2.1
- **Complexity**: 3
- **Acceptance criteria**:
  - Root README classifies `repo-retro` under Agent policy and evidence or the
    nearest appropriate local-first agent workflow category.
  - Crate README lists `repo-retro` in binary names and binary map.
  - Docs show example JSON and Markdown invocations.
  - Third-party artifacts are regenerated or verified unchanged.
- **Validation**:
  - `bash scripts/ci/docs-placement-audit.sh --strict`
  - `bash scripts/ci/docs-hygiene-audit.sh --strict`
  - `bash scripts/ci/markdownlint-audit.sh --strict`
  - `bash scripts/generate-third-party-artifacts.sh --check`

### Task 2.3: Run nils-cli release-readiness checks

- **Location**:
  - `nils-cli/crates/agent-workflow-primitives/tests/integration/cli.rs`
  - `nils-cli/DEVELOPMENT.md`
- **Description**: Run the required nils-cli gates before release, including
  coverage for non-doc changes.
- **Dependencies**:
  - Task 2.1
  - Task 2.2
- **Complexity**: 4
- **Acceptance criteria**:
  - Formatting, clippy, tests, docs audits, completion audits, and coverage pass.
  - A real local smoke report against agent-kit passes in JSON and Markdown.
  - Any release-blocking dirty state is resolved or explicitly separated.
- **Validation**:
  - `NILS_CLI_TEST_RUNNER=nextest bash scripts/ci/nils-cli-checks-entrypoint.sh --with-coverage`
  - `cargo run -p nils-agent-workflow-primitives --bin repo-retro -- report --repo "$HOME/.config/agent-kit" --days 7 --mode team --format json`

## Sprint 3: nils-cli Release, Homebrew Tap, And Local Install

**Goal**: Publish `repo-retro` through the normal nils-cli release path and
verify the local machine is using the Homebrew-installed binary before
agent-kit adoption starts.
**Demo/Validation**:

- Command(s): `.agents/scripts/release.sh --version "$NILS_CLI_NEXT_VERSION" --tap-dir /Users/terry/Project/sympoies/homebrew-tap`,
  `command -v repo-retro`, `repo-retro report --repo "$HOME/.config/agent-kit" --days 7 --mode team --format json`
- Verify: source release, tap release, local brew install, and `repo-retro`
  runtime all work.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 3.1: Release nils-cli with `repo-retro`

- **Location**:
  - `nils-cli/Cargo.toml`
  - `nils-cli/Cargo.lock`
  - `nils-cli/README.md`
  - `nils-cli/release/crates-io-publish-order.txt`
  - `nils-cli/THIRD_PARTY_LICENSES.md`
  - `nils-cli/THIRD_PARTY_NOTICES.md`
- **Description**: Run the canonical nils-cli release workflow to bump the next
  version, tag the source release, and trigger source artifacts.
- **Dependencies**:
  - Task 2.3
- **Complexity**: 5
- **Acceptance criteria**:
  - Release script chooses or receives the next version after live tag/version
    inspection.
  - Source repo version bump commit and tag are created through the release
    workflow.
  - Source `release.yml` completes successfully and includes `repo-retro` in the
    packaged `bin/` payload.
  - Release evidence records the exact version and tag.
- **Validation**:
  - `.agents/scripts/release.sh --version "$NILS_CLI_NEXT_VERSION" --tap-dir /Users/terry/Project/sympoies/homebrew-tap`
  - `gh run list --workflow release.yml --limit 5`

### Task 3.2: Update Homebrew tap and verify local install

- **Location**:
  - `homebrew-tap/Formula/nils-cli.rb`
  - `homebrew-tap/README.md`
  - `homebrew-tap/DEVELOPMENT.md`
- **Description**: Complete or verify the release workflow's tap stage, then
  confirm local Homebrew installation exposes `repo-retro`.
- **Dependencies**:
  - Task 3.1
- **Complexity**: 4
- **Acceptance criteria**:
  - Tap formula points at the new nils-cli version and platform sha256 values.
  - Tap release workflow completes successfully.
  - `brew list --versions nils-cli` reports the released version.
  - `command -v repo-retro` resolves to the Homebrew-installed binary path, not
    an unreleased checkout wrapper.
  - `repo-retro --version`, `repo-retro --help`, and a real report command pass.
- **Validation**:
  - `ruby -c homebrew-tap/Formula/nils-cli.rb`
  - `HOMEBREW_NO_AUTO_UPDATE=1 brew style homebrew-tap/Formula/nils-cli.rb`
  - `brew list --versions nils-cli`
  - `command -v repo-retro`
  - `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode team --format json`

## Sprint 4: agent-kit Project-Retro Adoption

**Goal**: After `repo-retro` is installed from Homebrew, migrate agent-kit from
the local `weekly-retro` helper to a `project-retro` skill that consumes the
released CLI.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k project_retro`,
  `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode maintainer --format markdown`,
  `scripts/check.sh --all`
- Verify: agent-kit skill docs/tests use `project-retro` as the workflow name,
  call installed `repo-retro`, and no longer treat weekly as the primary
  capability name.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 4.1: Rename and rewrite the reporting skill surface

- **Location**:
  - `agent-kit/skills/workflows/reporting/project-retro/SKILL.md`
  - `agent-kit/skills/workflows/reporting/project-retro/tests/test_workflows_reporting_project_retro.py`
  - `agent-kit/skills/workflows/reporting/weekly-retro/SKILL.md`
  - `agent-kit/skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Make `project-retro` the primary agent-kit reporting skill.
  Move or rewrite the old weekly-retro docs/tests as a compatibility note only
  if the repo needs a transition path.
- **Dependencies**:
  - Task 3.2
- **Complexity**: 5
- **Acceptance criteria**:
  - The primary skill name is `project-retro`.
  - The skill says weekly is just a window choice, not the workflow identity.
  - The skill requires or verifies installed `repo-retro` before report
    synthesis.
  - The skill preserves no-remote/no-hidden-state and HEURISTIC_SYSTEM read-only
    boundaries.
  - Tests no longer assert `weekly-retro` as the primary name.
- **Validation**:
  - `scripts/check.sh --tests -- -k project_retro`
  - `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode team --format json`

### Task 4.2: Remove agent-kit local helper ownership

- **Location**:
  - `agent-kit/skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
  - `agent-kit/skills/workflows/reporting/weekly-retro/scripts/weekly-retro.sh`
  - `agent-kit/tests/script_specs/skills/workflows/reporting/weekly-retro/scripts/weekly-retro.sh.json`
  - `agent-kit/docs/runbooks/skills/TOOLING_INDEX_V2.md`
- **Description**: Remove or deprecate the old repo-local Python helper and
  script spec once the released nils-cli binary is the deterministic source of
  truth.
- **Dependencies**:
  - Task 4.1
- **Complexity**: 4
- **Acceptance criteria**:
  - agent-kit no longer has a duplicate implementation of repo-retro parsing.
  - Any compatibility wrapper, if kept, shells out to installed `repo-retro` and
    is documented as transitional.
  - Script specs match the final agent-kit entrypoint surface.
  - Tooling index points to nils-cli `repo-retro` rather than local helper
    ownership.
- **Validation**:
  - `scripts/check.sh --entrypoint-ownership`
  - `scripts/check.sh --tests -- -k project_retro`

### Task 4.3: Update agent-kit catalogs, docs, and changelog

- **Location**:
  - `agent-kit/README.md`
  - `agent-kit/skills/README.md`
  - `agent-kit/docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `agent-kit/CHANGELOG.md`
- **Description**: Update discoverability and release notes for the new
  `project-retro` workflow and nils-cli `repo-retro` dependency.
- **Dependencies**:
  - Task 4.1
  - Task 4.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Catalogs list `project-retro` under Reporting.
  - Docs show examples using `repo-retro report`.
  - Changelog records the workflow rename and nils-cli-backed implementation.
  - Any legacy `weekly-retro` references are either removed or explicitly marked
    transitional.
- **Validation**:
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`

## Sprint 5: Cross-Repo Final Validation

**Goal**: Prove the full dependency chain works from installed nils-cli through
agent-kit reporting docs/tests.
**Demo/Validation**:

- Command(s): `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode team --format json`,
  `scripts/check.sh --all`
- Verify: Homebrew-installed `repo-retro` works and agent-kit is cleanly adapted.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 5.1: Validate installed CLI against real agent-kit repo

- **Location**:
  - `agent-kit/skills/workflows/reporting/project-retro/SKILL.md`
  - `nils-cli/crates/agent-workflow-primitives/src/repo_retro.rs`
- **Description**: Run real JSON and Markdown reports against agent-kit using
  the Homebrew-installed binary and inspect output shape.
- **Dependencies**:
  - Task 3.2
  - Task 4.3
- **Complexity**: 2
- **Acceptance criteria**:
  - `command -v repo-retro` points at the installed release path.
  - JSON report includes mode, window, sources, warnings, analysis, and
    HEURISTIC_SYSTEM sections.
  - Markdown report is review-ready and does not require generated report files.
- **Validation**:
  - `command -v repo-retro`
  - `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode team --format json`
  - `repo-retro report --repo /Users/terry/.config/agent-kit --days 7 --mode maintainer --format markdown`

### Task 5.2: Run final repo gates and record delivery boundary

- **Location**:
  - `agent-kit/DEVELOPMENT.md`
  - `nils-cli/DEVELOPMENT.md`
- **Description**: Run final validation for both repos and record which release,
  tap, and local install versions were used.
- **Dependencies**:
  - Task 5.1
- **Complexity**: 3
- **Acceptance criteria**:
  - nils-cli release/tag/tap version is recorded in final delivery notes.
  - Homebrew local version is recorded.
  - agent-kit `scripts/check.sh --all` passes after adoption.
  - Any unrelated dirty state in either repo is left untouched and reported.
- **Validation**:
  - `brew list --versions nils-cli`
  - `NILS_CLI_TEST_RUNNER=nextest bash nils-cli/scripts/ci/nils-cli-checks-entrypoint.sh`
  - `scripts/check.sh --all`

## Testing Strategy

- nils-cli unit/integration: `repo-retro` parser, window modes, git log parsing,
  optional JSONL parsing, HEURISTIC_SYSTEM parsing, history writes, schema
  envelopes, error envelopes, completions, and no-secret output.
- nils-cli real smoke: `repo-retro report` against agent-kit in JSON and
  Markdown modes before release.
- nils-cli release: required checks with coverage, source release workflow,
  Homebrew tap formula validation, tap workflow wait, local brew upgrade, and
  installed binary smoke.
- agent-kit tests: `project-retro` skill contract, catalog references,
  installed CLI detection, report command examples, and removal/deprecation of
  old helper ownership.
- Cross-repo final: installed `repo-retro` command plus agent-kit full check.

## Risks & gotchas

- Do not let agent-kit consume a local nils-cli checkout; the gate is the
  Homebrew-installed `repo-retro`.
- The nils-cli release script and tap are live external state. Verify current
  version, branch, tag, CI, tap cleanliness, and installed formula during
  execution.
- Moving from `weekly-retro.report.v1` to `repo-retro.report.v1` can break old
  history comparison. Add compatibility or explicit migration warnings.
- Completion assets and release tarballs must include `repo-retro`; use
  workspace binary inventory and release artifact inspection.
- Keep nils-cli deterministic. Do not move agent synthesis, recommendation
  prose, or workflow policy into the CLI.
- Agent-kit skill rename can create duplicate discovery. Prefer one primary
  `project-retro` skill and make legacy `weekly-retro` transitional only if
  needed.

## Rollback plan

- If nils-cli implementation fails before release, keep agent-kit unchanged and
  continue using the existing local `weekly-retro` helper.
- If source release succeeds but tap/local install fails, do not change
  agent-kit; fix tap/install first or release a patch.
- If agent-kit adoption fails after Homebrew install, revert only agent-kit
  migration while keeping the released nils-cli `repo-retro` available.
- If `repo-retro` schema has a critical bug after release, publish a nils-cli
  patch release and keep agent-kit pinned to the corrected Homebrew version
  before re-enabling the skill migration.
