nitm-ai-dev-toolkit 5.2.1 → 5.3.0

package/src/repo/.claude/rules-snippets/fit-review.md

@@ -0,0 +1,62 @@
+# Goal-Fit Review Brief
+
+Read and follow this brief when a gate or command asks for a goal-fit review of a spec, a plan, or a build's scope. It adds to the reviewer rules of the calling flow.
+
+## Reviewer
+
+- Read-only. Do not edit files, stage, or commit. Do not write any file the caller did not ask for.
+- Independent of the author. Use Oracle when it is available read-only; otherwise a separate reviewer in fresh context. The author's self-review, the author's summary, and a single session playing every role do not count.
+- If no independent reviewer can run, the caller reports `BLOCKED`. Do not review in its place.
+- Review the current artifacts from scratch on every run, including resumed runs. Do not rely on an earlier reply, an earlier summary, or the author's account of what changed.
+
+## Goal sources
+
+Use only these as goal authority:
+
+1. The original user request, verbatim, and every explicit user amendment (intake answers, operator change requests, rework decisions). The caller passes them to you as text in the dispatch.
+2. Accepted constraints from earlier artifacts, when the caller passes them: for a plan review, the accepted spec's requirements, acceptance criteria, and `[DECIDED]` items; for a build review, the accepted spec and plan. Trace against these. They are not goal authority on their own.
+
+Not goal sources: a slug, a ticket key, a ticket title, the existing spec alone, the planner's or author's summary, and any reviewer finding from an earlier round.
+
+If the original request is not in the dispatch, do not infer goals from the spec or the plan. Reply `VERDICT: CHANGES` with a blocking finding: `Missing authoritative baseline: requires user decision; do not auto-repair.`
+
+Quote the original request in your report. When a lower source (a spec, a plan, or a summary) conflicts with the original request, report the conflict with both quotes. Do not silently trust the lower source.
+
+## Trace both ways
+
+- **Forward:** every goal is covered by a requirement, acceptance criterion, or step. Name the section that covers it, or report the gap.
+- **Backward:** every requirement, step, or file change traces to a goal. A change that no goal needs is scope drift.
+- Implementation details that a goal needs are allowed without their own acceptance criterion (for example, a migration that a storage goal requires). Do not demand that every mundane detail be an acceptance criterion. Name the goal that justifies such a detail.
+
+## Lenses (separate from correctness)
+
+- **Ponytail:** is this the simplest work that meets the goals? Flag speculative abstraction, dead flexibility, reinvented standard-library behavior, and steps no goal asks for. Block only when the finding adds scope or complexity the goals do not justify; otherwise note it.
+- **SOLID and SRP, proportional:** flag a responsibility split only when it harms a goal, for example one unit doing unrelated work the request keeps apart. Do not require abstractions or interfaces, and do not forbid a justified interface. Judge by the goals, not by the pattern.
+
+## Decisions and repairs
+
+- A change to a goal (dropping, narrowing, or adding one) is a user decision. So is any other question only the user can settle. A decision stays blocking until the user resolves it with an explicit amendment. Report it as a blocking finding under `VERDICT: CHANGES`, marked `requires user decision; do not auto-repair`, and also list it under **Decisions for the user**. Do not repair it, and do not assume an answer.
+- Other blocking findings are scoped repairs: name the section and the specific change. The caller passes your findings to the author as dispatch context and reviews the changed artifacts again. You do not write repair notes or repair files.
+- `VERDICT: PASS` means no blocking findings. Absence of blocking findings is not a pass. A finding that needs a user decision is blocking, so it is never a pass.
+
+## Output
+
+The first line is exactly `VERDICT: PASS` or `VERDICT: CHANGES`. `CHANGES` needs at least one blocking finding. Then use these sections:
+
+```markdown
+## Goal sources
+- Original request (quoted, short), amendments, accepted constraints. Conflicts: <quotes, or none>
+
+## Trace
+- Forward: <goal → covering section, or gap>
+- Backward: <untraced item → scope drift, or none>
+
+## Blocking findings
+- [section] Problem. Repair: <specific change>
+
+## Decisions for the user
+- <goal change or open decision, or none>
+
+## Notes (non-blocking)
+- [section] Ponytail or SRP observation. Optional.
+```

