prizmkit 1.1.94 → 1.1.96

package/bundled/dev-pipeline-windows/templates/bootstrap-tier2.md

@@ -220,7 +220,7 @@ Wait for Reviewer to return.
 **CP-2**: No CRITICAL issues.
 
 {{IF_CRITIC_ENABLED}}
-### Phase 3.5: Plan Challenge — Critic Agent
+### Phase 3.5: Plan Challenge — Critic Agent(s)
 
 **Guard**: Verify critic agent file exists before spawning:
 ```powershell
@@ -290,7 +290,7 @@ Gate requirements:
 - Only after a valid `PASS`, write the report path to `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt` and append a 3-5 bullet `## PrizmKit Test Gate` summary to `context-snapshot.md`.
 - If the report verdict is `NEEDS_FIXES`, fix in-scope implementation/test issues and rerun `/prizmkit-test`. If the report is `BLOCKED`, missing, stale, or for the wrong scope/artifact dir, write `failure-log.md` and stop for recovery.
 
-### Phase 5: Review + Test — Reviewer Subagent
+### Phase 5: Review — Reviewer Subagent
 
 Spawn Reviewer subagent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false).
 
@@ -302,8 +302,7 @@ Prompt:
 > 2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks
 > 3. Read `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt`, then read the referenced `/prizmkit-test` report. Review generated/updated tests, `In-Scope Failures`, `Baseline Failures`, `Out of Scope Gaps`, boundary coverage if present, and the report verdict.
 > 4. Run /prizmkit-code-review with artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/. The skill runs an internal review-fix loop (Reviewer → filter → Dev fix, max 3 rounds) and writes review-report.md.
-> 5. Run the full test suite using `{{TEST_CMD}}`. When running: `& { {{TEST_CMD}} } 2>&1 | Tee-Object (Join-Path $env:TEMP "review-test-out.txt") | Select-Object -Last 20`, then use Select-String on the file for details — do NOT re-run the suite multiple times.
-> 6. review-report.md will be written to .prizmkit/specs/{{FEATURE_SLUG}}/ by prizmkit-code-review.
+> 5. Do NOT run test suites — the Orchestrator already ran prizmkit-test. Focus on code review and fix strategy.
 > Report: verdict (PASS/NEEDS_FIXES), number of rounds, findings fixed/rejected."
 
 Wait for Reviewer to return.
@@ -323,7 +322,7 @@ Read `review-report.md` and check the Verdict:
 - `PASS` → proceed to next phase
 - `NEEDS_FIXES` → the skill exhausted its max rounds; log the remaining findings and proceed
 
-**CP-3**: Tests pass, review complete.
+**CP-3**: Review complete.
 
 {{IF_BROWSER_INTERACTION}}
 ### Phase 5.5: Browser Verification — MANDATORY
@@ -696,7 +695,7 @@ Remove-Item -Force -ErrorAction SilentlyContinue .prizmkit/specs/{{FEATURE_SLUG}
 
 ## Reminders
 
-- Tier 2: orchestrator builds context+plan, Analyzer checks consistency, Dev implements, Reviewer reviews+tests — use direct Agent spawn for agents
+- Tier 2: orchestrator builds context+plan, Analyzer checks consistency, Dev implements, Reviewer reviews — use direct Agent spawn for agents
 - Build context-snapshot.md FIRST; all subagents read it instead of re-reading source files
 - context-snapshot.md is append-only: orchestrator writes Sections 1-4, Dev appends Implementation Log, Reviewer appends Review Notes
 - Gate checks enforce Implementation Log and Review Notes are written before proceeding

package/bundled/dev-pipeline-windows/templates/bootstrap-tier3.md

@@ -266,7 +266,9 @@ Prompt:
 
 **If {{CRITIC_COUNT}} = 3 → Multi-Critic Voting** (skip Single Critic above):
 
-Spawn 3 Critic agents sequentially (each with mode="plan", run_in_background=false), each with a different focus lens:
+**IMPORTANT**: Spawn all 3 Critics in PARALLEL (issue all 3 Agent tool calls in the SAME message turn). Do NOT wait for one before spawning the next.
+
+Spawn Critic-A, Critic-B, Critic-C simultaneously (each with mode="plan", run_in_background=false):
 
 Critic-A prompt (append to base prompt above):
 > "**Focus Lens: Architecture & Scalability.** Prioritize: architectural pattern fit, scalability implications, over-engineering risks, component boundary design.
@@ -280,6 +282,8 @@ Critic-C prompt (append to base prompt above):
 > "**Focus Lens: Security & Performance.** Prioritize: security attack surface, authentication/authorization gaps, performance bottlenecks, resource leaks.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-C.md`."
 
+Spawn failure cap: for team/config/lock errors, each Critic retries at most once. If 2 or more Critics fail to spawn after retry, perform the plan challenge inline and record the fallback.
+
 After all critics return, read all 3 reports:
 - Challenge raised by **2/3 or more** critics → **must respond** (adjust plan or justify why not)
 - Challenge raised by **1/3 only** → logged in context-snapshot but not blocking
@@ -351,7 +355,7 @@ Gate requirements:
 - Only after a valid `PASS`, write the report path to `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt` and append a 3-5 bullet `## PrizmKit Test Gate` summary to `context-snapshot.md`.
 - If the report verdict is `NEEDS_FIXES`, fix in-scope implementation/test issues and rerun `/prizmkit-test`. If the report is `BLOCKED`, missing, stale, or for the wrong scope/artifact dir, write `failure-log.md` and stop for recovery.
 
-### Phase 5: Review + Test — Reviewer Agent
+### Phase 5: Review — Reviewer Agent
 
 Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false).
 
