avtc-pi-featyard 1.1.0

package/skills/fy-design/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: fy-design
+description: "Run before any feature or behavior-changing work begins: research the codebase, settle the design with the user, and write the design document the planning and implementation phases follow."
+disable-model-invocation: true
+---
+
+# Designing a Feature
+Investigate the codebase before asking anything. Drive the design as a dialogue — one focused question per turn, one section at a time, each section confirmed before the next.
+
+> The document is a **specification, not a plan.** It states WHAT the feature achieves, HOW it integrates with the existing system, and HOW it affects every area it touches — in enough detail that planning only has to *sequence* the work, not *decide* it. If you drift into step-by-step build instructions, pull back to the contract.
+
+## Scope of action
+- Read source code and documentation.
+- Write design documents to `{{PI_FY_DESIGN_RELATIVE_DIR}}/`.
+- Read from `.featyard/research/`.
+- Dispatch fy-researcher subagents.
+- Modify no other files.
+
+## Before you start
+- Run `git status` and the recent-commit log before any design work. If the branch already carries uncommitted or unmerged work, surface it and ask the user how to proceed: finish that work first, stash it, or continue here. The user picks the base branch.
+- Check AGENTS.md/CLAUDE.md for requirements to address during design.
+
+## Frame the Goal
+- Ground every later decision in the codebase's present state: read the relevant files, docs, and recent history before deciding.
+- Before designing anything new, search the codebase and its ecosystem for an existing solution. Reuse it when the approach is sound; do not perpetuate a wrong architecture — judge the existing design before building on it.
+- When the feature hooks into existing control flow, read the full target function and enumerate every branch; specify how the feature applies to each. Ask before proceeding if behavior is unclear.
+- Drive the conversation with one question per turn; offer multiple-choice options when possible. Aim each question at the purpose, the hard constraints, and what counts as done.
+- **Lock the evaluation criteria now:** the purpose, constraints, and success criteria are the yardstick every approach is measured against — write them down explicitly. Separate hard constraints (must do / must not break) from soft preferences (nice to optimize).
+- If the change seems trivial after understanding: ask whether to create a design doc (reviews/verification catch side-effects), or `/fy:reset` + implement directly + `/skill:fy-review` after.
+
+## Ideation
+Strong design is two moves — diverge, then converge. The common failure is committing to the first plausible idea.
+- **Diverge first:** generate genuinely distinct *architectures* — where the logic lives, what owns what, what flows where — not the same design relabeled or merely split into files. Make each sharp enough to name; if two answer "what it makes easy / hard" the same way, they are still one — keep diverging.
+- **Converge against the locked criteria:** score *each* option against *each* criterion (the locked criteria plus coupling, blast radius, testability, behavior-change scope, reversibility) — not pros for your favorite and cons for the rest.
+- Lead with the recommendation; justify it against the **runner-up** — name the closest alternative and why the pick wins for this codebase. If you can't articulate why the runner-up loses, you don't yet know enough to recommend.
+- Stress-test: where does it break under failure, concurrency, or scale? Which plausible future change or existing component does it fight? Re-open the choice if later research invalidates an assumption it rested on.
+
+## Deep investigation
+Use fy-researcher subagents for any question about code behavior, dependencies, or call chains. They run in isolated context and trace deep call chains without crowding your conversation. Spawn {{PI_FY_RESEARCHER_MIN}}-{{PI_FY_RESEARCHER_MAX}} per question, scaled to scope.
+
+- **Initial exploration** before writing: survey relevant code areas. Output `{{PI_FY_RESEARCH_DIR}}/{{PI_FY_FEATURE_SLUG}}-design-initial-agent-{N}.md`.
+- **Per-section deep dive** before each section: trace the code it affects. Output `{{PI_FY_RESEARCH_DIR}}/{{PI_FY_FEATURE_SLUG}}-design-section-{sectionNumber}-agent-{N}.md`.
+- **On-demand** whenever a codebase question arises during conversation.
+- **Locate every integration point:** all callers of functions you change, all readers/writers of data you change, all subscribers to events or signals you change, and any code that pattern-matches (by name, type, or string) on something you alter. An integration point first found during planning or review is a gap this phase closed.
+- **Map the blast radius:** every area the change touches — callers, callees, consumers of the data/state, shared state, types/schemas, config, persistence, tests, docs, scripts, tooling — and the impact type (consumes, produces, breaks, must update). An affected area is anywhere behavior is observable to a caller, consumer, or stored artifact. If you can't yet name them, that's a research gap, not a reason to narrow scope.
+- **Trace control-flow and data-flow end to end:** control from invocation to termination (early returns, errors, async completion); data from each value's origin through every transformation to its sink. Every place they cross a boundary is where a contract must be defined.
+- **Stock the solution space, not just the status quo:** have fy-researchers surface other ways this problem (or an analogous one) is already solved — in this codebase, dependencies, or the ecosystem. Prior art is a candidate approach to evaluate, not background reading.
+- **Depth rules:** trace to root cause, not symptoms; understand the mechanism before changing it; check history (git blame, docs, prior decisions) before changing established patterns; separate investigation from design (answer with facts; propose changes only when asked).
+- **Sufficiency loop:** after each report, ask what new questions arose, what stays uncertain, what needs another angle, what blocks a decision; spawn more fy-researchers until no new questions arise and the picture is fully explored. If a fy-researcher fails: retry once narrower, else proceed and note the gap.
+
+**Anti-patterns — do NOT:**
+- Read a file or two, form a surface impression, and proceed. Spawn a fy-researcher.
+- Describe the existing state as optimal. Ask "is there a better way?" before preserving it.
+- Propose the weakest enforcement. For safety/correctness, propose code-level enforcement, not instruction-based self-restraint.
+- Change form without changing structure. Renaming/reorganizing/splitting is not improvement — redesign the architecture first.
+- Accept coupling as necessary because it exists. Ask "architectural or accidental?"
+- State assumptions as facts. When uncertain, flag "needs investigation".
+
+```ts
+subagent({
+  tasks: [{ agent: "fy-researcher", task: "<what to investigate and where to write findings>" }]
+})
+```
+
+## Architecture
+{{PI_FY_ARCHITECTURE_PRINCIPLES}}
+- Specify what must be covered: critical paths, edge cases, and regressions, so implementation and verification know the target.
+
+## Present the design
+- Build the design document one numbered section at a time. Show each section in chat and get explicit approval before writing it to the file.
+- **NEVER write to `{{PI_FY_DESIGN_DOC_PATH}}` before user approval.** The `<!-- approved -->` marker is added only after the user confirms. Once approved, append via `edit`.
+- The design doc is the permanent knowledge base; research reports are working notes. Summarize key findings with a link to the report; do not copy reports verbatim.
+- **Every section includes:** Current state (mechanism traced during research); Proposed change (what & why); Constraints & edge cases; Uncertainties; Rejected alternatives (brief).
+- **Make the architectural decisions explicit per section** — these are spec, not for planning to invent:
+  - **Failure modes** — what can fail, how it fails (exception, default, no-op, degraded mode), and how the failure is bounded so it cannot cascade.
+  - **Backwards compatibility** — which callers, consumers, persisted data, configs, or running instances rely on current behavior; whether the change preserves, migrates, or breaks each; if it breaks, the migration and who is affected.
+  - **State & data migration** — if stored state, schema, or format changes: how existing data transitions, and what happens to data that doesn't fit.
+  - **Concurrency, ordering & lifecycle** — if the feature involves shared state, background work, or startup/shutdown interleaving: the ordering guarantees and the races that cannot occur.
+- **Scenario enumeration:** for each component or integration point, specify behavior for the normal case, each error type, boundary conditions, and interaction with other components. Each scenario must be concrete enough to act as ground truth — if it leaves a real choice open, resolve it or raise it as an unresolved decision. This prevents the most common review finding: "the design doesn't say what happens when X."
+- **Define every behavioral change as what / where / new-behavior:** WHERE (file, module, integration point), WHAT changes, and the NEW behavior — how it differs from current and how an observer detects the difference. Cover the normal path AND every error/failure/boundary path.
+- **Treat Uncertainties as work items to close:** the user is consulted here, so resolve each in design via targeted research, history/docs, or surfacing it to the user — never defer one to a later phase. One that survives every attempt is a genuine open question — escalate it explicitly; don't let it quietly become a gap.
+- **Every factual claim is traceable** to evidence — a cited research report or a specific file/location you read. A claim resting on assumption is not yet a fact; flag it for investigation.
+- **State acceptance criteria:** the testable conditions that define done — what must be true or observable for the feature to be considered complete. These feed verification.
+- **Give each architectural decision a stable reference** (e.g. D1, D2) so the document and later phases can cite it ("amends D3", "see D7") and verification can check each one. (Distinct from numbering *sections* — this is decision traceability.)
+- **If the change spans independently-shippable components** (packages, services, repos), state the ordering / deployment dependency between them and which side lands first.
+- **If the feature has user- or operator-visible state or failures**, specify how they surface (status, logs, error reporting) and how the user knows it is working — or that it failed.
+- Favor designs that are cheap to verify: sharp boundaries, few hidden dependencies, behavior you can assert directly.
+- Use the `todo` tools to track planned work for preparing the design document. The todo list survives context compaction — every item needs comprehensive details (step-by-step instructions and references to docs, sections, or file paths).
+- **Record all user decisions** into the doc's "Appendix: User Decisions" immediately after each decision (do not batch). Each entry: decision, rationale, implication. Do not defer without explicit user approval.
+
+## Completeness — the done-condition
+Do not declare the design complete until every one passes; state the passing audit before stopping:
+- Every user decision captured, with rationale and implication.
+- Every open question resolved — none left dangling.
+- Every codebase research the design depends on — done and cited.
+- Every affected area from the blast-radius map — covered in detail.
+- Every behavioral change — defined as what / where / new-behavior.
+- Every rejected alternative — recorded with the decisive reason.
+
+**Re-read the document as a stranger:** planning will break it into steps and review will audit the build against it; both read what is written, not what you intended. Re-read end-to-end once and fix any missing step, undefined behavior, or uncovered area first.
+
+## When the user corrects you
+When the user corrects you, revise to match the correction and confirm your understanding before continuing. If still uncertain, investigate with a fy-researcher — do not guess.
+
+## Hand-off
+- {{PI_FY_DESIGN_HANDOFF}}
+- Do NOT run design review — the extension handles it automatically.
+- Do NOT start implementing.