package/src/repo/.claude/rules-snippets/subagent-workflow.md

@@ -71,42 +71,73 @@ When dispatching implementation tasks, match the specialist to the domain:
 
 ## Orchestration Patterns
 
-### Sequential (default)
+### Delegation Default
 
-Tasks with dependencies are implemented one at a time in dependency order. Each must pass review before the next begins.
+- **Delegate by default.** Hand substantial, safely separable discovery, implementation, test, and review work to subagents. Use a single agent only for trivial work, as listed under "When to Use a Single Agent Directly".
+- **The coordinator keeps outcome responsibility.** It defines each task's scope, reconciles every result, makes sure verification runs, and reports the final outcome. A subagent reporting success is not the outcome.
+- **Work directly only** for trivial changes (one small edit, a quick answer) or when the context is too heavy to hand off cheaply, such as work that depends on large context the coordinator already holds. Say why when you skip delegation.
+- **No delegation capability.** If the host offers no subagent dispatch, say so explicitly in the report. Do permitted direct work where it is safe. Never self-review in place of an independent gate: record the gate as pending and end as BLOCKED or WAITING.
 
-### Parallel
+### Dependency Graph and Parallel Batches (REQUIRED before dispatching)
 
-Independent tasks can be dispatched to multiple specialist subagents simultaneously. Use when tasks don't share files or state.
+Before dispatching any task list, the orchestrator builds the dependency graph. No `[P]` marker is required. If a task list has `[P]` markers, treat them as hints and verify them.
 
-### Parallelization Analysis (REQUIRED before dispatching)
+1. **Read and write sets.** For each task, list the files, directories, or packages it reads and writes.
+2. **Exclusive writable scopes.** Each writer gets a scope no other concurrent task writes. Two tasks that share any writable path are dependent. A task whose write set is unknown or undeclared runs serially until its scope is established from the changed-file list.
+3. **Data dependencies.** A task that reads what another task writes waits for that task.
+4. **Ready batch.** Tasks whose dependencies are satisfied and whose writable scopes are disjoint form one batch. Dispatch the whole batch together. Dependent and shared-write tasks run in later batches, one at a time.
+5. **Route by domain.** Backend tasks → Backend Architect; frontend → Frontend Developer; API contracts → API Specialist; docs → Documenter; cross-cutting → Implementer.
+6. **Track handles.** Record each dispatched task's handle, agent, writable scope, and status until its result is reconciled.
+7. **Reconcile before dependents.** Inspect each result (changed files, summary, verification) before dispatching any task that depends on it. If a result changed a path the graph did not expect, stop the affected tasks and re-plan the batch.
+8. **Continue the chain.** When a batch's results are reconciled, compute the next ready batch and dispatch it. Do not wait for the user unless a mandatory gate applies or no authorized, unblocked work remains (see Autonomous Execution and Blockers).
 