@@ -363,8 +367,7 @@ Prompt:
 > 2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks
 > 3. Read `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt`, then read the referenced `/prizmkit-test` report. Review generated/updated tests, `In-Scope Failures`, `Baseline Failures`, `Out of Scope Gaps`, boundary coverage if present, and the report verdict.
 > 4. Run /prizmkit-code-review with artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/. The skill runs an internal review-fix loop (Reviewer → filter → Dev fix, max 3 rounds) and writes review-report.md.
-> 5. Run the full test suite using `{{TEST_CMD}}`. When running tests: `& { {{TEST_CMD}} } 2>&1 | Tee-Object (Join-Path $env:TEMP "review-test-out.txt") | Select-Object -Last 20`, then Select-String `(Join-Path $env:TEMP "review-test-out.txt")` for details — do NOT re-run the suite multiple times.
-> 6. review-report.md will be written to .prizmkit/specs/{{FEATURE_SLUG}}/ by prizmkit-code-review.
+> 5. Do NOT run test suites — the Orchestrator already ran prizmkit-test. Focus on code review and fix strategy.
 > Report: verdict (PASS/NEEDS_FIXES), number of rounds, findings fixed/rejected."
 
 Wait for Reviewer to return.
@@ -384,7 +387,7 @@ Read `review-report.md` and check the Verdict:
 - `PASS` → proceed to next phase
 - `NEEDS_FIXES` → the skill exhausted its max rounds; log the remaining findings and proceed
 
-**CP-3**: Integration tests pass, review complete.
+**CP-3**: Review complete.
 
 {{IF_BROWSER_INTERACTION}}
 ### Phase 5.5: Browser Verification — MANDATORY
