npm - avtc-pi-featyard - Versions diffs - 1.1.0 - Mend

avtc-pi-featyard 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (153) hide show

package/LICENSE +21 -0
package/README.md +194 -0
package/agents/fy-design-reviewer.md +77 -0
package/agents/fy-feature-verifier.md +24 -0
package/agents/fy-general-reviewer.md +81 -0
package/agents/fy-guidelines-reviewer.md +46 -0
package/agents/fy-implementer.md +20 -0
package/agents/fy-performance-reviewer.md +46 -0
package/agents/fy-plan-reviewer.md +74 -0
package/agents/fy-plan-verifier.md +44 -0
package/agents/fy-quality-reviewer.md +50 -0
package/agents/fy-requirements-reviewer.md +46 -0
package/agents/fy-researcher.md +6 -0
package/agents/fy-security-reviewer.md +46 -0
package/agents/fy-task-verifier.md +42 -0
package/agents/fy-testing-reviewer.md +60 -0
package/assets/images/kanban-board.png +0 -0
package/assets/images/settings-dropdown.png +0 -0
package/assets/images/settings.png +0 -0
package/assets/images/widget.png +0 -0
package/docs/CONFIGURATION.md +266 -0
package/index.ts +8 -0
package/package.json +85 -0
package/skills/fy-design/SKILL.md +108 -0
package/skills/fy-design-review/SKILL.md +45 -0
package/skills/fy-finish/SKILL.md +28 -0
package/skills/fy-implement/SKILL.md +36 -0
package/skills/fy-plan/SKILL.md +77 -0
package/skills/fy-plan-review/SKILL.md +45 -0
package/skills/fy-research/SKILL.md +38 -0
package/skills/fy-review/SKILL.md +88 -0
package/skills/fy-verify/SKILL.md +23 -0
package/src/commands/auto-agent-commands.ts +748 -0
package/src/commands/kanban-commands.ts +278 -0
package/src/commands/workflow-commands.ts +531 -0
package/src/compaction/compact-handler.ts +371 -0
package/src/compaction/compact-message.ts +52 -0
package/src/compaction/compact-trigger.ts +121 -0
package/src/compaction/safe-editor-write.ts +18 -0
package/src/events/agent/agent-end.ts +19 -0
package/src/events/agent/agent-settled.ts +20 -0
package/src/events/agent/agent-start.ts +18 -0
package/src/events/agent/turn-end.ts +20 -0
package/src/events/agent/turn-start.ts +19 -0
package/src/events/event-deps.ts +33 -0
package/src/events/index.ts +91 -0
package/src/events/input/input.ts +143 -0
package/src/events/session/context.ts +68 -0
package/src/events/session/model-select.ts +20 -0
package/src/events/session/session-compact.ts +20 -0
package/src/events/session/session-shutdown.ts +26 -0
package/src/events/session/session-start.ts +45 -0
package/src/events/session/session-tree.ts +17 -0
package/src/events/tool/tool-call.ts +58 -0
package/src/events/tool/tool-result.ts +54 -0
package/src/git/git-queries.ts +154 -0
package/src/git/resolve-base-branch.ts +173 -0
package/src/git/worktrees/worktree-helpers.ts +142 -0
package/src/git/worktrees/worktree-interception.ts +66 -0
package/src/git/worktrees/worktree-lifecycle.ts +380 -0
package/src/guardrails/completion-gating.ts +63 -0
package/src/guardrails/file-classifier.ts +461 -0
package/src/guardrails/force-add-guard.ts +312 -0
package/src/guardrails/guardrail-tracker.ts +73 -0
package/src/guardrails/guardrail-violations.ts +47 -0
package/src/guardrails/guardrails-engine.ts +663 -0
package/src/guardrails/session-guardrails.ts +75 -0
package/src/guardrails/shell-decompose.ts +285 -0
package/src/guardrails/tdd-enforcement.ts +122 -0
package/src/guardrails/test-output.ts +272 -0
package/src/index.ts +598 -0
package/src/integrations/parallel-work-guardrail-integration.ts +29 -0
package/src/integrations/subagent-integration.ts +166 -0
package/src/integrations/todo-integration.ts +58 -0
package/src/kanban/auto-agent/auto-agent-cleanup.ts +37 -0
package/src/kanban/auto-agent/auto-agent-events.ts +142 -0
package/src/kanban/auto-agent/auto-agent-grace-period.ts +83 -0
package/src/kanban/auto-agent/auto-agent-lifecycle.ts +497 -0
package/src/kanban/auto-agent/auto-agent-notify.ts +43 -0
package/src/kanban/auto-agent/auto-agent-pause.ts +44 -0
package/src/kanban/auto-agent/auto-agent-state-machine.ts +629 -0
package/src/kanban/data/kanban-database.ts +851 -0
package/src/kanban/data/kanban-db-schema.ts +137 -0
package/src/kanban/data/kanban-detect-project.ts +43 -0
package/src/kanban/data/kanban-move-feature.ts +43 -0
package/src/kanban/data/kanban-types.ts +64 -0
package/src/kanban/ensure-feature.ts +226 -0
package/src/kanban/kanban-board-ui/app.js +1125 -0
package/src/kanban/kanban-board-ui/csv-parser.d.ts +5 -0
package/src/kanban/kanban-board-ui/csv-parser.js +80 -0
package/src/kanban/kanban-board-ui/index.html +127 -0
package/src/kanban/kanban-board-ui/style.css +820 -0
package/src/kanban/kanban-bridge.ts +216 -0
package/src/kanban/kanban-context.ts +43 -0
package/src/kanban/kanban-events.ts +34 -0
package/src/kanban/kanban-generate-title.ts +259 -0
package/src/kanban/kanban-generate-topic.ts +170 -0
package/src/kanban/kanban-operations.ts +170 -0
package/src/kanban/kanban-server.ts +931 -0
package/src/kanban/kanban-turn-handlers.ts +55 -0
package/src/kanban/model-capture.ts +34 -0
package/src/log.ts +47 -0
package/src/phases/env-sync.ts +64 -0
package/src/phases/execution-mode.ts +79 -0
package/src/phases/implement-to-verify.ts +31 -0
package/src/phases/phase-progression.ts +249 -0
package/src/phases/phase-transitions.ts +226 -0
package/src/phases/workflow-router.ts +98 -0
package/src/prompts/finish-instructions.ts +143 -0
package/src/prompts/skill-block-builder.ts +73 -0
package/src/prompts/skill-expansion.ts +262 -0
package/src/prompts/task-gate-skill.ts +83 -0
package/src/prompts/template-engine.ts +433 -0
package/src/prompts/text-blocks.ts +279 -0
package/src/review/review-context.ts +56 -0
package/src/review/review-counter.ts +66 -0
package/src/review/review-empty-loop-tracking.ts +52 -0
package/src/review/review-loops.ts +217 -0
package/src/review/review-report.ts +101 -0
package/src/settings/model-overrides.ts +269 -0
package/src/settings/settings-schema.ts +458 -0
package/src/settings/settings-types.ts +81 -0
package/src/settings/settings-ui.ts +222 -0
package/src/shared/errors.ts +24 -0
package/src/shared/global.d.ts +22 -0
package/src/shared/session-entries.ts +24 -0
package/src/shared/types.ts +195 -0
package/src/shared/workflow-refs.ts +253 -0
package/src/shared/workflow-types.ts +180 -0
package/src/snippets/vendored/subscribe-to-dialog-coordinator.ts +98 -0
package/src/snippets/vendored/subscribe-to-notifications.ts +150 -0
package/src/snippets/vendored/subscribe-to-parallel-work-guardrail.ts +35 -0
package/src/snippets/vendored/subscribe-to-subagent.ts +67 -0
package/src/snippets/vendored/subscribe-to-todo.ts +63 -0
package/src/state/archive-artifacts.ts +602 -0
package/src/state/artifact-junction.ts +462 -0
package/src/state/artifact-paths.ts +230 -0
package/src/state/feature-activation.ts +239 -0
package/src/state/feature-management.ts +325 -0
package/src/state/feature-record-store.ts +39 -0
package/src/state/feature-session.ts +263 -0
package/src/state/feature-state.ts +439 -0
package/src/state/post-turn-dispatch.ts +106 -0
package/src/state/session-lifecycle.ts +346 -0
package/src/state/state-persistence.ts +122 -0
package/src/state/worth-notes.ts +89 -0
package/src/tools/add-to-backlog.ts +117 -0
package/src/tools/phase-ready.ts +742 -0
package/src/tools/task-ready-advance.ts +235 -0
package/src/tools/text-result.ts +15 -0
package/src/ui/featyard-widget.ts +250 -0
package/src/ui/manage-features-dialog.ts +246 -0
package/src/ui/select-dialog.ts +27 -0

