semantu-agents 1.3.0 → 1.4.0

package/README.md

@@ -23,33 +23,45 @@ For normal users, rerun:
 npx semantu-agents global
 ```
 
-For contributors with an editable checkout at `~/.agents-src`, run this from anywhere:
+For contributors with a registered editable checkout, run this from anywhere:
 
 ```bash
 npx semantu-agents update
 ```
 
-This updates `~/.agents-src/main`, syncs it to `~/.claude/skills` and `~/.agents/skills`, then restores your previous branch when possible. If `~/.agents-src` has uncommitted changes, commit or stash them first.
+This updates the registered checkout's `main` branch, repairs its global skill links, then restores your previous branch when possible. If the checkout has uncommitted changes, commit or stash them first.
+
+`update` requires a named Git branch. It refuses dirty checkouts and detached HEAD states.
 
 ## Contributing Skill Changes
 
-Install an editable source checkout:
+Register an existing editable checkout:
 
 ```bash
+cd /path/to/semantu-agents
 npx semantu-agents dev
 ```
 
-This clones or pulls `github.com:Semantu/agents` into `~/.agents-src`, installs a post-merge hook, and syncs that checkout globally.
+You can also provide the checkout explicitly:
+
+```bash
+npx semantu-agents dev /path/to/semantu-agents
+```
+
+Without a path, `dev` uses the current directory when it is the agents checkout, then a previously registered checkout, then `~/packages/semantu-agents`. It never clones another checkout.
+
+The resolved path is stored in `~/.config/semantu-agents/config.json`. Each package-managed skill in `~/.claude/skills` and `~/.agents/skills` is linked to that checkout, so edits are available globally immediately. Unrelated installed skills are preserved.
+
+Directory junctions are used on Windows; directory symlinks are used elsewhere.
 
-Dev mode requires repo access. If cloning fails, ask for access to the Semantu agents repo.
+Dev mode requires an existing checkout. Clone the repository separately first if needed.
 
 Make changes in the source checkout only:
 
 ```bash
-cd ~/.agents-src
+cd /path/to/semantu-agents
 git checkout -b my-change
 # edit skills/public/... or skills/private/...
-npm run sync
 git add .
 git commit -m "improve workflow skill"
 git push -u origin my-change
@@ -61,9 +73,9 @@ Do not edit these generated folders directly:
 - `~/.claude/skills`
 - `~/.agents/skills`
 
-They are overwritten by `semantu-agents global`, `semantu-agents sync`, and `semantu-agents update`.
+In normal global mode, package-managed skills are copied from npm. In development mode, they are links managed by `dev`, `sync`, and `update`; edit the registered checkout instead.
 
-The dev post-merge hook runs `node cli.mjs sync` after pulls, so merged changes are synced globally automatically.
+Running `semantu-agents global` exits development mode and clears the registered checkout. Run `dev [path]` again to restore live links.
 
 ## Project Setup
 

package/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 import {execSync} from 'node:child_process';
-import {cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync} from 'node:fs';
 import {homedir} from 'node:os';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {directoryLinkType} from './lib/link-type.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
@@ -38,15 +39,6 @@ function cloneOrPull(dir) {
   }
 }
 