@@ -774,7 +777,7 @@ Remove-Item -Force -ErrorAction SilentlyContinue .prizmkit/specs/{{FEATURE_SLUG}
 
 ## Reminders
 
-- Tier 3: full team — Dev (implementation) → Reviewer (review + test) — spawn agents directly via Agent tool
+- Tier 3: full team — Dev (implementation) → Reviewer (review) — spawn agents directly via Agent tool
 - context-snapshot.md is append-only: orchestrator writes Sections 1-4, Dev appends Implementation Log, Reviewer appends Review Notes
 - Gate checks enforce Implementation Log and Review Notes are written before proceeding
 - Do NOT use `run_in_background=true` when spawning agents

package/bundled/dev-pipeline-windows/templates/sections/phase-critic-plan-full.md

@@ -32,7 +32,7 @@ If CRITIC:MISSING — skip this phase entirely and proceed. Log: "Critic agent n
 
 **If {{CRITIC_COUNT}} = 3 → Multi-Critic Voting** (skip Single Critic above):
 
-Spawn 3 Critic agents sequentially (each with mode="plan", run_in_background=false), each with a different focus lens:
+Spawn 3 Critic agents in PARALLEL (issue all 3 Agent tool calls in the SAME message turn). Do NOT wait for one before spawning the next. Each with mode="plan", run_in_background=false:
 
 Critic-A prompt (append to base prompt above):
 > "**Focus Lens: Architecture & Scalability.** Prioritize: architectural pattern fit, scalability implications, over-engineering risks, component boundary design.

package/bundled/dev-pipeline-windows/templates/sections/phase-review-full.md

@@ -23,9 +23,7 @@ Read `review-report.md` and check the Verdict:
 - `PASS` → proceed to next phase
 - `NEEDS_FIXES` → the skill exhausted its max rounds; log the remaining findings and proceed (do not retry externally)
 
-Run the full test suite: `& { {{TEST_CMD}} } 2>&1 | Tee-Object (Join-Path $env:TEMP "review-test-out.txt") | Select-Object -Last 20`
-
-**CP-3**: Review complete, report written, and the Test Failure Recovery Protocol's Success Rule is satisfied.
+**CP-3**: Review complete, report written.
 
 
 **Checkpoint update**: Run the update script to set step `prizmkit-code-review` to `"completed"`:

package/bundled/rules/_rules-metadata.json

@@ -20,6 +20,10 @@
     "general/cohesive-modeling": {
       "description": "Group co-occurring variables/fields/concepts into a cohesive unit (struct/class/interface)",
       "tags": ["general", "design"]
+    },
+    "general/agent-operational-rules": {
+      "description": "Framework-level operational rules for all agents — Edit failure recovery, Read offset safety, test output hygiene, incremental validation",
+      "tags": ["general", "agent", "operational"]
     }
   },
   "presets": {
@@ -30,14 +34,16 @@
         "prizm/prizm-commit-workflow",
         "prizm/prizm-progressive-loading",
         "general/prefer-linux-commands",
-        "general/cohesive-modeling"
+        "general/cohesive-modeling",
+        "general/agent-operational-rules"
       ]
     },
     "minimal": {
-      "description": "Minimal: progressive loading + general rules only",
+      "description": "Minimal: progressive loading + general rules + operational rules",
       "rules": [
         "prizm/prizm-progressive-loading",
-        "general/prefer-linux-commands"
+        "general/prefer-linux-commands",
+        "general/agent-operational-rules"
       ]
     },
     "none": {

package/bundled/rules/general/agent-operational-rules.md

@@ -0,0 +1,30 @@
+---
+name: agent-operational-rules
+description: Framework-level operational rules for AI agents — handling Edit failures, Read offsets, test output hygiene, and escalation. These apply to all agents regardless of role.
+tags: [general, agent, operational]
+---
+
+# Agent Operational Rules
+
+These rules apply to ALL agents in the PrizmKit ecosystem. They cover common operational patterns that prevent wasted context and infinite loops.
+
+## Edit Failure Recovery
+
+When an Edit call fails with 'String to replace not found':
+1. STOP editing immediately — do NOT retry the same Edit.
+2. Run `grep -n` to locate the exact line of the target text.
+3. Read with offset = max(grep_line - 20, 0), limit = 50.
+4. Copy the exact text from the Read result into the Edit old_string.
+5. Never guess or extrapolate an offset — grep first, then read, then edit.
+
+## Read Offset Safety
+
+Before any Read with offset + limit:
+- Compute offset + limit. If the last tool_result for this file shows it has N lines, offset MUST be < N.
+- Never request an offset >= known file length.
+
+## Stale Line Counts (Large Files)
+
+Before editing a large file (>1000 lines), verify you know its current line count from the most recent tool_result. Old line counts from earlier turns may be stale if you have since edited the file.
+
+

package/bundled/rules/general/cohesive-modeling.md

@@ -1,27 +1,40 @@
 ---
-description: "将总是同时出现的变量/字段/概念建模为高内聚的整体，而非散落碎片"
+description: "Model variables/fields/concepts that always appear together as a cohesive whole, not scattered fragments"
 ---
 
-在设计或理解任何系统时，如果一组变量、字段、概念总是同时出现、表达同一个语义单元，就应该把它们规划成一个整体，而不是散落为独立的碎片：
+When designing or understanding any system, if a group of variables, fields, or concepts always appear together and express the same semantic unit, they should be modeled as a single whole rather than scattered fragments:
 
-- **Go** — 定义 struct
-- **Java/Python** — 定义 class
-- **TypeScript** — 定义 interface/type
-- **配置** — 归入嵌套配置块
-- **模块划分** — 拆为独立模块
+- **Go** — define a struct
+- **Java/Python** — define a class
+- **TypeScript** — define an interface/type
+- **Config** — group into a nested config block
+- **Module partitioning** — split into an independent module
 
-本质是同一个原则：**高内聚的东西，在建模那一刻就应该是一个东西。**
+The essence is the same principle: **highly cohesive things should be a single thing at the moment of modeling.**
 
-## 触发场景
+## Trigger Scenarios
 
-1. 同一个函数/方法的参数列表中，某几个参数始终一起传递 → 抽取为参数对象
-2. 多个变量总是被一起赋值、一起传递、一起返回 → 合并为结构体/类
-3. 配置文件中一组键总是成对/成群出现 → 合并为嵌套配置块
-4. 发现自己在不同文件里重复声明相同的一组字段 → 提取为公共类型/接口
-5. 修改一个值就必须同步修改另一个值 → 它们属于同一个不变量，应封装在一起
+1. Within a function/method parameter list, a few parameters are always passed together → extract into a parameter object
+2. Multiple variables are always assigned, passed, and returned together → merge into a struct/class
+3. A group of keys in a config file always appears in pairs/clusters → group into a nested config block
+4. You find yourself repeatedly declaring the same set of fields across different files → extract a shared type/interface
+5. Modifying one value requires synchronously modifying another → they belong to the same invariant and should be encapsulated together
 
-## 反面模式（应避免）
+## Anti-Patterns (Avoid)
 
-- 基本类型偏执（Primitive Obsession）：用散落的 string/number 代替有意义的类型
-- 数据泥团（Data Clumps）：相同的一组数据在参数列表、返回值、变量声明中反复出现
-- 霰弹式修改（Shotgun Surgery）：加一个字段需要改 N 个文件的函数签名
+- **Primitive Obsession**: using scattered string/number in place of meaningful types
+- **Data Clumps**: the same group of data repeatedly appearing in parameter lists, return values, and variable declarations
+- **Shotgun Surgery**: adding one field requires changing function signatures across N files
+
+## How to Apply
+
+- When you spot a trigger scenario, extract the cohesive group into a named unit in one pass — do not leave it for "later refactoring."
+- Prefer immutability for the extracted unit to preserve the invariant across the codebase.
+- Name the unit after the domain concept it represents, not the data it happens to contain (e.g., `Money`, not `AmountAndCurrency`).
+- Apply the rule at the lowest level first (parameter object, struct), then propagate upward to interfaces and modules if the cohesion holds.
+
+## Related Principles
+
+- **Single Responsibility Principle** — a cohesive unit should have one reason to change.
+- **Invariant Encapsulation** — bundle data that must satisfy a shared constraint so the constraint can be enforced in one place.
+- **Tell, Don't Ask** — once grouped, expose behavior on the whole rather than dissecting it at call sites.

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.94",
+  "version": "1.1.96",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/app-planner/SKILL.md

@@ -66,7 +66,7 @@ Do NOT use this skill when:
 ## Resource Loading Rules (Mandatory)
 
 1. **App design reference** — always load at session start:
-   - Read `${SKILL_DIR}/assets/app-design-guide.md` for vision templates and tech stack matrix
+   - Read `${SKILL_DIR}/references/app-design-guide.md` for vision templates and tech stack matrix
 
 2. **Load on-demand references when triggered**:
    - Architecture decisions emerged → read `${SKILL_DIR}/references/architecture-decisions.md`
@@ -218,7 +218,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
    1.1 Confirm deliverable intent (→ Intent Confirmation — option-based)
    1.2 **Requirement clarification** — for ANY unclear aspect of the user's vision, goals, target users, or scope, use option-based questions where possible. When common patterns exist, present them as choices. Only use open-ended questions for truly unique input (e.g., "describe your app idea"). Follow up with option-based clarifications.
 2. Confirm constraints and tech assumptions
-   2.1 Tech stack selection — use `${SKILL_DIR}/assets/app-design-guide.md` §2 decision matrix. Use `AskUserQuestion` for each major tech decision (framework, database, styling, etc.)
+   2.1 Tech stack selection — use `${SKILL_DIR}/references/app-design-guide.md` §2 decision matrix. Use `AskUserQuestion` for each major tech decision (framework, database, styling, etc.)
    2.2 **Frontend design check** (for frontend projects) — scan for existing UI/UX design docs. If none found, use `AskUserQuestion`:
        - Question: "No UI/UX design docs found. Would you like to establish design direction?"
        - Options: "Establish design direction now (Recommended)", "Skip for now", "I have external designs"

package/bundled/skills/app-planner/references/project-state-detection.md

@@ -32,7 +32,7 @@ Before ANY planning work, check if AI-essential project context files exist:
 **If ANY are missing**, show the status table, then use `AskUserQuestion`:
 
 **Question**: "Some AI context files are missing. These help AI understand your project — making planning much more effective. How would you like to proceed?"
-- **Run project init first (Recommended)** — invoke `prizmkit-init` to scan your codebase and generate these files, then return to planning
+- **Run project init first** — invoke `prizmkit-init` to scan your codebase and generate these files, then return to planning
 - **Continue without init** — I'll scan the project manually during this session (less thorough)
 - **Skip, I'll set these up later** — proceed with planning using only what's available
 
@@ -71,7 +71,7 @@ Show the summary as text, then use `AskUserQuestion`:
 > **Architecture**: [e.g., monolithic, microservices, serverless]
 
 **Question**: "Does this look correct?"
-- **Yes, looks correct (Recommended)** — proceed with planning
+- **Yes, looks correct** — proceed with planning
 - **Mostly correct, with changes** — I'll note corrections
 - **This is off** — let me describe the project
 

package/bundled/skills/bug-planner/SKILL.md

@@ -212,9 +212,8 @@ Before generating `.prizmkit/plans/bug-fix-list.json`, perform a holistic scan a
 
 **Step 4 — Present review table**: Display the completeness assessment using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md` (§Completeness Review Template).
 
-For any items that need attention, ask targeted questions to fill gaps. Iterate until the user confirms all bugs are adequately described. Present bilingual prompt:
+For any items that need attention, ask targeted questions to fill gaps. Iterate until the user confirms all bugs are adequately described. Present the prompt:
 
-> "以上是完整性审查结果。需要补充的项目是否逐一补充？还是先跳过，之后再完善？"
 > "Above is the completeness review. Items needing more detail — address them now, or proceed and refine later?"
 
 Only proceed to Phase 5 after user confirms.

package/bundled/skills/bug-planner/assets/bug-confirmation-template.md

@@ -23,9 +23,9 @@ Present this after extracting and clarifying each bug:
 ```
 
 Then ask three confirmation questions:
-1. "描述是否准确？是否需要修改？" / "Is the description accurate? Any corrections?"
-2. "是否需要补充更多细节？（复现步骤、环境信息、相关代码位置等）" / "Need to add more details? (reproduction steps, environment, related code locations, etc.)"
-3. "验证条件是否具体到 pipeline 可以自主判断修复成功？" / "Are the acceptance criteria specific enough that the pipeline can autonomously verify the fix?"
+1. "Is the description accurate? Any corrections?"
+2. "Need to add more details? (reproduction steps, environment, related code locations, etc.)"
+3. "Are the acceptance criteria specific enough that the pipeline can autonomously verify the fix?"
 
 Only finalize the bug entry after user confirms all three points.
 

package/bundled/skills/feature-planner/SKILL.md

@@ -266,7 +266,7 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
 4. Draft features (title + description + acceptance_criteria + dependencies)
 5. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the generate script:
    ```bash
-   python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode incremental
+   python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
    ```
 6. If valid → summarize and recommend next step
 7. If invalid → apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
@@ -317,7 +317,7 @@ Key requirements:
 1. Write a draft JSON to a temporary path (e.g., `.prizmkit/plans/feature-list.draft.json`)
 2. Call the generate script to validate and produce the final file:
 ```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode <new|incremental>
+python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
 ```
 The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes. If validation fails, fix the draft and retry.
 

package/bundled/skills/feature-planner/references/error-recovery.md

@@ -4,7 +4,7 @@ Structured error handling for validation failures, interrupted sessions, and che
 
 ## Validation Failures
 
-When `python3 scripts/validate-and-generate.py validate --input <file> --mode <mode>` returns errors:
+When `python3 scripts/validate-and-generate.py validate --input <file>` returns errors:
 
 ### Parse validation output
 Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]`

package/bundled/skills/feature-planner/references/incremental-feature-planning.md

@@ -83,7 +83,7 @@ Keep dependency correctness as first constraint.
 ### Step 5: Validate
 Run:
 ```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json --mode incremental