package/src/prompts/text-blocks.ts ADDED Viewed

@@ -0,0 +1,279 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+// Static text blocks injected by the template engine's PI_FY_* placeholders.
+// Pure data (array-joined strings) with no runtime deps; the engine imports these.
+// Split out of template-substitution so the prompt content is browsable apart from
+// the substitution mechanics.
+/** General reviewer dispatch template — single generalist reviewer. */
+export const GENERAL_DISPATCH_TEMPLATE = [
+  "Dispatch the fy-general-reviewer as a subagent:",
+  "",
+  "```ts",
+  "subagent({",
+  '  tasks: [{ agent: "fy-general-reviewer", task: `<filled template>` }],',
+  "})",
+  "```",
+  "",
+  "**Template for the reviewer task:**",
+  "",
+  "```",
+  "Review the following changed files for all quality aspects (SOLID, KISS, DRY, security, performance, testing, guidelines, requirements compliance):",
+  "**Changed files:**",
+  "<list of changed files with git diff summary>",
+  "",
+  "**Diff base:** <base SHA> — the commit before feature work began.",
+  "**HEAD:** <head SHA>",
+  "",
+  "Report findings using the standard issue format:",
+  "- ID: R<loopNumber>-<index>",
+  "- Severity: Critical | Important | Minor",
+  "- Category: <category>",
+  "- File: path/to/file:startLine-endLine (optional)",
+  "- Description: What is wrong and why",
+  "- Suggested fix: How to fix (optional)",
+  "",
+  'If no NEW issues found, report "No new issues found."',
+  "```",
+].join("\n");
+/** Comprehensive reviewer dispatch template — all 6 specialized reviewers. */
+export const COMPREHENSIVE_DISPATCH_TEMPLATE = [
+  "Dispatch ALL 6 specialized reviewers as parallel subagents. Do NOT skip any reviewer — each has a unique perspective that catches issues the others miss:",
+  "",
+  "- `fy-quality-reviewer` — SOLID, KISS, DRY, maintainability, naming",
+  "- `fy-testing-reviewer` — Test coverage, edge cases, mock quality",
+  "- `fy-security-reviewer` — Injection, auth, secrets, data exposure, input validation",
+  "- `fy-performance-reviewer` — Data processing, algorithms, loops, queries, caching",
+  "- `fy-guidelines-reviewer` — Project conventions, linting rules, architecture patterns, file organization",
+  "- `fy-requirements-reviewer` — Spec compliance: verify implementation matches plan/spec document",
+  "",
+  "```ts",
+  "subagent({",
+  "  tasks: [",
+  '    { agent: "fy-quality-reviewer", task: "<filled template>" },',
+  '    { agent: "fy-testing-reviewer", task: "<filled template>" },',
+  '    { agent: "fy-security-reviewer", task: "<filled template>" },',
+  '    { agent: "fy-performance-reviewer", task: "<filled template>" },',
+  '    { agent: "fy-guidelines-reviewer", task: "<filled template>" },',
+  '    { agent: "fy-requirements-reviewer", task: "<filled template>" },',
+  "  ],",
+  "})",
+  "```",
+  "",
+  "**Template for each reviewer task:**",
+  "",
+  "```",
+  "Review the following changed files for <specialty>:",
+  "**Changed files:**",
+  "<list of changed files with git diff summary>",
+  "",
+  "**Diff base:** <base SHA> — the commit before feature work began.",
+  "**HEAD:** <head SHA>",
+  "",
+  "Review each file and report only NEW findings using the issue format:",
+  "- ID: R<loopNumber>-<index>",
+  "- Severity: Critical | Important | Minor",
+  "- Category: <specialty-category>",
+  "- File: path/to/file:startLine-endLine (optional)",
+  "- Description: What is wrong and why",
+  "- Suggested fix: How to fix (optional)",
+  "",
+  'If no NEW issues found in your specialty area, report "No new issues found."',
+  "```",
+].join("\n");
+/** Deferred-as-finding rule — treat a `⏭️ deferred` verifier outcome as a finding, not an escape. */
+export const DEFERRED_IS_A_FINDING =
+  "`⏭️ deferred` is a finding, not an escape — treat it like `❌ missing`: the work is not done, implement it.";
+/** Verify phase templates — full verifier spawn instruction blocks. */
+export const VERIFY_PHASE_TEMPLATES: Record<"verify" | "plan", string> = {
+  verify: [
+    '1. **Spawn fy-feature-verifier subagent** — `subagent({ agent: "fy-feature-verifier", task: "..." })`.',
+    "Always run this verification — NEVER skip, even if you think there is nothing new to verify.",
+    "2. **If issues found:** Use `todo_add` with `parentId` set to the currently active todo item to create sub-items for all issues (single call, multiple items). Fix them one at a time. After all fixes, commit. Then re-init the todo list (`todo_init` with `overwrite: true`) with a fresh cycle: [spawn verifier, fix issues, run build/lint/tests, call phase_ready], and return to step 1. Max iterations: {{PI_FY_VERIFY_ITERATIONS}}. After max attempts, escalate to user.",
+    DEFERRED_IS_A_FINDING,
+    "3. **Fallback:** If fy-feature-verifier subagent fails (timeout, crash, error), retry once. If still fails, report failure to user.",
+  ].join("\n"),
+  plan: [
+    "1. Load the design document.",
+    '2. Spawn `fy-plan-verifier` subagent — `subagent({ agent: "fy-plan-verifier", task: "..." })`.',
+    "Always run this verification — NEVER skip, even if you think there is nothing new to verify.",
+    "3. If fy-plan-verifier finds issues: fix the plan, then re-dispatch fy-plan-verifier to confirm fixes. Max iterations: {{PI_FY_VERIFY_ITERATIONS}}. After max attempts, escalate to user.",
+    DEFERRED_IS_A_FINDING,
+    "4. If all ✅: proceed to `phase_ready`",
+    "5. **Fallback:** If fy-plan-verifier subagent fails (timeout, crash, error), retry once. If still fails, fall back to the manual per-point checklist: re-init the todo list (`todo_init` with `overwrite: true`) with one item per design point, verify each has a corresponding plan task.",
+  ].join("\n"),
+};
+/**
+ * Architecture principles — injected by {{PI_FY_ARCHITECTURE_PRINCIPLES}}.
+ * Shared across design / plan / fy-implement / fy-implementer (single source of truth).
+ * Role-neutral wording so it fits every phase.
+ */
+export const ARCHITECTURE_PRINCIPLES = [
+  "- Apply SOLID, Clean Architecture, best practices. Favor separation of concerns and narrow interfaces.",
+  "- Favor composition over inheritance — build from small, composable units.",
+  "- Prefer explicit contracts (interfaces, defined boundaries) over implicit coupling (callbacks, shared mutable state, hidden assumptions).",
+  '- Name the contract at every boundary crossing: inputs, outputs, invariants, error semantics. "A calls B" without the contract is hand-waving; state it explicitly.',
+  "- Map the coupling: for each dependency, what must each side know — minimize it. The minimal contract that satisfies the real need wins.",
+  "- Single source of truth: each piece of state has one authoritative location; derive the rest, never duplicate.",
+  "- Stateless where possible: minimize mutable and shared state; prefer pure transformation — the principle, not a mandated mechanism.",
+  "- Point dependencies toward stable abstractions, never in cycles; high-level policy does not depend on low-level details (dependency inversion).",
+  "- Make invalid states unrepresentable: use types and constraints so illegal states cannot be constructed; fail fast on the rest.",
+  "- Treat error handling as a first-class concern: define failure semantics at boundaries, fail fast, never swallow errors — errors are values.",
+  "- Minimal public surface: expose the smallest useful API; do not build speculative generality (YAGNI).",
+  "- Design for testability: units are independently testable via dependency injection and clear seams, with no hidden globals.",
+].join("\n");
+/** Coverage-first review process — mechanical skeleton shared across the seven code reviewers. */
+export const COVERAGE_REVIEW_PROCESS = [
+  "Review exhaustively, not by free-form scanning: build a complete checklist of the diff, then work every item in order. This is what surfaces issues that ad-hoc review misses loop after loop. The report file is an ISSUES list - track coverage through the todo list, not the report.",
+  "",
+  "1. **Scope.** Base commit = the commit before this work began (from your task prompt; if `(not available)`, find it with `git log`). It is fixed — review the full cumulative diff from base to HEAD. Run `git diff --name-only <base>..HEAD` and walk the changed files in diff order so nothing is skipped.",
+  '2. **Build the checklist (your first todo item).** `todo_init` one item: "Build coverage checklist". Work it: read each changed source file and enumerate its reviewable units (functions/methods, classes, branches, error paths, public interfaces); for each changed test file, enumerate what it covers. For every Coverage Area below (including the final "Other"), `todo_add` an area item, then `todo_add` leaf items under it (`parentId`) — concrete `file:method`, line ranges, or data flows. The bullet points under an area are the checks to run on each leaf — they are NOT items. Finish by `todo_add`-ing a last item "Re-validate findings for false positives", then `todo_complete` the build item. Every leaf\'s `details` MUST hold the exact file/method refs and what to check — only what is written to the todo list or report file survives context compaction, not what is held in mind.',
+  "3. **Work every item in order, one at a time.** For each leaf: actively hunt for an issue in your domain. The moment you find a potential issue, append it to the report file IMMEDIATELY — do not batch to the end, because the checklist can be large and a compaction may occur mid-way. Then `todo_complete` the leaf. Completing items is your coverage record; the report holds only real issues.",
+  "4. **Re-validate (last item).** For each finding in the report, re-read the surrounding code and confirm it is real and within your role; then check it against the known-issues file and drop it if it duplicates an already-dismissed entry. Remove false positives. If the report is large, decompose this item into one sub-item per finding.",
+].join("\n");
+/** Coverage-first review process for documents — the doc analog of COVERAGE_REVIEW_PROCESS. */
+export const DOC_COVERAGE_PROCESS = [
+  "Review exhaustively, not by free-form scanning: enumerate the document into checkable items, then work every one in order. This surfaces issues that ad-hoc review misses loop after loop. The report file is an ISSUES list - track coverage through the todo list, not the report.",
+  "",
+  "1. **Read.** Read the document(s) named in your task, plus any docs you reference only for intent.",
+  '2. **Build the checklist (your first todo item).** `todo_init` one item: "Build coverage checklist". Work it: read the document and enumerate its reviewable units. For every Coverage Area below (including the final "Other"), `todo_add` an area item, then `todo_add` leaf items under it (`parentId`) — concrete `section`/`file`/`task` refs. The bullet points under an area are the checks to run on each leaf — they are NOT items. Finish by `todo_add`-ing a last item "Re-validate findings for false positives", then `todo_complete` the build item. Every leaf\'s `details` MUST hold the exact refs and what to check — only what is in the todo list or report file survives context compaction, not what is held in mind.',
+  "3. **Work every item in order, one at a time.** For each leaf: actively hunt for an issue in your domain. The moment you find one, append it to the report file IMMEDIATELY — do not batch to the end, because the checklist can be large and a compaction may occur mid-way. Then `todo_complete` the leaf. Completing items is your coverage record; the report holds only real issues.",
+  "4. **Re-validate (last item).** For each finding, re-read the surrounding document/code and confirm it is real and within your role; then check it against the known-issues file and drop it if it duplicates an already-dismissed entry. Remove false positives. If the report is large, decompose this item into one sub-item per finding.",
+].join("\n");
+/**
+ * Additional areas of attention — injected by {{PI_FY_ADDITIONAL_AREAS_OF_ATTENTION}}.
+ * Concerns to be mindful of while writing tasks (plan) or code (fy-implementer), drawn from
+ * the specialized code reviewers. Heading-less body; each consumer owns its own heading.
+ * Deduped against ARCHITECTURE_PRINCIPLES (SOLID/error-handling/coupling/contracts live there).
+ */
+export const ADDITIONAL_AREAS_OF_ATTENTION = [
+  "**Requirements**",
+  "- Spec compliance — every requirement implemented; no scope creep; no divergent behavior.",
+  "",
+  "**Security**",
+  "- Input validation at every trust boundary — reject early; defend against injection.",
+  "- Authentication and authorization on every privileged action — fail closed.",
+  "- Secrets, credentials, and PII kept out of code, logs, error messages, and config.",
+  "- Data exposure, CSRF, dependency vulnerabilities, and configuration security.",
+  "",
+  "**Performance**",
+  "- Algorithmic complexity, N+1 queries, allocations, and I/O in hot paths; right data structure; caching where it pays off.",
+  "- Actual scale respected — a loop over ten items is not an issue.",
+  "- Resources closed (files, handles, connections); no leaks; bounded concurrency.",
+  "",
+  "**Testing**",
+  "- Critical path, every error and boundary path, edge cases, and negative cases covered.",
+  "- Real assertions, not weak tautologies; mocking only what crosses the boundary.",
+  "- Unit/integration balance; realistic test data.",
+  "",
+  "**Quality**",
+  "- KISS and DRY — shared logic extracted once.",
+  "- Intent-revealing names; small single-purpose units (high cohesion); readable code.",
+  "",
+  "**Conventions**",
+  "- Project lint/format, naming, import/export, file-organization, and architecture-pattern conventions matched exactly.",
+  "",
+  "**Production readiness**",
+  "- Backwards compatibility preserved, migrated, or broken deliberately — know what relies on current behavior.",
+  "- Every caller and every reader/writer of changed data found before the change.",
+  "- Shared state or background work: ordering guarantees and impossible races nailed.",
+  "- Documentation and config aligned with the changes.",
+].join("\n");
+/**
+ * Implementer guidance — injected by {{PI_FY_IMPLEMENTER_GUIDANCE}}.
+ * Shared by BOTH the fy-implementer agent (agents/implementer.md) and fy-implement's
+ * current-session mode. Inner placeholders (ARCHITECTURE_PRINCIPLES, ADDITIONAL_AREAS_OF_ATTENTION)
+ * are INLINED here so the block substitutes once (no nested/double substitution).
+ */
+export const IMPLEMENTER_GUIDANCE = [
+  "## Cycle",
+  "",
+  "For each behavior a task requires:",
+  "",
+  "1. **Red.** Write a test for one behavior. Run it. Confirm it fails for the *right* reason — assertion failure, not a compile or import error. If it fails for the wrong reason, fix that first.",
+  "2. **Green.** Write the minimum code to pass it. Run it. Confirm green.",
+  "3. **Refactor.** Clean up only after green. Re-run after each change; revert if it goes red.",
+  "",
+  "## Discipline",
+  "",
+  "- **Do NOT skip the failing run.** A new test that passes before you've implemented tests nothing — find out why it's already green before writing any code.",
+  "- **Do NOT write code before its test.** If you already did, delete it, write the test, watch it fail, then reimplement to pass.",
+  "- **One test, one behavior.** Don't stack tests against one monolithic change. Cycle per behavior.",
+  "- **Do NOT commit red.** Build clean and all tests green at every commit.",
+  "- **Do NOT rationalize an untested path** as obvious or covered elsewhere — if it's behavior, it has a test.",
+  "",
+  "## Architecture",
+  ARCHITECTURE_PRINCIPLES,
+  "",
+  "## Reuse & dedup",
+  "",
+  "Reuse existing code when it already solves the problem and follows best practices — search before you write, and do not duplicate. As you work, refactor in progress to deduplicate code you write: extract the shared piece once and point every caller at it. Judge existing code before building on it — do not perpetuate a wrong design.",
+  "",
+  "## Refactoring scope",
+  "",
+  "Refactor whatever the task needs for a clean, correct implementation — decide autonomously; do not ask the user for routine improvements. High-level designs and tasks often leave details to your judgment; make the code right.",
+  "",
+  "Do not refactor code unrelated to the task. When you notice an out-of-scope code smell, a bug you cannot fix, or anything strange, report it in your final report as a **worth-note** (what and where) for the caller to record — do not fix it.",
+  "",
+  "## Bugs",
+  "",
+  "When fixing a bug or a verifier finding, write a failing test that reproduces it first, then fix. The test stays — it guards the regression.",
+  "",
+  "When you notice a real bug along the way — outside the literal task — investigate until 100% certain the logic is wrong, then fix it with a failing test that reproduces it (the test stays). Track each fix as additional `todo` items, and report every extra bug fixed: what was wrong and how you fixed it.",
+  "",
+  "## Commits",
+  "",
+  "Commit at green points: after a red→green cycle completes, or after a refactor that stayed green. Never commit broken builds, skipped tests, or work-in-progress.",
+  "",
+  "## Completion Rules",
+  "",
+  "You MUST implement EVERYTHING the task specifies. Do NOT stop partial.",
+  "",
+  '- **Do NOT stop early** because you think "enough was done" or "the rest is trivial" — implement everything.',
+  "- **Do NOT skip steps** from the task description — each step was planned for a reason.",
+  '- **Do NOT defer** planned work to "follow-up" or "future work" — this task IS the follow-up.',
+  "- **Size up the scope.** If the task is large or under-specified — mis-planning, or high-level planning that omits details — deconstruct it into sub-steps with the `todo` tool and work them sequentially. Make each sub-step independently completable.",
+  "",
+  "## Very large tasks",
+  "",
+  "If a task is too large to finish in one session AND it decomposes into granular, independently-verifiable parts, decompose it and dispatch one nested `fy-implementer` subagent at a time per part, then review each subagent's work for correctness before moving on. Verify sequentially — do not dispatch in parallel.",
+  "",
+  "## Blockers",
+  "",
+  "Detect blockers and stop. When you cannot proceed cleanly — an unresolved ambiguity, a missing dependency, broken upstream code, or a decision out of your lane — do not guess or improvise around it. Stop and report to the user: what blocks you, what you tried, and what unblocks you. Do not silently narrow scope.",
+  "",
+  "## Additional areas of attention",
+  "",
+  ADDITIONAL_AREAS_OF_ATTENTION,
+].join("\n");
+/** Researcher delegation section — injected by {{PI_FY_RESEARCHER_DELEGATION}} when nestedResearchers is "on". */
+export const RESEARCHER_DELEGATION_SECTION = [
+  "## Delegation",
+  "",
+  "When the investigation covers multiple independent sub-areas (multiple modules, long call chains, broad subsystems), delegate each to a nested `fy-researcher` subagent in parallel after mapping the landscape yourself.",
+  "",
+  "- **Delegate a part, not the whole task** — split your investigation into narrower scopes, not a repeat of it",
+  "- **Map before delegating** — do the initial `find`/`grep` yourself; delegate only after you know what sub-areas exist",
+  "- **Don't delegate single lookups** — do them yourself",
+  "- **Hierarchical output files** — append `.N` to your file stem: `feature-agent-1.md` → `feature-agent-1.1.md`",
+  "- **Synthesize, don't concatenate** — connect findings across nested reports, note relationships and gaps",
+  "",
+  "```ts",
+  "subagent({",
+  "  tasks: [",
+  '    { agent: "fy-researcher", task: "<narrow sub-task>. Write to: <your-path>-agent-X.1.md" },',
+  '    { agent: "fy-researcher", task: "<narrow sub-task>. Write to: <your-path>-agent-X.2.md" },',
+  "  ],",
+  "})",
+  "```",
+].join("\n");

