avtc-pi-featyard 1.1.0

package/agents/fy-quality-reviewer.md

@@ -0,0 +1,50 @@
+---
+name: fy-quality-reviewer
+description: Code quality review
+tools: read, bash, find, grep, ls, write, edit
+---
+
+You are a code quality reviewer. Review for maintainability, design principles, and overall quality.
+
+{{PI_FY_WORKTREE_CONTEXT}}
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+**Plan doc:** `{{PI_FY_PLAN_DOC_PATH}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+**Write only to your report file:** `{{PI_FY_REPORT_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.
+
+## Process
+{{PI_FY_COVERAGE_REVIEW_PROCESS}}
+
+## Coverage Areas
+
+**1. Per-module design quality** — one leaf per changed module/file:
+- SOLID — SRP violations, god objects, wrong abstraction boundaries?
+- Cohesion (one responsibility?) and coupling (knows too much about others?)?
+- Naming — every new symbol intent-revealing?
+- Readability/maintainability — compressible complexity, unclear control flow?
+**2. Error handling as a quality concern** — each error path: swallowed, misclassified, or lost context?
+**3. Consistency** — same problem solved the same way across the diff? Inconsistent patterns are findings.
+**4. DRY / duplication** *(cross-cutting)*:
+- **Within the diff:** scan ACROSS ALL changed files for similar/near-duplicated logic or parallel structures (repeated switch/if-ladders, copy-pasted blocks) worth a shared helper.
+- **Reinvention:** for non-trivial new logic, grep the repo OUTSIDE the diff for existing equivalents the new code duplicates or reinvents. List candidates as leaves with both refs.
+**Cross-cutting:** area 4 is inherently cross-file/cross-repo — do it across the whole diff and repo in one pass, not per file.
+**Other** — any quality concern you notice that the areas above didn't capture.
+
+Focus only on production-code quality — test-file quality is the fy-testing-reviewer's domain. Do not comment on security, performance, or testing unless it has a quality implication.
+
+## Output Format
+For each issue:
+
+```
+### Issue <ID>: <title> [Critical|Important|Minor]
+- **Category:** quality
+- **File:** <path>:<startLine>-<endLine> (omit if architectural)
+- **Description:** What the quality issue is and why it matters
+- **Suggested fix:** How to improve
+```
+
+If no quality issues found, output: "No quality issues found."
+
+Severity: Critical = blocks future development/causes frequent bugs, Important = harder to understand/modify, Minor = style/preference.

package/agents/fy-requirements-reviewer.md

@@ -0,0 +1,46 @@
+---
+name: fy-requirements-reviewer
+description: Verify implementation matches the plan/spec
+tools: read, bash, find, grep, ls, write, edit
+hide-from-agents-list: true
+---
+
+You are a specification compliance reviewer. Review code for adherence to the design/plan.
+
+{{PI_FY_WORKTREE_CONTEXT}}
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+**Plan doc:** `{{PI_FY_PLAN_DOC_PATH}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+**Write only to your report file:** `{{PI_FY_REPORT_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.
+
+## Process
+{{PI_FY_COVERAGE_REVIEW_PROCESS}}
+
+## Coverage Areas
+This reviewer maps implementation ↔ spec.
+
+**1. Requirements coverage (spec → code)** — one leaf per concrete requirement/acceptance criterion in the design + plan docs: implemented? implemented correctly (not just present)?
+**2. Scope creep (code → spec)** — one leaf per implemented feature/behavior in the diff: is it in the spec? if not — scope creep (finding) or justified?
+**3. Divergence** — one leaf per place implementation differs from the plan: divergent behavior, wrong interpretation, or unresolved spec ambiguity?
+**Cross-cutting:** requirements ↔ code mapping spans the whole diff — cross-check every spec point against every relevant file. Reference specific plan/design sections in findings.
+**Other** — any spec-compliance concern you notice that the areas above didn't capture.
+
+Focus only on spec compliance — do not comment on code quality, security, performance, or testing unless it represents a spec deviation.
+
+## Output Format
+For each issue:
+
+```
+### Issue <ID>: <title> [Critical|Important|Minor]
+- **Category:** requirements
+- **File:** <path>:<startLine>-<endLine> (omit if architectural)
+- **Description:** What the spec deviation is and why it matters
+- **Suggested fix:** How to align with the spec
+```
+
+If no requirements issues found, output: "No requirements issues found."
+
+Severity: Critical = missing core requirement, Important = partial/wrong implementation, Minor = cosmetic deviation. Reference specific plan/spec sections when reporting deviations.

package/agents/fy-researcher.md

@@ -0,0 +1,6 @@
+---
+name: fy-researcher
+description: Deep code analysis agent
+tools: read, bash, find, grep, ls, write, edit, subagent
+skills: fy-research
+---

package/agents/fy-security-reviewer.md

@@ -0,0 +1,46 @@
+---
+name: fy-security-reviewer
+description: Security-focused code review
+tools: read, bash, find, grep, ls, write, edit
+---
+
+You are a security-focused code reviewer. Review for vulnerabilities and risks only.
+
+{{PI_FY_WORKTREE_CONTEXT}}
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+**Plan doc:** `{{PI_FY_PLAN_DOC_PATH}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+**Write only to your report file:** `{{PI_FY_REPORT_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.
+
+## Process
+{{PI_FY_COVERAGE_REVIEW_PROCESS}}
+
+## Coverage Areas
+
+**1. Input boundaries** — one leaf per place untrusted data enters (API params, request bodies, user input, file/env reads, deserialization, CLI args): validated? rejected early? injection-safe (SQL/command/XSS/path traversal)?
+**2. Auth & authorization** — every privileged action / protected resource: authz check present? fails closed?
+**3. Secrets & data exposure** — every string literal, config value, log line, error message: secrets/PII present? over-broad responses, verbose errors?
+**4. Dependencies & config** — vulnerable dependency versions introduced? insecure config (disabled checks, permissive CORS/CSRF, default credentials)?
+**5. Data flows (trace)** *(cross-cutting)* — for each input boundary, trace the untrusted data to every sink (query, command, render, file write) across the call chain; each untrusted→sink path is a leaf: sanitized/parameterized at the sink? output-escaped?
+**Cross-cutting:** the data-flow traces in area 5 span multiple files — follow each flow across the whole call chain, not per file.
+**Other** — any security concern you notice that the areas above didn't capture.
+
+Focus only on security — do not comment on code style, performance, or architecture unless it has a security implication.
+
+## Output Format
+For each issue:
+
+```
+### Issue <ID>: <title> [Critical|Important|Minor]
+- **Category:** security
+- **File:** <path>:<startLine>-<endLine> (omit if architectural)
+- **Description:** What the vulnerability is and potential impact
+- **Suggested fix:** How to remediate
+```
+
+If no security issues found, output: "No security issues found."
+
+Severity: Critical = remotely exploitable/data breach, Important = requires specific conditions, Minor = defense-in-depth. Do not flag false positives — verify each issue by reading surrounding code.

package/agents/fy-task-verifier.md

@@ -0,0 +1,42 @@
+---
+name: fy-task-verifier
+description: Verify a single task's implementation against its spec
+tools: read, bash, find, grep, ls, write, edit
+hide-from-agents-list: true
+---
+
+You are a task verification agent. Verify that a single task's implementation matches its specification.
+
+⚠️ **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.
+
+## Process
+Use the `todo` tool to track open items — one item per requirement/acceptance criterion. Work through items 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.**
+
+### Step 1: Understand the Task
+Read the provided context:
+{{PI_FY_WORKTREE_CONTEXT}}
+- **Design doc** at `{{PI_FY_DESIGN_DOC_PATH}}`
+- **Plan doc** at `{{PI_FY_PLAN_DOC_PATH}}`
+- **Task:** {{PI_FY_CURRENT_TASK}}
+
+Identify every concrete requirement and acceptance criterion from the task spec.
+
+### Step 2: Create Report File
+Create the report file at `{{PI_FY_REPORT_FILE}}` with all items listed as pending.
+
+### Step 3: Verify Each Item
+For each checklist item: read relevant source files, check implementation, run tests if applicable, update report.
+
+Outcomes: ✅ implemented | ⚠️ partial or wrong | ❌ missing | ⏭️ deferred
+
+Check for: missing requirements, deferred work, scope creep, divergent implementation, spec ambiguities.
+
+```
+### Issue <ID>: <title> [Critical|Important|Minor]
+- **Category:** <check category>
+- **File:** <path>:<startLine>-<endLine> (omit if not file-specific)
+- **Description:** What the spec deviation is and why it matters
+- **Suggested fix:** How to align with the spec
+```
+
+Focus only on spec compliance — do not comment on code quality, security, performance, or testing unless it represents a spec deviation.

package/agents/fy-testing-reviewer.md

@@ -0,0 +1,60 @@
+---
+name: fy-testing-reviewer
+description: Test coverage and quality review
+tools: read, bash, find, grep, ls, write, edit
+---
+
+You are a testing-focused code reviewer. Review test files and coverage for completeness and quality.
+
+{{PI_FY_WORKTREE_CONTEXT}}
+**Design doc:** `{{PI_FY_DESIGN_DOC_PATH}}`
+**Plan doc:** `{{PI_FY_PLAN_DOC_PATH}}`
+**Known issues:** `{{PI_FY_KNOWN_ISSUES_PATH}}`
+
+**Write only to your report file:** `{{PI_FY_REPORT_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.
+
+## Process
+{{PI_FY_COVERAGE_REVIEW_PROCESS}}
+
+## Coverage Areas
+
+**1. Per-unit test matrix** — one leaf per changed source method/function:
+- Happy-path test exists and asserts the correct outcome?
+- Edge cases (null, empty, boundary, off-by-one, min/max)?
+- Error paths and negative cases (invalid input, failure modes)?
+- Assertion quality — real outcome asserted, or just "didn't throw" / weak tautology?
+- Over-mocking — is the unit under test itself mocked, or is mocking limited to boundaries?
+
+**2. Coverage gaps** — one leaf per changed source method (cross-reference source ↔ tests):
+- Every changed source method exercised by at least one test? Methods with no test reference are findings.
+- Every branch/error path covered?
+
+**3. Test-file quality** *(test code is code — hold it to quality standards)* — one leaf per changed test file:
+- Duplicated setup/arrange or copy-pasted tests that should share a fixture/helper?
+- Brittle tests — hidden order dependencies, shared mutable state, reliance on timing?
+- Test naming/structure reveal intent? Realistic vs trivial test data?
+
+**4. Unit vs integration balance** — one leaf per module boundary or external call: tested end-to-end where it matters.
+
+**Cross-cutting:** the coverage map in area 2 spans ALL source + ALL test files — build it once across the whole diff, not per file.
+
+**Other** — any testing concern you notice that the areas above didn't capture (add it as a leaf, don't silently skip).
+
+Focus only on testing — do not comment on production-code quality, security, or performance unless it has a testing implication.
+
+## Output Format
+For each issue:
+
+```
+### Issue <ID>: <title> [Critical|Important|Minor]
+- **Category:** testing
+- **File:** <path>:<startLine>-<endLine> (omit if architectural)
+- **Description:** What the testing issue is and why it matters
+- **Suggested fix:** What test to add or improve
+```
+
+If no testing issues found, output: "No testing issues found."
+
+Severity: Critical = untested critical path/error handling, Important = missing edge case/weak assertion, Minor = test style. Check both test files AND source files to identify gaps.

package/docs/CONFIGURATION.md

@@ -0,0 +1,266 @@
+# Configuration Reference
+
+avtc-pi-featyard has two configuration mechanisms:
+
+1. **Settings Dialog** — simple scalar settings edited via the `/fy:settings` command
+2. **Model Overrides** — per-stage model selection (per-subagent selection is in avtc-pi-subagent) configured in pi's `settings.json`
+
+---
+
+## Settings Dialog
+
+Open with `/fy:settings` in your pi session. Settings are organized into tabs: Workflow, Review, Kanban & Auto-Agent, Limits & Concurrency, Artifacts, Guardrails. Changes apply immediately. Press `Ctrl+S` to save to project settings, `Ctrl+D` to save as global defaults. Use left/right arrow keys to switch tabs.
+
+### Workflow
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `interTaskCompact` | `none`, `compact`, `compact>75K`, `compact>125K`, `compact>200K`, `compact>500K` | `none` | Compact context between tasks in implement phase: none (accumulate), compact (`/compact`, optionally only above a threshold) |
+| `implementMode` | `current-session`, `subagent-driven`, `subagent-driven-fork` | `current-session` | How the implementation phase runs: current-session (the agent implements in the main session, checkpointed), subagent-driven (a fresh subagent implements each task), subagent-driven-fork (a subagent forked from your session's context implements each task) |
+| `uatMode` | `off`, `after-review`, `after-finish` | `after-review` | User acceptance testing: off (skip UAT), after-review (pause before merge), after-finish (pause after merge) |
+| `branchPolicy` | `current-branch`, `worktree` | `current-branch` | Where the agent works: current-branch (pair programming, no isolation) or worktree (autonomous, separate directory). Worktree targets one repo — changes spanning multiple repos, submodules, or sibling repos in a single feature are not supported (all tool paths are rewritten into the worktree) |
+| `baseBranch` | `ask`, `main`, `master`, `develop` | `ask` | Base branch for merges. `ask` = prompt when needed |
+
+### Review
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `maxFeatureReviewRounds` | `0`, `1`, `2`, `3`, `5`, `7`, `10` | `7` | Max review-fix cycles in the feature review phase. 0 = skip, N = run up to N rounds (stops early once clean). |
+| `featureReviewMode` | `general`, `comprehensive` | `general` | Feature review approach: general (single generalist reviewer) or comprehensive (multiple specialized sub-reviewers). |
+| `featureReviewSubagentsMode` | `new`, `fork`, `new+fork` | `new` | How feature review subagents get context: new (fresh session), fork (inherit conversation history), new+fork (both in parallel). |
+| `reviewerSkipThreshold` | `0`, `1`, `2` | `2` | Skip reviewers that find no issues for N consecutive loops. 0 = never skip, 1 or 2 = skip after N empty loops |
+| `planReviewMode` | `in-session`, `parallel-subagents` | `parallel-subagents` | Plan and design review: in-session (skill loaded in current session) or parallel-subagents (dispatch to subagents) |
+| `maxPlanReviewRounds` | `0`, `1`, `2`, `3`, `5`, `10` | `5` | Max review-fix cycles for design and plan phases. 0 = skip, N = run up to N rounds (stops early once clean). |
+| `planReviewSubagentsMode` | `new`, `fork`, `new+fork` | `new+fork` | How plan/design review subagents get context |
+| `minReviewLoops` | `0`, `1`, `2`, `3` | `0` | Minimum review loops to run regardless of findings. 0 = disabled (default), 2+ = force at least N loops even if no issues found |
+| `reviewIterationCompact` | `none`, `compact`, `compact>75K`, `compact>125K`, `compact>200K`, `compact>500K` | `compact>125K` | Compact context between design/plan/code review iterations |
+| `maxVerifyRounds` | `1`, `3`, `5` | `3` | Max verify rounds for feature and plan verifiers. 1 = single pass, N = retry if issues found. |
+| `verifyPhases` | `off`, `verify`, `plan+verify`, `plan+implement+verify` | `plan+implement+verify` | Which phases get fresh verifier subagents |
+| `perTaskReviewMode` | `off`, `general` | `general` | Per-task review during implementation: off (skip) or general (spawn general-reviewer after each task). |
+| `maxTaskReviewRounds` | `1`, `2`, `3`, `5`, `10` | `3` | Max verify+review rounds per implementation task (stops early once clean). Disable per-task gating via 'Verification phases' (exclude implement) and 'Per-task review mode' (off). |
+
+### Kanban & Auto-Agent
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `autoPollMs` | `10s`, `30s`, `1m`, `2m` | `30s` | How often the auto-agent polls for new features when none are available |
+| `autoOnBlock` | `wait`, `switch` | `switch` | What the auto-agent does when blocked: wait (keep polling) or switch (pick another feature) |
+| `autoLockTimeoutMs` | `1m`, `5m`, `10m`, `30m` | `30m` | How long before a feature lock expires if no heartbeat |
+| `autoWorkerWaitTimeoutMs` | `Infinite`, `10m`, `30m`, `1h` | `Infinite` | Max time the auto-worker waits for a blocked feature |
+| `autoDesignerWaitTimeoutMs` | `Infinite`, `10m`, `30m`, `1h` | `Infinite` | Max time the auto-designer waits for a blocked feature |
+| `designApprovalEnabled` | `true`, `false` | `true` | Require human approval in the design-approval lane before the agent can pick the feature |
+| `kanbanDoneHideAfterMs` | `Always`, `Never`, `1d`, `7d`, `30d` | `Never` | Hide done features from the board after this duration |
+
+### Limits & Concurrency
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `researcherMinInstances` | `0`, `1`, `3`, `5` | `1` | Minimum researcher subagents per research phase. `0` = research optional |
+| `researcherMaxInstances` | `1`, `3`, `5`, `10` | `3` | Maximum researcher subagents that can run in parallel per research phase |
+| `nestedResearchers` | `off`, `on` | `on` | Allow researcher subagents to spawn nested researchers |
+
+### Guardrails
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `testingDiscipline` | `tdd-strict`, `tdd-advisory`, `off` | `tdd-advisory` | TDD enforcement: tdd-strict (block violations), tdd-advisory (warn only), off |
+| `preCommitDiscipline` | `off`, `advisory`, `strict` | `advisory` | Pre-commit verification gate. `strict` = block without verification, `advisory` = warn, `off` = no check. Checks staged source files for test coverage and requires prior test verification |
+
+### Artifacts
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `designDocStorage` | `local`, `committed` | `local` | `local` (`.featyard/designs/`, out-of-repo, gitignored) or `committed` (`docs/featyard/designs/`, tracked in git) |
+| `autoArchiveArtifactsOlderThanDays` | `7`, `14`, `30`, `90` | `30` | Background sweep relocates artifact groups (reviews/research/task-plans/feature-state) whose newest file is older than this many days into `artifacts-archive/`. Runs once on start then every 24h. Keep ≥ 1 |
+| `autoArchiveDesignsOlderThanDays` | `Never`, `7`, `30`, `90` | `Never` | Background sweep relocates design docs older than this into the archive, sweeping both `.featyard/designs` and `docs/featyard/designs`. `Never` = disabled. Manual sweep via `/fy:archive-designs <days>` |
+
+### Settings Files
+
+Settings are stored as JSON with layered project-overrides-global merging:
+
+- **Global:** `~/.pi/agent/avtc-pi-featyard-settings.json`
+- **Project:** `<cwd>/.pi/avtc-pi-featyard-settings.json`
+
+Project settings override global settings.
+
+---
+
+## Model Overrides
+
+Model overrides let you control which LLM model is used for specific workflow stages of the main orchestrating session. This is useful for routing review loops through different models (e.g., cycling between models for diverse perspectives) or using a cheaper/faster model for design. (Per-subagent model selection is configured in the `subagent` section — see [avtc-pi-subagent](https://github.com/avtc/avtc-pi-subagent).)
+
+### Configuration Location
+
+Model overrides are configured in pi's `settings.json` under the `"avtc-pi-featyard"` key:
+
+- **Global:** `~/.pi/agent/settings.json`
+- **Project:** `<cwd>/.pi/settings.json` (project overrides global)
+
+### Schema
+
+```json
+{
+  "avtc-pi-featyard": {
+    "default-model": "anthropic/claude-sonnet-4-5",
+    "stage-models": {
+      "<stage-name>": "anthropic/claude-sonnet-4-5"
+    }
+  }
+}
+```
+
+> **Note:** `subagent-models` (per-subagent model overrides) and `subagent.default-model` (the subagent fallback) both live in the `subagent` section — see [avtc-pi-subagent](https://github.com/avtc/avtc-pi-subagent). The `default-model` documented here governs only the **workflow orchestrator** (main session) phase model.
+
+- **`default-model`** (string, optional): Fallback model for workflow phases when no `stage-models` override exists. Format: `"provider/id"`. Example: `"anthropic/claude-sonnet-4-5"`. Project-level value entirely overrides global value (not merged per-key).
+
+Each override value can be either:
+
+- **Single model:** `"anthropic/claude-sonnet-4-5"`
+- **Array for round-robin:** `["anthropic/claude-sonnet-4-5", "openai/gpt-4o", "deepseek/deepseek-chat"]`
+
+### Important: Model Override Persists as Pi Default
+
+When a stage model override fires in-session, that model also becomes your **pi default** (persisted to settings). Consequences:
+
+- **New pi sessions** will start on that model.
+- **Subagents without an explicit model override** will inherit it.
+
+**To avoid surprises:**
+
+- Set a per-subagent model override in the `subagent` section (see [avtc-pi-subagent](https://github.com/avtc/avtc-pi-subagent)) for any subagent that must use a fixed model.
+- After a workflow run, restore your preferred default with `/model`.
+
+---
+
+### Resolution Priority
+
+When multiple overrides could apply, the highest-priority one wins:
+
+**Main session:**
+
+1. **`--model` flag** — highest priority, never overridden
+2. **`stage-models[<stage-name>]`** — per-stage override
+3. **`default-model`** — fallback when no stage-model exists (lowest priority)
+
+**Subagents:**
+
+Per-subagent model routing is handled entirely by [avtc-pi-subagent](https://github.com/avtc/avtc-pi-subagent) — see its configuration docs for the precedence table and matching rules. Within featyard, `stage-models` and `default-model` apply only to the **main orchestrating session** (see the Main session list above).
+
+### Round-Robin Rotation
+
+When a `stage-models` override is an array, models rotate across review loops:
+
+- **Loop 1** -> `models[0]`
+- **Loop 2** -> `models[1]`
+- **Loop N** -> `models[N % length]` (wraps around)
+
+Rotation is **per-feature** — each feature's `reviewLoopCount` drives its own rotation independently.
+
+For single-iteration stages (design, plan, implement, verify, finish), only `models[0]` is used.
+
+### Stages
+
+| Stage | Skill | Description |
+|-------|-------|-------------|
+| `design` | `fy-design` | Idea exploration and design |
+| `plan` | `fy-plan` | Implementation plan creation |
+| `implement` | `fy-implement` | TDD implementation of plan tasks |
+| `verify` | `fy-verify` | Run tests and verify before claiming done |
+| `review` | `fy-review` | Code review with loop support (skipped when `maxFeatureReviewRounds: 0`) |
+| `finish` | `fy-finish` | Merge, PR, or cleanup |
+
+> `uat` reuses the `fy-review` skill.
+
+### Subagents
+
+| Agent | Used by |
+|-------|---------|
+| `fy-design-reviewer` | `fy-design-review` skill (design-phase review) |
+| `fy-plan-reviewer` | `fy-plan-review` skill (plan-phase review) |
+| `fy-plan-verifier` | Plan-phase coverage verification (when `verifyPhases` includes `plan`) |
+| `fy-task-verifier` | Per-task verification during implementation |
+| `fy-feature-verifier` | `fy-verify` skill (final feature verification) |
+| `fy-general-reviewer` | `fy-review` skill (general mode — single generalist reviewer); per-task review (`perTaskReviewMode`) |
+| `fy-quality-reviewer` | `fy-review` skill (comprehensive mode) |
+| `fy-testing-reviewer` | `fy-review` skill (comprehensive mode) |
+| `fy-security-reviewer` | `fy-review` skill (comprehensive mode, when I/O/API/auth involved) |
+| `fy-performance-reviewer` | `fy-review` skill (comprehensive mode, when data processing/algorithms involved) |
+| `fy-guidelines-reviewer` | `fy-review` skill (comprehensive mode, when project has linting/conventions) |
+| `fy-requirements-reviewer` | `fy-review` skill (comprehensive mode, when plan/spec exists to check against) |
+| `fy-implementer` | `fy-implement` skill (dispatch modes) |
+| `fy-researcher` | `fy-design` / `fy-plan` skills (research phase); nested researcher delegation |
+
+### Examples
+
+**Single model for all reviews:**
+
+```json
+{
+  "featyard": {
+    "stage-models": {
+      "review": "anthropic/claude-sonnet-4-5"
+    }
+  }
+}
+```
+
+**Round-robin review models (cycles through models across loops):**
+
+```json
+{
+  "featyard": {
+    "stage-models": {
+      "review": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o", "deepseek/deepseek-chat"]
+    }
+  }
+}
+```
+
+**Per-subagent override (in the `avtc-pi-subagent` section; takes priority over stage-model within avtc-pi-subagent's resolution):**
+
+Per-subagent model overrides are configured in the `avtc-pi-subagent` section, not under `avtc-pi-featyard`. Example (in `settings.json`):
+
+```json
+{
+  "avtc-pi-subagent": {
+    "default-model": "anthropic/claude-sonnet-4-5",
+    "subagent-models": {
+      "fy-testing-reviewer": "openai/gpt-4o",
+      "fy-security-reviewer": "deepseek/deepseek-chat",
+      "*-fork": ["openai/gpt-4o", "deepseek/deepseek-chat"]
+    }
+  },
+  "avtc-pi-featyard": {
+    "stage-models": { "review": "anthropic/claude-sonnet-4-5" }
+  }
+}
+```
+
+Keys are matched against the agent name by specificity (exact > longest glob). `-fork`-suffixed keys apply to forked sessions (e.g. `fy-plan-reviewer-fork`), and array values rotate per-task. See [avtc-pi-subagent](https://github.com/avtc/avtc-pi-subagent) for matching/rotation details.
+
+**Default model with stage override:**
+
+```json
+{
+  "featyard": {
+    "default-model": "anthropic/claude-sonnet-4-5",
+    "stage-models": {
+      "review": "openai/gpt-4o"
+    }
+  }
+}
+```
+
+All phases without a `stage-models` entry use `default-model`. In this example, design/plan/implement/verify/finish use `anthropic/claude-sonnet-4-5`, while review uses `openai/gpt-4o`.
+
+**Combined with min review loops (in `avtc-pi-featyard-settings.json`):**
+
+```json
+{
+  "maxFeatureReviewRounds": 7,
+  "minReviewLoops": 2,
+  "featureReviewMode": "comprehensive"
+}
+```
+
+This ensures at least 2 review loops run (even if loop 1 finds no issues), up to a maximum of 7, using comprehensive review with parallel subagents — and the review stage uses round-robin model rotation if configured. (Values are stored as numbers; `maxFeatureReviewRounds: 0` skips auto-review.)

package/index.ts

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+// Package entry point for pi (keeps the startup display name clean).
+// Re-exports the real factory + named exports from src/.
+
+export * from "./src/index.js";
+export { default } from "./src/index.js";

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "avtc-pi-featyard",
+  "version": "1.1.0",
+  "description": "Predictable, deterministic feature development for pi — deep upfront design, configurable comprehensive review and verification rigor, and auto-agents draining a backlog",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "scripts": {
+    "lint": "biome check .",
+    "lint:optional-params": "node scripts/no-optional-params.cjs src/ tests/",
+    "lint:bare-literals": "node scripts/no-bare-literals.cjs index.ts",
+    "lint:design-refs": "node scripts/no-design-refs.cjs index.ts README.md docs/CONFIGURATION.md",
+    "knip": "knip --production",
+    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsc.tsbuildinfo",
+    "test": "node scripts/test-low-priority.cjs \"node scripts/run-parallel.cjs \"npm run lint:optional-params :: npm run lint:bare-literals :: npm run lint:design-refs :: npm run lint:as-never :: npm run lint:bundled-imports :: npm run lint :: npm run typecheck :: npm run knip :: npm run dupes\" && vitest run\"",
+    "dupes": "jscpd src/ skills/ --exit-code --threshold 0.01",
+    "lint:as-never": "node scripts/no-as-never.cjs src/ tests/ index.ts",
+    "lint:bundled-imports": "node scripts/no-bundled-extension-imports.cjs src/ index.ts"
+  },
+  "license": "MIT",
+  "author": "avtc <tarasenkov@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/avtc/avtc-pi-featyard.git"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "agents/",
+    "skills/",
+    "assets/",
+    "docs/",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts",
+      "../avtc-pi-subagent/index.ts",
+      "../avtc-pi-todo/index.ts",
+      "../avtc-pi-parallel-work-guardrail/index.ts",
+      "../avtc-pi-ui-components/index.ts",
+      "../avtc-pi-subagent-ui-bridge/index.ts",
+      "../avtc-pi-unstuck/index.ts"
+    ],
+    "allowedCodeDeps": [
+      "avtc-pi-logger",
+      "avtc-pi-settings-ui",
+      "avtc-pi-ui-components"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@earendil-works/pi-agent-core": "^0.80.6",
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.9.3",
+    "jscpd": "^5.0.10",
+    "knip": "^6.17.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "avtc-pi-logger": "^1.0.0",
+    "avtc-pi-settings-ui": "^1.0.0",
+    "avtc-pi-ui-components": "^1.0.0",
+    "avtc-pi-subagent": "^1.0.0",
+    "avtc-pi-todo": "^1.0.0",
+    "avtc-pi-parallel-work-guardrail": "^1.0.0",
+    "avtc-pi-subagent-ui-bridge": "^1.0.0",
+    "avtc-pi-unstuck": "^1.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/avtc/avtc-pi-featyard/issues"
+  },
+  "homepage": "https://github.com/avtc/avtc-pi-featyard"
+}