semantu-agents 1.2.2 → 1.3.0

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.0",
   "description": "Reusable Claude Code skills and hooks for Semantu projects",
   "type": "module",
   "bin": "cli.mjs",

package/skills/public/automatic/SKILL.md

@@ -27,11 +27,11 @@ Then pause.
 
 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:
@@ -45,16 +45,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 +65,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 +73,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
@@ -82,7 +86,7 @@ Follow numbering and conversion rules from workflow mode.
 If the user chooses `iterate` after 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.
+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,7 +112,7 @@ 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.
+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`

package/skills/public/explore/SKILL.md

@@ -11,24 +11,25 @@ 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).
+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.
 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.
+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.
 
 ## Guardrails
 
 - 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, including 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.
 
@@ -46,10 +47,11 @@ When the plan marks phases as parallelizable, use the Task tool (or any availabl
 
 ## 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,12 +11,18 @@ 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. 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:
+   - 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
 
@@ -42,13 +48,13 @@ For gaps the user wants to **address now** (iterate):
 - 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:
+- 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
 
 ## Iteration structure
 
@@ -78,10 +84,10 @@ 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 gaps.
+- 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.
 
@@ -104,13 +110,17 @@ The ideation within this section follows the same rules as the ideation skill:
 - 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 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.
+- If deferring: backlog docs were created for user-deferred gaps.
 - 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)
   - **Wrapup** — no more work needed, 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).
@@ -64,10 +64,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,6 +14,7 @@ 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
 
@@ -43,34 +44,40 @@ 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/`.
 - 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,17 @@ 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.
 
 ## Report quality
 
@@ -56,8 +57,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
@@ -93,6 +95,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 +103,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.