-function cloneIfMissing(dir) {
-  if (existsSync(path.join(dir, '.git'))) {
-    console.log('Using existing editable agents repo at ~/.agents-src');
-  } else {
-    console.log('Cloning agents repo...');
-    run(`git clone ${skillsRepo} ${dir}`);
-  }
-}
-
 function globalTargets() {
   const home = homedir();
   return [
@@ -55,93 +47,155 @@ function globalTargets() {
   ];
 }
 
-function syncSkillsInto(skillsSource, targets) {
-  if (!existsSync(skillsSource)) return;
+function skillSources(sourceDir, includePrivate) {
+  const sources = new Map();
+  const roots = [path.join(sourceDir, 'skills', 'public')];
+  if (includePrivate) roots.push(path.join(sourceDir, 'skills', 'private'));
 
-  for (const dest of targets) {
-    mkdirSync(dest, {recursive: true});
-    cpSync(skillsSource, dest, {recursive: true});
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const name of readdirSync(root)) {
+      const source = path.join(root, name);
+      if (statSync(source).isDirectory()) sources.set(name, source);
+    }
   }
+
+  return sources;
 }
 
-function syncFromSource(sourceDir, label = 'source checkout', options = {}) {
+function installSkillsFromSource(sourceDir, label, options = {}) {
   const includePrivate = options.includePrivate ?? true;
+  const mode = options.mode ?? 'copy';
   const targets = globalTargets();
-  const publicSkills = path.join(sourceDir, 'skills', 'public');
-  const privateSkills = path.join(sourceDir, 'skills', 'private');
+  const sources = skillSources(sourceDir, includePrivate);
 
   for (const dest of targets) {
-    rmSync(dest, {recursive: true, force: true});
+    mkdirSync(dest, {recursive: true});
+    for (const [name, source] of sources) {
+      // Replace only skills managed by this package; preserve every other entry in the global directory.
+      const target = path.join(dest, name);
+      rmSync(target, {recursive: true, force: true});
+      if (mode === 'link') {
+        symlinkSync(source, target, directoryLinkType(process.platform));
+      } else {
+        cpSync(source, target, {recursive: true});
+      }
+    }
   }
 
-  syncSkillsInto(publicSkills, targets);
-  if (includePrivate) {
-    syncSkillsInto(privateSkills, targets);
+  console.log(`${mode === 'link' ? 'Linked' : 'Synced'} skills from ${label} -> ~/.claude/skills/ and ~/.agents/skills/`);
+}
+
+function devConfigPath() {
+  return path.join(homedir(), '.config', 'semantu-agents', 'config.json');
+}
+
+function readDevConfig() {
+  const configPath = devConfigPath();
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    console.error(`Invalid development configuration: ${configPath}`);
+    console.error('Rerun `npx semantu-agents dev [path]` after removing or repairing this file.');
+    process.exit(1);
   }
+}
 
-  console.log(`Synced skills from ${label} -> ~/.claude/skills/ and ~/.agents/skills/`);
+function writeDevConfig(source) {
+  const configPath = devConfigPath();
+  mkdirSync(path.dirname(configPath), {recursive: true});
+  writeFileSync(configPath, `${JSON.stringify({source}, null, 2)}\n`);
 }
 
-function setupGlobal() {
-  syncFromSource(__dirname, 'npm package', {includePrivate: false});
-  console.log('\nDone. Public skills synced globally. Run `npx semantu-agents dev` to install an editable source checkout.');
+function clearDevConfig() {
+  rmSync(devConfigPath(), {force: true});
 }
 
-function installPostMergeHook(repoDir) {
-  const hooksDir = path.join(repoDir, '.git', 'hooks');
-  const hookPath = path.join(hooksDir, 'post-merge');
-  const hook = `#!/bin/sh
-[ "$SEMANTU_AGENTS_SKIP_HOOK_SYNC" = "1" ] && exit 0
-cd "$(git rev-parse --show-toplevel)" && node cli.mjs sync
-`;
-
-  mkdirSync(hooksDir, {recursive: true});
-  writeFileSync(hookPath, hook, {mode: 0o755});
-  console.log('Installed post-merge hook to sync global skills after pulls');
+function isAgentsCheckout(candidate) {
+  try {
+    const packageJson = JSON.parse(readFileSync(path.join(candidate, 'package.json'), 'utf8'));
+    return packageJson.name === 'semantu-agents' &&
+      existsSync(path.join(candidate, '.git')) &&
+      existsSync(path.join(candidate, 'skills', 'public'));
+  } catch {
+    return false;
+  }
 }
 
-function setupDev() {
-  const srcDir = path.join(homedir(), '.agents-src');
+function resolveDevSource(inputPath) {
+  if (inputPath) {
+    const resolved = path.resolve(inputPath);
+    if (isAgentsCheckout(resolved)) return realpathSync(resolved);
+    console.error(`Not an editable semantu-agents checkout: ${resolved}`);
+    process.exit(1);
+  }
+
+  const configured = readDevConfig()?.source;
+  const candidates = [
+    process.cwd(),
+    configured,
+    path.join(homedir(), 'packages', 'semantu-agents'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (isAgentsCheckout(resolved)) return realpathSync(resolved);
+  }
+
+  console.error('No editable semantu-agents checkout found.');
+  console.error('Run `npx semantu-agents dev /path/to/checkout` from an existing checkout.');
+  process.exit(1);
+}
 
-  cloneIfMissing(srcDir);
-  installPostMergeHook(srcDir);
-  syncFromSource(srcDir, '~/.agents-src');
+function setupGlobal() {
+  installSkillsFromSource(__dirname, 'npm package', {includePrivate: false});
+  clearDevConfig();
+  console.log('\nDone. Public skills synced globally. Run `npx semantu-agents dev [path]` to link an editable checkout.');
+}
 
-  console.log('\nDone. Edit skills in ~/.agents-src, run `node cli.mjs sync`, then commit and open a PR.');
+function setupDev(inputPath) {
+  const source = resolveDevSource(inputPath);
+  writeDevConfig(source);
+  installSkillsFromSource(source, source, {mode: 'link'});
+  console.log(`\nDone. Edit skills in ${source}; changes are available globally immediately.`);
 }
 
 function syncGlobalFromCurrentCheckout() {
-  syncFromSource(__dirname, 'current checkout');
+  setupDev(__dirname);
 }
 
 function updateDevCheckout() {
-  const srcDir = path.join(homedir(), '.agents-src');
-
-  if (!existsSync(path.join(srcDir, '.git'))) {
-    console.log('No editable checkout found at ~/.agents-src.');
-    console.log('Run `npx semantu-agents dev` if you have access to github.com:Semantu/agents.');
+  const source = readDevConfig()?.source;
+  if (!source || !isAgentsCheckout(source)) {
+    console.log('No registered editable checkout found.');
+    console.log('Run `npx semantu-agents dev [path]` from an existing checkout.');
     process.exit(1);
   }
 
-  const currentBranch = output('git branch --show-current', {cwd: srcDir});
-  const dirty = output('git status --porcelain', {cwd: srcDir});
+  const currentBranch = output('git branch --show-current', {cwd: source});
+  if (!currentBranch) {
+    console.log(`Cannot update ${source} from a detached HEAD.`);
+    console.log('Switch to a named branch, then rerun `npx semantu-agents update`.');
+    process.exit(1);
+  }
+  const dirty = output('git status --porcelain', {cwd: source});
 
   if (dirty) {
-    console.log('Cannot update ~/.agents-src because it has uncommitted changes.');
+    console.log(`Cannot update ${source} because it has uncommitted changes.`);
     console.log('Commit, stash, or discard them, then rerun `npx semantu-agents update`.');
     process.exit(1);
   }
 
-  run('git fetch origin main', {cwd: srcDir});
-  run('git switch main', {cwd: srcDir});
-  run('git pull --ff-only origin main', {
-    cwd: srcDir,
-    env: {...process.env, SEMANTU_AGENTS_SKIP_HOOK_SYNC: '1'},
-  });
-  syncFromSource(srcDir, '~/.agents-src');
-
-  if (currentBranch && currentBranch !== 'main') {
-    run(`git switch ${currentBranch}`, {cwd: srcDir});
+  run('git fetch origin main', {cwd: source});
+  try {
+    if (currentBranch !== 'main') run('git switch main', {cwd: source});
+    run('git pull --ff-only origin main', {cwd: source});
+    installSkillsFromSource(source, source, {mode: 'link'});
+  } finally {
+    if (currentBranch && currentBranch !== 'main') {
+      run(`git switch ${currentBranch}`, {cwd: source});
+    }
   }
 }
 
@@ -403,7 +457,7 @@ if (command === 'docs') {
 } else if (command === 'global' || isGlobal) {
   setupGlobal();
 } else if (command === 'dev') {
-  setupDev();
+  setupDev(args[1]);
 } else if (command === 'sync') {
   syncGlobalFromCurrentCheckout();
 } else if (command === 'update') {

package/lib/link-type.mjs

@@ -0,0 +1,3 @@
+export function directoryLinkType(platform) {
+  return platform === 'win32' ? 'junction' : 'dir';
+}

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "semantu-agents",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Reusable Claude Code skills and hooks for Semantu projects",
   "type": "module",
   "bin": "cli.mjs",
   "files": [
     "cli.mjs",
+    "lib",
     "skills/public"
   ],
   "scripts": {
-    "sync": "node cli.mjs sync"
+    "sync": "node cli.mjs sync",
+    "test": "node --test test/*.test.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.29.8"
+    "@changesets/cli": "^2.29.8",
+    "js-yaml": "^4.3.2"
   },
   "dependencies": {
     "gray-matter": "^4.0.3"

package/skills/public/automatic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: automatic
-description: Execute the full workflow cycle (ideation -> plan -> tasks -> implementation -> review) without waiting for user confirmation between modes. Use only when the user explicitly requests automatic mode. Never auto-suggest or auto-enter this mode. Pause after review and ask whether to continue with wrapup or iterate.
+description: Execute the full workflow cycle and automatically iterate on review findings of medium severity or higher. Use only when the user explicitly requests automatic mode. Never auto-suggest or auto-enter this mode.
 ---
 
 # Instructions
@@ -21,7 +21,7 @@ Run the standard workflow end-to-end without waiting for user confirmation betwe
 4. `implementation`
 5. `review`
 
-Then pause.
+Automatically iterate on review findings until only low/minor gaps remain, then pause.
 
 ## Core behavior
 
@@ -34,9 +34,7 @@ Then pause.
    For each decision, show the reasoning and chosen option in chat, then record it in the active plan doc just as in interactive mode.
 4. **Progress indicators**: When walking through decisions or gaps, always show position — e.g. "Decision 2 of 5" — so the user can gauge progress when reviewing.
 5. After ideation is complete, continue immediately into plan mode, then tasks mode, then implementation mode, then review mode.
-6. Pause after review and ask the user to choose exactly one:
-   - `wrapup`
-   - `iterate` — select which gaps to address
+6. After review, automatically iterate on every medium-or-higher gap, including stale comments and documentation. Leave low/minor gaps for the final review pause.
 
 ## Mandatory transition gates
 
@@ -83,9 +81,9 @@ Follow numbering and conversion rules from workflow mode.
 
 ## Iterate loop
 
-If the user chooses `iterate` after review:
+After each review:
 
-1. Ask the user which review-identified gaps to address now and which to defer.
+1. Classify findings as critical/urgent, high, medium, or low/minor. Select every medium-or-higher gap, plus stale comments and documentation.
 2. **All iteration work stays in the active plan document.** Do not create additional plan docs for iteration gaps.
 3. Append the following sections to the plan doc:
 
@@ -113,11 +111,8 @@ If the user chooses `iterate` after review:
 ```
 
 4. Walk through ideation for **all selected gaps first** (in chat batches where possible, emulating user responses with the same priority framework), then condense into a plan, then break into phases/tasks, then implement all phases.
-5. After implementation, run review again. Pause and ask:
-   - `wrapup`
-   - `iterate`
-
-Repeat until the user selects `wrapup` or stops.
+5. After implementation, run review again and repeat while selected gaps remain.
+6. When only low/minor gaps remain, pause and ask whether to `wrapup` or address any remaining gap.
 
 ## Handoff to wrapup
 
@@ -135,5 +130,5 @@ Enter `wrapup` only after the user explicitly chooses `wrapup` at a review pause
 
 ## Exit criteria
 
-- Reached review mode and paused with explicit `wrapup` vs `iterate` question, or
+- Completed review iterations until only low/minor gaps remain and paused, or
 - User explicitly selected `wrapup` and control has been handed off to wrapup mode.

package/skills/public/explore/SKILL.md

@@ -18,16 +18,17 @@ Run this skill when the user explicitly says `explore <topic>`, clearly asks to
 1. Confirm scope only if the topic is ambiguous; otherwise proceed directly.
 2. Decompose the topic into decision candidates and unknowns.
 3. Prioritize planning blockers first when called from ideation or review iteration.
-4. For each decision, give concise context and assumptions, then provide exactly 3 viable approaches (A-C).
-5. For each approach, list pros, cons, and risks.
-6. Recommend one approach (A/B/C) with a one-line rationale.
-7. If there are multiple decisions, present them in batches of 3 by default (use fewer only when fewer remain or when the user asks for a different batch size). Start with `Decision x-y of N`, and end with `Recap: 1A 2C 3B`; ask for agreement or edits.
+4. Before presenting options, explain the affected area, current behavior, wider context, and why the decision matters. Assume the user may not know the implementation. Include code, before/after, or concrete examples when useful.
+5. Present exactly 3 viable approaches (A–C), each with pros, cons, and risks. Mark the suggested option in its heading with **(Recommended)**.
+6. Immediately after that decision's options, add a separate **Recommendation** section naming the suggested option and why it is the best fit. Do this before presenting the next decision; never collect recommendations at the end of a batch.
+7. If there are multiple decisions, present them in batches of 3 by default (use fewer only when fewer remain or when the user asks for a different batch size). Start with `Decision x-y of N`, and end with `Recap: 1A 2C 3B`; ask for agreement or edits in normal chat.
 8. Iterate until consent; no feedback on a decision counts as acceptance after an explicit agreement prompt.
 9. Recurse only for nested decisions that block planning. Default max depth is 2 unless the user asks for deeper drilldown.
-10. After consent, ask whether to continue the current mode or switch modes.
+10. After consent, ask whether to continue the current mode or switch modes in normal chat.
 
 ## Guardrails
 
+- Do not use interactive question tools such as `AskUserQuestion`, `request_user_input`, picker UIs, or multiple-choice tool prompts. They interrupt reading the proposals. Ask follow-up questions as ordinary chat text.
 - Do not force a mode switch by default; this skill can run inside any active mode.
 - Do not create ideation/plan artifacts unless the active mode requires them or the user asks.
 - When called from ideation, explore in chat first and let ideation persist only accepted decisions.

package/skills/public/implementation/SKILL.md

@@ -17,7 +17,7 @@ Run only after explicit user confirmation to enter implementation mode, with an
 4. Before completing a phase, compare changed behavior/API/contracts against the plan's Architecture compliance section.
 5. Run the phase validation criteria and record results, including the quick regression gate for impacted packages (target total runtime 1-2 minutes).
 6. After a phase is completed, update `docs/plans/<nnn>-<topic>.md` to reflect completed work and mark phase status. This update is mandatory before moving to the next phase.
-7. Create one commit per phase, including code changes and the phase-completion plan update in the same commit.
+7. Create one commit per phase per repository. Never combine parent and nested repository changes. For reusable packages, keep root-project-specific names out of commit messages. Include code changes and the phase-completion plan update in the same commit.
 8. Continue to next phase without pausing only if there are no deviations and no major problems.
 9. If any deviation/blocker/major risk appears, pause and report.
 
@@ -43,7 +43,7 @@ When the plan marks phases as parallelizable, use the Task tool (or any availabl
 
 ## Documentation
 
-- Update `docs/reports` when pausing for deviations/problems.
+- Record deviations and problems in the active plan. Never update historical reports.
 
 ## Guardrails
 

package/skills/public/review/SKILL.md

@@ -14,11 +14,17 @@ Run only when the user explicitly confirms review mode.
 1. Set or update the active plan frontmatter status to `Review`.
 2. Compare current implementation against the original intent and agreed plan.
 3. Assess whether the result is ready for others to use.
-4. Identify what is still missing to make this work more complete.
-5. Identify gaps or risks in the current implementation.
-6. Identify likely future work required for fuller completeness.
-7. Re-run deferred full/slow test suites for all impacted repos/packages from the plan's test strategy, and report pass/fail with any skipped checks and reasons.
-8. Audit architecture compliance:
+4. Spend independent attention on each review pass below. Do not collapse these into a single generic gap scan:
+   - **Intent and plan fit**: What was promised, what exists, and what diverged.
+   - **Remaining functional gaps**: Missing behavior, incomplete flows, unhandled edge cases, or acceptance criteria that are only partially met.
+   - **Weaknesses and issues**: Bugs, brittle assumptions, confusing UX/API behavior, failure modes, data integrity risks, security/privacy concerns, performance risks, and operational risks.
+   - **Cleanup needed**: Dead code, unused files, stale scaffolding, naming drift, duplication, unnecessary TODOs, and generated artifacts that should not remain.
+   - **Simplification opportunities**: Overbuilt abstractions, needless configuration, avoidable branching, complicated contracts, or places where less code would be clearer.
+   - **Comments needed**: Non-obvious intent, invariants, boundary conditions, or algorithms that need concise explanatory comments.
+   - **Documentation updates**: README, setup instructions, examples, architecture docs, API docs, env/config notes, changelogs, reports, or plan docs that need to reflect the work.
+   - **Tests and validation**: Missing coverage, weak assertions, manual QA still needed, deferred suites to rerun, and any checks that should be added before external use.
+5. Re-run deferred full/slow test suites for all impacted repos/packages from the plan's test strategy, and report pass/fail with any skipped checks and reasons.
+6. Audit architecture compliance:
    - Run `npx semantu-agents docs architecture`.
    - Re-read the architecture docs cited by the plan.
    - Compare changed code, behavior, APIs, and contracts against those docs.
@@ -28,26 +34,46 @@ Run only when the user explicitly confirms review mode.
 
 When the implementation spans multiple modules or many files, spawn subagents to review different areas concurrently. For example: one agent reviews API surface correctness, another checks test coverage against the plan, another checks for dead code or missing error handling.
 
-Each review subagent receives: the relevant plan section, the list of files in its review area, and the specific review questions to answer. Subagents report findings; the main agent synthesizes results into the gap list presented to the user.
+Each review subagent receives: the relevant plan section, the list of files in its review area, and the specific review questions to answer. Subagents report findings; the main agent synthesizes results into the review sections presented to the user.
 
 ## Output
 
 Review findings must be emitted in chat first.
 Do not write findings to plan or report files until decisions are clarified with the user.
 
-Present each gap with a **progress indicator** — e.g. "Gap 1 of 4" — so the user knows how many remain.
+Use these sections in the review output. Each section must either list findings or explicitly say `No findings`.
 
-## Gap triage
+```markdown
+## Intent and Plan Fit
+## Remaining Functional Gaps
+## Weaknesses / Issues
+## Cleanup Needed
+## Simplification Opportunities
+## Comments Needed
+## Documentation Updates
+## Tests / Validation
+## Architecture Compliance
+## Proposed Fixes and Improvements
+## Proposed Deferrals
+```
+
+Present each actionable finding with a **progress indicator** — e.g. "Finding 1 of 7" — so the user knows how many remain.
 
-After presenting all gaps, ask the user:
+At the end of the review, the agent must independently propose:
+- **Proposed Fixes and Improvements**: A prioritized list of things that should be fixed, improved, cleaned up, simplified, documented, commented, or validated before wrapup. This list is based on the whole review, not only direct plan misses.
+- **Proposed Deferrals**: A separate list of work that can genuinely wait because it belongs to a later phase of the active plan, another plan, or a future todo/backlog item. For each deferral, state why it is not part of the current completion bar.
 
-> "Which of these gaps do you want to address now, and which should we defer?"
+## Finding triage
 
-For gaps the user wants to **address now** (iterate):
+After presenting all findings and the proposed fix/defer lists, ask the user:
+
+> "Which proposed fixes/improvements should we address now, which should we defer, and which risks do you accept as-is?"
+
+For findings the user wants to **address now** (iterate):
 - These will go through a full ideation → plan → tasks → implementation cycle.
 - All iteration work stays in the active plan document (see Iteration structure below).
 
-For gaps the user wants to **defer**:
+For findings the user wants to **defer**:
 - Create backlog docs in `docs/backlog/` using the `todo` skill to capture what's known so far:
   - The problem/need (e.g. "currently we can only do X, but we want Y")
   - Existing context and open questions that surfaced during review
@@ -56,26 +82,30 @@ For gaps the user wants to **defer**:
   - Create separate backlog docs only for very different, large deferred tasks
   - Assign the next available 3-digit prefix in `docs/backlog` for each new doc
 
+For risks the user explicitly accepts:
+- Record the accepted risk and rationale in the review section.
+- Do not create a backlog item unless the user also wants future tracking.
+
 ## Iteration structure
 
-When the user chooses to iterate on gaps, append to the **active plan document**:
+When the user chooses to iterate on findings, append to the **active plan document**:
 
 ```markdown
 ## Review
 
-<gap analysis findings>
+<review findings and proposed fix/defer lists>
 
 ## Iteration {n} — Ideation
 
-### Gap 1 of {total}: <gap title>
+### Finding 1 of {total}: <finding title>
 <ideation content: context, approaches, pros/cons, chosen approach, rationale>
 
-### Gap 2 of {total}: <gap title>
+### Finding 2 of {total}: <finding title>
 ...
 
 ## Iteration {n} — Plan
 
-<condensed plan for all gaps: architecture decisions, file changes, contracts>
+<condensed plan for all selected findings: architecture decisions, file changes, contracts>
 
 ## Iteration {n} — Phases
 
@@ -84,16 +114,16 @@ When the user chooses to iterate on gaps, append to the **active plan document**
 ```
 
 The ideation within this section follows the same rules as the ideation skill:
-- Build an open-item map for selected gaps.
+- Build an open-item map for selected findings.
 - Immediately use `explore` on the highest-priority planning blockers in chat, in batches of 3 where possible.
 - Record accepted decisions only after consent.
 - Keep the active plan document lightweight until decisions are accepted.
 
-**Ideate all selected gaps first**, then condense into a plan section, then break into phases/tasks. Do not run the full cycle per individual gap.
+**Ideate all selected findings first**, then condense into a plan section, then break into phases/tasks. Do not run the full cycle per individual finding.
 
 ## Follow-up questions before switching modes
 
-**After ideation for all gaps is complete, ask implementation-specific follow-up questions before moving forward.** Gaps identified during review are often under-specified. Proactively ask about:
+**After ideation for all selected findings is complete, ask implementation-specific follow-up questions before moving forward.** Findings identified during review are often under-specified. Proactively ask about:
 
 - **Placement decisions**: Where should new files/configs live?
 - **Tool/dependency choices**: Which specific library, image, or tool version to use?
@@ -103,25 +133,29 @@ The ideation within this section follows the same rules as the ideation skill:
 
 ## Guardrails
 
-- Do not perform cleanup/release tasks in this mode; use wrapup mode for that.
+- Do not rush from review to wrapup. Assume review usually uncovers follow-up work that deserves careful triage.
+- Do not perform release-prep tasks in this mode; use wrapup mode for that. Review mode may identify cleanup, simplification, comments, docs, and validation work, then route it through iteration or deferral.
 - Do not remove `docs/plans/<nnn>-<topic>.md` in review mode; plan removal happens in wrapup after report approval.
 - If big remaining work is identified, discuss tradeoffs/solutions in chat first.
-- Only convert review findings into iteration content after the user confirms which gaps to address.
+- Only convert review findings into iteration content after the user confirms which findings to address.
 - For newly uncovered work, always go through ideation first — never skip straight to tasks or implementation.
 - If the user's response involves clarifying approach or scope, treat this as still in the clarification loop — ask follow-ups for any remaining ambiguity.
 - Do not claim review completion without test evidence for impacted packages (or explicit user-approved skips).
 - Do not claim review completion without architecture compliance findings.
+- Do not claim review completion until every required output section has been assessed with findings or `No findings`.
+- Do not recommend wrapup until the proposed fixes/improvements list has been triaged.
 - Do not decide that work is out of scope yourself. Only create backlog items after the user explicitly agrees to defer them.
 
 ## Exit criteria
 
-- Gaps are triaged with explicit user decisions (now vs defer).
-- If iterating: ideation for all selected gaps is recorded in the plan doc, and user has confirmed next step.
-- If deferring: backlog docs were created for user-deferred gaps.
+- Findings are triaged with explicit user decisions (fix/improve now, defer, or accept risk).
+- If iterating: ideation for all selected findings is recorded in the plan doc, and user has confirmed next step.
+- If deferring: backlog docs were created for user-deferred findings.
+- Accepted risks, if any, are recorded with rationale.
 - Deferred full/slow test suites for impacted packages were executed and reported, or explicitly skipped with user approval.
 - Architecture compliance was checked against the plan's cited architecture docs and reported.
 - The active plan doc has `status: Review` and is committed unless the repo ignores `docs/`.
 - User has explicitly confirmed whether to:
-  - **Iterate** — proceed to plan the ideated gaps (manually via plan mode, or via automatic mode for plan → tasks → implementation → review)
+  - **Iterate** — proceed to plan the ideated findings (manually via plan mode, or via automatic mode for plan → tasks → implementation → review)
   - **Wrapup** — no more work needed, move to wrapup mode
-  - **Defer all** — all gaps deferred, move to wrapup mode
+  - **Defer all** — all findings deferred, move to wrapup mode

package/skills/public/tasks/SKILL.md

@@ -21,6 +21,7 @@ Run only when the user explicitly confirms tasks mode.
    - full/slow suites deferred to review.
 6. Write detailed test specifications for every phase (see **Test specification** below).
 7. Ensure phases are commit-friendly (one commit per phase).
+8. When work spans repositories, separate phases and validation by repository.
 
 ## Parallel execution
 

package/skills/public/workflow/SKILL.md

@@ -18,6 +18,7 @@ description: Enforce the explicit mode cadence (ideation -> plan -> tasks -> imp
 
 ## Mode selection at task start
 
+- At task start, inspect `package.json` workspaces and Git roots under their package paths. If work spans repositories, handle branches, commits, changesets, and PRs separately for each repository.
 - If the user has already explicitly chosen a mode (or explicitly called a mode skill), enter that mode directly.
 - `automatic` is a special meta mode and can only be entered when the user explicitly requests it.
 - Never auto-suggest `automatic` in startup prompts.
@@ -76,6 +77,7 @@ These transition gates apply to standard modes. `automatic` mode is an explicit
 - One task/thread uses one active plan doc from ideation through review. Do not create additional plan docs for the same thread.
 - Update the active plan doc `status` frontmatter when entering each mode.
 - Before switching from ideation, plan, tasks, or review, commit the final active plan state unless the repo ignores `docs/`.
+- Existing files in `docs/reports` are historical snapshots. Never edit them; apply later documentation fixes and renames only to current documentation.
 - After each completed implementation phase, the on-disk plan file MUST be updated before moving to the next phase.
 - Each implementation phase MUST be committed with code changes and the updated plan together.
 - Mode changes are never implicit; every mode switch requires explicit user confirmation.

package/skills/public/wrapup/SKILL.md

@@ -44,6 +44,7 @@ Also treat any user request to prepare/open/update a PR, or draft PR title/body/
 13. Changeset handling — see the dedicated section below.
 14. Draft a PR title and PR message/body summarizing changes, validation, architecture doc updates, and follow-up notes.
 15. **Final commit**: all cleanup (comments, dead code removal, plan deletion, report) must be committed before creating the PR.
+16. Prepare commits, changesets, and PRs separately for each repository.
 
 ## Report quality
 
@@ -73,6 +74,10 @@ The report replaces the plan as the permanent record. Any agent working on code
 
 **Sizing guideline:** If the plan was 500+ lines, the report should be at least 150-300 lines. A 10-line report for a 3000-line plan means critical information was lost.
 
+## Reusable package wording
+
+For nested repositories and reusable packages under `packages/`, keep root-project, app, client, and product names out of branch names, commit messages, PR titles/bodies, changeset filenames, and changeset prose. Use generic capability language. Exact package names are allowed where tooling requires them, such as changeset frontmatter.
+
 ## Changeset handling
 
 **Always create a changeset** when package code changed, even if other changesets already exist. Each changeset becomes a separate entry in the public changelog via CI/CD, so it should describe what users of the library need to know about THIS set of changes.