package/src/review/review-context.ts ADDED Viewed

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+/**
+ * Review iteration context helpers.
+ *
+ * Small shared utilities consumed by the placeholder substitution pipeline
+ * and phase dispatch: review-method strings, the display loop-number
+ * transform, phase→review-skill-name mapping, and the review-phase guard.
+ */
+import type { Phase } from "../phases/phase-progression.js";
+/**
+ * Check if a task is a commit task (not a review fix task).
+ */
+export function isCommitTask(task: { name: string | null; result: string | null }): boolean {
+  return task.result === "committed" || /Commit:/.test(task.name ?? "");
+}
+/**
+ * Convert a raw "iterations started" review loop count (1-indexed: 1 = first
+ * iteration has started) into the 0-indexed "iteration being reviewed" display
+ * number. Clamped at 0 to avoid negatives. Centralized so the off-by-one is
+ * defined once across phase-ready and the substitution pipeline.
+ */
+export function toDisplayLoopNumber(rawCount: number): number {
+  return Math.max(0, rawCount - 1);
+}
+/** True for the two phases that drive design/plan review loops. Undefined-safe. */
+export function isReviewPhase(phase: Phase | undefined): phase is "design" | "plan" {
+  return phase === "design" || phase === "plan";
+}
+export function reviewSkillName(phase: "design" | "plan"): "fy-design-review" | "fy-plan-review" {
+  return phase === "design" ? "fy-design-review" : "fy-plan-review";
+}
+/**
+ * Compute the review method string for design/plan review iteration skills.
+ */
+export function computeReviewMethod(isDesign: boolean, settings: { planReviewMode: string }): string {
+  const mode = settings.planReviewMode;
+  if (mode === "parallel-subagents") {
+    if (isDesign) {
+      return "Dispatch reviewer: `subagent({ agent: 'fy-design-reviewer', task: 'Review the design document for design mistakes. Read the design doc and relevant project files, then output findings following the fy-design-review skill format.' })`";
+    } else {
+      return "Dispatch reviewer: `subagent({ agent: 'fy-plan-reviewer', task: 'Review the implementation plan against the design document for gaps, inconsistencies, and mistakes. Read both documents and relevant project files, then output findings.' })`";
+    }
+  }
+  if (isDesign) {
+    return "Read the full assembled design document carefully. Review for logical consistency (contradictions, missing transitions, circular deps), architectural soundness (abstraction boundaries, reinvented solutions, coupling), design clarity (vague specs, missing interfaces), feasibility & scope (too large, unrelated concerns), and common-sense (over/under-engineering). Output findings with severity and suggested resolutions, plus a scope assessment.";
+  }
+  return "Read the design document and implementation plan. Review the plan against the design for: inconsistencies, gaps, missing pieces, incorrect steps, unclear instructions.";
+}