package/skills/fy-design-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fy-design-review
+description: "Single-iteration design review — runs one review pass on a design document. The extension handles loop decisions."
+disable-model-invocation: true
+---
+
+# Design Review — Single Iteration
+You are performing **one iteration** of design review. The extension decides whether to loop again.
+
+## Review Context
+**Feature:** `{{PI_FY_FEATURE_SLUG}}`
+**Review loop:** `{{PI_FY_REVIEW_LOOP_NUMBER}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+## Process
+
+### Step 1: Scope the Review
+1. Read the design document at `{{PI_FY_DESIGN_DOC_PATH}}`
+2. Read relevant project context (existing code, patterns, conventions)
+
+### Step 2: Run Design Review
+Always run this review — NEVER skip, even if you think there is nothing new to review.
+
+{{PI_FY_REVIEW_METHOD}}
+
+> ⚠️ **Do not dispatch a `-fork` variant.** The extension auto-forks reviewers when configured in settings.
+
+### Step 3: Revalidate Findings
+For each finding: read the design document section, verify the claim against source code. Do not accept reviewer claims at face value.
+
+**Review corrects an approved spec — it never makes or changes a decision.** When a fix might change a decision, default to the user: present it, never apply it.
+- **Correction → apply** to the design document — after confirming it contradicts nothing in the doc's "User Decisions" appendix. A correction preserves meaning: a citation, path, or line number; a contradiction between statements already in the doc; or a gap in a mechanism the doc already specifies.
+- **Change request → present to the user**, re-checking it against the document and its recorded user decisions. A fix changes a decision if it adds, removes, or alters any decision, option, type, interface, component, concept, or dependency; changes behavior or defaults; or amends or reverses a recorded user decision. If dismissed → append to known-issues file as "pending user decision".
+- **False positive → discard** and append to known-issues file.
+
+Do not duplicate existing entries in the known-issues file.
+
+### Step 4: Fix Issues
+Fix confirmed issues in the design document. Commit changes.
+
+### Step 5: Present Results
+Summary table: `| # | Severity | Issue | Action |`
+
+### Step 6: Done
+Call `phase_ready({ issuesFound, cannotFix, falsePositives })` — issuesFound counts real issues (fixed + cannot-fix), excluding false positives; cannotFix and falsePositives are the counts you dismissed to the known-issues file. The extension handles looping.