+python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json
 ```
 
 Fix and re-run until pass.

package/bundled/skills/feature-planner/references/new-project-planning.md

@@ -55,7 +55,7 @@ Split into `sub_features` when:
 1. Write `feature-list.json`.
 2. Run:
    ```bash
-   python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json --mode new
+   python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json
    ```
 3. Fix all errors, then re-run.
 

package/bundled/skills/feature-planner/scripts/validate-and-generate.py

@@ -11,12 +11,16 @@ Commands:
   grade       Generate grading results from eval runs (for npm run skill:review)
 
 Usage:
-  python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json] [--mode new|incremental]
+  python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json]
   python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
-  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json [--mode new|incremental]
+  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json
   python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
   python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
 
+Mode is determined automatically by --output path:
+  - Output file does NOT exist -> new plan (all features must be "pending")
+  - Output file already exists -> incremental append (existing features keep their status)
+
 Python 3.6+ required. No external dependencies.
 """
 
@@ -38,8 +42,6 @@ VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "s
 VALID_COMPLEXITIES = {"low", "medium", "high", "critical"}
 VALID_PRIORITIES = {"critical", "high", "medium", "low"}
 VALID_GRANULARITIES = {"feature", "sub_feature", "auto"}
-VALID_PLANNING_MODES = {"new", "incremental"}
-
 FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
 SUB_FEATURE_ID_RE = re.compile(r"^F-\d{3}-[A-Z]$")
 
@@ -156,13 +158,11 @@ def _detect_cycles(features):
 # ---------------------------------------------------------------------------
 
 
-def validate_feature_list(data, planning_mode="new"):
+def validate_feature_list(data, is_new_plan=True):
     """Validate a parsed feature-list data structure.
 
     Returns a dict with keys ``valid``, ``errors``, ``warnings``, ``stats``.
     """
-    if planning_mode not in VALID_PLANNING_MODES:
-        planning_mode = "new"
 
     errors = []
     warnings = []
@@ -299,7 +299,7 @@ def validate_feature_list(data, planning_mode="new"):
                     label, status, ", ".join(sorted(VALID_STATUSES))
                 )
             )
-        if planning_mode == "new" and status and status != "pending":
+        if is_new_plan and status and status != "pending":
             warnings.append(
                 "{}: status is '{}' (expected 'pending' for new plans)".format(label, status)
             )
@@ -680,7 +680,9 @@ def cmd_validate(args):
         print(json.dumps(result, indent=2, ensure_ascii=False))
         return 2
 
-    result = validate_feature_list(data, planning_mode=args.mode)
+    # Validate input file exists -> incremental mode (existing features keep their status)
+    is_new_plan = False
+    result = validate_feature_list(data, is_new_plan=is_new_plan)
 
     # Print results to stdout
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -758,9 +760,11 @@ def cmd_generate(args):
     for feature in data.get("features", []):
         feature.setdefault("status", "pending")
 
-    # Validate
-    mode = getattr(args, "mode", "new") or "new"
-    result = validate_feature_list(data, planning_mode=mode)
+    # Validate. Mode is determined by whether --output file already exists:
+    #   - does NOT exist -> new plan (all features must be "pending")
+    #   - already exists -> incremental append (existing features keep their status)
+    is_new_plan = not os.path.exists(args.output)
+    result = validate_feature_list(data, is_new_plan=is_new_plan)
 
     # Output validation result
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -856,7 +860,7 @@ def cmd_grade(args):
             continue
         
         # Run validation
-        result = validate_feature_list(data, planning_mode="new")
+        result = validate_feature_list(data, is_new_plan=True)
         
         # Create grading entry
         grade_entry = {
@@ -916,7 +920,6 @@ def main():
         epilog=(
             "Examples:\n"
             "  %(prog)s validate --input .prizmkit/plans/feature-list.json\n"
-            "  %(prog)s validate --input .prizmkit/plans/feature-list.json --mode incremental\n"
             "  %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
             "  %(prog)s template --output .prizmkit/plans/feature-list.json\n"
             "  %(prog)s generate --input draft.json --output .prizmkit/plans/feature-list.json\n"
@@ -938,12 +941,6 @@ def main():
     p_validate.add_argument(
         "--output", help="Path to write validated output (optional)"
     )
-    p_validate.add_argument(
-        "--mode",
-        choices=["new", "incremental"],
-        default="new",
-        help="Validation mode (default: new)",
-    )
 
     # -- template --
     p_template = subparsers.add_parser(
@@ -965,12 +962,6 @@ def main():
     p_generate.add_argument(
         "--output", required=True, help="Path to write final feature-list.json"
     )
-    p_generate.add_argument(
-        "--mode",
-        choices=["new", "incremental"],
-        default="new",
-        help="Validation mode (default: new)",
-    )
 
     # -- summary --
     p_summary = subparsers.add_parser(

package/bundled/skills/prizm-kit/SKILL.md

@@ -72,7 +72,7 @@ All three follow the same per-task flow. Detailed documentation policies (when t
 | `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
 | `/prizmkit-retrospective` | Sync .prizmkit/prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
 | `/prizmkit-committer` | Safe git commit with Conventional Commits | "commit", "submit", "finish", "ship it" |