package/src/review/review-counter.ts ADDED Viewed

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+/**
+ * Review iteration counter — single source of truth for incrementing the
+ * design/plan review loop counter and persisting feature state.
+ *
+ * Used by both the code-driven path (phase_ready handler) and the manual
+ * invocation path (events/input/, when the user types /skill:fy-design-review or
+ * /skill:fy-plan-review). Compaction recovery does NOT use this — it resumes the
+ * current iteration rather than starting a new one.
+ */
+import { log } from "../log.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { DEFAULT_DIR, type FeatureState, saveFeatureState } from "../state/feature-state.js";
+/** Marks the review loop as active when persisting a new iteration counter. */
+const REVIEW_ACTIVE = true;
+/** Map a review phase to its phase-data object. Single source of truth for the
+ *  phase→object mapping (used by startReviewIteration). */
+export function reviewPhaseData(phase: "design" | "plan"): "design" | "plan" {
+  return phase;
+}
+/** Back-compat alias retained for callers that still reference the field selector. */
+export function reviewLoopStateField(phase: "design" | "plan"): "design" | "plan" {
+  return phase;
+}
+/**
+ * Start a new review iteration: increment the phase's review loop counter, mark
+ * the review as active, and persist feature state.
+ *
+ * @param featureState - Pre-loaded state to mutate (e.g. one that already carries
+ *   unsaved mutations such as recorded review history). Pass `null`
+ *   (NO_FEATURE_STATE_OVERRIDE) to load fresh from disk. Either way it is saved
+ *   after incrementing.
+ *
+ * @returns the saved FeatureState (with the incremented counter), or `null` if no
+ *   feature state exists (counter unchanged). Callers reuse the returned state for
+ *   downstream env/widget sync to avoid a redundant disk read.
+ */
+export function startReviewIteration(
+  handler: FeatureSession,
+  slug: string,
+  phase: "design" | "plan",
+  featureState: FeatureState | null,
+): FeatureState | null {
+  const state = featureState ?? handler.getActiveFeatureState();
+  if (!state) {
+    log.warn(`startReviewIteration: no feature state for '${slug}' — counter unchanged`);
+    return null;
+  }
+  const obj = phase === "design" ? state.design : state.plan;
+  const current = obj.reviewLoopCount ?? 0;
+  obj.reviewLoopCount = current + 1;
+  obj.reviewActive = REVIEW_ACTIVE;
+  handler.setReviewActiveFlag(phase, REVIEW_ACTIVE);
+  saveFeatureState(state, DEFAULT_DIR);
+  log.info(`[workflow] startReviewIteration: phase=${phase} slug=${slug} counter ${current}→${current + 1}`);
+  return state;
+}