-Before executing any task list, the orchestrator MUST run this analysis:
-
-1. **Scan for `[P]` markers** in the task list — these are pre-identified parallel candidates
-   - If no `[P]` markers exist, do **not** assume sequential-only work. Treat all tasks as candidates and infer parallel-safe groups via the independence test.
-2. **Build a dependency graph**: For each task, list which files it reads and writes
-3. **Apply the independence test**:
-   - Tasks that write to **different files** with **no shared state** → parallel-safe
-   - Tasks that share any writable file → sequential (dependency edge)
-   - Tasks where one reads what another writes → sequential (data dependency)
-4. **Group by domain** for specialist routing:
-   - Backend tasks → Backend Architect
-   - Frontend tasks → Frontend Developer
-   - API contract tasks → API Specialist
-   - Documentation tasks → Documenter
-   - Cross-cutting → Implementer
-5. **Dispatch decision**:
-   - **3+ independent tasks** → Use `dispatching-parallel-agents` skill, one agent per task
-   - **2 independent tasks** → Parallel dispatch (simpler coordination)
-   - **All tasks dependent** → Sequential with `subagent-driven-development` skill
-   - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
+**Dispatch shape:** 3+ independent tasks → `dispatching-parallel-agents`, one agent per task. 2 independent tasks → parallel dispatch. All tasks dependent → sequential with `subagent-driven-development`. Mixed → run each ready batch in parallel, then continue the sequential chain.
 
 ```
-Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI) + T4 [P] (docs) → T5 (integration tests)
-         Dispatch: T1 sequential → T2+T3+T4 parallel → T5 sequential
+Example: 5 tasks → T1 (setup) → T2 (backend API) + T3 (frontend UI) + T4 (docs) → T5 (integration tests)
+         Batches: [T1] → [T2, T3, T4] → [T5]
+         T2, T3, and T4 run together only because their writable scopes are disjoint.
 ```
 
+## Turn Completion and Waiting
+
+During active multi-step execution, never end a turn silently, and never treat dispatch or partial progress as completion. End each such turn in exactly one of these states. Informational answers need no status line:
+
+- **DONE:** the requested work is complete and verified under Quality Gates. State the outcome and the validation that ran.
+- **WAITING:** name each pending task (handle and agent) and its resume trigger, such as a subagent notification or a user reply at a named gate. List what completed and what remains.
+- **BLOCKED / NEEDS-DECISION:** state the blocker or decision, what completed, what remains, and the exact next user action.
+
+Resume mechanics depend on the host:
+
+- When the host notifies on subagent completion, reconcile the notified result and continue with the next eligible batch. Check each handle once per notification.
+- When the host cannot resume in the background, do not claim that it will. Either run the batch in the foreground and collect the results within the turn, or end as WAITING and say that the user must send a message to resume, naming the exact step.
+- Do not busy-poll. Never loop on status checks.
+
+## Autonomous Execution and Blockers
+
+During multi-step execution, work autonomously within the approved goal, scope, and permissions. Autonomy grants no extra authority.
+
+- **A blocker pauses only the affected task and its dependents.** Independent ready work within authority continues in the next batch.
+- **Record each unresolved blocker immediately** in the existing progress record or the conversation: the affected task, what is needed and why, safe options or a targeted input, and the next action. Keep it visible in progress updates and the final report. Never drop it silently.
+- **Defer non-global blockers** as follow-up questions while work can safely advance.
+- **Stop for user input** only when no authorized, unblocked work remains, or when a mandatory approval, security, or permission gate prevents the remaining work. Agents still running are WAITING, not blocked.
+- **Ask clearly.** Present the consolidated outstanding questions through the harness's native question or clarification tool when one is available. Do not assume a tool name or support. Without one, give numbered options or a fill-in block in chat.
+- **Answers can arrive early.** Do not require a blocking tool prompt while independent work continues. Report deferred questions in progress updates.
+- **Never** silently choose a consequential scope or requirement change, bypass a required human approval, or mark a partially blocked task DONE.
+
+## Long-Session Checkpoint
+
+For sessions that span several batches or a context reset:
+
+- Use existing progress records only: a progress section the plan or task list already has, Factory job notes, or task records, when they exist. Keep the approved goal, current step, active task handles, blocker, and next action in those notes or in the conversation.
+- Never add fields to structured files such as Factory `job.json`, never rewrite accepted requirements or spec/plan text, and never replace an authoritative source with a summary.
+- If no such records exist, a short checkpoint in the conversation is enough. Do not create new files for trivial work.
+- On resume, reread the accepted source (spec, plan, or task text) instead of relying on the checkpoint summary, and check the working tree before dispatching anything.
+
+## Factory Approvals
+
+Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation, batching, autonomy, and subagent sign-offs never satisfy spec or plan human confirmation, or human final approval when `APPROVAL_MODE=human`. Mode-defined approver behavior is preserved. Stop at the gate and report it as WAITING or BLOCKED.
+
 ## Quality Gates
 
 - Every implementation must pass **Reviewer** before proceeding