-| `/prizmkit-test` | Generate + run tests, analyze coverage gaps, unified quality report | "test", "run tests", "check quality", "verify code", "补测试" |
+| `/prizmkit-test` | Generate + run tests, analyze coverage gaps, unified quality report | "test", "run tests", "check quality", "verify code", "add tests" |
 | `/prizmkit-deploy` | Universal deployment gateway: SSH automation, cloud/Docker guided setup, status/logs/rollback | "deploy", "ship it", "go live", "rollback", "deploy status" |
 | `/prizmkit-init` | Project bootstrap + .prizmkit/prizm-docs/ setup | "init", "initialize", "take over this project" |
 | `/prizmkit-prizm-docs` | Doc management (init/status/rebuild/validate) | "check docs", "rebuild docs", "validate docs" |

package/bundled/skills/prizmkit-deploy/SKILL.md

@@ -204,14 +204,14 @@ The following sections define the SSH deployment adapter — the only fully-auto
 After Discovery routes to SSH, **before** entering the configuration wizard, ask the user how they want to deploy.
 
 **First question:**
-> "你想怎么部署到服务器？"
-> - **A. 直接上传（快速上手）** — 本地构建，传到服务器启动。适合第一次部署。
-> - **B. CI/CD 自动部署（推荐）** — 配置 GitHub Actions，以后 `git push` 自动部署。
+> "How do you want to deploy to the server?"
+> - **A. Direct Upload (quick start)** — build locally, transfer to server and start. Good for first deployment.
+> - **B. CI/CD Auto-Deploy (recommended)** — configure GitHub Actions, then `git push` auto-deploys.
 
 **If user chooses CI/CD, second question:**