package/skills/fy-finish/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: fy-finish
+description: Finish and integrate completed feature work.
+disable-model-invocation: true
+---
+
+# Finishing the Feature
+Execute finishing instructions → resolve conflicts → verify tests post-merge → call phase_ready.
+
+## Step 1: Execute Finishing Instructions
+{{PI_FY_FINISH_INSTRUCTIONS}}
+
+## Conflict Resolution
+If `git merge` reports conflicts:
+1. List conflicted files: `git diff --name-only --diff-filter=U`
+2. For each: read conflict markers, analyze both sides, resolve preferring feature branch BUT validating base branch changes aren't silently discarded. `git add` after resolving.
+3. After all resolved: `git commit`, review the merge diff, verify no unintended changes.
+4. If resolution seems wrong or too complex: `git merge --abort`, report to user.
+
+## Post-Merge Verification
+After any successful merge: run the full test suite. If tests fail, investigate whether the merge introduced the breakage. If it did, fix it — the merge caused it, so it is resolvable — then re-run and re-verify before calling phase_ready. If you cannot fix it, revert the merge and report.
+
+## Rules
+- Signal completion only for terminal actions (merge, PR, discard) — never for keep-as-is.
+- Never remove worktrees or delete branches; the extension owns cleanup.
+- Require typed confirmation before discarding.
+- Resolve merge conflicts per-file; never blanket `--theirs`.
+- After a merge, investigate and fix any test breakage before completing.

