semantu-agents 1.2.2 → 1.3.1

package/README.md

@@ -81,7 +81,7 @@ Print a markdown or JSON index of docs that use YAML frontmatter.
 
 ```bash
 npx semantu-agents docs
-npx semantu-agents docs ideas
+npx semantu-agents docs backlog
 npx semantu-agents docs architecture
 npx semantu-agents docs --all
 npx semantu-agents docs --format markdown
@@ -92,7 +92,7 @@ Supported scopes:
 
 - `root` (default) -> `docs/*.md`
 - `architecture` -> `docs/architecture/*.md`
-- `ideas` -> `docs/ideas/*.md`
+- `backlog` -> `docs/backlog/*.md`
 - `plans` -> `docs/plans/*.md`
 - `reports` -> `docs/reports/*.md`
 
@@ -126,4 +126,5 @@ Both are merged into the same flat `.claude/skills/` directory at sync time.
 | `implementation` | Execute tasks phase-by-phase with commits and validation |
 | `review` | Review work against intent, readiness, and gaps; triage iterate vs defer |
 | `wrapup` | Cleanup, changesets, and PR preparation |
+| `todo` | Capture user-deferred follow-up work in `docs/backlog` |
 | `automatic` | Run the full workflow without manual mode transitions |

package/cli.mjs

@@ -15,7 +15,7 @@ const skillsRepo = 'git@github.com:Semantu/agents.git';
 const DOC_FOLDERS = {
   root: 'docs',
   architecture: path.join('docs', 'architecture'),
-  ideas: path.join('docs', 'ideas'),
+  backlog: path.join('docs', 'backlog'),
   plans: path.join('docs', 'plans'),
   reports: path.join('docs', 'reports'),
 };
@@ -91,6 +91,7 @@ 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
 `;
 
@@ -133,7 +134,10 @@ function updateDevCheckout() {
 
   run('git fetch origin main', {cwd: srcDir});
   run('git switch main', {cwd: srcDir});
-  run('git pull --ff-only origin 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') {
@@ -208,7 +212,7 @@ function setupProject() {
     console.log('Updated .gitignore');
   }
 
-  for (const dir of ['docs/ideas', 'docs/plans', 'docs/reports']) {
+  for (const dir of ['docs/backlog', 'docs/plans', 'docs/reports']) {
     const fullPath = path.join(projectRoot, dir);
     if (!existsSync(fullPath)) {
       mkdirSync(fullPath, {recursive: true});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantu-agents",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Reusable Claude Code skills and hooks for Semantu projects",
   "type": "module",
   "bin": "cli.mjs",

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,22 +21,20 @@ 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
 
 1. Execute each mode in sequence using the same requirements and artifact rules as the corresponding individual mode skills.
 2. Keep momentum: do not stop between internal mode transitions unless blocked by missing mandatory input, hard failures, or safety constraints.
-3. **Ideation in automatic mode** follows the exact same flow as the interactive ideation skill (discover decision points, walk through each one, record decisions), but the agent emulates user responses instead of waiting for input. Apply this priority framework when choosing between approaches:
+3. **Ideation in automatic mode** follows the exact same flow as the interactive ideation skill (create the active plan doc, discover open items, explore planning blockers, record accepted decisions), but the agent emulates user responses instead of waiting for input. Apply this priority framework when choosing between approaches:
    1. **Long-term maintainability** — simplicity, elegance, least complexity
    2. **Scalability** — handles growth without redesign
    3. **Performance** — fastest/most efficient option
-   For each decision, show the reasoning and chosen option in chat, then record it in the ideation doc just as in interactive mode.
+   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
 
@@ -45,16 +43,19 @@ Never transition to the next mode until the current mode's required on-disk arti
 Before leaving each mode, enforce all checks below:
 
 1. Ideation -> Plan gate:
-   - A concrete ideation doc exists/was updated in `docs/ideas/<nnn>-<topic>.md`.
-   - The doc contains alternatives, tradeoffs, and a clearly selected route.
+   - A concrete active plan doc exists/was updated in `docs/plans/<nnn>-<topic>.md`.
+   - The plan doc has `status: Ideation`.
+   - The doc contains planning blockers, accepted decisions, and a clearly selected route.
 
 2. Plan -> Tasks gate:
    - A plan doc exists/was updated in `docs/plans/<nnn>-<topic>.md`.
+   - The plan doc has `status: Plan`.
    - The plan includes architecture decisions, expected file changes, pitfalls, and explicit contracts.
    - The plan is focused on the chosen route (not a list of all routes).
 
 3. Tasks -> Implementation gate:
    - The same plan doc includes phased tasks.
+   - The plan doc has `status: Tasks`.
    - Every phase has explicit validation criteria.
    - Dependency graph / parallelization notes are present.
 
@@ -62,6 +63,7 @@ Before leaving each mode, enforce all checks below:
    - Implementation work is executed phase by phase against the tasked plan.
    - Validation for each completed phase is run and recorded.
    - The plan doc is updated after each completed phase before moving on.
+   - The plan doc has `status: Implementation`.
 
 If any gate check fails, stop and fix the missing artifact first. Do not implement code before the tasks gate is satisfied.
 
@@ -69,8 +71,8 @@ If any gate check fails, stop and fix the missing artifact first. Do not impleme
 
 Use the same artifact contract as the normal workflow:
 
-- `ideation`: create/update `docs/ideas/<nnn>-<topic>.md`
-- `plan`: create/update `docs/plans/<nnn>-<topic>.md`
+- `ideation`: create/update the active `docs/plans/<nnn>-<topic>.md`
+- `plan`: update the same active plan doc
 - `tasks`: update the active plan doc with phases/tasks/validation
 - `implementation`: execute phases and update the active plan doc after completed phases
 - `review`: emit findings in chat, then update plan doc with review section and iteration content
@@ -79,10 +81,10 @@ 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.
-2. **All iteration work stays in the active plan document.** Do not create new ideation docs for iteration gaps.
+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:
 
 ```markdown
@@ -108,12 +110,9 @@ If the user chooses `iterate` after review:
 ...
 ```
 
-4. Walk through ideation for **all selected gaps first** (one by one, 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.
+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 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
 
@@ -131,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

@@ -11,24 +11,26 @@ Provide a reusable deep-dive format for `explore <topic>` in any mode, including
 
 ## Entry gate
 
-Run this skill when the user explicitly says `explore <topic>` (or clearly asks to explore a topic in this format).
+Run this skill when the user explicitly says `explore <topic>`, clearly asks to explore a topic in this format, or another active skill delegates decision exploration.
 
 ## Steps
 
 1. Confirm scope only if the topic is ambiguous; otherwise proceed directly.
 2. Decompose the topic into decision candidates and unknowns.
-3. For each decision, classify as `must decide now` or `can defer`.
-4. For each `must decide now` 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.
+3. Prioritize planning blockers first when called from ideation or review iteration.
+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.
+6. After all options, add a separate **Recommendation** section naming the suggested option and why it is the best fit.
+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 classified as `must decide now`; defer the rest. 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.
+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 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.
 - Keep outputs structured and concise; avoid repeating unchanged context.
-- Do not recurse indefinitely; respect the depth cap and defer non-blocking items.
+- Do not recurse indefinitely; respect the depth cap and keep non-blocking items as open context.

package/skills/public/ideation/SKILL.md

@@ -16,26 +16,47 @@ Run this mode when the user explicitly chooses ideation, or when workflow routes
 ## Steps
 
 1. Read relevant code, tests, and docs first.
-2. Create/update `docs/ideas/<nnn>-<topic>.md`.
-   - For new ideation docs, `<nnn>` MUST be the next available 3-digit prefix in `docs/ideas`.
-   - Every new ideation doc MUST start with YAML frontmatter containing at least a summary key.
-3. Discover impacted repo/package test surfaces:
+2. Create/update the active plan doc in `docs/plans/<nnn>-<topic>.md` with `status: Ideation`.
+   - For new plan docs, `<nnn>` MUST be the next available 3-digit prefix in `docs/plans`.
+   - Every new plan doc MUST start with YAML frontmatter containing at least `summary` and `status: Ideation`.
+   - If starting from `docs/backlog/<nnn>-<topic>.md`, copy relevant context into the plan and add a source backlog reference in frontmatter or the opening section.
+3. Discover relevant architecture context:
+   - Run `npx semantu-agents docs architecture` to list architecture docs and summaries.
+   - Read the docs relevant to the current scope before proposing approaches.
+   - Record applicable constraints and architecture unknowns/gaps in the active plan doc.
+4. Discover impacted repo/package test surfaces:
    - Locate changed package roots (root repo and/or `packages/<name>` roots as applicable).
    - For each impacted package, identify quick test commands (target total runtime 1-2 minutes), full/slow test commands, and where each was found (`package.json` scripts first, README fallback).
    - Record unknowns/gaps when no reliable quick regression command exists.
-4. Build a decision map: list major decisions, unknowns, and research gaps.
-5. Classify each item as `must decide now` (blocks planning) or `can defer`.
-6. Use the `explore` skill for each `must decide now` decision/topic.
-7. Record accepted choices, deferred unknowns, and discovered test surfaces in the ideation doc.
-8. Continue until blocking decisions reach consent; then ask whether to switch to `plan` mode.
+5. Build an open-item map: list decisions, gaps, assumptions, architecture questions, research needs, unclear requirements, impact questions, and implementation risks.
+6. Mark which open items block planning.
+7. Immediately use the `explore` skill on the highest-priority planning blockers in batches of 3. Do not ask where to start unless priority is genuinely ambiguous.
+8. Use chat as the primary place for A/B/C decision exploration. Keep the active plan doc lightweight until choices are accepted.
+9. After each accepted batch, record the chosen option, rationale, relevant context, and brief rejected-alternative summary in the active plan doc.
+10. Continue until planning blockers reach consent; then ask whether to switch to `plan` mode.
+
+## Open-item examples
+
+Use these examples as discovery prompts, not a checklist. Surface only open items that are relevant to the current scope and important enough to affect the plan:
+- Unknown implementation details or code paths that need research.
+- Effects on other packages, APIs, data flows, runtime behavior, or developer workflows.
+- Architecture constraints, violations, extensions, or documentation updates.
+- Public API, naming, ownership, storage, auth, deployment, or package-boundary decisions.
+- Migration, backwards compatibility, release, or rollout questions.
+- Testing gaps, missing quick regression checks, or slow-suite risks.
+- Performance, security, reliability, error handling, or observability concerns.
+- UX/product scope ambiguities when they affect technical design.
 
 ## Guardrails
 
 - Do not write implementation code in this mode.
 - Do not convert ideation into a plan unless the user explicitly requests it.
+- Do not write full A/B/C analysis into the active plan doc before user consent; explore in chat first.
+- Do not decide that work is out of scope yourself. If a follow-up seems outside the current scope, propose deferring it; only create a backlog item with the `todo` skill after the user explicitly agrees.
 
 ## Exit criteria
 
-- Blocking decisions and deferred unknowns are documented.
+- Planning blockers, architecture context, and accepted decisions are documented.
 - User feedback has narrowed choices.
+- The active plan doc has `status: Ideation` and is committed unless the repo ignores `docs/`.
 - User has explicitly confirmed whether to switch to plan mode or stay in ideation mode.

package/skills/public/implementation/SKILL.md

@@ -12,13 +12,14 @@ Run only after explicit user confirmation to enter implementation mode, with an
 ## Steps
 
 1. Confirm the approved plan exists on disk at `docs/plans/<nnn>-<topic>.md`. Tool-native plan mode alone is not sufficient.
-2. If this plan stems from an ideation doc, remove the originating ideation doc in `docs/ideas` when implementation begins.
+2. Set or update the active plan frontmatter status to `Implementation`.
 3. Implement one planned phase at a time.
-4. Run the phase validation criteria and record results, including the quick regression gate for impacted packages (target total runtime 1-2 minutes).
-5. 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.
-6. Create one commit per phase, including code changes and the phase-completion plan update in the same commit.
-7. Continue to next phase without pausing only if there are no deviations and no major problems.
-8. If any deviation/blocker/major risk appears, pause and report.
+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 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.
 
 Full/slow test suites may be deferred until review by default. Run deferred suites earlier only if the user requests it.
 
@@ -42,14 +43,15 @@ 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
 
-- If the originating ideation doc is ambiguous, pause and ask the user which ideation file to remove.
 - Do not skip plan updates between completed phases.
 - Do not switch to review/wrapup implicitly; ask the user to explicitly confirm the next mode.
 - Do not mark a phase complete if its quick regression gate fails.
+- Do not silently diverge from architecture docs or the plan's Architecture compliance section; pause and report deviations.
+- Do not decide that work is out of scope yourself. If a follow-up seems outside the current scope, propose deferring it; only create a backlog item with the `todo` skill after the user explicitly agrees.
 
 ## Exit criteria
 

package/skills/public/plan/SKILL.md

@@ -11,11 +11,12 @@ Run only when the user explicitly confirms plan mode (for example: converting id
 
 ## Steps
 
-1. Create/update `docs/plans/<nnn>-<topic>.md`. This on-disk plan file is mandatory.
-   - When creating a new plan doc (including ideation -> plan conversion), `<nnn>` MUST be the next available 3-digit prefix in `docs/plans`.
-   - Every new plan doc MUST start with YAML frontmatter containing at least a summary key.
+1. Update the active plan doc in `docs/plans/<nnn>-<topic>.md` and set frontmatter `status: Plan`. This on-disk plan file is mandatory.
+   - Create a new plan doc only when plan mode starts without an existing active plan.
+   - When creating a new plan doc, `<nnn>` MUST be the next available 3-digit prefix in `docs/plans`.
+   - Every new plan doc MUST start with YAML frontmatter containing at least `summary` and `status: Plan`.
 2. Focus on chosen route(s), not all explored options.
-3. **Carry forward all decided features and details from the ideation doc.** Every feature, API surface, design detail, and example that was explored and not explicitly rejected must appear in the plan. No idea can be silently dropped. If unsure whether something was tentatively discussed or firmly decided, ask the user for clarification rather than omitting it.
+3. **Carry forward all accepted ideation decisions already captured in the active plan doc.** Every feature, API surface, design detail, and example that was accepted and not explicitly rejected must appear in the plan. No accepted idea can be silently dropped. If unsure whether something was tentatively discussed or firmly decided, ask the user for clarification rather than omitting it.
 4. Include:
    - Main architecture decisions
    - Files expected to change
@@ -23,6 +24,11 @@ Run only when the user explicitly confirms plan mode (for example: converting id
    - Potential pitfalls
    - Remaining unclear areas/decisions
    - **Inter-component contracts**: When the architecture has separable parts (layers, modules, packages), make the contracts between them explicit — type definitions, function signatures, shared data structures. These contracts enable parallel implementation in tasks mode.
+   - **Architecture compliance**:
+     - relevant `docs/architecture` files discovered with `npx semantu-agents docs architecture`
+     - applicable constraints from those docs
+     - how the chosen design follows them
+     - any approved architecture change, extension, or unresolved gap
    - **Test strategy**:
      - impacted repo/package list
      - quick regression gate commands (target total runtime 1-2 minutes) to run after each phase
@@ -37,10 +43,14 @@ Run only when the user explicitly confirms plan mode (for example: converting id
 - Do not add task breakdown in this mode.
 - Do not start implementation.
 - Do not rely on tool-native planning state alone; all plan content MUST be persisted to `docs/plans/<nnn>-<topic>.md`.
-- Do not remove the ideation doc in this mode.
+- Do not create a second plan doc for the same task/thread.
+- Do not approve a plan without naming the relevant architecture docs, or explicitly stating that none were found.
+- Do not decide that work is out of scope yourself. If a follow-up seems outside the current scope, propose deferring it; only create a backlog item with the `todo` skill after the user explicitly agrees.
 
 ## Exit criteria
 
 - Plan clearly reflects chosen decisions.
+- Relevant architecture docs are named and the plan explains compliance or approved deviations.
 - Risks and open questions are explicit.
+- The active plan doc has `status: Plan` and is committed unless the repo ignores `docs/`.
 - User has explicitly approved the plan and explicitly confirmed whether to switch to tasks mode or remain in plan mode.

package/skills/public/review/SKILL.md

@@ -11,65 +11,101 @@ Run only when the user explicitly confirms review mode.
 
 ## Review focus
 
-1. Compare current implementation against the original intent and agreed plan.
-2. Assess whether the result is ready for others to use.
-3. Identify what is still missing to make this work more complete.
-4. Identify gaps or risks in the current implementation.
-5. Identify likely future work required for fuller completeness.
-6. 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.
+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. 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.
+   - Report architecture violations, missing architecture updates, or explicitly state that no architecture issues were found.
 
 ## Parallel review via subagents
 
 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**:
-- Create ideation docs in `docs/ideas/` to capture what's known so far:
+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")
-  - Any approaches, ideas, or open questions that surfaced during review
+  - Existing context and open questions that surfaced during review
   - Do NOT expand beyond what was discovered — just write up the current state
-  - Group related deferred items into one ideation doc
-  - Create separate ideation docs only for very different, large deferred tasks
-  - Assign the next available 3-digit prefix in `docs/ideas` for each new doc
+  - Group related deferred items into one backlog doc
+  - 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
 
@@ -78,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:
-- Walk through each gap one by one with the user
-- For each gap: present context, 2–3 approaches, pros/cons, recommended path
-- Wait for user input before moving to the next gap
-- Record decisions as they're made
+- 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?
@@ -97,21 +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: ideation docs were created for 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

@@ -11,7 +11,7 @@ Run only when the user explicitly confirms tasks mode.
 
 ## Steps
 
-1. Update the active plan doc in `docs/plans/<nnn>-<topic>.md`. Task breakdown MUST be persisted in this same on-disk plan file.
+1. Update the active plan doc in `docs/plans/<nnn>-<topic>.md` and set frontmatter `status: Tasks`. Task breakdown MUST be persisted in this same on-disk plan file.
 2. Define implementation phases.
 3. Define concrete tasks under each phase.
 4. Add explicit validation criteria per phase (for example: unit tests, integration tests, build/typecheck commands, targeted runtime checks).
@@ -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
 
@@ -64,10 +65,12 @@ The validation specifications serve as the phase's acceptance criteria: a phase
 ## Guardrails
 
 - Do not start implementation unless user explicitly requests implementation mode.
+- Do not create a second plan doc for the same task/thread.
 
 ## Exit criteria
 
 - Every phase has tasks and validation criteria.
 - Dependency graph and parallel opportunities are explicit.
 - Stubs needed for parallel execution are noted.
+- The active plan doc has `status: Tasks` and is committed unless the repo ignores `docs/`.
 - User has explicitly confirmed whether to switch to implementation mode or remain in tasks mode.

package/skills/public/todo/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: todo
+description: Capture user-deferred follow-up work as a lightweight backlog document with context and first open questions.
+---
+
+# Instructions
+
+## Objective
+
+Create a concise backlog item for future work without derailing the active plan.
+
+## Entry gate
+
+Run this skill only when the user explicitly asks to create a todo/backlog item or explicitly agrees to defer work for later.
+
+## Steps
+
+1. Create `docs/backlog/<nnn>-<topic>.md`.
+   - `<nnn>` MUST be the next available 3-digit prefix in `docs/backlog`.
+   - The document MUST start with YAML frontmatter containing at least `summary`.
+2. Include:
+   - Main task/problem statement.
+   - Relevant context known so far.
+   - Source plan/report link when applicable.
+   - Relevant files, docs, architecture constraints, or package names.
+   - First open questions that should be explored next.
+3. Keep it lightweight; do not perform full ideation or planning inside the backlog doc.
+4. Report the created backlog path to the user.
+
+## Guardrails
+
+- Do not decide scope yourself. Only create a backlog item after explicit user deferral/approval.
+- Do not create a plan, tasks, or implementation work in this skill.
+- Do not duplicate large chat transcripts; capture only reusable context.

package/skills/public/workflow/SKILL.md

@@ -14,9 +14,11 @@ description: Enforce the explicit mode cadence (ideation -> plan -> tasks -> imp
 - If the user says `explore <topic>`, run the `explore` skill immediately, even when already inside another mode.
 - `explore` is a deep-dive formatting shortcut, not a mode switch by itself.
 - After finishing an `explore` pass, ask whether to continue the current mode or switch modes.
+- If the user explicitly defers work or asks to capture a future task, use the `todo` skill to create a `docs/backlog` item.
 
 ## 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.
@@ -43,34 +45,41 @@ Meta mode:
 Only switch to the next sequential mode with explicit user confirmation. When completing any mode, the agent must ask: `Shall we switch to {name of next mode}?`.
 Never skip a mode unless explicitly told to. 
 If user seems to suggest skipping a mode but is not explicitly saying which mode to use, then the agent must ask the user `Do you want to continue with {name of next mode} or continue straight to {user suggested mode}?`
-When review identifies remaining work, the agent iterates: `review -> ideation (for all gaps) -> plan -> tasks -> implementation -> review`. Iteration work stays in the active plan document — no new ideation docs for iterate gaps. Every switch still requires explicit user confirmation.
-When review defers work for future scope, the agent creates ideation docs in `docs/ideas/` capturing what's known so far.
+When review identifies remaining work, the agent iterates: `review -> ideation (for all gaps) -> plan -> tasks -> implementation -> review`. Iteration work stays in the active plan document. Every switch still requires explicit user confirmation.
+When the user explicitly defers work for future scope, the agent creates backlog docs in `docs/backlog/` using the `todo` skill.
 Requests related to PR preparation/publishing are an explicit exception and should route directly to `wrapup` mode.
 These transition gates apply to standard modes. `automatic` mode is an explicit exception and manages internal transitions autonomously until its review pause point.
 
 ## Required artifacts by mode
 
-- `ideation`: update/create `docs/ideas/<nnn>-<topic>.md`
-- `plan`: update/create `docs/plans/<nnn>-<topic>.md`
-- `tasks`: update the same plan doc with phased tasks and validation criteria
-- `implementation`: update the plan doc after every completed phase; remove the originating ideation doc once implementation starts
-- `review`: emit findings in chat first; after user decisions, update plan with now-work tasks and/or create ideation docs for deferred future work
-- `wrapup`: convert plan into a final report doc in `docs/reports`, then remove the plan doc after report approval
+- `backlog`: optional source/follow-up docs in `docs/backlog/<nnn>-<topic>.md`
+- `ideation`: create/update one active plan doc in `docs/plans/<nnn>-<topic>.md` with `status: Ideation`
+- `plan`: update the same active plan doc with `status: Plan`
+- `tasks`: update the same active plan doc with `status: Tasks`
+- `implementation`: update the same active plan doc after every completed phase with `status: Implementation`
+- `review`: update the same active plan doc with `status: Review`; emit findings in chat first
+- `wrapup`: convert the active plan into `docs/reports/<nnn>-<topic>.md`, remove the plan doc, and remove the consumed source backlog doc if any
 
 ## Frontmatter requirements for docs
 
-- Any new doc created under `docs/ideas`, `docs/plans`, `docs/reports`, or `docs/architecture` MUST start with YAML frontmatter.
+- Any new doc created under `docs/backlog`, `docs/plans`, `docs/reports`, or `docs/architecture` MUST start with YAML frontmatter.
 - Minimum required frontmatter for new docs:
   ```yaml
   ---
   summary: One or two lines describing the document.
   ---
   ```
+- Active plan docs MUST also include `status: Ideation|Plan|Tasks|Implementation|Review`.
 
 ## Global constraints
 
 - Tool-native plan modes do NOT replace the on-disk plan file requirement.
+- 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.
-- Numbering rule: when creating a new doc in `docs/ideas`, `docs/plans`, or `docs/reports`, `<nnn>` MUST be the next available 3-digit prefix in the destination folder.
-- Conversion rule: when converting/moving docs across folders (for example `ideas -> plans` or `plans -> reports`), do not reuse the old prefix; assign the next available prefix in the destination folder and update references accordingly.
+- Numbering rule: when creating a new doc in `docs/backlog`, `docs/plans`, or `docs/reports`, `<nnn>` MUST be the next available 3-digit prefix in the destination folder.
+- Conversion rule: when converting/moving docs across folders (for example `plans -> reports`), do not reuse the old prefix; assign the next available prefix in the destination folder and update references accordingly.

package/skills/public/wrapup/SKILL.md

@@ -33,16 +33,18 @@ Also treat any user request to prepare/open/update a PR, or draft PR title/body/
    - When converting from a plan, rewrite the `summary` so it reflects the completed result and report scope, not the earlier proposed plan.
    - Update any references to the report path after conversion.
 7. **Report quality** — see the dedicated section below. The report is a condensed but comprehensive record of everything that was done. It is NOT a brief summary.
-8. **Remove the plan doc** `docs/plans/<nnn>-<topic>.md` after the report is written. Do not wait until after the PR — the plan must be gone before the final commit.
+8. **Remove the plan doc** `docs/plans/<nnn>-<topic>.md` after the report is written. If the plan frontmatter or opening section references a consumed source backlog doc, remove that `docs/backlog/<nnn>-<topic>.md` doc too. Do not wait until after the PR — cleanup must happen before the final commit.
 
 ### PR preparation
 
 9. Verify documentation coverage for what changed.
-10. Run a PR-readiness checklist and identify anything missing (for example: docs updates, tests/validation evidence, plan/report consistency, release notes).
-11. If anything is missing, notify the user with a concrete checklist and ask whether to add/fix the missing items now.
-12. Changeset handling — see the dedicated section below.
-13. Draft a PR title and PR message/body summarizing changes, validation, and follow-up notes.
-14. **Final commit**: all cleanup (comments, dead code removal, plan deletion, report) must be committed before creating the PR.
+10. Update architecture docs when approved work changed architecture, contracts, storage, naming, auth, infrastructure, package boundaries, or other architecture-covered behavior. Do not ask for permission again when the change was already approved in the plan/review; make the doc update and report exactly what changed.
+11. Run a PR-readiness checklist and identify anything missing (for example: architecture docs, tests/validation evidence, plan/report consistency, release notes).
+12. If anything is missing, notify the user with a concrete checklist and ask whether to add/fix the missing items now.
+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
 
@@ -56,8 +58,9 @@ The report replaces the plan as the permanent record. Any agent working on code
 - Conversion/mapping rules (e.g., IR node → algebra node mapping tables)
 - All resolved gaps, bugs, and edge cases with their chosen approach
 - Test coverage summary (which test files, what they cover, total counts)
+- Architecture docs updated, with exact files and rationale
 - Known limitations and remaining test gaps
-- Deferred work with pointers to ideation docs
+- Deferred work with pointers to backlog docs
 - Links to relevant documentation files (e.g., `documentation/sparql-algebra.md`)
 - PR reference (number and URL) when a PR was created during this scope
 - Anything that affects future work or that future agents need to know
@@ -71,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.
@@ -93,6 +100,7 @@ A changeset is only skippable when the scope is purely internal (docs, CI config
 - All changed code reviewed for readability, with comments added where needed.
 - Dead code removed.
 - Plan doc removed (`docs/plans/<nnn>-<topic>.md`).
+- Consumed source backlog doc removed when applicable (`docs/backlog/<nnn>-<topic>.md`).
 - Final report at `docs/reports/<nnn>-<topic>.md`.
 - Changeset file in `.changeset/` (when applicable).
 
@@ -100,8 +108,10 @@ A changeset is only skippable when the scope is purely internal (docs, CI config
 
 - Code review pass is complete (readability, comments, dead code).
 - Plan doc has been removed.
+- Consumed source backlog doc has been removed when applicable.
 - Final report is written.
 - Cleanup and documentation checks are complete.
+- Approved architecture doc updates are complete and explicitly reported.
 - PR readiness gaps (if any) were surfaced to the user and a decision was collected.
 - Changeset requirement is resolved (prepared, or explicitly skipped for docs-only/no-code-change scope).
 - PR title and message are ready.