-> "CI/CD 有两种模式："
-> - **Push 模式** — GitHub Actions runner 编译，SCP 传到服务器。服务器压力小。
-> - **Pull 模式** — 服务器自己拉代码编译。配置更简单但需 Deploy Key。
+> "CI/CD has two modes:"
+> - **Push mode** — GitHub Actions runner builds, SCP transfers to server. Low server load.
+> - **Pull mode** — server pulls code and builds itself. Simpler config but requires a Deploy Key.
 
 For detailed mode descriptions and the full Push/Pull comparison table, read `references/deployment-modes.md`.
 
@@ -306,7 +306,7 @@ After generating the workflow, verify: the first `git push` to the configured br
 
 Before SSL, check if the user has a domain pointing to the server.
 
-1. Ask: "你有没有域名要绑定到这个项目？" If no domain → skip DNS + SSL, note in deploy.md.
+1. Ask: "Do you have a domain to bind to this project?" If no domain → skip DNS + SSL, note in deploy.md.
 2. Check DNS: `dig +short <domain> A`. If resolved → proceed to SSL.
 3. If not resolved: show the user DNS setup instructions. Full procedure in `references/dns-setup.md`.
 
@@ -360,7 +360,7 @@ If no previous release exists, rollback is not possible — state this clearly.
 
 After a successful direct-upload deployment, proactively offer CI/CD setup:
 
