nitm-ai-dev-toolkit 5.2.0 → 5.3.0

package/src/repo/.opencode/commands/bootstrap-patch.md

@@ -9,7 +9,7 @@ description: "Patch AI instructions by fetching updates from the toolkit repo an
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 ## Arguments
 

package/src/repo/.opencode/commands/implement-feature.md

@@ -9,7 +9,7 @@ description: "Implement a feature by completing tasks sequentially"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 ## Arguments
 

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
 
@@ -395,10 +402,14 @@ Documentation updates are **mandatory before committing** any feature or fix. Se
 - Reference `docs/constitution.md` for project principles and governance
 - Include all doc changes in the same commit/PR as the code
 
+**Supplied-task exception (`implement`, `implement-feature`, `implement-fixes` only):** the task supplied to these commands replaces the spec and plan prerequisites. Do not create or require `spec.md` or `plan.md` for the feature or fix unless the user asks for them. Every other applicable item in the [documentation checklist](.claude/rules-snippets/documentation.md) still applies, including the fix log, `CHANGELOG.md`, `docs/api/`, and `README.md`.
+
+**Requirement-only planning exception:** For `/plan` without an existing specification, preserve the original supplied requirements and acceptance criteria in `plan.md` under **Requirements Source** and **Acceptance Criteria**; do not require or create `spec.md`. `/tasks` and `/assign-tasks` consume that plan source when no specification exists; keep acceptance criteria out of the slim task checklist. This exception overrides the spec prerequisite and mandatory spec-first sequence above and in the documentation checklist only for these planning artifacts. It does not authorize implementation, replace artifact review, waive required human approvals, or change any other documentation duties. The separate implementation-command supplied-task exception remains unchanged.
+
 ## Contributing
 
 **Standards:** Follow {{FRAMEWORK}} and {{LANGUAGE}} best practices
-**Process:** Feature branch → spec/plan docs → tests → implementation → update docs → lint → build → PR
+**Process:** Feature branch → spec/plan docs (subject to the requirement-only planning and supplied-task exceptions above) → tests → implementation → update docs → lint → build → PR
 
 ## Related Documentation
 

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.