package/skills/fy-implement/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: fy-implement
+description: Implement a feature from its task-plan.
+disable-model-invocation: true
+---
+
+# Executing the Task-Plan
+{{PI_FY_WORKTREE_CONTEXT}}
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+**Plan doc:** `{{PI_FY_PLAN_DOC_PATH}}`
+
+**Use the `todo` tool to track your work.** The todo list survives context compaction — every item MUST have comprehensive details (step-by-step instructions, references to design sections or file paths).
+
+## The Process
+
+### Step 1: Load Plan
+Read the plan and seed your task list from its tasks:
+- Init: `todo_init({ items: [{ name: "Task 1", details: "..." }, ...] })`
+- For each task, `todo_add` sub-items mirroring its per-task cycle (Step 2): implement → call `task_ready_advance` (the extension dispatches the per-task gates or advances) → triage any dispatched gate findings → call `task_ready_advance` again with the fixable counts.
+- Complete each sub-item as you finish: `todo_complete({ id })`
+
+### Step 2: Execute Tasks
+
+`task_ready_advance` starts a task, gates it, and advances — the extension decides whether to run the per-task gates. The `todo` tool tracks the finer work items within each task.
+
+Start the first task: `task_ready_advance(nextTask: "<task number + name>")`.
+
+For each task:
+**Implement**
+{{PI_FY_IMPLEMENT_MODE}}
+{{PI_FY_WORTH_NOTES}}
+**Gate + advance**
+After task implemented, call `task_ready_advance(nextTask: "<next task number + name>")` and follow tool call result instructions. The extension either asks to end turn to wait for further instructions (run them, triage, then call again with the fixable counts) or advances to the next task (continue working). On the **last planned task**, omit `nextTask` param.
+
+### Step 3: All Tasks Complete
+After the last task's `task_ready_advance` call (`nextTask` omitted) the extension advances to the `verify` phase and runs the verification skill.

