thanh-kit 2.5.1 → 2.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thanh-kit",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "CLI tool to scaffold AI agent projects with pre-configured kits (Claude, OpenCode, Codex)",
   "type": "module",
   "bin": {

package/templates/{commands → command-archive}/ask.md

@@ -8,10 +8,10 @@ Technical question or architecture challenge:
 <questions>$ARGUMENTS</questions>
 
 Current development workflows, system constraints, scale requirements, and business context will be considered:
-- Primary workflow: `./.claude/workflows/primary-workflow.md`
-- Development rules: `./.claude/workflows/development-rules.md`
-- Orchestration protocols: `./.claude/workflows/orchestration-protocol.md`
-- Documentation management: `./.claude/workflows/documentation-management.md`
+- Primary workflow: `./.claude/rules/primary-workflow.md`
+- Development rules: `./.claude/rules/development-rules.md`
+- Orchestration protocols: `./.claude/rules/orchestration-protocol.md`
+- Documentation management: `./.claude/rules/documentation-management.md`
 
 **Project Documentation:**
 ```
@@ -35,7 +35,7 @@ You operate by the holy trinity of software engineering: **YAGNI** (You Aren't G
 
 ## Process
 1. **Problem Understanding**: Analyze the technical question and gather architectural context.
-   - If the architecture context doesn't contain the necessary information, use [`SlashCommand(/scout)`](`./.claude/commands/scout.md`) to scout the codebase again.
+   - If the architecture context doesn't contain the necessary information, use the `scout` skill to scout the codebase again.
 2. **Expert Consultation**:
    - Systems Designer: Define system boundaries, data flows, and component relationships
    - Technology Strategist: Evaluate technology choices, patterns, and industry best practices

package/templates/{commands → command-archive}/ck-help.md

@@ -6,7 +6,23 @@ argument-hint: [category|command|task description]
 Think harder.
 All-in-one ClaudeKit guide. Run the script and present output based on type markers.
 
-## Pre-Processing
+## Intent Validation
+
+The script uses keyword matching with smart weighting. After getting results, **validate** against these heuristics:
+
+| Sentence Pattern | Primary Intent | Example |
+|------------------|----------------|---------|
+| `[action verb] my [object]` | The action verb | "commit my changes" → git |
+| `[context] [subject noun]` | The subject noun | "setup notifications" → notifications |
+| `[noun] [noun]` | Last noun (topic) | "discord webhook" → notifications |
+
+**Action verbs** (high intent when first): fix, test, commit, push, build, create, review, deploy, run, check, find, plan, refactor
+
+**Context words** (low intent, modify subject): setup, add, start, new, my, the, configure
+
+**Override script only if:** result clearly mismatches the sentence pattern above. Otherwise trust the algorithm.
+
+## Translation
 
 **IMPORTANT: Always translate `$ARGUMENTS` to English before passing to script.**
 
@@ -108,6 +124,6 @@ Never replace or summarize the script output. Always show it fully, then enhance
 
 ## Important: Correct Workflows
 
-- **`/plan` → `/code`**: Plan first, then execute the plan
+- **`/plan` → `/cook`**: Plan first, then execute the plan
 - **`/cook`**: Standalone - plans internally, no separate `/plan` needed
 - **NEVER** suggest `/plan` → `/cook` (cook has its own planning)

package/templates/command-archive/docs/init.md

@@ -0,0 +1,38 @@
+---
+description: ⚡⚡⚡⚡ Analyze the codebase and create initial documentation
+---
+
+## Phase 1: Parallel Codebase Scouting
+
+1. Scan the codebase and calculate the number of files with LOC in each directory (skip credentials, cache or external modules directories, such as `.claude`, `.opencode`, `.git`, `tests`, `node_modules`, `__pycache__`, `secrets`, etc.)
+2. Target directories **that actually exist** - adapt to project structure, don't hardcode paths
+3. Activate `scout` skill to explore the code base and return detailed summary reports to the main agent
+4. Merge scout reports into context summary
+
+## Phase 2: Documentation Creation (docs-manager Agent)
+
+**CRITICAL:** You MUST spawn `docs-manager` agent via Task tool with merged reports. Do not wait for user input.
+
+Pass the gathered context to docs-manager agent to create initial documentation:
+- `README.md`: Update README with initial documentation (keep it under 300 lines)
+- `docs/project-overview-pdr.md`: Project overview and PDR (Product Development Requirements)
+- `docs/codebase-summary.md`: Codebase summary
+- `docs/code-standards.md`: Codebase structure and code standards
+- `docs/system-architecture.md`: System architecture
+- `docs/project-roadmap.md`: Project roadmap
+- `docs/deployment-guide.md` [optional]: Deployment guide
+- `docs/design-guidelines.md` [optional]: Design guidelines
+
+Use `docs/` directory as the source of truth for documentation.
+
+## Phase 3: Size Check (Post-Generation)
+
+After docs-manager completes:
+1. Run `wc -l docs/*.md 2>/dev/null | sort -rn` to check LOC
+2. Use `docs.maxLoc` from session context (default: 800)
+3. For files exceeding limit:
+   - Report which files exceed and by how much
+   - docs-manager should have already split proactively per Section 6 guidelines
+   - If still oversized, ask user: split now or accept as-is?
+
+**IMPORTANT**: **Do not** start implementing.

package/templates/command-archive/docs/summarize.md

@@ -0,0 +1,22 @@
+---
+description: '⚡ Analyze the codebase and update documentation'
+argument-hint: '[focused-topics] [should-scan-codebase]'
+---
+
+Activate `scout` skill to analyze the codebase and update `docs/codebase-summary.md` and respond with a summary report.
+
+## Arguments:
+$1: Focused topics (default: all)
+$2: Should scan codebase (`Boolean`, default: `false`)
+
+## Focused Topics:
+<focused_topics>$1</focused_topics>
+
+## Should Scan Codebase:
+<should_scan_codebase>$2</should_scan_codebase>
+
+## Important:
+- Use `docs/` directory as the source of truth for documentation.
+- Do not scan the entire codebase unless the user explicitly requests it.
+
+**IMPORTANT**: **Do not** start implementing.

package/templates/command-archive/docs/update.md

@@ -0,0 +1,76 @@
+---
+description: ⚡⚡⚡ Analyze the codebase and update documentation
+---
+
+## Phase 1: Parallel Codebase Scouting
+
+1. Scan the codebase and calculate the number of files with LOC in each directory (skip credentials, cache or external modules directories, such as `.claude`, `.opencode`, `.git`, `tests`, `node_modules`, `__pycache__`, `secrets`, etc.)
+2. Target directories **that actually exist** - adapt to project structure, don't hardcode paths
+3. Activate `scout` skill to explore the code base and return detailed summary reports to the main agent
+4. Merge scout reports into context summary
+
+## Phase 1.5: Parallel Documentation Reading
+
+**You (main agent) must spawn readers** - subagents cannot spawn subagents.
+
+1. Count docs: `ls docs/*.md 2>/dev/null | wc -l`
+2. Get LOC: `wc -l docs/*.md 2>/dev/null | sort -rn`
+3. Strategy:
+   - 1-3 files: Skip parallel reading, docs-manager reads directly
+   - 4-6 files: Spawn 2-3 `Explore` agents
+   - 7+ files: Spawn 4-5 `Explore` agents (max 5)
+4. Distribute files by LOC (larger files get dedicated agent)
+5. Each agent prompt: "Read these docs, extract: purpose, key sections, areas needing update. Files: {list}"
+6. Merge results into context for docs-manager
+
+### Workload Distribution Example
+
+| Agent | Files | Est. LOC |
+|-------|-------|----------|
+| 1 | codebase-summary.md (800) | 800 |
+| 2 | system-architecture.md (400), code-standards.md (300) | 700 |
+| 3 | project-overview-pdr.md (500), project-roadmap.md (200) | 700 |
+
+## Phase 2: Documentation Update (docs-manager Agent)
+
+**CRITICAL:** You MUST spawn `docs-manager` agent via Task tool with merged reports and doc readings. Do not wait for user input.
+
+Pass the gathered context to docs-manager agent to update documentation:
+- `README.md`: Update README (keep it under 300 lines)
+- `docs/project-overview-pdr.md`: Update project overview and PDR (Product Development Requirements)
+- `docs/codebase-summary.md`: Update codebase summary
+- `docs/code-standards.md`: Update codebase structure and code standards
+- `docs/system-architecture.md`: Update system architecture
+- `docs/project-roadmap.md`: Update project roadmap
+- `docs/deployment-guide.md` [optional]: Update deployment guide
+- `docs/design-guidelines.md` [optional]: Update design guidelines
+
+## Additional requests
+<additional_requests>
+  $ARGUMENTS
+</additional_requests>
+
+## Phase 3: Size Check (Post-Update)
+
+After docs-manager completes:
+1. Run `wc -l docs/*.md 2>/dev/null | sort -rn` to check LOC
+2. Use `docs.maxLoc` from session context (default: 800)
+3. For files exceeding limit:
+   - Report which files exceed and by how much
+   - docs-manager should have already split proactively per Section 6 guidelines
+   - If still oversized, ask user: split now or accept as-is?
+
+## Phase 4: Documentation Validation (Post-Update)
+
+Run validation to detect potential hallucinations:
+1. Run: `node .claude/scripts/validate-docs.cjs docs/`
+2. Display validation report (warnings only, non-blocking)
+3. Checks performed:
+   - Code references: Verify `functionName()` and `ClassName` exist in codebase
+   - Internal links: Verify `[text](./path.md)` links point to existing files
+   - Config keys: Verify `ENV_VAR` mentioned in docs exist in `.env.example`
+
+## Important
+- Use `docs/` directory as the source of truth for documentation.
+
+**IMPORTANT**: **Do not** start implementing.

package/templates/command-archive/journal.md

@@ -0,0 +1,18 @@
+---
+description: ⚡ Write some journal entries.
+---
+
+## Writing Style Detection
+
+Before writing, check for a writing-styles directory:
+1. Check `docs/writing-styles/` — if exists, read all `.md` files inside
+2. Check `assets/writing-styles/` — if exists and step 1 not found, read all `.md` files inside
+3. If writing styles found → adopt tone, vocabulary, sentence structure, and formatting rules from those files
+4. If no writing-styles directory found → write freely in a natural, conversational tone
+
+## Journal Writing
+
+Use the `journal-writer` subagent to explore the memories and recent code changes, and write journal entries.
+- Concise, focused on important events, key changes, impacts, and decisions
+- Apply detected writing style (if any) to the journal voice
+- Keep journal entries in `docs/journal/` directory

package/templates/{commands → command-archive}/kanban.md

@@ -1,8 +1,8 @@
 ---
-description: AI agent orchestration board (Coming Soon)
+description: 'AI agent orchestration board (Coming Soon)'
 arguments:
   - name: dir
-    description: Plans directory (default: ./plans)
+    description: 'Plans directory (default: ./plans)'
     required: false
 ---
 
@@ -26,16 +26,14 @@ Plans dashboard with progress tracking and timeline visualization.
 
 **IMPORTANT:** Run server as Claude Code background task using `run_in_background: true` with the Bash tool. This makes the server visible in `/tasks` and manageable via `KillShell`.
 
-Check if this script is located in the current workspace or in `$HOME/.claude/skills/plans-kanban` directory:
-- If in current workspace: `$SKILL_DIR_PATH` = `./.claude/skills/plans-kanban/`
-- If in home directory: `$SKILL_DIR_PATH` = `$HOME/.claude/skills/plans-kanban/`
+The skill is located at `.claude/skills/plans-kanban/`.
 
 ### Stop Server
 
 If `--stop` flag is provided:
 
 ```bash
-node $SKILL_DIR_PATH/scripts/server.cjs --stop
+node .claude/skills/plans-kanban/scripts/server.cjs --stop
 ```
 
 ### Start Server
@@ -48,7 +46,7 @@ INPUT_DIR="{{dir}}"
 PLANS_DIR="${INPUT_DIR:-./plans}"
 
 # Start kanban dashboard
-node $SKILL_DIR_PATH/scripts/server.cjs \
+node .claude/skills/plans-kanban/scripts/server.cjs \
   --dir "$PLANS_DIR" \
   --host 0.0.0.0 \
   --open \

package/templates/{commands → command-archive}/plan/archive.md

@@ -38,8 +38,8 @@ Start archiving the plans based on the user's choice:
 
 ### Step 5: Ask if user wants to commit the changes
 Use `AskUserQuestion` tool to ask if user wants to commit the changes with these options:
-- Stage and commit the changes (Use `/git:cm` slash command)
-- Commit and push the changes (Use `/git:cp` slash command)
+- Stage and commit the changes (Use `/git cm` slash command)
+- Commit and push the changes (Use `/git cp` slash command)
 - Nah, I'll do it later
 
 ## Output

package/templates/command-archive/plan/red-team.md

@@ -0,0 +1,200 @@
+---
+description: Adversarial plan review — spawn hostile reviewers to find flaws, security holes, false assumptions, failure modes
+argument-hint: [plan-path]
+---
+
+## Your Mission
+
+Adversarially review an implementation plan by spawning parallel reviewer subagents that try to tear it apart. Each reviewer adopts a different hostile lens. You then adjudicate findings, and the user decides which to apply.
+
+**Mindset:** Like hiring someone who hates the implementer to destroy their work.
+
+## Plan Resolution
+
+1. If `$ARGUMENTS` provided → Use that path
+2. Else check `## Plan Context` section → Use active plan path
+3. If no plan found → Ask user to specify path or run `/plan` first
+
+## Workflow
+
+### Step 1: Read Plan Files
+
+Read the plan directory:
+- `plan.md` — Overview, phases, dependencies
+- `phase-*.md` — All phase files (full content)
+- Note: architecture decisions, assumptions, scope, risks, implementation steps
+
+Collect all plan file paths for reviewers to read directly.
+
+### Step 2: Scale Reviewer Count
+
+Scale reviewers based on plan complexity:
+
+| Phase Count | Reviewers | Lenses Selected |
+|-------------|-----------|-----------------|
+| 1-2 phases | 2 | Security Adversary + Assumption Destroyer |
+| 3-5 phases | 3 | + Failure Mode Analyst |
+| 6+ phases | 4 | + Scope & Complexity Critic (all lenses) |
+
+### Step 3: Define Adversarial Lenses
+
+Available lenses (select per Step 2):
+
+| Reviewer | Lens | Focus |
+|----------|------|-------|
+| **Security Adversary** | Attacker mindset | Auth bypass, injection, data exposure, privilege escalation, supply chain, OWASP top 10 |
+| **Failure Mode Analyst** | Murphy's Law | Race conditions, data loss, cascading failures, recovery gaps, deployment risks, rollback holes |
+| **Assumption Destroyer** | Skeptic | Unstated dependencies, false "will work" claims, missing error paths, scale assumptions, integration assumptions |
+| **Scope & Complexity Critic** | YAGNI enforcer | Over-engineering, premature abstraction, unnecessary complexity, missing MVP cuts, scope creep, gold plating |
+
+### Step 4: Spawn Reviewers
+
+Launch reviewers simultaneously via Task tool with `subagent_type: "code-reviewer"`.
+
+**Each reviewer prompt MUST include:**
+1. This override: `"IGNORE your default code-review instructions. You are reviewing a PLAN DOCUMENT, not code. There is no code to lint, build, or test. Focus exclusively on plan quality."`
+2. Their specific adversarial lens and persona
+3. The plan file paths so they can read original files directly
+4. These instructions:
+
+```
+You are a hostile reviewer. Your job is to DESTROY this plan.
+Adopt the {LENS_NAME} perspective. Find every flaw you can.
+
+Rules:
+- Be specific: cite exact phase/section where the flaw lives
+- Be concrete: describe the failure scenario, not just "could be a problem"
+- Rate severity: Critical (blocks success) | High (significant risk) | Medium (notable concern)
+- Skip trivial observations (style, naming, formatting) — not worth reporting.
+- No praise. No "overall looks good". Only findings.
+- 5-10 findings per reviewer. Quality over quantity.
+
+Output format per finding:
+## Finding {N}: {title}
+- **Severity:** Critical | High | Medium
+- **Location:** Phase {X}, section "{name}"
+- **Flaw:** {what's wrong}
+- **Failure scenario:** {concrete description of how this fails}
+- **Evidence:** {quote from plan or missing element}
+- **Suggested fix:** {brief recommendation}
+```
+
+### Step 5: Collect, Deduplicate & Cap
+
+After all reviewers complete:
+1. Collect all findings
+2. Deduplicate overlapping findings (merge if same root issue)
+3. Sort by severity: Critical → High → Medium
+4. **Cap at 15 findings:** Keep all Critical, top High by specificity, note dropped Medium count
+
+### Step 6: Adjudicate
+
+For each finding, the main agent evaluates and proposes a disposition:
+
+| Disposition | Meaning |
+|-------------|---------|
+| **Accept** | Valid flaw — plan should be updated |
+| **Reject** | False positive, acceptable risk, or already handled |
+
+**Adjudication format:**
+
+```markdown
+## Red Team Findings
+
+### Finding 1: {title} — {SEVERITY}
+**Reviewer:** {lens name}
+**Location:** {phase/section}
+**Flaw:** {description}
+**Failure scenario:** {concrete scenario}
+**Disposition:** Accept | Reject
+**Rationale:** {why accept/reject — be specific}
+```
+
+### Step 7: User Review
+
+Present the adjudicated findings to the user via `AskUserQuestion`:
+
+```
+Review red-team findings. Which dispositions do you want to change?
+```
+
+Options:
+- "Looks good, apply accepted findings" — proceed with current Accept/Reject
+- "Let me review each one" — walk through findings individually
+- "Reject all, plan is fine" — discard all findings
+
+**If "Let me review each one":**
+For each finding marked Accept, ask via `AskUserQuestion`:
+- "Apply this fix to the plan?"
+- Options: "Yes, apply" | "No, reject" | "Modify suggestion"
+
+**If "Modify suggestion":**
+Ask via `AskUserQuestion`: "Describe your modification to this finding's suggested fix:"
+(user provides free text via "Other" option)
+Record the modified suggestion in the finding's "Suggested fix" field.
+Set disposition to "Accept (modified)" in the Red Team Review table.
+
+### Step 8: Apply to Plan
+
+For each accepted finding:
+1. Locate the target phase file and section
+2. Add the fix/note inline with a marker:
+   ```markdown
+   <!-- Red Team: {finding title} — {date} -->
+   ```
+3. If finding requires new content, add to the most relevant section
+4. If finding requires removing/changing content, edit in place
+
+After applying, add a `## Red Team Review` section to `plan.md`.
+If section already exists (repeat run), **append** a new session block — never overwrite history.
+
+**Placement order in plan.md** (bottom of file):
+1. `## Red Team Review` (before validation)
+2. `## Validation Log` (after red-team)
+
+This ordering matches the execution sequence: red-team → validate.
+
+```markdown
+## Red Team Review
+
+### Session — {YYYY-MM-DD}
+**Findings:** {total} ({accepted} accepted, {rejected} rejected)
+**Severity breakdown:** {N} Critical, {N} High, {N} Medium
+
+| # | Finding | Severity | Disposition | Applied To |
+|---|---------|----------|-------------|------------|
+| 1 | {title} | Critical | Accept | Phase 2 |
+| 2 | {title} | High | Reject | — |
+```
+
+## Output
+
+After completion, provide summary:
+- Total findings by severity
+- Accepted vs rejected count
+- Files modified
+- Key risks addressed
+- Remaining concerns (if any rejected findings were borderline)
+
+## Next Steps (MANDATORY)
+
+After providing the summary, remind the user:
+
+> **Plan updated with red-team findings.** Consider running:
+> ```
+> /plan:validate {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md
+> ```
+> to re-validate decisions after changes, then:
+> ```
+> /cook --auto {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md
+> ```
+> to implement.
+
+## Important Notes
+
+**IMPORTANT:** Reviewers must be HOSTILE, not helpful. No softening language.
+**IMPORTANT:** Deduplicate aggressively — reviewers will find overlapping issues.
+**IMPORTANT:** Adjudication must be evidence-based. Don't reject valid findings to be nice.
+**IMPORTANT:** If plan has a Validation Log from `/plan:validate`, reviewers should check if validation answers introduced new assumptions.
+**IMPORTANT:** Sacrifice grammar for concision in reports.
+**IMPORTANT:** Reviewers read plan files directly — do NOT duplicate content in a summary.

package/templates/command-archive/plan/validate.md

@@ -0,0 +1,188 @@
+---
+description: Validate plan with critical questions interview
+argument-hint: [plan-path]
+---
+
+## Your mission
+
+Interview the user with critical questions to validate assumptions, confirm decisions, and surface potential issues in an implementation plan before coding begins.
+
+## Plan Resolution
+
+1. If `$ARGUMENTS` provided → Use that path
+2. Else check `## Plan Context` section → Use active plan path
+3. If no plan found → Ask user to specify path or run `/plan --hard` first
+
+## Configuration (from injected context)
+
+Check `## Plan Context` section for validation settings:
+- `mode` - Controls auto/prompt/off behavior
+- `questions` - Range like `3-8` (min-max)
+
+These values are automatically injected from user config. Use them as constraints.
+
+## Workflow
+
+### Step 1: Read Plan Files
+
+Read the plan directory:
+- `plan.md` - Overview and phases list
+- `phase-*.md` - All phase files
+- Look for decision points, assumptions, risks, tradeoffs
+
+### Step 2: Extract Question Topics
+
+Scan plan content for:
+
+| Category | Keywords to detect |
+|----------|-------------------|
+| **Architecture** | "approach", "pattern", "design", "structure", "database", "API" |
+| **Assumptions** | "assume", "expect", "should", "will", "must", "default" |
+| **Tradeoffs** | "tradeoff", "vs", "alternative", "option", "choice", "either/or" |
+| **Risks** | "risk", "might", "could fail", "dependency", "blocker", "concern" |
+| **Scope** | "phase", "MVP", "future", "out of scope", "nice to have" |
+
+### Step 3: Generate Questions
+
+For each detected topic, formulate a concrete question:
+
+**Question format rules:**
+- Each question must have 2-4 concrete options
+- Mark recommended option with "(Recommended)" suffix
+- Include "Other" option is automatic - don't add it
+- Questions should surface implicit decisions
+
+**Example questions:**
+
+```
+Category: Architecture
+Question: "How should the validation results be persisted?"
+Options:
+1. Save to plan.md frontmatter (Recommended) - Updates existing plan
+2. Create validation-answers.md - Separate file for answers
+3. Don't persist - Ephemeral validation only
+```
+
+```
+Category: Assumptions
+Question: "The plan assumes API rate limiting is not needed. Is this correct?"
+Options:
+1. Yes, rate limiting not needed for MVP
+2. No, add basic rate limiting now (Recommended)
+3. Defer to Phase 2
+```
+
+### Step 4: Interview User
+
+Use `AskUserQuestion` tool to present questions.
+
+**Rules:**
+- Use question count from `## Plan Context` → `Validation: mode=X, questions=MIN-MAX`
+- Group related questions when possible (max 4 questions per tool call)
+- Focus on: assumptions, risks, tradeoffs, architecture
+
+### Step 5: Document Answers
+
+After collecting answers, update `plan.md` with a detailed validation log. If a `## Validation Log` section already exists (from previous sessions), **append** a new session block — never overwrite history.
+
+1. Add or append to `## Validation Log` section in `plan.md`:
+
+```markdown
+## Validation Log
+
+### Session 1 — {YYYY-MM-DD}
+**Trigger:** {what prompted this validation — initial plan creation, re-validation after scope change, etc.}
+**Questions asked:** {count}
+
+#### Questions & Answers
+
+1. **[{Category}]** {full question text}
+   - Options: {A} | {B} | {C}
+   - **Answer:** {user's choice}
+   - **Custom input:** {verbatim "Other" text if user selected Other, otherwise omit this line}
+   - **Rationale:** {why this decision matters for implementation}
+
+2. **[{Category}]** {full question text}
+   - Options: {A} | {B} | {C}
+   - **Answer:** {user's choice}
+   - **Custom input:** {verbatim text, omit if N/A}
+   - **Rationale:** {why this matters}
+
+#### Confirmed Decisions
+- {decision}: {choice} — {brief why}
+
+#### Action Items
+- [ ] {specific change needed based on answers}
+
+#### Impact on Phases
+- Phase {N}: {what needs updating and why}
+```
+
+**Recording rules:**
+- **Full question text**: Copy the exact question asked, not a summary
+- **All options**: List every option that was presented
+- **Verbatim custom input**: If user selected "Other" and typed custom text, record it exactly as entered — this often contains critical context
+- **Rationale**: Explain why the decision affects implementation (helps future agents understand intent)
+- **Session numbering**: Increment session number from last existing session. First validation = Session 1
+- **Trigger**: State what prompted this validation round (initial, re-validation, scope change, etc.)
+
+2. If answers require plan changes, document them in `#### Impact on Phases` section.
+
+### Step 6: Propagate Changes to Phases (Auto-Apply)
+
+**Auto-propagate** validation decisions to affected phase files.
+
+**Process:**
+1. Parse "Impact on Phases" section → If empty, skip and report "No phase changes required"
+2. For each phase reference (accepts "Phase 2", "phase-02", "P2"):
+   - Glob for `phase-{N:02d}-*.md` → If missing, warn and skip
+   - Locate target section (exact → fuzzy → fallback to Key Insights)
+   - Apply change + add marker: `<!-- Updated: Validation Session N - {change} -->`
+   - Skip if same-session marker already exists (prevent duplication)
+
+**Section mapping:**
+| Change Type | Target Section |
+|-------------|----------------|
+| Requirements | Requirements |
+| Architecture | Architecture |
+| Scope | Overview / Implementation Steps |
+| Risk | Risk Assessment |
+| Unknown | Key Insights (new subsection) |
+
+**Error handling:** Best-effort — log warnings for missing files/sections, continue with others, report all in Output.
+
+## Output
+
+After validation completes, provide summary:
+- Number of questions asked
+- Key decisions confirmed
+- **Phase propagation results:**
+  - ✅ Files updated (with section names)
+  - ⚠️ Warnings (skipped phases, fallback sections)
+  - ❌ Errors (if any write failures)
+- Any items flagged for plan revision
+- Recommendation: proceed to implementation or revise plan first
+
+## Next Steps (MANDATORY)
+
+**IMPORTANT:** After providing the validation summary, you MUST remind the user with the **full absolute path**:
+
+> **Best Practice:** Run `/clear` before implementing to start with fresh context.
+> Then run:
+> ```
+> /cook --auto {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md
+> ```
+> *(Replace with actual absolute path, e.g., `/home/user/project/plans/260203-1234-feature/plan.md`)*
+>
+> **Why `--auto`?** Plan was already validated - safe to skip review gates.
+> **Why absolute path?** After `/clear`, the new session loses context. Worktree paths won't be discoverable without the full path.
+>
+> Fresh context helps Claude focus solely on implementation without planning context pollution, improving plan adherence.
+
+This reminder is **NON-NEGOTIABLE** - always output it at the end of validation with the actual absolute path.
+
+## Important Notes
+
+**IMPORTANT:** Only ask questions about genuine decision points - don't manufacture artificial choices.
+**IMPORTANT:** If plan is simple with few decisions, it's okay to ask fewer than min questions.
+**IMPORTANT:** Prioritize questions that could change implementation significantly.