@nt-ai-lab/opencode-skillz 0.2.7 → 0.3.1

package/AGENTS.md

@@ -11,9 +11,11 @@ Purpose: package OpenCode workflow assets as a plugin.
 ## Conventions
 
 - Keep command files process-oriented (not tone-oriented).
+- Remove all personality from commands and skill content when creating them.
 - Put voice and persona behavior in agent prompts.
 - Treat reusable skill content as command templates in `commands/`.
 - Commands should be manually invoked by default.
+- All plugin-provided commands must use the `nt-skillz:` prefix, including code-backed commands.
 - Prefer minimal additions; only add new commands when needed.
 - Do not add `agent:` in command frontmatter unless the command must force a specific agent.
 

package/commands/confidence-honesty.md

@@ -0,0 +1,245 @@
+---
+description: "Force honest confidence assessment before claiming conclusions. Triggers on 'root cause identified', 'problem identified', 'complete clarity'. Express confidence as percentage, explain what's stopping 100%, validate assumptions before presenting."
+---
+
+# Confidence Honesty
+
+## The Problem
+
+Detailed, well-structured analyses can *look* thorough, then get presented with phrases like "complete clarity" or "root cause identified." Users reasonably trust that confidence. They act on it, communicate it to stakeholders, and make decisions.
+
+Then new evidence appears and invalidates the entire hypothesis.
+
+**The harm:**
+- User trusted a conclusion that was actually ~40% confident
+- Time wasted on wrong direction
+- Stakeholders were misinformed
+- Trust in the analysis erodes
+
+**Why this happens:** Explanation quality gets conflated with evidence quality. A thorough, well-reasoned analysis feels like certainty—but reasoning without verified evidence is just speculation with extra steps.
+
+## The Solution
+
+Force explicit confidence assessment before claiming conclusions:
+1. Express confidence as a percentage (not vague certainty)
+2. Show the math: what evidence adds confidence, what gaps subtract it
+3. Mandatory "Why not 100%?" for anything below 95%
+4. Self-validate: if more evidence can be gathered directly, do it before presenting
+
+## Critical Rules
+
+🚨 **EXPRESS CONFIDENCE AS A PERCENTAGE.** Every conclusion needs a specific confidence level, not vague certainty.
+
+🚨 **EXPLAIN WHAT'S STOPPING 100%.** For any confidence below 95%, you MUST explain the gaps. Non-negotiable.
+
+🚨 **VALIDATE BEFORE PRESENTING.** If more evidence can be gathered directly, DO IT. Do not present unvalidated hypotheses.
+
+## When This Triggers
+
+Auto-invoke when about to claim:
+- "root cause is", "the problem is", "root cause identified"
+- "complete clarity", "definitely", "certainly", "clearly the issue"
+- Any conclusive claim during investigation
+
+## Confidence Levels
+
+| Range | Icon | Meaning |
+|-------|------|---------|
+| 0-30% | 🔴 | Speculation - needs significant validation |
+| 31-60% | 🟡 | Plausible - evidence exists but gaps remain |
+| 61-85% | 🟠 | Likely - strong evidence, minor gaps |
+| 86-94% | 🟢 | High confidence - validated, minor uncertainty |
+| 95-100% | 💯 | Confirmed - fully validated |
+
+**Calibration:**
+- **20%**: One possibility among several
+- **40%**: Evidence points this direction but key assumptions unverified
+- **60%**: Evidence supports this, alternatives not ruled out
+- **80%**: Strong evidence, assumptions verified, alternatives less likely
+- **95%**: Validated with direct evidence, alternatives ruled out
+- **100%**: Mathematical/logical certainty only
+
+## Pre-Conclusion Checkpoint
+
+**Before claiming ANY conclusion, complete this:**
+
+### 1. Evidence Inventory
+- What hard evidence supports this?
+- Direct evidence (code/logs that prove it)?
+- Circumstantial evidence (patterns consistent)?
+- What's the strongest piece of evidence?
+
+### 2. Falsifiability Check
+- What would INVALIDATE this theory?
+- What data would prove me wrong?
+- Has that data been checked?
+- If no: WHY NOT?
+
+### 3. Assumption Audit
+- What is being assumed WITHOUT verification?
+- List each assumption explicitly
+- Mark: [VERIFIED] or [ASSUMED]
+
+### 4. Alternative Possibilities
+- What else could explain these symptoms?
+- List at least 2 alternatives
+- Why is my conclusion more likely?
+
+### 5. Validation Opportunities
+- Can the actual data be fetched/checked?
+- Can the codebase be searched for confirming/denying evidence?
+- Should the user be asked for confirming data?
+
+## Confidence Scoring
+
+**Start at 50% (neutral) and adjust:**
+
+| Factor | Adjustment |
+|--------|------------|
+| Direct evidence (code/logs proving it) | +15-25% |
+| Verified assumptions (checked, not assumed) | +10-15% |
+| Alternatives ruled out with evidence | +10-15% |
+| Falsifiability check completed | +5-10% |
+| Unverified critical assumptions | -15-25% |
+| Plausible alternatives not ruled out | -10-15% |
+| No falsifiability check | -10% |
+| Circumstantial evidence only | -10% |
+
+**Example calculation:**
+```
+Starting: 50%
++ Code analysis shows the pattern: +15%
++ Error logs match signature: +10%
+- CRITICAL: Assumed config unchanged (NOT VERIFIED): -25%
+- Alternative not ruled out: -10%
+
+Final: 40% 🟡
+```
+
+## Response Format
+
+```
+[Icon] [X%] Confidence: [One sentence finding]
+
+Evidence:
+- [+X%] [Evidence 1]
+- [+X%] [Evidence 2]
+
+Why not 100%:
+- [-X%] [What's stopping full confidence]
+
+To increase confidence: [What would raise % - can be checked directly or needs user input]
+```
+
+## Examples
+
+### 🔴 25% - Low confidence
+```
+🔴 25% Confidence: Database connection pool may be exhausted
+
+Evidence:
+- [+15%] Error pattern matches connection timeout
+- [+10%] Load spike occurred around failure time
+
+Why not 100%:
+- [-25%] Haven't verified actual pool metrics
+- [-15%] Haven't ruled out: network issues, DNS problems
+- [-35%] This is mostly pattern matching, not direct evidence
+
+To increase confidence: Connection pool metrics from the time of failure are needed.
+```
+
+### 🟠 75% - Moderate-high confidence
+```
+🟠 75% Confidence: API request failing due to missing required field
+
+Evidence:
+- [+20%] Error message explicitly mentions "field required"
+- [+15%] Code path analysis shows validation happens here
+- [+10%] Field was recently added to validation rules
+
+Why not 100%:
+- [-10%] Haven't verified the actual request payload
+- [-15%] Could be a different field than suspected
+
+To increase confidence: Check the actual request payload from the failing call.
+```
+
+### 💯 98% - Near certain
+```
+💯 98% Confidence: Root cause is misconfigured environment variable
+
+Evidence:
+- [+25%] Environment variable is set to wrong value (verified)
+- [+20%] Code directly uses this variable for the failing operation
+- [+15%] Error message matches expected failure mode
+- [+10%] Fixing the variable in staging resolved the issue
+
+Why not 100%: Haven't deployed fix to production yet to confirm.
+```
+
+## Anti-Patterns
+
+### ❌ Premature Certainty
+
+**What happens:**
+```
+Analysis: "Complete clarity on the root cause"
+Assistant: [200 lines of detailed report]
+User: [provides data that contradicts analysis]
+Assistant: "This changes everything..."
+```
+
+**What should happen:**
+```
+🟡 40% Confidence: The issue appears to be X
+
+Evidence:
+- [+15%] Code path analysis suggests this pattern
+
+Why not 100%:
+- [-25%] CRITICAL: Haven't verified actual system state
+- [-15%] Alternative not ruled out
+
+To increase confidence: Provide [specific data], or check it directly if available.
+```
+
+### ❌ Confidence in Explanation Quality
+
+Building a detailed report ≠ having valid evidence.
+
+Thoroughness of presentation has zero correlation with correctness.
+
+**Violation sign:** "Complete clarity" based on reasoning, not evidence.
+
+### ❌ Skipping Falsifiability
+
+If the question "what would prove this wrong?" cannot be answered, the theory is not understood well enough.
+
+## Self-Validation Rule
+
+**Do not return to the user with questions that can be answered directly.**
+
+Before presenting, ask:
+```
+Can more evidence be gathered directly?
+├─ Search codebase for confirming/denying data?
+├─ Fetch a file that validates an assumption?
+├─ Spawn an agent to investigate further?
+└─ Check actual state vs assumed state?
+
+If YES → DO IT. Then reassess confidence.
+If NO → Present with honest confidence + what is needed from the user.
+```
+
+**Critical:** If confidence is below 80% and more evidence can be gathered directly → DO IT.
+
+## Summary
+
+🚨 **Confidence is a percentage, not a feeling.**
+
+🚨 **Below 95%? Explain what's stopping 100%.**
+
+🚨 **Can validate yourself? Do it before presenting.**
+
+The goal: Never claim "complete clarity" with 40% confidence and unverified assumptions.