package/src/review/review-empty-loop-tracking.ts ADDED Viewed

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+/**
+ * Reviewer empty-loop tracking.
+ *
+ * Tracks how many consecutive empty (no-change) loops each reviewer has produced
+ * per feature slug. Used to decide when to skip a reviewer that keeps producing
+ * empty results (configurable threshold).
+ *
+ * State is in-memory only — not persisted to disk.
+ */
+export class EmptyLoopTracker {
+  private readonly loops = new Map<string, Map<string, number>>();
+  private getEmptyLoops(slug: string): Map<string, number> {
+    if (!this.loops.has(slug)) this.loops.set(slug, new Map());
+    return this.loops.get(slug) as Map<string, number>;
+  }
+  incrementEmptyLoop(slug: string, reviewerName: string): void {
+    const map = this.getEmptyLoops(slug);
+    map.set(reviewerName, (map.get(reviewerName) ?? 0) + 1);
+  }
+  resetEmptyLoop(slug: string, reviewerName: string): void {
+    this.getEmptyLoops(slug).delete(reviewerName);
+  }
+  getEmptyLoopsForSlug(slug: string): Record<string, number> {
+    return Object.fromEntries(this.getEmptyLoops(slug));
+  }
+  getReviewerEmptyLoops(): Record<string, Record<string, number>> {
+    const result: Record<string, Record<string, number>> = {};
+    for (const [slug, map] of this.loops) {
+      result[slug] = Object.fromEntries(map);
+    }
+    return result;
+  }
+  isReviewerSkipped(slug: string, reviewerName: string, threshold: number): boolean {
+    if (threshold === 0) return false;
+    const count = this.getEmptyLoops(slug).get(reviewerName) ?? 0;
+    return count >= threshold;
+  }
+  resetAllEmptyLoops(): void {
+    this.loops.clear();
+  }
+}