litclaude-ai 0.2.2

package/plugins/litclaude/skills/deep-interview/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: deep-interview
+description: Socratic deep-interview loop that turns a vague idea into an execution-ready spec, using a quantitative ambiguity score to gate when requirements are clear enough to build. Use this BEFORE planning or implementation whenever a request is broad, underspecified, or missing acceptance criteria — or when the user says "interview me", "ask me everything", "don't assume", or "deep interview".
+argument-hint: "[--quick|--standard|--deep] <idea or vague description>"
+---
+
+<Purpose>
+Deep Interview is an intent-first Socratic clarification loop that runs before planning or implementation. It turns vague ideas into execution-ready specifications by asking targeted questions about why the user wants a change, how far it should go, what should stay out of scope, and what the implementer may decide without confirmation.
+</Purpose>
+
+<Use_When>
+- The request is broad, ambiguous, or missing concrete acceptance criteria
+- The user says "deep interview", "interview me", "ask me everything", or "don't assume"
+- The user wants to avoid misaligned implementation from underspecified requirements
+- You need a clear requirements artifact before handing off to planning or implementation
+</Use_When>
+
+<Do_Not_Use_When>
+- The request already has concrete file/symbol targets and clear acceptance criteria
+- The user explicitly asks to skip planning/interview and execute immediately
+- The user asks for lightweight, open-ended brainstorming only
+- A complete spec/plan already exists and execution should start
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Execution quality is usually bottlenecked by intent clarity, not just missing implementation detail. A single expansion pass often misses why the user wants a change, where the scope should stop, which tradeoffs are unacceptable, and which decisions still require user approval. This workflow applies Socratic pressure + quantitative ambiguity scoring so downstream planning and execution begin with an explicit, testable, intent-aligned spec.
+</Why_This_Exists>
+
+<Depth_Profiles>
+| Profile | Flag | Target ambiguity | Max rounds | Use for |
+|---------|------|-----------------:|-----------:|---------|
+| Quick | `--quick` | ≤ 30% | 5 | Fast pre-spec pass |
+| Standard *(default)* | `--standard` | ≤ 20% | 12 | Full requirement interview |
+| Deep | `--deep` | ≤ 15% | 20 | High-rigor exploration |
+
+If no flag is provided, use **Standard**.
+</Depth_Profiles>
+
+<Execution_Policy>
+- Ask ONE question per round (never batch)
+- Ask about intent and boundaries before implementation detail
+- Target the weakest clarity dimension each round after applying the stage-priority rules below
+- Treat every answer as a claim to pressure-test before moving on: the next question should usually demand evidence or examples, expose a hidden assumption, force a tradeoff or boundary, or reframe root cause vs symptom
+- Do not rotate to a new clarity dimension just for coverage when the current answer is still vague; stay on the same thread until one layer deeper, one assumption clearer, or one boundary tighter
+- Before crystallizing, complete at least one explicit pressure pass that revisits an earlier answer with a deeper, assumption-focused, or tradeoff-focused follow-up
+- Gather codebase facts with read-only search tools (or an exploration subagent) before asking the user about internals
+- Keep exploration prompts narrow and concrete; fall back to the user only for facts that can't be discovered directly
+- Always run a preflight context intake before the first interview question
+- Reduce user effort: ask only the highest-leverage unresolved question, and never ask the user for codebase facts you can discover yourself
+- For brownfield work, prefer evidence-backed confirmation questions such as "I found X in Y. Should this change follow that pattern?"
+- Prefer a structured user-input tool (`AskUserQuestion` / equivalent) for each round; if none is available, fall back to concise plain-text one-question turns
+- Re-score ambiguity after each answer and show progress transparently
+- Do not hand off to execution while ambiguity remains above threshold unless the user explicitly opts to proceed with warning
+- Do not crystallize or hand off while `Non-goals` or `Decision Boundaries` remain unresolved, even if the weighted ambiguity threshold is met
+- Treat early exit as a safety valve, not the default success path
+- Persist progress to a state file after each round so the interview can resume if interrupted
+</Execution_Policy>
+
+<Steps>
+
+## Phase 0: Preflight Context Intake
+
+1. Parse `{{ARGUMENTS}}` and derive a short task slug.
+2. Attempt to load the latest relevant context snapshot from `deep-interview/{slug}-context.md`.
+3. If no snapshot exists, create a minimum context snapshot with:
+   - Task statement
+   - Desired outcome
+   - Stated solution (what the user asked for)
+   - Probable intent hypothesis (why they likely want it)
+   - Known facts/evidence
+   - Constraints
+   - Unknowns/open questions
+   - Decision-boundary unknowns
+   - Likely codebase touchpoints
+4. Save the snapshot to `deep-interview/{slug}-context.md` and reference it in the state file.
+
+## Phase 1: Initialize
+
+1. Parse `{{ARGUMENTS}}` and depth profile (`--quick|--standard|--deep`).
+2. Detect project context:
+   - Classify **brownfield** (existing codebase target) vs **greenfield** using read-only search.
+   - For brownfield, collect relevant codebase context before questioning.
+3. Initialize the state file at `deep-interview/{slug}-state.json`. Set `threshold` and `max_rounds` from the chosen profile (see the Depth Profiles table) — the values below are illustrative:
+
+```json
+{
+  "active": true,
+  "current_phase": "deep-interview",
+  "state": {
+    "interview_id": "<uuid>",
+    "profile": "quick|standard|deep",
+    "type": "greenfield|brownfield",
+    "initial_idea": "<user input>",
+    "rounds": [],
+    "current_ambiguity": 1.0,
+    "threshold": 0.2,
+    "max_rounds": 12,
+    "challenge_modes_used": [],
+    "codebase_context": null,
+    "current_stage": "intent-first",
+    "current_focus": "intent",
+    "context_snapshot_path": "deep-interview/<slug>-context.md"
+  }
+}
+```
+
+4. Announce kickoff with a compact banner so the user immediately understands the contract (profile, target, budget, starting point). Render it before the first question:
+
+```
+🎯 Deep Interview · {Quick|Standard|Deep} · {greenfield|brownfield}
+   Goal      turn "{short initial idea}" into an execution-ready spec
+   Target    ambiguity ≤ {threshold}%   ·   Budget   up to {max_rounds} rounds
+   Starting  ambiguity {score}%   ·   One question per round, intent before detail
+```
+
+   For a colorized banner, run `scripts/render_progress.py banner --color always ...` via Bash (see the renderer note in 2b).
+
+## Phase 2: Socratic Interview Loop
+
+Repeat until ambiguity `<= threshold`, the pressure pass is complete, the readiness gates are explicit, the user exits with warning, or max rounds are reached.
+
+### 2a) Generate next question
+Use:
+- Original idea
+- Prior Q&A rounds
+- Current dimension scores
+- Brownfield context (if any)
+- Activated challenge mode injection (Phase 3)
+
+Target the lowest-scoring dimension, but respect stage priority:
+- **Stage 1 — Intent-first:** Intent, Outcome, Scope, Non-goals, Decision Boundaries
+- **Stage 2 — Feasibility:** Constraints, Success Criteria
+- **Stage 3 — Brownfield grounding:** Context Clarity (brownfield only)
+
+Follow-up pressure ladder after each answer:
+1. Ask for a concrete example, counterexample, or evidence signal behind the latest claim
+2. Probe the hidden assumption, dependency, or belief that makes the claim true
+3. Force a boundary or tradeoff: what would you explicitly not do, defer, or reject?
+4. If the answer still describes symptoms, reframe toward essence / root cause before moving on
+
+Prefer staying on the same thread for multiple rounds when it has the highest leverage. Breadth without pressure is not progress.
+
+Detailed dimensions:
+- Intent Clarity — why the user wants this
+- Outcome Clarity — what end state they want
+- Scope Clarity — how far the change should go
+- Constraint Clarity — technical or business limits that must hold
+- Success Criteria Clarity — how completion will be judged
+- Context Clarity — existing codebase understanding (brownfield only)
+
+`Non-goals` and `Decision Boundaries` are mandatory readiness gates. Ask about them early and keep revisiting them until they are explicit.
+
+### 2b) Ask the question
+Lead with a one-glance ambiguity meter so the user always sees how close the spec is to ready and how much budget remains. The meter is a *draining gauge*: the filled cells represent the ambiguity that still remains, and a `┊` tick marks the target — the job each round is to drain the filled edge down to or under the tick. The fill reads red while far from target, amber as it approaches, and green once at or under it.
+
+```
+Round {n}/{max_rounds}  ·  Stage {1-3}: {stage name}  ·  Focus: {weakest_dimension}
+Ambiguity  {score}%  [███████░░░░░░░░░░░░░░░]  target ≤ {threshold}%   (┊ tick appears as you drain past it)
+```
+
+Then ask exactly one question.
+
+**Optional color rendering (pretty TUI):** for a polished colorized terminal display, render the banner / meter / breakdown with the bundled `scripts/render_progress.py` via the Bash tool — a terminal renders its ANSI color, whereas the assistant's markdown reply channel does not, so never paste raw escape codes into a reply. The script degrades to plain text under `--color never` or `NO_COLOR`, so it's safe everywhere. Example:
+
+```
+python3 scripts/render_progress.py --color always meter \
+  --round {n} --max-rounds {max} --stage "{1-3}: {stage}" \
+  --focus {dimension} --ambiguity {score} --threshold {threshold}
+```
+
+The inline markdown blocks above are the always-works fallback; reach for the script when a richer TUI is wanted.
+
+**Rendering with structured tools:** when `AskUserQuestion` (or equivalent) is available, prefer it for crisp option capture — but those tools don't render the meter inside the prompt. So emit the meter line (or run the script) *immediately before* the tool call, use the focus dimension as the short header chip (e.g. `Scope`, `Non-goals`), and put the round/ambiguity context in the question text. If no structured tool is available, fall back to a plain-text single-question turn with the same meter on top.
+
+### 2c) Score ambiguity
+Score each weighted dimension in `[0.0, 1.0]` with justification + gap.
+
+Greenfield: `ambiguity = 1 - (intent × 0.30 + outcome × 0.25 + scope × 0.20 + constraints × 0.15 + success × 0.10)`
+
+Brownfield: `ambiguity = 1 - (intent × 0.25 + outcome × 0.20 + scope × 0.20 + constraints × 0.15 + success × 0.10 + context × 0.10)`
+
+Readiness gate:
+- `Non-goals` must be explicit
+- `Decision Boundaries` must be explicit
+- A pressure pass must be complete: at least one earlier answer has been revisited with an evidence, assumption, or tradeoff follow-up
+- If either gate is unresolved, or the pressure pass is incomplete, continue interviewing even when weighted ambiguity is below threshold
+
+### 2d) Report progress
+After scoring, show a compact breakdown so the user sees *what moved* and *what's still blocking readiness*. The readiness gates are shown every round (not just at the end), because they can block crystallization even when the weighted score is already under threshold — surfacing them early tells the user exactly why the interview is still open.
+
+```
+Clarity
+  Intent      ▓▓▓▓▓▓▓▓░░  0.80   why they want it — clear
+  Outcome     ▓▓▓▓▓▓░░░░  0.60   end state — partially defined
+  Scope       ▓▓▓▓░░░░░░  0.40   ← weakest, next focus
+  Constraints ▓▓▓▓▓▓▓░░░  0.70   limits mostly known
+  Success     ▓▓▓░░░░░░░  0.30   no acceptance criteria yet
+  (Context)   ▓▓▓▓▓░░░░░  0.50   brownfield only
+
+Readiness gates
+  ✅ Non-goals explicit      ⬜ Decision Boundaries      ✅ Pressure pass done
+        → blocked by: Decision Boundaries (not yet explicit)
+
+Ambiguity {prev}% → {new}%   ·   Next: {weakest_dimension}
+```
+
+Use `✅` for met gates and `⬜` for open ones, and name what's blocking. If all gates are met and ambiguity is under threshold, say so plainly: "All gates met — ready to crystallize." For the colorized version, run `scripts/render_progress.py breakdown --color always --scores "Intent=0.80,..." --gates "nongoals=1,boundaries=0,pressure=1" --threshold {t} --prev {p} --ambiguity {a} --next {dim}` via Bash.
+
+### 2e) Persist state
+Append the round result and updated scores to the state file.
+
+### 2f) Round controls
+- Do not offer early exit before the first explicit assumption probe and one persistent follow-up have happened
+- Round 4+: allow explicit early exit with risk warning. Make it visible once available — add a quiet footer line so the user knows the escape hatch exists, e.g. `(You can say "good enough" to stop early and crystallize with the current clarity.)`
+- Soft warning at profile midpoint (e.g., round 3/6/10 depending on profile): surface remaining budget, e.g. `⚠️ Round {n}/{max_rounds} — {remaining} rounds left before the cap.`
+- Hard cap at profile `max_rounds`
+
+## Phase 3: Challenge Modes (assumption stress tests)
+
+Use each mode once when applicable. These are normal escalation tools, not rare rescue moves:
+
+- **Contrarian** (round 2+ or immediately when an answer rests on an untested assumption): challenge core assumptions
+- **Simplifier** (round 4+ or when scope expands faster than outcome clarity): probe minimal viable scope
+- **Ontologist** (round 5+ and ambiguity > 0.25, or when the user keeps describing symptoms): ask for essence-level reframing
+
+Track used modes in the state file to prevent repetition.
+
+## Phase 4: Crystallize Artifacts
+
+When threshold is met (or user exits with warning / hard cap):
+
+1. Write the interview transcript summary to `deep-interview/{slug}-transcript.md`.
+2. Write the execution-ready spec to `deep-interview/{slug}-spec.md`.
+
+Spec should include:
+- Metadata (profile, rounds, final ambiguity, threshold, context type)
+- Context snapshot reference/path (for downstream reuse)
+- Clarity breakdown table
+- Intent (why the user wants this)
+- Desired Outcome
+- In-Scope
+- Out-of-Scope / Non-goals
+- Decision Boundaries (what the implementer may decide without confirmation)
+- Constraints
+- Testable acceptance criteria
+- Assumptions exposed + resolutions
+- Pressure-pass findings (which answer was revisited, and what changed)
+- Brownfield evidence vs inference notes for any repository-grounded confirmation questions
+- Technical context findings
+- Full or condensed transcript
+
+## Phase 5: Handoff
+
+Deep-interview is a requirements mode. When the spec is ready, hand off to planning or implementation — do **not** implement directly here. The spec is the requirements source of truth: preserve intent, non-goals, decision boundaries, acceptance criteria, and any residual-risk warning across the handoff.
+
+Present a short menu of next steps and let the user choose:
+
+```
+Spec ready → deep-interview/{slug}-spec.md   ·   final ambiguity {score}%{ · residual risk: <reason>}
+
+  1. Plan      turn the spec into a detailed implementation/architecture plan first
+  2. Build     implement directly — the spec is strong enough to start
+  3. Refine    keep interviewing — ambiguity or boundaries are still too loose
+```
+
+When handing the spec to a downstream planner or implementer:
+- Pass the spec file as the requirements source of truth; don't re-run the interview unless the user asks to refine.
+- Carry the non-goals, decision boundaries, and acceptance criteria forward as binding constraints.
+
+**Residual-Risk Rule:** if the interview ended via early exit, hard-cap completion, or proceed-with-warning, state that residual-risk explicitly in the handoff so the downstream step knows it inherited a partially clarified brief.
+
+</Steps>
+
+<Tool_Usage>
+- Use read-only search tools (or an exploration subagent) for codebase fact gathering
+- Use a structured user-input tool (`AskUserQuestion` / equivalent) for each interview round when available
+- If structured question tools are unavailable, use plain-text single-question rounds and keep the same stage order
+- Persist round state to `deep-interview/{slug}-state.json` for resumability; read it back to resume
+- Read/write the context snapshot at `deep-interview/{slug}-context.md`
+- Save transcript and spec artifacts to `deep-interview/{slug}-transcript.md` and `deep-interview/{slug}-spec.md`
+- For a colorized TUI, render the banner / meter / breakdown with `scripts/render_progress.py` via Bash (ANSI shows in the terminal, not in markdown replies); it degrades to plain text under `--color never` / `NO_COLOR`
+</Tool_Usage>
+
+<Escalation_And_Stop_Conditions>
+- User says stop/cancel/abort -> persist state and stop
+- Ambiguity stalls for 3 rounds (+/- 0.05) -> force Ontologist mode once
+- Max rounds reached -> proceed with explicit residual-risk warning
+- All dimensions >= 0.9 -> allow early crystallization even before max rounds
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Preflight context snapshot exists at `deep-interview/{slug}-context.md`
+- [ ] Progress strip (round budget + ambiguity bar) shown each round
+- [ ] Readiness-gate status (`Non-goals`, `Decision Boundaries`, pressure pass) shown each round with what's blocking
+- [ ] Intent-first stage priority used before implementation detail
+- [ ] Weakest-dimension targeting used within the active stage
+- [ ] At least one explicit assumption probe happened before crystallization
+- [ ] At least one persistent follow-up / pressure pass deepened a prior answer
+- [ ] Challenge modes triggered at thresholds (when applicable)
+- [ ] Transcript written to `deep-interview/{slug}-transcript.md`
+- [ ] Spec written to `deep-interview/{slug}-spec.md`
+- [ ] Brownfield questions use evidence-backed confirmation when applicable
+- [ ] Next-step handoff menu presented (Plan / Build / Refine)
+- [ ] No direct implementation performed in this mode
+</Final_Checklist>
+
+<Advanced>
+## Resume
+
+If interrupted, rerun the skill. Resume by reading the persisted state file (`deep-interview/{slug}-state.json`) and continuing from the last completed round.
+
+## Recommended pipeline
+
+```
+deep-interview  →  planning  →  execution
+```
+
+- Stage 1 (deep-interview): clarity gate — this skill
+- Stage 2 (planning): feasibility + architecture gate
+- Stage 3 (execution): build + QA + validation gate
+</Advanced>
+
+Task: {{ARGUMENTS}}

