agentic-retro 0.1.0 → 0.1.2

package/README.md

@@ -86,6 +86,7 @@ Using Codex? It asks you to trust the new session-end hook the first time a sess
 
 ## CLI commands
 
+- `agentic-retro about` – print a short intro to what agentic-retro does
 - `agentic-retro setup` – interactive config, the human alternative to the setup skill
 - `agentic-retro config list | get <key> | set <key> <value>` – read or write one config key
 - `agentic-retro enqueue` – add a finished session to the queue (hooks call this)

package/cli/agentic-retro.js

@@ -10,8 +10,10 @@ import { syncOutcomes } from './lib/outcomes.js';
 import { notice } from './lib/notice.js';
 import { stats } from './lib/stats.js';
 import { installPi } from './lib/pi.js';
+import { INTRO } from './lib/intro.js';
 
 const USAGE = `usage: agentic-retro <command>
+  about
   setup
   config list | get <key> | set <key> <value>
   enqueue [--harness <h>] [--session <id> --transcript <path> --cwd <dir>]   (or hook JSON on stdin)
@@ -76,6 +78,7 @@ async function main() {
   if (command === 'notice') return notice(flags);
   if (command === 'stats') return stats(flags);
   if (command === 'install-pi') return installPi();
+  if (command === 'about') return process.stdout.write(INTRO);
   throw new Error(USAGE);
 }
 

package/cli/lib/commands.js

@@ -1,5 +1,5 @@
 // Builds the command that starts the batch agent in each harness.
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -37,7 +37,15 @@ function sessionsOf(batchDir) {
 }
 
 function workDirs(config, sessions) {
-  const paths = [...sessions.map((s) => s.repo), ...(config.editable ?? []).map(expandHome)];
+  const editable = (config.editable ?? []).map((path) => {
+    path = expandHome(path);
+    try {
+      return statSync(path).isFile() ? dirname(path) : path;
+    } catch {
+      return path;
+    }
+  });
+  const paths = [...sessions.flatMap((s) => [s.repo, s.cwd]), ...editable];
   return [...new Set(paths.filter(Boolean))];
 }
 

package/cli/lib/intro.js

@@ -0,0 +1,6 @@
+// The one-screen intro shown before setup asks anything. The setup skill prints it too, via `agentic-retro about`.
+export const INTRO = `agentic-retro reviews your finished coding-agent sessions in batches and suggests improvements.
+- It looks for code that could be clearer, agent setup (skills, instructions) that would have saved time, and repo changes that help agents work faster
+- You get one pull request per repo, or a report you walk through with your agent
+- Nothing lands without your review, unless you turn on auto-merge for low-risk changes
+`;

package/cli/lib/outcomes.js

@@ -39,7 +39,7 @@ export function syncOutcomes() {
     if (status !== 'open') setStatus(p, status);
   }
 
-  for (const p of open()) {
+  for (const p of open().filter((p) => !p.pr)) {
     if (ledger.batchCount - p.batch >= expireAfterBatches) setStatus(p, 'expired');
   }
   saveLedger(ledger);

package/cli/lib/queue.js

@@ -2,17 +2,21 @@
 import { execFileSync } from 'node:child_process';
 import { readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, basename } from 'node:path';
+import { join, basename, resolve } from 'node:path';
 import { readJson, writeJson } from './paths.js';
 import { loadConfig } from './config.js';
 import { startBatch } from './runner.js';
 
-function repoOf(cwd) {
+function repoOf(cwd, fallback = cwd) {
   try {
-    return execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const options = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
+    const commonDir = execFileSync('git', ['-C', cwd, 'rev-parse', '--git-common-dir'], options).replace(/\n$/, '');
+    // Git lists the shared identity first: the main checkout or its separate metadata directory.
+    const worktrees = execFileSync('git', ['--git-dir', resolve(cwd, commonDir), 'worktree', 'list', '--porcelain', '-z'], options);
+    const main = worktrees.split('\0').find((field) => field.startsWith('worktree '));
+    return main ? main.slice('worktree '.length) : fallback;
   } catch {
-    return cwd;
+    return fallback;
   }
 }
 
@@ -43,8 +47,8 @@ export async function enqueue({ harness, sessionId, transcript, cwd }) {
   harness ||= harnessOf(transcript);
   if (!harness || !sessionId || !cwd) throw new Error('enqueue needs a harness, session, and cwd');
 
-  const queue = readJson('queue.json', []);
-  if (queue.some((s) => s.sessionId === sessionId)) return;
+  const queue = readJson('queue.json', []).map((s) => ({ ...s, repo: repoOf(s.cwd, s.repo) }));
+  if (queue.some((s) => s.sessionId === sessionId)) return writeJson('queue.json', queue);
   const entry = { harness, sessionId, transcript, cwd, repo: repoOf(cwd), endedAt: new Date().toISOString() };
   queue.push(entry);
 

package/cli/lib/setup.js

@@ -3,6 +3,7 @@ import { createInterface } from 'node:readline';
 import { existsSync } from 'node:fs';
 import { delimiter, join } from 'node:path';
 import { loadConfig, saveConfig, getKey, parseValue } from './config.js';
+import { INTRO } from './intro.js';
 
 const onPath = (bin) => (process.env.PATH || '').split(delimiter).some((dir) => existsSync(join(dir, bin)));
 
@@ -34,6 +35,7 @@ export async function setup() {
   const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
   const lines = rl[Symbol.asyncIterator]();
   const config = loadConfig();
+  process.stdout.write(`${INTRO}\nThese questions take about two minutes. Press Enter to keep the value in brackets.\n\n`);
 
   for (const [key, label, presets] of questions()) {
     const current = show(getKey(config, key));

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "agentic-retro",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "agentic-retrospective: reviews finished agent coding sessions and proposes improvements",
   "type": "module",
-  "bin": { "agentic-retro": "cli/agentic-retro.js" },
-  "files": ["cli/", "skills/"],
-  "engines": { "node": ">=20" },
-  "scripts": { "test": "node --test test/*.test.js" },
+  "bin": {
+    "agentic-retro": "cli/agentic-retro.js"
+  },
+  "files": [
+    "cli/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "license": "MIT",
-  "repository": "github:ac8318740/agentic-retro"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ac8318740/agentic-retro.git"
+  }
 }

package/skills/run/SKILL.md

@@ -109,20 +109,25 @@ agentic-retro propose --repo <target repo path> --category <category> [--risk lo
 
 Do this once per target repo. Skip a target with no git remote, and put its proposals in a report file instead (5b).
 
+Before you branch, read the repo's PR rules in its `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` and CI workflows, such as a `dev` base branch or a version bump.
+
 ```bash
 git -C "$repo" fetch origin