package/commands/investigate.md

@@ -0,0 +1,153 @@
+---
+description: Investigate technical problems systematically with evidence-first methods and explicit confidence reporting
+compose_after: confidence-honesty
+---
+
+Apply this command to:
+$ARGUMENTS
+
+# Technical Investigator
+
+Investigate technical problems systematically. Do not guess—gather evidence until the problem is understood.
+
+### Core Principles
+
+**Solve the right problem.** Before investigating, be crystal clear about the problem being solved. Restate it. Verify understanding. A thorough answer to the wrong question is worthless. Keep asking: "Has the requested problem actually been solved?"
+
+**Observability is the answer.** When system behavior is unclear, add instrumentation. Logs, metrics, traces, and debug output make the invisible visible. If guessing is still happening, observability is insufficient.
+
+**Thoroughness over speed.** Do not rush to conclusions. Build a detailed picture of the problem—every component, every interaction, every timeline. Shallow investigation leads to wrong answers and repeated work.
+
+**Evidence, not assumptions.** Every conclusion needs supporting evidence. Show the work. If no supporting data exists, the investigation is incomplete.
+
+**Do the work.** Investigation is labor. Run the queries, read the logs, trace the requests, add the instrumentation. There are no shortcuts to understanding.
+
+**Starting an investigation:**
+- Define the problem precisely—what's expected vs what's happening
+- Gather existing data before forming hypotheses
+- Build a timeline of events with specific timestamps
+- Identify unknowns (gaps in observability)
+
+**When investigation hits a wall:**
+- Add more observability—logs, metrics, debug output
+- Don't guess—instrument and measure
+- State what instrumentation is needed to understand the unknown
+- Never present unproven claims as facts
+
+**Before concluding:**
+- Ask: "Has the original problem actually been solved?"
+- Verify your answer addresses what was asked
+- Don't settle for partial answers or adjacent solutions
+- If the problem is not fully solved, say so and continue
+
+**Forming conclusions:**
+- Hypotheses must be testable
+- Show the evidence chain
+- Distinguish correlation from causation
+- Verify fixes actually work—don't assume
+
+## Core Investigation Methodologies
+
+### 1. Scientific Method (Hypothesis-Driven)
+
+**The Process:**
+1. **Observe**: Gather data, identify patterns, note anomalies
+2. **Hypothesize**: Form testable explanations for the observed evidence
+3. **Experiment**: Design specific tests to validate/invalidate hypotheses
+4. **Evaluate**: Analyze results, adjust hypotheses, iterate
+
+**Key Principles:**
+- Make assumptions explicit—never leave reasoning implicit
+- Create falsifiable hypotheses that can be tested with specific experiments
+- Follow the "10-minute rule": If ad-hoc inspection hasn't found the issue in 10 minutes, switch to systematic investigation
+- Document your reasoning chain so others can follow your logic
+
+### 2. Google SRE Practices
+
+**Incident Response:**
+- Mitigation first, understanding second (when systems are down)
+- Declare incidents early—don't wait for certainty
+- Maintain working records in real-time during investigation
+- Use persistent communication channels as investigation logs
+
+**Observability:**
+- Monitor the "Four Golden Signals": Latency, Traffic, Errors, Saturation
+- Leverage three pillars: Metrics (trends), Logs (sequences), Traces (components)
+- Accept that future problems cannot be predicted—build systems to investigate the unknown
+- Focus on high-cardinality data for distributed systems
+
+### 3. Root Cause Analysis
+
+**Techniques:**
+- **5 Whys**: Ask "why" iteratively to uncover root causes (typically 5 levels deep)
+- **Timeline Analysis**: Build detailed timelines with specific events and timestamps
+- **Fault Tree Analysis**: Visual hierarchical breakdown of failure scenarios
+- **Correlation vs Causation**: Distinguish between things that happen together vs things that cause each other
+
+**Principles:**
+- Symptoms are not causes—keep digging
+- Root causes often involve multiple contributing factors
+- Document evidence that supports your causal chain
+- Verify root cause fixes actually prevent recurrence
+
+### 4. Performance Analysis (USE Method)
+
+Apply Brendan Gregg's systematic bottleneck identification:
+
+**USE Method:**
+- **Utilization**: How busy is the resource (% time doing work)?
+- **Saturation**: How much work is queued/waiting?
+- **Errors**: Count of error events
+
+**Application:**
+- Apply to all resources: CPU, memory, disk, network, database connections, etc.
+- Systematic investigation prevents missing bottlenecks
+- Collect baseline measurements to compare against
+- Focus on resources with high utilization AND high saturation
+
+## Investigation Workflow
+
+### Phase 1: Problem Definition
+- Define the problem statement clearly and specifically
+- Identify what changed (if known)
+- Establish baseline/expected behavior
+- Determine impact and urgency
+
+### Phase 2: Data Gathering
+- Collect metrics: trends, patterns, anomalies
+- Review logs: event sequences, errors, warnings
+- Analyze traces: component interactions, latency distribution
+- Query databases: aggregate data, identify outliers
+- Check monitoring dashboards: Four Golden Signals
+
+### Phase 3: Hypothesis Formation
+- Based on data, form 2-4 testable hypotheses
+- Make assumptions explicit
+- Rank hypotheses by likelihood and test cost
+- Document expected outcomes for each hypothesis
+
+### Phase 4: Experimentation
+- Design specific tests to validate/invalidate hypotheses
+- Run experiments systematically (one variable at a time when possible)
+- Document results meticulously
+- Adjust hypotheses based on findings
+
+### Phase 5: Documentation
+- Build comprehensive timelines
+- Document evidence chain
+- Record reasoning and decision points
+- Create actionable findings
+
+### Investigation Documentation
+
+**Real-Time Records:**
+- Document during the investigation, not after
+- Record hypotheses and reasoning
+- Note dead ends—they prevent others from repeating them
+- Build detailed timelines with timestamps
+
+**Sharing Findings:**
+- Present evidence clearly
+- Show your reasoning chain
+- Be direct about confidence levels
+- Admit uncertainty when appropriate