package/skills/fy-plan/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: fy-plan
+description: Turn an approved design into a task-plan for implementation.
+disable-model-invocation: true
+---
+
+# Producing the Task-Plan
+Turn the approved design into a task-plan the implementer runs top-to-bottom: every task sized to one session, self-contained, and traced to a design section.
+
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+
+## Scope of action
+- Read source code and documentation.
+- Dispatch fy-researcher subagents.
+- Read from `.featyard/research/`.
+- Write task-plan to `{{PI_FY_PLAN_DOC_PATH}}`.
+- Modify no other files.
+
+## Research Phase
+Before writing each section/task, spawn fy-researcher subagents to verify the design's assumptions about the codebase.
+Spawn up to {{PI_FY_RESEARCHER_MAX}} fy-researcher(s) per section/task (target: at least {{PI_FY_RESEARCHER_MIN}}). When min is 0, research is optional. Use them to: verify exact file paths and functions, identify line ranges, find related test files, discover integration points.
+When spawning multiple fy-researchers, assign sequential instance numbers to output file paths so they don't collide. Output: `{{PI_FY_RESEARCH_DIR}}/{{PI_FY_FEATURE_SLUG}}-implementation-phase-{phaseNumber}-task-{taskNumber}-agent-{N}.md`
+After fy-researchers complete, read their reports and incorporate findings.
+The agent drives the research, not the reverse: hand each fy-researcher the exact yield to bring back — locations, signatures, line ranges, test files, commands, expected behavior — then carry those specifics into the tasks.
+If the design omits, contradicts, or is ambiguous about something the implementation needs, investigate with a fy-researcher, then resolve it, flag it back as a design gap, or make it an explicit task. Never inherit a silent hole.
+**If a fy-researcher fails:** retry once with narrower scope; else proceed and note the gap.
+
+```ts
+subagent({
+  tasks: [{ agent: "fy-researcher", task: "<what to investigate and where to write findings>" }]
+})
+```
+
+## Architecture
+- Carry forward the design's architecture unchanged; do not alter it in the plan.
+- Preserve the design's contracts and boundaries when decomposing into tasks.
+- Flag back to design any task that needs an architecture decision the design did not make.
+{{PI_FY_ARCHITECTURE_PRINCIPLES}}
+- Specify what must be covered: critical paths, edge cases, and regressions, so implementation and verification know the target.
+
+## Task shape
+- Size each task so it ships one testable behavior end-to-end — writes it, verifies it green, and commits with nothing left to break down or defer.
+- Carry every detail, decision, and behavior from the design into the task — nothing dropped, condensed, or silently changed.
+- Shape each task so the implementer follows it without doing its own research, making design decisions, decomposing it into subtasks, or resolving uncertainties: state the files it touches, the change it makes, and the test that proves it done.
+- Cover documentation: if the change affects docs (README, CHANGELOG, API docs), plan its update — a dedicated task, or a step in each task that touches it.
+- Reference the design section or decision each task implements (e.g. "implements §4.2 / D7").
+- Order tasks so each one's prerequisites are already done. Default to the design's section order.
+
+## Plan Document Header
+```markdown
+# <Feature Name> Task-Plan
+
+**Goal:** <one line — what this delivers>
+**Approach:** <the approach in brief>
+**Tech Stack:** <key technologies>
+
+> Execution is driven by the `fy-implement` skill the extension injects.
+```
+
+## Guardrails
+Address these failures by design, without over-prescribing implementation technique:
+- Task too large to finish in one pass: decompose before handoff.
+- Plan silently reversing or dropping a design decision: every deviation is explicit and flagged back as a design gap.
+- Component built but never wired together: include a task that integrates each component into its caller or runtime.
+
+## Additional areas of attention
+{{PI_FY_ADDITIONAL_AREAS_OF_ATTENTION}}
+
+## Incremental Writing
+Write the plan header first, then append each task section on its own, so every task gets full attention and no write runs past its limit. A small plan may go down in a single write.
+
+## Hand-off
+Use the `todo` tool to track open items and work through them one at a time — every item needs comprehensive details (step-by-step instructions and references to docs, design sections, or file paths).
+
+{{PI_FY_VERIFY_PHASES:plan}}
+
+- Call `phase_ready` and end your turn. Do NOT run plan review — the extension handles it. Do NOT start implementing.