-base=$(git -C "$repo" symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@')
+base=$(git -C "$repo" symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@')  # override with the rules' base
 wt=$(mktemp -d)/wt
 git -C "$repo" worktree add -b "agentic-retro/batch-<n>" "$wt" "origin/$base"
 ```
 
 1. Apply each proposal in `$wt`, then commit it on its own: `git -C "$wt" add -A && git -C "$wt" commit -m "P12: <title>"`
-2. Push the branch: `git -C "$wt" push -u origin "agentic-retro/batch-<n>"`
-3. Write the body per `writing-proposals.md`, then open the PR from `$wt`: `gh pr create --base "$base" --title "<title>" --body-file <file>`
-4. Record the PR and commit on each proposal: `agentic-retro link P12 --pr <url> --commit <sha>`
-5. Remove the worktree: `git -C "$repo" worktree remove "$wt"`
-
-When `autoMergeLowRisk` is `true`, low-risk agent-setup proposals go on a second branch, `agentic-retro/batch-<n>-low-risk`, with their own PR. Merge that PR with `gh pr merge --merge` once it opens. Everything else waits for the user.
+2. Do the steps the rules require in one last commit without a proposal ID, so dropping a proposal keeps them. When a step needs a command you cannot run, say so at the top of the PR body
+3. Push the branch: `git -C "$wt" push -u origin "agentic-retro/batch-<n>"`
+4. Make sure the `agentic-retro` label exists from `$wt`: `(cd "$wt" && gh label create agentic-retro --force)`
+5. Write the body per `writing-proposals.md`, then open the PR from `$wt`: `(cd "$wt" && gh pr create --base "$base" --title "<title>" --body-file <file> --label agentic-retro)`
+6. Wait for CI with `gh pr checks <url> --watch`, then fix each failure in a new commit and push
+7. Record the PR and commit on each proposal: `agentic-retro link P12 --pr <url> --commit <sha>`
+8. Remove the worktree: `git -C "$repo" worktree remove "$wt"`
+
+When `autoMergeLowRisk` is `true`, low-risk agent-setup proposals go on a second branch, `agentic-retro/batch-<n>-low-risk`, with their own PR. Merge that PR with `gh pr merge --merge` once its checks pass. Everything else waits for the user.
 
 ## 5b. Report mode: one report file
 

package/skills/run/agent-setup.md

@@ -41,7 +41,7 @@ Every agent-setup proposal carries a risk label.
 ## Where a change may go
 
 - **New things** go under `targets.preset`, such as `~/.claude/skills`
-    - `targets.note` may name another place, such as "send spechub fixes to the spechub repo at <path>"
+    - `targets.note` may name another place, such as "send acme-skills fixes to its repo at <path>"
     - Follow the note when it covers the finding
 - **Edits to existing files** go only under a path listed in `editable`
     - Drop a finding against a file outside `editable`, however good it is

package/skills/setup/SKILL.md

@@ -12,6 +12,10 @@ Walk the user through agentic-retro's config, one question at a time, then write
 1. Run `command -v agentic-retro`.
 2. If the command is missing, tell the user to run `npm install -g agentic-retro`, then stop.
 
+## Open with the intro
+
+Run `agentic-retro about` and show its output to the user as is, before the first question. It says what agentic-retro does in a few lines. Add nothing to it.
+
 ## Ask each question
 
 Use the host's question tool (for example `AskUserQuestion`) when one is available. Otherwise ask in plain chat, one question at a time.
@@ -32,7 +36,7 @@ Offer the presets below for each question, and let the user type a different ans
 9. **Auto-merge** – merge low-risk agent-setup PRs automatically? Default off
 10. **Expire after** – batches an open proposal waits before it expires with no action, default 3
 11. **Targets** – where agent-setup proposals go: `~/.claude/skills`, `~/.codex/skills`, or a plugin repo path
-    - Also ask for a free-text note the batch agent reads, for example: "I develop spechub; send spechub fixes to the spechub repo at ~/spechub"
+    - Also ask for a free-text note the batch agent reads, for example: "I maintain the acme-skills plugin; send fixes to its repo at ~/code/acme-skills"
 12. **Editable paths** – which paths proposals can write to, as a JSON list; every other path stays read-only
 13. **Notes** – free text, anything else the batch agents should know
 
@@ -52,7 +56,7 @@ agentic-retro config set output pr
 agentic-retro config set autoMergeLowRisk false
 agentic-retro config set expireAfterBatches 3
 agentic-retro config set targets.preset ~/.claude/skills
-agentic-retro config set targets.note "I develop spechub; send spechub fixes to ~/spechub"
+agentic-retro config set targets.note "I maintain the acme-skills plugin; send fixes to its repo at ~/code/acme-skills"
 agentic-retro config set editable '["~/.claude/skills"]'
 agentic-retro config set notes "ask about this"
 ```