package/plugins/litclaude/skills/deep-interview/scripts/render_progress.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Colorized TUI renderer for the deep-interview skill.
+
+Prints ANSI-colored progress surfaces — the kickoff banner, the per-round
+ambiguity meter, and the clarity breakdown + readiness gates — to stdout.
+
+Why a script instead of inline text: the assistant's markdown reply channel
+does not render ANSI escape codes (they show up as literal garbage), but the
+terminal output of a Bash command does. So run this via Bash whenever you want
+the pretty colorized TUI; the plain markdown blocks in SKILL.md remain the
+always-works fallback.
+
+Degrades gracefully: pass --color never, or set NO_COLOR=1, to emit plain text
+(safe for logs and pipes). Uses 256-color codes for broad terminal support.
+
+Examples
+--------
+  render_progress.py banner --profile Standard --context greenfield \
+      --idea "add dark mode to settings" --threshold 20 --max-rounds 12 --ambiguity 100
+
+  render_progress.py meter --round 3 --max-rounds 12 \
+      --stage "1: Intent-first" --focus Scope --ambiguity 52 --threshold 20
+
+  render_progress.py breakdown --threshold 20 --prev 60 --ambiguity 52 --next Scope \
+      --scores "Intent=0.80,Outcome=0.60,Scope=0.40,Constraints=0.70,Success=0.30" \
+      --gates "nongoals=1,boundaries=0,pressure=1"
+"""
+import argparse
+import os
+import sys
+
+# 256-color palette
+RED, AMBER, GREEN, GRAY, CYAN, WHITE = 203, 214, 78, 244, 80, 252
+_use_color = True
+
+
+def c(code, s, bold=False):
+    if not _use_color:
+        return s
+    pre = "\033[1m" if bold else ""
+    return f"{pre}\033[38;5;{code}m{s}\033[0m"
+
+
+def amb_color(amb, threshold):
+    """Red far from target, amber approaching, green at/under target."""
+    if amb <= threshold:
+        return GREEN
+    if amb <= 2 * threshold:
+        return AMBER
+    return RED
+
+
+def meter_bar(amb, threshold, width=22):
+    """Draining ambiguity meter: filled cells = remaining ambiguity, a tick
+    marks the target. Goal is to drain the filled edge at/under the tick."""
+    filled = round(width * amb / 100)
+    tick = round(width * threshold / 100)
+    col = amb_color(amb, threshold)
+    cells = []
+    for i in range(width):
+        if i < filled:
+            cells.append(c(col, "█"))
+        elif i == tick:
+            cells.append(c(GREEN if amb <= threshold else CYAN, "┊"))
+        else:
+            cells.append(c(GRAY, "░"))
+    return "".join(cells)
+
+
+def dim_bar(score, width=10):
+    filled = round(width * score)
+    col = GREEN if score >= 0.7 else AMBER if score >= 0.4 else RED
+    return c(col, "█" * filled) + c(GRAY, "░" * (width - filled))
+
+
+def banner(a):
+    bar = c(CYAN, "│")
+    edge_t = c(CYAN, "╭─")
+    edge_b = c(CYAN, "╰" + "─" * 50)
+    idea = a.idea if len(a.idea) <= 52 else a.idea[:49] + "..."
+    lines = [
+        f" {edge_t} {c(WHITE, '🎯 Deep Interview', bold=True)} {c(CYAN, '─' * 30)}",
+        f" {bar}  {c(GRAY, 'Profile ')}  {c(WHITE, a.profile)} · {a.context}",
+        f" {bar}  {c(GRAY, 'Goal    ')}  turn \"{idea}\" into an execution-ready spec",
+        f" {bar}  {c(GRAY, 'Target  ')}  ambiguity {c(GREEN, f'≤ {a.threshold}%')}   ·   Budget  up to {a.max_rounds} rounds",
+        f" {bar}  {c(GRAY, 'Start   ')}  ambiguity {c(amb_color(a.ambiguity, a.threshold), f'{a.ambiguity}%')}   ·   one question / round, intent before detail",
+        f" {edge_b}",
+    ]
+    print("\n".join(lines))
+
+
+def meter(a):
+    head = (
+        f"{c(GRAY, 'Round')} {c(WHITE, f'{a.round}/{a.max_rounds}', bold=True)}"
+        f"  {c(GRAY, '·')}  {c(GRAY, 'Stage')} {a.stage}"
+        f"  {c(GRAY, '·')}  {c(GRAY, 'Focus:')} {c(CYAN, a.focus)}"
+    )
+    bar = meter_bar(a.ambiguity, a.threshold)
+    line = (
+        f"{c(GRAY, 'Ambiguity')} {c(amb_color(a.ambiguity, a.threshold), f'{a.ambiguity:>3}%', bold=True)} "
+        f"[{bar}] {c(GRAY, f'target ≤ {a.threshold}%')}"
+    )
+    print(head)
+    print(line)
+
+
+def breakdown(a):
+    print(c(WHITE, "Clarity", bold=True))
+    scores = {}
+    for pair in a.scores.split(","):
+        if not pair.strip():
+            continue
+        k, v = pair.split("=")
+        scores[k.strip()] = float(v)
+    weakest = min(scores, key=scores.get) if scores else None
+    for name, score in scores.items():
+        mark = c(CYAN, "  ← weakest") if name == weakest else ""
+        print(f"  {name:<12}{dim_bar(score)}  {c(WHITE, f'{score:.2f}')}{mark}")
+
+    print()
+    print(c(WHITE, "Readiness gates", bold=True))
+    gate_labels = {
+        "nongoals": "Non-goals explicit",
+        "boundaries": "Decision Boundaries",
+        "pressure": "Pressure pass done",
+    }
+    gates, open_gates = {}, []
+    for pair in a.gates.split(","):
+        if not pair.strip():
+            continue
+        k, v = pair.split("=")
+        gates[k.strip()] = v.strip() in ("1", "true", "yes")
+    cells = []
+    for key, label in gate_labels.items():
+        met = gates.get(key, False)
+        cells.append(c(GREEN, f"✅ {label}") if met else c(GRAY, f"⬜ {label}"))
+        if not met:
+            open_gates.append(label)
+    print("  " + "      ".join(cells))
+    if open_gates:
+        print(c(AMBER, f"        → blocked by: {', '.join(open_gates)}"))
+    elif a.ambiguity <= a.threshold:
+        print(c(GREEN, "        → all gates met — ready to crystallize"))
+
+    print()
+    delta = c(GREEN, "↓") if a.ambiguity < a.prev else c(GRAY, "·")
+    print(
+        f"{c(GRAY, 'Ambiguity')} {a.prev}% {delta} {c(amb_color(a.ambiguity, a.threshold), f'{a.ambiguity}%', bold=True)}"
+        f"   {c(GRAY, '·')}   {c(GRAY, 'Next:')} {c(CYAN, a.next)}"
+    )
+
+
+def main():
+    global _use_color
+    p = argparse.ArgumentParser(description="deep-interview TUI renderer")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    b = sub.add_parser("banner")
+    b.add_argument("--profile", required=True)
+    b.add_argument("--context", default="greenfield")
+    b.add_argument("--idea", default="")
+    b.add_argument("--threshold", type=int, required=True)
+    b.add_argument("--max-rounds", type=int, required=True)
+    b.add_argument("--ambiguity", type=int, default=100)
+    b.set_defaults(fn=banner)
+
+    m = sub.add_parser("meter")
+    m.add_argument("--round", type=int, required=True)
+    m.add_argument("--max-rounds", type=int, required=True)
+    m.add_argument("--stage", default="")
+    m.add_argument("--focus", default="")
+    m.add_argument("--ambiguity", type=int, required=True)
+    m.add_argument("--threshold", type=int, required=True)
+    m.set_defaults(fn=meter)
+
+    d = sub.add_parser("breakdown")
+    d.add_argument("--scores", required=True, help="Name=0.80,Name=0.60,...")
+    d.add_argument("--gates", default="nongoals=0,boundaries=0,pressure=0")
+    d.add_argument("--threshold", type=int, required=True)
+    d.add_argument("--prev", type=int, default=100)
+    d.add_argument("--ambiguity", type=int, required=True)
+    d.add_argument("--next", default="")
+    d.set_defaults(fn=breakdown)
+
+    a = p.parse_args()
+    if a.color == "never" or (a.color == "auto" and os.environ.get("NO_COLOR")):
+        _use_color = False
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

package/plugins/litclaude/skills/frontend-ui-ux/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: frontend-ui-ux
+description: Frontend and user-facing UX review discipline adapted for LitClaude for Claude Code apps, docs, CLI surfaces, and plugin install flows.
+---
+
+# Frontend UI UX
+
+Use this skill for browser UI, CLI UX, documentation UX, screenshots, and any
+user-facing workflow. For LitClaude, the main UX surface is install, command
+activation, docs, and clear terminal output.
+
+## Product Posture
+
+LitClaude is a developer/operator tool. Prefer quiet, direct, scan-friendly
+interfaces over marketing-heavy copy. A good UX lets the user install, launch,
+verify, update, and uninstall without remembering long paths.
+
+## CLI UX Rules
+
+- Show the command the user should run next.
+- Prefer `Launch with: claude` after global plugin install.
+- Keep errors actionable and short.
+- Do not expose implementation paths unless they help diagnosis.
+- Include `--dry-run` for safe inspection.
+- Do not require repeated long `claude --plugin-dir ...` commands after install.
+
+## Documentation UX
+
+- First screen should answer what it is, how to install, and how to run.
+- English and Korean READMEs should agree on commands and version.
+- Put caveats near the command they affect.
+- Avoid claiming unsupported automation such as silent `/goal` injection.
+- Keep private-use posture clear: public npm convenience, no advertisement.
+
+## Visual Assets
+
+If changing `cover.png` or visual docs, verify dimensions and rendering. In this
+repo, tests expect a PNG with social dimensions. Do not replace it with a broken
+or purely decorative asset that hides the product signal.
+
+## Manual QA
+
+For browser UI, drive the browser. For CLI UX, a tmux transcript or captured
+shell output is the surface. The artifact must show the exact text a user sees.
+
+Good LitClaude CLI QA:
+
+```sh
+npm exec --yes --package ./ -- litclaude-ai --dry-run install
+```
+
+PASS if the output shows the intended version, install paths, plugin key, and
+`Launch with: claude`.
+
+## Accessibility and Clarity
+
+- Avoid long wrapped commands when a shorter command exists.
+- Avoid jargon in first-use docs.
+- Make fallback behavior explicit only where it helps action.
+- Keep warnings near risky operations such as publish, uninstall, or registry
+  mutation.
+