-> "部署成功。要不要顺手帮你配置 CI/CD 自动部署？以后 `git push` 就自动上线。"
+> "Deployment succeeded. Want me to set up CI/CD auto-deploy? After that, `git push` will auto-deploy."
 
 If user agrees, ask push vs pull, then configure accordingly. If Pull mode: set up deploy key. If Push mode: add GitHub Actions secrets. Generate `deploy.yml` from `references/ci-cd-workflows.md`, update `deployStrategy` in config, write upgrade event to history.
 

package/bundled/skills/prizmkit-deploy/references/database-setup.md

@@ -6,9 +6,9 @@ Read this file when Discovery detected a database driver and the user wants AI-a
 
 During Discovery Step 1 (Project Detection), database drivers were already scanned. If a driver was detected, ask after bootstrap tools are installed:
 
-> "检测到项目使用了 <PostgreSQL/MySQL/Redis>，需要帮你在服务器上安装配置吗？"
-> - **需要** → 继续数据库安装
-> - **不需要** → 跳过，记录到 deploy.md，标注"数据库需用户自行配置"
+> "Detected the project uses <PostgreSQL/MySQL/Redis>. Want me to install and configure it on the server?"
+> - **Yes** → proceed with database installation
+> - **No** → skip, record in deploy.md with note "database must be configured by user"
 
 ## PostgreSQL setup
 