package/skills/fy-plan-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fy-plan-review
+description: "Single-iteration plan review — runs one review pass on an implementation plan. The extension handles loop decisions."
+disable-model-invocation: true
+---
+
+# Plan Review — Single Iteration
+You are performing **one iteration** of plan review. The extension decides whether to loop again.
+
+## Review Context
+**Feature:** `{{PI_FY_FEATURE_SLUG}}`
+**Review loop:** `{{PI_FY_REVIEW_LOOP_NUMBER}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+## Process
+
+### Step 1: Scope the Review
+1. Read the implementation plan at `{{PI_FY_PLAN_DOC_PATH}}`
+2. Read the design document at `{{PI_FY_DESIGN_DOC_PATH}}`
+3. Read relevant project context
+
+### Step 2: Run Plan Review
+Always run this review — NEVER skip, even if you think there is nothing new to review.
+{{PI_FY_REVIEW_METHOD}}
+
+> ⚠️ **Do not dispatch a `-fork` variant.** The extension auto-forks reviewers when configured in settings.
+
+### Step 3: Revalidate Findings
+For each finding: read the plan and design sections, verify the claim against source code. Do not accept reviewer claims at face value.
+
+**Plan review corrects the plan — it never changes design intent.** When a finding requires a design-level decision, surface it with a proposal so the design can be updated.
+- **Correction → apply** to the plan document — after confirming it doesn't alter the design's intent or recorded user decisions. A correction preserves intent: a citation, path, or line number; a contradiction between statements already in the plan; or a missing detail in a task the plan already specifies.
+- **Design proposal → present to the user** with the rationale, a concrete proposed change to the design, and the trade-offs versus the current design. A finding requires a design-level decision if it adds, removes, or alters any design decision, option, type, interface, component, concept, or dependency; changes behavior or defaults; or conflicts with a recorded user decision. If the user defers → append to known-issues file as "pending user decision" with the proposal, so it is not lost or re-raised.
+- **False positive → discard** and append to known-issues file.
+
+Do not duplicate existing entries in the known-issues file.
+
+### Step 4: Fix Issues
+Fix confirmed issues in the plan document. Commit changes.
+
+### Step 5: Present Results
+Summary table: `| # | Severity | Issue | Action |`
+
+### Step 6: Done
+Call `phase_ready({ issuesFound, cannotFix, falsePositives })` — issuesFound counts real issues (fixed + cannot-fix), excluding false positives; cannotFix and falsePositives are the counts you dismissed to the known-issues file. The extension handles looping.

package/skills/fy-research/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fy-research
+description: Deep code analysis
+disable-model-invocation: true
+---
+
+# Research
+Investigate a specific area of the codebase and produce a structured report of findings. Your job is to find facts, not to make design decisions.
+
+**Write only to the output file specified in your task.** Do not write to any other file.
+
+⚠️ **Parallel work safety:** You work in parallel with a team on the same working tree. Do not use `git stash/checkout/reset/clean/merge/rebase`, `npm install`, or any command that mutates the working tree or git state. Read-only commands only.
+
+## Methodology
+1. **Scope the investigation** — understand the question and focus areas
+2. **Map the landscape** — `find` to list files, `grep` for imports to understand module boundaries. List relevant files and roles.
+3. **Trace call chains** — for each relevant function, `grep` for all callers. Read each caller. Note what conditions trigger the call. Follow the chain upward.
+4. **Enumerate branches** — for central functions, read full body. List every `if`/`else`/`switch`/`try`/`catch` branch and what triggers it. Do not skip branches.
+5. **Identify touch points** — `grep` for variable names, type names, function names across the codebase.
+6. **Record exact references** — file paths, function signatures, type definitions, line numbers.
+7. **Check git history for context** — when investigating a pattern that seems suboptimal (type widening, coupling, cross-boundary access), run `git blame` on affected lines. Note: was this always this way, or was there a deliberate reason?
+8. **Flag suspected issues** — you report facts, not opinions. But if behavior looks incorrect (a flag that skips intended side-effects, a guard that never fires, data that is produced but never consumed), note it as "suspected issue: ..." with evidence. The orchestrator decides.
+
+{{PI_FY_RESEARCHER_DELEGATION}}
+
+## Output
+Write findings to the output file specified in your task. If no output file is specified, report findings directly in your response. Structure:
+- **What was investigated** — question and scope
+- **Key findings** — facts with exact file references
+- **Call chains and data flow** — how functions connect
+- **Branch enumerations** — every code path where relevant
+- **Dependency classification** (if investigating module boundaries) — for each cross-module reference: exact symbol used, direction (produce/consume), classification (generic interface / host-specific logic / true coupling)
+- **Uncertainties** — anything you could not fully determine
+
+## Rules
+- Be precise — exact file paths, function signatures, type names
+- If you cannot fully answer, state what you found and what remains unknown
+- Focus on facts, not opinions or design recommendations