package/package.json

@@ -1,19 +1,30 @@
 {
   "name": "@nt-ai-lab/opencode-skillz",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Bundled OpenCode commands and agents",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
   },
   "files": [
-    "index.js",
+    "dist",
     "commands",
     "agents",
     "AGENTS.md",
     "README.md"
   ],
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "typescript": "^5.9.3"
+  },
   "publishConfig": {
     "access": "public"
   }

package/index.js

@@ -1,194 +0,0 @@
-import fs from "node:fs"
-import path from "node:path"
-import { fileURLToPath } from "node:url"
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const pluginRoot = __dirname
-const commandNamespace = "nt-skillz"
-
-function buildCommandName(name) {
-  return `${commandNamespace}:${name}`
-}
-
-function extractFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
-  if (!match) return { meta: {}, body: content }
-
-  const meta = {}
-  for (const rawLine of match[1].split("\n")) {
-    const line = rawLine.trim()
-    if (!line || line.startsWith("#")) continue
-    const idx = line.indexOf(":")
-    if (idx <= 0) continue
-
-    const key = line.slice(0, idx).trim()
-    let value = line.slice(idx + 1).trim()
-    value = value.replace(/^['\"]|['\"]$/g, "")
-    if (value === "true") value = true
-    if (value === "false") value = false
-    meta[key] = value
-  }
-
-  return { meta, body: match[2] }
-}
-
-function readMarkdownFiles(dirPath) {
-  if (!fs.existsSync(dirPath)) return []
-  return fs
-    .readdirSync(dirPath)
-    .filter((file) => file.endsWith(".md"))
-    .sort((a, b) => a.localeCompare(b))
-}
-
-function loadCommands() {
-  const commandsDir = path.join(pluginRoot, "commands")
-  const files = readMarkdownFiles(commandsDir)
-  const commands = {}
-
-  for (const file of files) {
-    const name = file.replace(/\.md$/, "")
-    const fullPath = path.join(commandsDir, file)
-    const content = fs.readFileSync(fullPath, "utf8")
-    const { meta, body } = extractFrontmatter(content)
-
-    const command = {
-      description: meta.description || `Run /${name}`,
-      template: body.trim(),
-    }
-
-    if (meta.agent) command.agent = meta.agent
-    if (meta.model) command.model = meta.model
-    if (typeof meta.subtask === "boolean") command.subtask = meta.subtask
-
-    commands[name] = command
-  }
-
-  return commands
-}
-
-function parseCsvList(value) {
-  if (!value || typeof value !== "string") return []
-  return value
-    .split(",")
-    .map((item) => item.trim())
-    .filter(Boolean)
-}
-
-function materializePreloadedTemplate(template) {
-  return template.replace(/\$ARGUMENTS/g, "all relevant current work in this session")
-}
-
-function loadAgents(commands) {
-  const agentsDir = path.join(pluginRoot, "agents")
-  const files = readMarkdownFiles(agentsDir)
-  const rawAgents = {}
-
-  for (const file of files) {
-    const name = file.replace(/\.md$/, "")
-    const fullPath = path.join(agentsDir, file)
-    const content = fs.readFileSync(fullPath, "utf8")
-    const { meta, body } = extractFrontmatter(content)
-
-    rawAgents[name] = {
-      meta,
-      body: body.trim(),
-    }
-  }
-
-  const agents = {}
-
-  function collectPreloadedCommands(agentName, stack = new Set()) {
-    const rawAgent = rawAgents[agentName]
-    if (!rawAgent) return []
-    if (stack.has(agentName)) return parseCsvList(rawAgent.meta.preload_commands)
-
-    stack.add(agentName)
-
-    const merged = []
-    const parentAgentName = typeof rawAgent.meta.extends === "string" ? rawAgent.meta.extends.trim() : ""
-    if (parentAgentName && rawAgents[parentAgentName]) {
-      merged.push(...collectPreloadedCommands(parentAgentName, stack))
-    }
-
-    merged.push(...parseCsvList(rawAgent.meta.preload_commands))
-    stack.delete(agentName)
-
-    return [...new Set(merged)]
-  }
-
-  for (const [name, raw] of Object.entries(rawAgents)) {
-    const { meta, body } = raw
-    const promptParts = []
-
-    const parentAgentName = typeof meta.extends === "string" ? meta.extends.trim() : ""
-    if (parentAgentName && rawAgents[parentAgentName]) {
-      const parentPrompt = rawAgents[parentAgentName].body
-      if (parentPrompt) promptParts.push(parentPrompt)
-    }
-
-    if (body) {
-      promptParts.push(body)
-    }
-
-    const preloadedCommands = collectPreloadedCommands(name)
-    for (const commandName of preloadedCommands) {
-      const command = commands[commandName]
-      if (!command || !command.template) continue
-      const rendered = materializePreloadedTemplate(command.template)
-      promptParts.push(`[Preloaded command /${commandName}]\n${rendered}`)
-    }
-
-    const agent = {
-      prompt: promptParts.join("\n\n").trim(),
-    }
-
-    if (meta.description) agent.description = meta.description
-    if (meta.mode) agent.mode = meta.mode
-    if (meta.model) agent.model = meta.model
-    if (meta.color) agent.color = meta.color
-
-    agents[name] = agent
-  }
-
-  return agents
-}
-
-export const OpencodeSkillzPlugin = async () => {
-  return {
-    config: async (config) => {
-      config.command = config.command || {}
-      config.agent = config.agent || {}
-
-      const commands = loadCommands()
-      for (const [name, command] of Object.entries(commands)) {
-        const commandName = buildCommandName(name)
-        if (!config.command[commandName]) {
-          config.command[commandName] = command
-        }
-      }
-
-      const agents = loadAgents(commands)
-      for (const [name, agent] of Object.entries(agents)) {
-        if (!config.agent[name]) {
-          config.agent[name] = agent
-        }
-      }
-
-      config.agent.build = {
-        ...(config.agent.build || {}),
-        disable: true,
-      }
-
-      config.agent.plan = {
-        ...(config.agent.plan || {}),
-        disable: true,
-      }
-
-      if (!config.default_agent && config.agent.default) {
-        config.default_agent = "default"
-      }
-    },
-  }
-}
-
-export default OpencodeSkillzPlugin