@@ -21,7 +21,7 @@ sudo -u postgres psql -c "GRANT ALL ON DATABASE <project> TO <project>;"
 
 - Generate a secure random password (32 chars, alphanumeric + symbols).
 - Write the connection string to `.prizmkit/deploy/secrets.local.json`: `DATABASE_URL=postgresql://<project>:<password>@localhost:5432/<project>`.
-- In deploy.md, write: "PostgreSQL 已安装，连接信息已记录到 `.prizmkit/deploy/secrets.local.json`（不提交到 git）".
+- In deploy.md, write: "PostgreSQL installed, connection info recorded in `.prizmkit/deploy/secrets.local.json` (not committed to git)".
 
 ## MySQL setup (future)
 

package/bundled/skills/prizmkit-deploy/references/deployment-modes.md

@@ -34,14 +34,14 @@ Best for: simple setup, servers with sufficient CPU/RAM, projects where build is
 
 ## Comparison
 
-| 对比 | Push 模式 | Pull 模式 |
+| Aspect | Push mode | Pull mode |
 |------|----------|----------|
-| 构建位置 | GitHub Actions runner | 服务器本地 |
-| 服务器压力 | 低（只运行应用） | 高（编译+运行） |
-| 配置复杂度 | 中（需 SCP 传产物） | 低（只需 SSH 触发脚本） |
-| 适合场景 | 服务器配置低、编译重 | 部署简单优先、服务器性能充裕 |
-| Deploy Key 需要 | 不需要 | 需要 |
-| 产物传输 | SCP tarball | git pull（仅增量） |
+| Build location | GitHub Actions runner | Server (local) |
+| Server load | Low (runs app only) | High (build + run) |
+| Config complexity | Medium (needs SCP transfer) | Low (SSH-triggered script only) |
+| Best for | Low-spec servers, heavy builds | Simple setup, capable servers |
+| Deploy Key required | No | Yes |
+| Artifact transfer | SCP tarball | git pull (incremental) |
 
 ## Common ground between all modes
 

package/bundled/skills/prizmkit-deploy/references/dns-setup.md

@@ -14,21 +14,21 @@ If not: continue below.
 ## Step 2 — DNS setup guidance
 
 ```
-域名 <example.com> 还未指向服务器 <服务器IP>。
+Domain <example.com> is not yet pointing to server <server-IP>.
 
-请在 DNS 服务商（如阿里云、Cloudflare、Namecheap）添加以下记录：
+Add the following record at your DNS provider (e.g., Alibaba Cloud, Cloudflare, Namecheap):
 
   Type:  A
   Name:  @
-  Value: <服务器IP>
+  Value: <server-IP>
   TTL:   600
 
-如果要同时支持 www 子域名：
+To also support the www subdomain:
   Type:  A
   Name:  www
-  Value: <服务器IP>
+  Value: <server-IP>
 
-配置完成后回复"好了"，我继续检查并配 SSL 证书。
+Reply "done" when configured, and I'll verify and set up the SSL certificate.
 ```
 
 ## Step 3 — Verify after user confirmation
@@ -39,4 +39,4 @@ If not: continue below.
 
 ## Edge case — IP-only deployment
 
-If user has no domain: skip DNS + SSL sections. Generate a note in deploy.md: "项目通过 IP 访问，未配置域名和 HTTPS。建议购买域名后运行 `/prizmkit-deploy setup-ssl`。"
+If user has no domain: skip DNS + SSL sections. Generate a note in deploy.md: "Project accessed via IP, no domain or HTTPS configured. Recommend purchasing a domain and running `/prizmkit-deploy setup-ssl`."