package/skills/fy-review/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: fy-review
+description: Feature review skill — dispatches reviewers based on featureReviewMode setting, aggregates findings, runs a single iteration, then calls phase_ready with the issue counts. The extension decides whether to loop again.
+disable-model-invocation: true
+---
+
+# Feature Review — Single Iteration
+You are orchestrating **one iteration** of feature review. Dispatch specialized sub-reviewers as parallel subagents, collect findings, deduplicate, fix, and verify. The extension decides whether to loop again.
+
+{{PI_FY_WORKTREE_CONTEXT}}
+**Feature:** `{{PI_FY_FEATURE_SLUG}}`
+**Review loop:** `{{PI_FY_REVIEW_LOOP_NUMBER}}`
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+**Plan doc:** `{{PI_FY_PLAN_DOC_PATH}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+⚠️ **Parallel work safety:** You work in parallel with a team on the same working tree. Do not use `git stash/checkout/reset/clean/merge/rebase`, `npm install`, or any command that mutates the working tree or git state.
+
+## Scope of action
+- Read code and run read-only git commands.
+- Write the review report and known-issues file.
+- Edit source files only during the fix steps (4–6) — not during review (1–3).
+
+## Process
+
+### Step 1: Scope the Review
+1. Determine the diff base. Base commit: `{{PI_FY_BASE_COMMIT_SHA}}`. If this shows `(not available)`, find the commit *before* the first feature commit manually using `git log`. This base is **fixed across all review loops** — every loop reviews the full cumulative diff from this base to HEAD, including unstaged files.
+2. Run: `git diff --name-only <base>..<head>` to list changed files
+3. Read the plan/spec document for requirements context
+4. **Every sub-reviewer MUST review ALL changed files (full diff from base to HEAD) on every review iteration.** Do not narrow scope to "recent changes". Each sub-reviewer won't find all issues in one pass — reviewing the same full scope repeatedly uncovers new findings each loop.
+
+### Step 2: Dispatch Reviewers
+Always dispatch reviewers — NEVER skip, even if you think there is nothing new to review.
+{{PI_FY_REVIEWER_DISPATCH}}
+
+> ⚠️ **Do not dispatch a `-fork` variant.** The extension auto-forks reviewers when configured in settings.
+
+### Step 3: Aggregate, Deduplicate, and Report
+When all sub-reviewers return:
+1. **Collect all findings** and **deduplicate** — different reviewers may describe the same issue differently. Merge by root cause, keep most severe classification and most actionable description.
+2. **Re-index** — Assign sequential issue IDs: `R<loopNumber>-1`, `R<loopNumber>-2`, etc.
+3. **Write the aggregated review report** to `{{PI_FY_REVIEW_REPORT_FILE}}`:
+
+```
+### Issue R<N>-<index>: <title> [Critical|Important|Minor]
+- **Category:** security|quality|testing|performance|guidelines|requirements|architecture
+- **File:** path/to/file.ts:42-55 (optional)
+- **Description:** What is wrong and why it matters
+- **Suggested fix:** How to fix (optional)
+```
+
+**⚠️ Do NOT fix issues during aggregation.** Every finding that survives deduplication becomes a fix task in Step 4.
+**Update known-issues file** (`{{PI_FY_KNOWN_ISSUES_PATH}}`): Append dismissed issues as `cannot-fix` or `false-positive`.
+**If no issues found:** Write report with empty Issues section. Add a single commit task with `todo_add` (do not re-init your list). Skip to Step 7.
+
+### Step 4: Add Fix Tasks
+Append fix tasks plus a final commit task with `todo_add` — do NOT re-init (`todo_init` wipes the whole feature's task state across loops):
+
+Example tasks:
+- "[Review #<N>] Fix: <issue summary>"
+- ...
+- "[Review #<N>] Commit: stage and commit all changes"
+
+### Step 5: Execute Fix Tasks
+Work through fix tasks one at a time.
+
+For each fix task:
+1. **REVALIDATE FIRST** — read the code, check surrounding context. Is this a real issue or false positive?
+2. **If false positive** → append to `{{PI_FY_KNOWN_ISSUES_PATH}}` as false-positive, `todo_complete` the task
+3. **If real issue** → investigate, fix, `todo_complete` the task
+4. **If cannot fix** → append to `{{PI_FY_KNOWN_ISSUES_PATH}}` as cannot-fix, `todo_complete` the task
+5. **For the commit task** → stage and commit, `todo_complete` the task
+
+## Fix Discipline
+**You MUST fix every real issue found during review.** Do NOT defer, postpone, or mark issues as cannot-fix unless you have a concrete, technical reason you cannot express in code.
+
+- **Do NOT mark issues as `cannot-fix`** because they are "pre-existing", "low-impact", "style", or "future work" — these are not valid reasons. Fix them.
+- **Do NOT mark issues as `false-positive`** without reading the code and verifying with evidence. If the reviewer found it, assume it is real until proven otherwise.
+- **Do NOT skip issues in code within the feature's scope** — if the file was changed as part of this feature (check the cumulative diff from the base commit to HEAD) or was designed/planned to be modified, the issue must be addressed.
+- **If an issue seems too large to fix**, deconstruct it with `todo_add` sub-items and fix each part.
+- **If you genuinely cannot fix an issue** (external blocker, missing dependency, breaking API contract), you MUST escalate to the user: describe the issue, explain why it cannot be fixed, and propose alternatives. Do not silently mark `cannot-fix`. If a feasible solution exists, fix it instead of escalating.
+
+### Step 6: Verify Fixes
+Run the project's verification commands. Fix any failures before proceeding.
+
+### Step 7: Done
+Call `phase_ready({ issuesFound, cannotFix, falsePositives })` — issuesFound counts real issues (fixed + cannot-fix), excluding false positives. The extension handles looping.
+**Known-issues file format:** Each entry has title, dismissed-as (cannot-fix | false-positive), and description.

package/skills/fy-verify/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: fy-verify
+description: Verify implementation before completion — spawns feature-verifier subagent, then runs build/lint/tests
+disable-model-invocation: true
+---
+
+# Verifying the Feature
+Use the `todo` tool to track open items and work through them one at a time. **The todo list survives context compaction — every item MUST have comprehensive details. Include step-by-step instructions and references to docs, design sections, or file paths wherever provided.**
+
+{{PI_FY_WORKTREE_CONTEXT}}
+{{PI_FY_VERIFY_PHASES:verify}}
+
+Discover and run the project's build, lint, and test commands.
+
+## Verification Discipline
+**You MUST fix every issue the verifier finds.** Do NOT dismiss issues as "acceptable" or "not a correctness issue".
+
+- **Do NOT skip issues** because "it works as-is" or "it's an internal improvement" — if the plan specified it, it must be implemented.
+- **Do NOT dismiss partial implementation** as acceptable — if the plan said decompose X into 3 modules, all 3 must exist.
+- **Do NOT rationalize gaps** — a gap between plan and implementation is a bug that must be fixed.
+- **If the verifier found it, it is real** until you have concrete evidence otherwise.
+
+After all tests pass, call `phase_ready` to signal verify phase completion. The extension handles the verify→review transition.