@@ -122,7 +153,7 @@ When a subagent stops on a model capacity, quota, session limit, or reset-wait f
 - **Model order, one attempt each.** Try the next model in the configured fallback order for that agent. When the order is exhausted, try the harness's known available default, unless it was already tried. Then stop; do not cycle back.
 - **Never** retry the same unavailable model, and never wait blindly for a quota reset.
 - **Only supported switching.** Change the model through per-call selection the runtime supports, using only fallback models and defaults that are already configured or exposed. Do not invent model IDs, and do not edit persistent or global config, accounts, or billing.
-- **Blocker when nothing is left.** If no configured fallback or default is available, or per-call selection is unsupported, stop, report the blocker, and ask the user which model to use.
+- **Blocker when nothing is left.** If no configured fallback or default is available, or per-call selection is unsupported, the affected task is reported BLOCKED with the question of which model to use. Its dependents stop; independent authorized work continues (see Autonomous Execution and Blockers).
 - **Inspect before resuming.** Check what the failed attempt left in the working tree, then resume from that partial work. Never run two writers on the same files at once.
 - **Keep review independent.** The reviewer stays a separate agent from the builder, even when the builder moves to a fallback model.
 - **Disclose.** The final report names the original model, each fallback attempted, and the model that finished the work.

package/src/repo/AGENTS.md

