thanh-kit 2.5.4 → 2.5.5

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.

package/templates/command-archive/preview.md

@@ -0,0 +1,283 @@
+---
+description: View files/directories OR generate visual explanations, slides, diagrams
+arguments:
+  - name: path
+    description: Path to file/directory to preview, OR topic for generation modes
+    required: false
+---
+
+Universal viewer + visual generator. View existing content OR generate new visual explanations.
+
+## Usage
+
+### View Mode (existing behavior)
+- `/preview <file.md>` - View markdown file in novel-reader UI
+- `/preview <directory/>` - Browse directory contents
+- `/preview --stop` - Stop running server
+
+### Generation Mode (new)
+- `/preview --explain <topic>` - Generate visual explanation (ASCII + Mermaid + prose)
+- `/preview --slides <topic>` - Generate presentation slides (one concept per slide)
+- `/preview --diagram <topic>` - Generate focused diagram (ASCII + Mermaid)
+- `/preview --ascii <topic>` - Generate ASCII-only diagram (terminal-friendly)
+
+## Examples
+
+```bash
+# View mode
+/preview plans/my-plan/plan.md     # View markdown file
+/preview plans/                    # Browse plans directory
+
+# Generation mode
+/preview --explain OAuth flow      # Generate OAuth explanation
+/preview --slides API architecture # Generate architecture slides
+/preview --diagram data flow       # Generate data flow diagram
+/preview --ascii auth process      # Generate ASCII-only diagram
+```
+
+## Argument Resolution
+
+When processing arguments, follow this priority order:
+
+1. **`--stop`** → Stop server (exit)
+2. **Generation flags** (`--explain`, `--slides`, `--diagram`, `--ascii`) → Generation mode
+3. **Resolve path from argument:**
+   - If argument is an explicit path → use directly
+   - If argument is a contextual reference (e.g., "that file", "the report", "this") → resolve from recent conversation context (look for file paths, URLs, or recently mentioned files)
+4. **Resolved path exists on filesystem** → View mode
+5. **Path doesn't exist or can't resolve** → Ask user to clarify which file they meant
+
+**Topic-to-slug conversion:**
+- Lowercase the topic
+- Replace spaces/special chars with hyphens
+- Remove non-alphanumeric except hyphens
+- Collapse multiple hyphens → single hyphen
+- Trim leading/trailing hyphens
+- **Max 80 chars** - truncate at word boundary if longer
+- If result is empty (topic was all special chars) → Error: ask for valid topic
+
+Example: `OAuth 2.0 Flow` → `oauth-2-0-flow.md`
+
+**Multiple flags:** If multiple generation flags provided, use first one; remaining treated as topic.
+Example: `/preview --explain --slides topic` → `--explain` mode, topic = "--slides topic"
+
+**Placeholder `{topic}`:** Replaced with original user input in title case (not the slug).
+
+## Execution
+
+**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`.
+
+The skill is located at `.claude/skills/markdown-novel-viewer/`.
+
+### Stop Server
+
+If `--stop` flag is provided:
+
+```bash
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs --stop
+```
+
+### Start Server
+
+Otherwise, run the `markdown-novel-viewer` server as CC background task with `--foreground` flag (keeps process alive for CC task management):
+
+```bash
+# Determine if path is file or directory
+INPUT_PATH="{{path}}"
+if [[ -d "$INPUT_PATH" ]]; then
+  # Directory mode - browse
+  node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+    --dir "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+else
+  # File mode - view markdown
+  node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+    --file "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+fi
+```
+
+**Critical:** When calling the Bash tool:
+- Set `run_in_background: true` to run as CC background task
+- Set `timeout: 300000` (5 minutes) to prevent premature termination
+- Parse JSON output and report URL to user
+
+Example Bash tool call:
+```json
+{
+  "command": "node .claude/skills/markdown-novel-viewer/scripts/server.cjs --dir \"path\" --host 0.0.0.0 --open --foreground",
+  "run_in_background": true,
+  "timeout": 300000,
+  "description": "Start preview server in background"
+}
+```
+
+After starting, parse the JSON output (e.g., `{"success":true,"url":"http://localhost:3456/view?file=...","networkUrl":"http://192.168.1.x:3456/view?file=..."}`) and report:
+- Local URL for browser access
+- Network URL for remote device access (if available)
+- Inform user that server is now running as CC background task (visible in `/tasks`)
+
+**CRITICAL:** MUST display the FULL URL including path and query string (e.g., `http://localhost:3456/view?file=/path/to/file.md`). NEVER truncate to just `host:port` (e.g., `http://localhost:3456`). The full URL is required for direct file access.
+
+---
+
+## Generation Mode
+
+When `--explain`, `--slides`, `--diagram`, or `--ascii` flag is provided:
+
+### Step 1: Determine Output Location
+
+1. Check if there's an active plan context (from `## Plan Context` in hook injection)
+2. If active plan exists: save to `{plan_dir}/visuals/{topic-slug}.md`
+3. If no active plan: save to `plans/visuals/{topic-slug}.md`
+4. Create `visuals/` directory if it doesn't exist
+
+### Step 2: Generate Content
+
+**Mermaid Diagram Syntax:**
+When generating ` ```mermaid ` code blocks, use `/mermaidjs-v11` skill for v11 syntax rules.
+
+**Essential rules (always apply):**
+- Quote node text with special characters: `A["text with /slashes"]`
+- Escape brackets in labels: `A["array[0]"]`
+
+Use the appropriate template based on flag:
+
+#### --explain (Visual Explanation)
+```markdown
+# Visual Explanation: {topic}
+
+## Overview
+Brief description of what we're explaining.
+
+## Quick View (ASCII)
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│ Component A │───>│ Component B │───>│ Component C │
+└─────────────┘    └─────────────┘    └─────────────┘
+
+## Detailed Flow
+\```mermaid
+sequenceDiagram
+    participant A as Component A
+    participant B as Component B
+    A->>B: Request
+    B-->>A: Response
+\```
+
+## Key Concepts
+1. **Concept A** - Explanation
+2. **Concept B** - Explanation
+
+## Code Example (if applicable)
+\```typescript
+// Relevant code snippet with comments
+\```
+```
+
+#### --slides (Presentation Format)
+```markdown
+# {Topic} - Visual Presentation
+
+---
+
+## Slide 1: Introduction
+- One concept per slide
+- Bullet points only
+
+---
+
+## Slide 2: The Problem
+\```mermaid
+flowchart TD
+    A[Problem] --> B[Impact]
+\```
+
+---
+
+## Slide 3: The Solution
+- Key point 1
+- Key point 2
+
+---
+
+## Slide 4: Summary
+Key takeaways...
+```
+
+#### --diagram (Focused Diagram)
+```markdown
+# Diagram: {topic}
+
+## ASCII Version
+┌──────────────────────────────────────────┐
+│               Architecture               │
+├─────────────┬──────────────┬─────────────┤
+│   Layer 1   │   Layer 2    │   Layer 3   │
+└─────────────┴──────────────┴─────────────┘
+
+## Mermaid Version
+\```mermaid
+flowchart TB
+    subgraph Layer1[Layer 1]
+        A[Component A]
+    end
+    subgraph Layer2[Layer 2]
+        B[Component B]
+    end
+    A --> B
+\```
+```
+
+#### --ascii (Terminal-Friendly Only)
+```
+┌────────────────────────────────────────────────────────┐
+│                    {Topic} Overview                    │
+├────────────────────────────────────────────────────────┤
+│                                                        │
+│   ┌─────────┐       ┌─────────┐       ┌─────────┐      │
+│   │  Input  │──────>│ Process │──────>│ Output  │      │
+│   └─────────┘       └─────────┘       └─────────┘      │
+│                                                        │
+│   Legend:                                              │
+│   ──────>  Data flow                                   │
+│   ──────   Connection                                  │
+│                                                        │
+└────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Save and Preview
+
+1. Write generated content to determined path
+2. Start preview server with the generated file:
+```bash
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+  --file "<generated-file-path>" \
+  --host 0.0.0.0 \
+  --open \
+  --foreground
+```
+
+### Step 4: Report to User
+
+Report:
+- Generated file path
+- Preview URL (local + network)
+- Remind: file saved in plan's `visuals/` folder for future reference
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Invalid topic (empty) | Ask user to provide a topic |
+| Flag without topic (`/preview --explain`) | Ask user: "Please provide a topic: `/preview --explain <topic>`" |
+| Topic becomes empty after sanitization | Ask user to provide topic with alphanumeric characters |
+| File write failure | Report error, suggest checking permissions |
+| Server startup failure | Check if port in use, try `/preview --stop` first |
+| No generation flag + unresolvable reference | Ask user to clarify which file they meant |
+| Existing file at output path | Overwrite with new content (no prompt) |
+| Server already running | Reuse existing server instance, just open new URL |
+| Parent `plans/` dir missing | Create directories recursively before write |