@mohammadhprp/system-prompt 0.12.2 → 0.12.4

package/framework/skills/how/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: how
+description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation."
+disable-model-invocation: true
+---
+
+# How
+
+Explore the codebase to answer "how does X work?" questions. Produce clear architectural explanations at the level of a senior engineer onboarding onto a subsystem. Enough to build a working mental model, not annotated source code.
+
+Two modes:
+
+1. **Explain** (default). Explore the codebase and produce a clear explanation
+2. **Critique.** Explain first, then spawn multiple models to independently identify architectural issues
+
+## Explain Mode
+
+### Step 1. Understand the Question and Assess Complexity
+
+Parse what the user is asking about:
+
+- "How does the rate limiter work?", a subsystem
+- "How do we handle billing for on-demand usage?", a feature flow
+- "How is the auth service structured?", an architectural overview
+- "Walk me through what happens when a user submits a form", a runtime trace
+
+Identify the scope. If ambiguous, state your best-guess interpretation before exploring. Don't ask. Let the user redirect if you're off.
+
+**Assess complexity to decide the approach:**
+
+- **Simple** (a single module, a small utility, a narrow question like "how does function X work"): skip explorer agents; the explainer explores and explains in a single pass. Go to Step 2b.
+- **Complex** (a subsystem spanning multiple files/services, a cross-cutting feature, a full architectural overview): spawn parallel explorer agents first, then hand off to the explainer. Go to Step 2a.
+
+When in doubt, lean simple. You can always spawn explorers if the explainer hits a wall.
+
+### Step 2a. Explore (complex questions only)
+
+Decompose the question into 2-4 parallel exploration angles, each a distinct slice of the subsystem so explorers don't duplicate work. Example split for "how does the rate limiter work?":
+
+- Explorer 1: data model and state management
+- Explorer 2: request path and enforcement
+- Explorer 3: configuration and metrics infrastructure
+
+The right decomposition depends on the question. Use your judgment. Narrow questions: 2 explorers is fine. Broad subsystems: up to 4.
+
+Spawn all explorers in a single message:
+
+- `subagent_type`: `generalPurpose`
+- `model`: your configured how-explorer model (default `grok-4.6-fast-xhigh`)
+- `readonly`: `true`
+
+Each explorer gets the same base prompt from `references/explorer-prompt.md` plus a specific exploration angle naming its slice. Each explorer should:
+- Start broad: Glob for relevant directories, Grep for key types/interfaces/class names
+- Follow the thread: from an entry point, trace the call chain (callers, callees, data flow, type definitions)
+- Read the actual code, don't guess from file names
+- Stop when it can describe the full path from input to output (or trigger to effect) without hand-waving any step
+- Note things that are surprising, non-obvious, or that a newcomer would get wrong
+
+Each explorer returns structured findings: components found, flow traced, files read, anything non-obvious. Overlap between explorers is fine; the explainer reconciles.
+
+Then proceed to Step 3.
+
+### Step 2b. Direct Explain (simple questions)
+
+Spawn a single Task subagent that explores and explains in one pass:
+
+- `subagent_type`: `generalPurpose`
+- `model`: your configured how-explainer model (default `claude-fable-5-1-thinking-max`)
+- `readonly`: `true`
+
+The agent does its own exploration (Glob, Grep, Read) and writes the explanation directly. Read `references/explainer-prompt.md` for the communication style and output format. Same structure, just no explorer findings as input.
+
+Proceed to Step 4.
+
+### Step 3. Synthesize (complex questions only)
+
+Once all explorers return, spawn a single Task subagent to synthesize their findings into one coherent explanation:
+
+- `subagent_type`: `generalPurpose`
+- `model`: your configured how-explainer model (default `claude-fable-5-1-thinking-max`)
+- `readonly`: `true`
+
+The explainer gets all explorers' findings and writes the human-facing explanation (output format below). Read `references/explainer-prompt.md` for the full prompt template. The explainer reconciles overlapping findings, resolves contradictions, and weaves the slices into a unified picture.
+
+### Step 4. Present
+
+Present the explainer's output to the user. You may lightly edit for clarity or add context from the conversation, but don't substantially rewrite. The explainer's communication is the product.
+
+### Output Format
+
+Follow this structure, adapted to the question. Not every section is needed for every question.
+
+**Overview.** 1-2 paragraphs. What it is, what it does, why it exists. Enough to decide whether to keep reading.
+
+**Key Concepts.** The important types, services, or abstractions. Brief definition of each. Not exhaustive, just the ones needed to understand the rest.
+
+**How It Works.** The core of the explanation. Walk through the flow: what triggers it, what happens step by step, where data goes, the decision points. Prose, not pseudocode. Reference specific files and functions so the reader can go look, but don't dump code blocks unless a snippet is genuinely necessary.
+
+**Where Things Live.** A brief map of the relevant files/directories. Not every file, just the ones needed to start working in this area.
+
+**Gotchas.** Non-obvious or surprising things that would trip someone up. Historical context that explains why something looks weird. Known sharp edges.
+
+## Critique Mode
+
+Triggered when the user asks for architectural issues, problems, or improvements, not just understanding.
+
+### Step 1. Explain First
+
+Run the full explain flow above (Steps 1-4). You must understand the architecture before critiquing it.
+
+### Step 2. Spawn Critics
+
+After the explanation is complete, spawn one architectural critic per model in your configured how-critics list (defaults `claude-fable-5-1-thinking-max`, `gpt-5.6-sol-max`, `grok-4.6-fast-xhigh`, `claude-opus-5-thinking-xhigh`), all in a single message.
+
+For each critic:
+- `subagent_type`: `generalPurpose`
+- `model`: one model from the configured how-critics list. These are minimum reasoning levels. The lead should escalate any model when the architecture warrants deeper analysis.
+- `readonly`: `true`
+
+Read `references/critic-prompt.md` for the prompt template. Each critic gets:
+1. The explanation from Step 1 (so they don't re-explore)
+2. The relevant file paths (so they can read the actual code)
+3. The architectural critique rubric from `references/critique-rubric.md`
+
+### Step 3. Lead Judgment
+
+Same framework as the interrogate skill. You're a pragmatic lead, not an aggregator.
+
+Categorize findings:
+- **Act on.** Architectural problems worth fixing now
+- **Consider.** Real concerns, but the cost/benefit is unclear
+- **Noted.** Valid observations, low priority
+- **Dismissed.** Wrong, missing context, or style preference
+
+Present the explanation first (from Step 1), then the critique verdict below it. The explanation should stand on its own; someone who just wants to understand the system shouldn't wade through critique.

package/framework/skills/how/examples.md

@@ -0,0 +1,5 @@
+# Examples
+
+- Trace how a request moves through a subsystem and identify the key files, symbols, and decision points.
+- Explain where a new piece of logic belongs and which layer should own it.
+- Walk a new engineer through a complex feature, including important gotchas and runtime flow.

package/framework/skills/how/references/critic-prompt.md

@@ -0,0 +1,59 @@
+# Critic Prompt Template
+
+Build each critic subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are reviewing the architecture of a codebase subsystem. An explanation of how it works has already been written. Read it to orient yourself, then read the actual code to form your own judgment.
+
+## Architectural Explanation
+
+{EXPLANATION}
+
+## Relevant Files
+
+{FILE_PATHS}
+
+## Critique Rubric
+
+{CRITIQUE_RUBRIC_CONTENTS}
+
+## Instructions
+
+Read the files listed above. Use the explanation as a map, but form your own opinions from the code itself. The explanation might miss things or frame them charitably.
+
+Find architectural problems, not line-level bugs or style issues. Ask whether this subsystem is built well for what it needs to do and how it will need to evolve.
+
+For each finding:
+
+1. **Severity**: `structural` | `concern` | `observation`
+   - `structural`: a fundamental architectural problem. Wrong abstraction boundary, broken data model, coupling that will block future work
+   - `concern`: a real issue that makes the system harder to work with or reason about, but not fundamentally broken
+   - `observation`: worth noting. A tradeoff that might not age well, a pattern inconsistent with the rest of the codebase, technical debt
+2. **Finding**: the architectural issue. Be specific. Name the components, the boundary, the coupling.
+3. **Evidence**: concrete code that demonstrates the problem. Don't just assert that "this is too coupled". Show the dependency chain.
+4. **Impact**: what the issue costs. Harder to test? Harder to change? Performance cliff at scale? Be concrete about the consequence.
+
+## What to Avoid
+
+- Line-level code review (not your job here)
+- Suggesting rewrites without demonstrating a problem with the current approach
+- "This could use more abstraction" without showing what the abstraction would actually solve
+- Flagging intentional tradeoffs with clear benefits as issues
+
+If the architecture is sound, say so. An empty critique is a valid outcome.
+
+## Output
+
+```
+## Findings
+
+### 1. [Severity] Short title
+**Components**: Which parts of the system are involved
+**Finding**: What's wrong architecturally
+**Evidence**: Concrete code references
+**Impact**: What this costs in practice
+
+### 2. [Severity] Short title
+...
+```

package/framework/skills/how/references/critique-rubric.md

@@ -0,0 +1,58 @@
+# Architectural Critique Rubric
+
+Review through whichever of these lenses are relevant. Not every lens applies to every subsystem.
+
+## Abstraction Fit
+
+Are the abstractions pulling their weight?
+
+- Does each abstraction represent a real concept, or is it an indirection layer "in case we need it"?
+- Are the boundaries in the right place? Do they separate things that change independently?
+- Is there accidental coupling where components share implementation details they shouldn't need to know about?
+- Is business logic entangled with framework wiring, or cleanly separated?
+
+Over-abstraction is as much a problem as under-abstraction. A flat, simple design is fine when the domain is simple.
+
+## Data Model
+
+Do the data structures fit the actual usage patterns?
+
+- Are the data models designed for how data is actually accessed, or for how it was conceptually modeled?
+- Are there impedance mismatches, places where code constantly reshapes data because the model doesn't match the access pattern?
+- Are types honest? Do they represent what data actually looks like at runtime, or claim more structure than exists?
+
+## Boundary Discipline
+
+Are system boundaries clean and well-placed?
+
+- Is validation concentrated at entry points, or scattered through internal code?
+- Are errors handled at boundaries and propagated cleanly, or caught and re-thrown at every layer?
+- Does data cross boundaries in well-typed shapes, or as bags of optional fields?
+- Could this subsystem be tested in isolation, or does it require the entire system to be running?
+
+## Evolution Readiness
+
+How well will this architecture handle likely changes?
+
+- If the most probable next requirement landed tomorrow, how much would change? "One file" or "everything"?
+- Are there hardcoded assumptions that would need to be relaxed?
+- Is the design bolted-on (integrated as an afterthought) or integrated (looks like it was always part of the plan)?
+- Are legacy paths preserved for compatibility that no one depends on?
+
+Don't penalize for not handling hypothetical changes. Focus on changes plausible given the codebase's trajectory.
+
+## Complexity vs. Value
+
+Is the complexity budget spent wisely?
+
+- Is complexity concentrated in the parts that need it (core logic, tricky invariants) or in accidental places (boilerplate, unnecessary indirection, configuration)?
+- Are there simpler ways to achieve the same behavior?
+- Does every component earn its existence, or are there vestigial pieces from an earlier design?
+
+## Consistency
+
+Does this subsystem follow the patterns established elsewhere in the codebase?
+
+- Are similar problems solved the same way here as elsewhere, or does this area invent its own patterns?
+- If the patterns differ, is there a good reason, or did it just evolve independently?
+- Inconsistency isn't automatically bad. But unexplained inconsistency is a maintenance burden.

package/framework/skills/how/references/explainer-prompt.md

@@ -0,0 +1,55 @@
+# Explainer Prompt Template
+
+Build the explainer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings. Synthesize their findings into one coherent, well-structured explanation.
+
+## Original Question
+
+> {QUESTION}
+
+## Explorer Findings
+
+{EXPLORER_FINDINGS_ALL}
+
+## Instructions
+
+The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and weave the separate slices into a unified picture.
+
+Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently.
+
+You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed. The explorers did the heavy lifting, so you shouldn't need to re-explore from scratch.
+
+## Output Format
+
+Use this structure, adapted to what makes sense for the question. Not every section is needed for every question.
+
+### Overview
+1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether to keep reading.
+
+### Key Concepts
+The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive.
+
+### How It Works
+The core of the explanation, and the longest section. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are.
+
+Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is genuinely essential to a point.
+
+When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment. A diagram should clarify, not decorate. If prose covers the flow, skip the diagram.
+
+### Where Things Live
+A brief file/directory map. Just the ones someone would need to start working here.
+
+### Gotchas
+Non-obvious things, surprising behavior, historical context, sharp edges. Skip this section if there's nothing worth calling out.
+
+## Communication Style
+
+- Use concrete language, not abstractions-about-abstractions
+- Say "the `UserService` calls `AuthClient.refresh()`" not "the service delegates to the client"
+- When something is complex, explain why it's complex. Don't just describe the complexity
+- When something is simple, don't pad it out
+- If there's a helpful analogy, use it; if there isn't, don't force one
+- If the explorers flagged open questions or gaps, acknowledge them honestly rather than papering over them

package/framework/skills/how/references/explorer-prompt.md

@@ -0,0 +1,52 @@
+# Explorer Prompt Template
+
+Build each explorer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are exploring a codebase to understand how something works. Gather facts: trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose.
+
+Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep.
+
+## Question
+
+> {QUESTION}
+
+## Your Exploration Angle
+
+{EXPLORATION_ANGLE}
+
+## Exploration Instructions
+
+Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names. Read the code.
+
+Follow this pattern:
+1. **Find the entry point.** What triggers this behavior? A user action, an API call, a scheduled job? Find where it starts.
+2. **Trace the flow.** Follow the call chain from the entry point. Read each function. Understand what data flows through and how it transforms.
+3. **Map the key abstractions.** What types, interfaces, services, or classes are central? Read their definitions. Understand what they represent and why they exist.
+4. **Find the boundaries.** Where does this subsystem interface with others? What goes in, what comes out?
+5. **Look for the non-obvious.** Anything surprising? Anything that looks like a historical artifact? Anything a newcomer would misunderstand?
+
+Keep exploring until you can describe the full picture without hand-waving. If you hit a part you can't trace, say so explicitly. "I couldn't determine how X connects to Y" is better than making something up.
+
+## Output
+
+Return your findings in this structure. Be factual and specific. Reference exact file paths, function names, type names, and line numbers where relevant.
+
+### Components Found
+The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.
+
+### Flow
+The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.
+
+### Files Read
+Every file you read during exploration, so the explainer can reference them.
+
+### Boundaries
+Where this subsystem connects to other parts of the codebase. The inputs and outputs.
+
+### Non-Obvious Things
+Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but actually work another.
+
+### Open Questions
+Anything you couldn't fully trace or understand. Be honest about gaps.

package/framework/skills/improve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: improve
-description: Audit an entire repository as a read-only senior advisor, identify evidence-backed bugs, security risks, performance issues, test gaps, technical debt, DX/docs problems, and grounded roadmap opportunities, then produce prioritized handoff plans for another agent. Use for repository-wide audits, improvement roadmaps, and implementation planning from existing code. Do not use for reviewing a specific diff or pull request (use code-review), security-only audits (use security-best-practices), documentation-only edits (use docs-writer), greenfield feature design or implementation (use brainstorming or tlc-spec-driven), or creating and evaluating agent skills (use skill-creator).
+description: Audit an entire repository as a read-only senior advisor, identify evidence-backed bugs, security risks, performance issues, test gaps, technical debt, DX/docs problems, and grounded roadmap opportunities, then produce prioritized handoff plans for another agent. Use for repository-wide audits, improvement roadmaps, and implementation planning from existing code. Do not use for reviewing a specific diff or pull request, security-only audits (use security-best-practices), documentation-only edits (use docs-writer), greenfield feature design or implementation (use tlc-spec-driven), or creating and evaluating agent skills (use skill-creator).
 license: MIT
 metadata:
   author: shadcn
@@ -28,10 +28,8 @@ The economics of this skill: an expensive, high-ceiling model does the part wher
 
 Use this skill when the user wants a broad assessment of an existing repository or wants possible improvements prioritized across multiple engineering concerns. Keep the audit advisory and read-only; implementation belongs to a separate executor or to the skill that owns the narrower task.
 
-- Review a specific diff, branch, or pull request with `code-review`.
 - Perform a security-only assessment with `security-best-practices`.
 - Edit or restructure documentation with `docs-writer`.
-- Explore an unresolved product or UI direction with `brainstorming`.
 - Specify or implement an approved feature with `tlc-spec-driven`.
 - Create, evaluate, or optimize an agent skill with `skill-creator`.
 

package/framework/skills/improve/examples.md

@@ -16,4 +16,4 @@
 
 **User:** Review the changes in my pull request for authorization bugs and missing tests.
 
-**Expected behavior:** Do not use `improve` for this narrow diff review. Route the request to `code-review`, optionally combining it with `security-best-practices` when a security-only review is explicitly requested.
+**Expected behavior:** Do not use `improve` for this narrow diff review. Decline the broad audit and review the pull request directly, combining it with `security-best-practices` when a security-only review is explicitly requested.