@@ -58,7 +58,7 @@ For CLI command reference, see the matching skill: `.agents/skills/{acli,gh-cli,
 
 #### 1. Proactive Clarification
 
-- **Identify Ambiguity**: Stop and ask if a task lacks clear acceptance criteria, inputs, or expected outputs.
+- **Identify Ambiguity**: Ask a targeted question if a task lacks clear acceptance criteria, inputs, or expected outputs. It blocks only that task and its dependents; independent work with clear requirements continues (see Autonomy with blockers, item 8).
 - **Resolve Conflicts**: Flag conflicting instructions between the user prompt, existing code, and documentation before writing code.
 - **Expose Assumptions**: State your assumptions clearly and ask for validation before proceeding with high-impact changes.
 
@@ -240,7 +240,8 @@ Use custom agents when you want explicit coordinator and worker roles. Use workf
 - Do not make an implementation subagent read the plan file on its own; pass the relevant task directly.
 - In `subagent-driven-development`, keep the review order strict: spec compliance first, then code quality.
 - If a reviewer finds issues, fix them and re-run the same review before moving on.
-- Do not run multiple implementation subagents in parallel when they could touch shared packages, shared docs, or the same app surface.
+- Parallel implementation subagents need exclusive writable scopes. If scopes could overlap (shared packages, shared docs, or the same app surface), or one task reads another's output, run them sequentially. See `.claude/rules-snippets/subagent-workflow.md` for the dependency graph and batch rules.
+- Delegate substantial, separable work by default; the coordinator stays responsible for the outcome and reconciles each result before dispatching dependents.
 
 #### Recommended Flow
 
@@ -308,6 +309,12 @@ Use the appropriate sub-agents when the task benefits from specialized expertise
 2. **Provide context** — Reference the relevant rules-snippets or prompt-snippets
 3. **Set constraints** — Use tool restrictions for read-only agents (researcher, reviewer)
 4. **Chain when needed** — Planner → Developer → Reviewer for complex changes
+5. **Delegate by default** — Delegate substantial, safely separable discovery, implementation, test, and review work. The coordinator keeps outcome responsibility; trivial or context-heavy work stays direct.
+6. **Batch by dependency** — Build the dependency graph. Dispatch ready tasks with exclusive writable scopes as one parallel batch; dependent or shared-write tasks run sequentially. Reconcile each result before dispatching its dependents. `[P]` markers are optional.
+7. **Never end silently** — During active multi-step execution, end each turn as DONE, WAITING (pending task handle and resume trigger), or BLOCKED / NEEDS-DECISION (what completed, what remains, exact next user action). Dispatch or partial progress is not completion. Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation or autonomy alone never satisfies a gate.
+8. **Autonomy with blockers** — Work autonomously within the approved goal, scope, and permissions. A blocker pauses only its task and dependents: record it, defer non-global questions, and continue independent authorized work. Stop for the user only when no authorized work remains or a mandatory gate applies, and ask through the harness's native question tool when one exists.
+
+Full workflow, including resume and checkpoint rules: `.claude/rules-snippets/subagent-workflow.md`.
 
 ## Custom Agents (Subagents)
 
@@ -364,8 +371,8 @@ Workers are dispatched by coordinators and are not directly user-invocable.
 - Admin dashboards, RBAC, reporting, monitoring → Admin Portal
 - General implementation → Implementer
 
-**Sequential**: Tasks with dependencies are implemented one at a time.
-**Parallel**: Independent tasks can be dispatched to multiple subagents simultaneously.
+**Sequential**: Dependent tasks, and tasks that share a writable file, run one at a time in dependency order.
+**Parallel**: Ready tasks with exclusive writable scopes run together as one batch. Reconcile each batch's results before dispatching the next.
 
 ### Invoking Subagents
 
@@ -381,7 +388,7 @@ Subagents are typically **agent-initiated** — the coordinator decides when to
 
 ### Factory (opt-in)
 
-An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md).
+An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Spec and plan goal-fit must be confirmed by an independent Oracle or read-only reviewer, not the spec or plan author. Single-session role switching, including the Codex fallback, does not satisfy that and blocks these gates. Spec and plan confirmations stay mandatory human steps in every approval mode. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md).
 
 ## Documentation Requirements
 

package/src/repo/factory/README.md

@@ -55,7 +55,7 @@ The orchestrator and agents are the same in every harness. Each harness has its
 | GitHub Copilot | `/factory` prompt (`.github/prompts/factory.prompt.md`) | `.github/agents/` |
 | Cursor | `/factory` (`.cursor/commands/factory.md`) | `.cursor/agents/` |
 | OpenCode | `/factory` (`.opencode/commands/factory.md`) | `.opencode/agents/` |
-| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | None. Runs each role brief directly, one role at a time in one session (see Harness notes in SKILL.md) |
+| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | No native agent definitions. Role briefs run directly; spec and plan acceptance requires an independent review session. Single-session role switching cannot satisfy that gate (see Harness notes in SKILL.md). |
 
 In OpenCode with the Slim plugin, `oracle` and `designer` are optional alternatives to `reviewer`, if you configure them as edit-denied. The default is the native agents.
 
@@ -77,6 +77,8 @@ Sizing is decided in `plan.md`:
 
 Every job stops twice, in every approval mode, before anything is ticketed or built:
 
+Before either confirmation, an independent read-only Oracle, or reviewer when Oracle is unavailable, checks goal fit. Revisions and resumed gates are reviewed again. Missing independent review blocks acceptance, including single-session Codex use; it does not block discussing unresolved decisions. If the original requirements cannot be recovered, the operator must confirm the recovered baseline rather than treating an agent-written summary as the original request.
+
 1. **Spec gate** (`awaiting-spec`). You read the spec summary, the acceptance criteria count, each open `[PRODUCT DECISION]` item, and open questions. Answer every open decision before you confirm: answers go in your change request, are saved as `spec-<k>.md`, and the spec writer records each one as `[DECIDED]`.
 2. **Plan gate** (`awaiting-plan`). You read the plan, the tasks, the size, the tracking proposal, and the build mode. Confirm, request changes (saved as `plan-<k>.md`), or change size, tracking, or build mode. Requests that touch the spec go back through the spec gate.