diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 642a45f..c843e9f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2,13 +2,19 @@ "name": "deepgrade-marketplace", "description": "Developer toolkit for codebase auditing, AI-readiness scanning, structured planning, and operational readiness. Four plugins, one lockstep release. Works on any stack.", "owner": { - "name": "Kyle Whynot", - "email": "krwhynot@github.com" + "name": "Kyle Whynot" }, "plugins": [ { "name": "deepgrade", "description": "9-phase planning with an adversarial verifier-first audit gate, plan-linked troubleshooting, and documentation generation.", + "category": "development", + "tags": [ + "planning", + "audit-gate", + "troubleshooting", + "documentation" + ], "source": { "source": "git-subdir", "url": "https://github.com/krwhynot/deepgrade.git", @@ -20,6 +26,12 @@ { "name": "deepgrade-readiness", "description": "AI-readiness scanning: 52 checks, 9 categories, composite letter grade, generated scaffolding for the gaps.", + "category": "development", + "tags": [ + "ai-readiness", + "codebase-grading", + "scanning" + ], "source": { "source": "git-subdir", "url": "https://github.com/krwhynot/deepgrade.git", @@ -31,6 +43,13 @@ { "name": "deepgrade-audit", "description": "Severity-graded codebase audits, security scans, delta/KPI tracking, characterization tests, generated CI gates.", + "category": "development", + "tags": [ + "audit", + "codebase", + "security", + "quality-gates" + ], "source": { "source": "git-subdir", "url": "https://github.com/krwhynot/deepgrade.git", @@ -42,6 +61,13 @@ { "name": "deepgrade-guard", "description": "Always-on safety hooks: force-push and DB-deploy blocking, migration protection, change/test tracking, session summaries.", + "category": "development", + "tags": [ + "safety", + "hooks", + "git-guard", + "migration-guard" + ], "source": { "source": "git-subdir", "url": "https://github.com/krwhynot/deepgrade.git", diff --git a/CHANGELOG.md b/CHANGELOG.md index 86204ae..0cb074e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,29 @@ single long command loses its later phases after context compaction in exactly the long sessions a nine-phase workflow produces. Tests that read Phase 5 content now point at `phases/phase-5-audit.md`. +- The `(deepgrade)` description prefix is stripped from all 23 commands and + skills. After the monorepo split it mislabelled 11 files owned by + deepgrade-audit and deepgrade-readiness. +- Marketplace entries carry `category` and `tags`; the non-deliverable + owner email is removed. + +### Fixed +- Backlog triage of the 32 low/info findings recorded against 4.31.0: 13 were + already closed by the hardening work; 15 fixed here. Scanner "Output" + sentences un-garbled in all 8 readiness scanners; database-scanner check 9.1 + name matches its contract; plan-auditor steps renumbered 1-7 and its subagent + count corrected to 5; gate-generator's duplicate Step 4.5 is now 4.6; every + `` block regenerated from the real 17-entry surface; help.md + drops the dead `/tp`, lists the plan skill, and namespaces its documentation + examples; the phantom `plan-review.js` reference is gone; two agents no longer + read a `$ARGUMENTS` that is never substituted; the documentation skill no + longer carries a literal positional placeholder in its body; the two long + templates have a Contents list; mcp-research drops a baked-in date; + METHODOLOGY.md stops describing the removed bash PATH preamble as current. +- Stop hooks (guard session-stop, deepgrade subagent-stop) exit silently when + `stop_hook_active` is set, so a continued turn cannot re-post the summary. + The session-stop hook also sweeps tracker files from other sessions older + than a day; before this they accumulated in TMPDIR forever. ### Internal - CR-7 (owner-ratified): the U7 compatibility-floor requirement is descoped. diff --git a/METHODOLOGY.md b/METHODOLOGY.md index 9e0d4a9..ae2b832 100644 --- a/METHODOLOGY.md +++ b/METHODOLOGY.md @@ -980,7 +980,7 @@ Node gives real `JSON.parse`, so a named field can be extracted rather than gues The concern that motivated the old design still stands: a security guard that fails to install is worse than no guard, because it creates a false sense of safety. v5.0.0 answers it differently. Rather than degrade quietly to a weaker parser, a host that cannot run the guards produces a visible hook error on every guarded event. You are told the safety layer is absent instead of being left to assume it is working. -On Windows, where Claude Code runs in Git Bash, `jq` installed via `winget` lands in `$LOCALAPPDATA/Microsoft/WinGet/Links/`, a path Git Bash does not include by default. Every hook starts with `export PATH="$PATH:$LOCALAPPDATA/Microsoft/WinGet/Links:/usr/local/bin"` to ensure `jq` is discoverable regardless of installation method. +Since v5.0.0 every hook is a Node script launched in exec form (`node ${CLAUDE_PLUGIN_ROOT}/scripts/dg-*.js`), so there is no shell PATH preamble and no `jq` dependency. The v4.x hooks were bash one-liners that prepended `$LOCALAPPDATA/Microsoft/WinGet/Links` to PATH so a winget-installed `jq` could be found under Git Bash; that preamble also broke under Git Bash because the Windows path contains a colon. ### Security Guards Must Never Fail-Open @@ -1731,7 +1731,7 @@ That is the failure mode we designed the current system to prevent. ### The Current Solution: Graceful Degradation -The architecture that shipped in v4.27 uses a three-layer fallback chain. Every hook follows the same pattern. +The architecture that shipped in v4.27 used a three-layer fallback chain, described here for the record. v5.0.0 replaced it with Node handlers and no preamble; the fail-closed principle survived, the mechanism did not. ```mermaid flowchart TD @@ -1766,7 +1766,7 @@ flowchart TD The PATH preamble is the first key insight. On Windows, `winget` installs binaries to `$LOCALAPPDATA/Microsoft/WinGet/Links`, which Git Bash does not include in its default PATH. On macOS/Linux, `/usr/local/bin` is the standard location for user-installed tools. By prepending both before every `jq` call, we cover the most common "installed but invisible" scenarios. -Source: [`.claude-plugin/plugin.json`](https://github.com/krwhynot/deepgrade/blob/main/.claude-plugin/plugin.json) -- every hook command begins with the PATH preamble. +Source (historical, v4.x): the inline hook commands in `.claude-plugin/plugin.json` at that time. Current hooks live in `plugins/*/hooks/hooks.json` and `plugins/*/scripts/`. ### The Five Design Rules diff --git a/plugins/deepgrade-audit/agents/characterization-generator.md b/plugins/deepgrade-audit/agents/characterization-generator.md index 6bbf4a6..b793567 100644 --- a/plugins/deepgrade-audit/agents/characterization-generator.md +++ b/plugins/deepgrade-audit/agents/characterization-generator.md @@ -37,7 +37,7 @@ appropriate test project directory. ## Step 1: Understand the Target -Read $ARGUMENTS to determine what to characterize. The user may specify: +Read the task description you were given to determine what to characterize. The user may specify: - A module name: "BusinessLogic" -> characterize all public methods - A file path: "POSetcPOS/ReportsDB.vb" -> characterize key functions in file - A specific function: "ReportsDB.GetSalesReport" -> characterize that function diff --git a/plugins/deepgrade-audit/agents/gate-generator.md b/plugins/deepgrade-audit/agents/gate-generator.md index d7b3f09..0f2e319 100644 --- a/plugins/deepgrade-audit/agents/gate-generator.md +++ b/plugins/deepgrade-audit/agents/gate-generator.md @@ -255,7 +255,7 @@ IMPORTANT: The DO_NOT_TOUCH_ZONES array must be populated with ACTUAL paths from risk-assessment.md. Read the HIGH-risk modules and do-not-touch zones from the audit data. Do not use placeholder paths. -## Step 4.5: Generate Baseline Tracker Script +## Step 4.6: Generate Baseline Tracker Script Create .claude/scripts/baseline-tracker.sh: diff --git a/plugins/deepgrade-audit/commands/codebase-audit.md b/plugins/deepgrade-audit/commands/codebase-audit.md index a1b4c03..fb4ddfe 100644 --- a/plugins/deepgrade-audit/commands/codebase-audit.md +++ b/plugins/deepgrade-audit/commands/codebase-audit.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Run a full DeepGrade codebase audit using a team of specialized agents working in parallel. Produces a standardized report with severity-classified findings that any engineer can act on. Works on any stack (React/TypeScript, C#/.NET, Python, Rust, Go). +description: Run a full DeepGrade codebase audit using a team of specialized agents working in parallel. Produces a standardized report with severity-classified findings that any engineer can act on. Works on any stack (React/TypeScript, C#/.NET, Python, Rust, Go). allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade-audit/commands/codebase-characterize.md b/plugins/deepgrade-audit/commands/codebase-characterize.md index 5ea3634..ac1d04f 100644 --- a/plugins/deepgrade-audit/commands/codebase-characterize.md +++ b/plugins/deepgrade-audit/commands/codebase-characterize.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Generate golden master / characterization tests that capture current behavior of a module BEFORE refactoring. These tests verify that refactored code produces identical outputs. Critical for monolith decomposition. Pass a module name, file path, function name, or domain as the argument. +description: Generate golden master / characterization tests that capture current behavior of a module BEFORE refactoring. These tests verify that refactored code produces identical outputs. Critical for monolith decomposition. Pass a module name, file path, function name, or domain as the argument. argument-hint: "[module|file|function|domain]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade-audit/commands/codebase-delta.md b/plugins/deepgrade-audit/commands/codebase-delta.md index 421a327..f3373d2 100644 --- a/plugins/deepgrade-audit/commands/codebase-delta.md +++ b/plugins/deepgrade-audit/commands/codebase-delta.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Re-measure the codebase against previous audit baselines. Shows what improved, what regressed, tracks KPIs over time, and flags stale findings. Quick check (2-3 min) without running a full scan. Use after making changes to see if scores improved. +description: Re-measure the codebase against previous audit baselines. Shows what improved, what regressed, tracks KPIs over time, and flags stale findings. Quick check (2-3 min) without running a full scan. Use after making changes to see if scores improved. allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade-audit/commands/codebase-gates.md b/plugins/deepgrade-audit/commands/codebase-gates.md index 3e0e418..335c641 100644 --- a/plugins/deepgrade-audit/commands/codebase-gates.md +++ b/plugins/deepgrade-audit/commands/codebase-gates.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Generate CI quality gates, Claude Code hooks, and baseline maintenance nudges from DeepGrade audit findings. Creates automated checks that warn when HIGH-risk modules are modified, track file change counts, and nudge you when audit baselines go stale. Requires a Phase 2 audit to have been run first. +description: Generate CI quality gates, Claude Code hooks, and baseline maintenance nudges from DeepGrade audit findings. Creates automated checks that warn when HIGH-risk modules are modified, track file change counts, and nudge you when audit baselines go stale. Requires a Phase 2 audit to have been run first. allowed-tools: Read, Write, Grep, Glob, Bash, Task disable-model-invocation: true --- diff --git a/plugins/deepgrade-audit/commands/codebase-security.md b/plugins/deepgrade-audit/commands/codebase-security.md index b158164..e10ec6b 100644 --- a/plugins/deepgrade-audit/commands/codebase-security.md +++ b/plugins/deepgrade-audit/commands/codebase-security.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Run a security-focused scan on the codebase. Checks dependency vulnerabilities, hardcoded secrets, SSL configuration, injection risks, and permission patterns. Security is a separate control loop from the general audit. Pass an optional focus area to narrow the scan. +description: Run a security-focused scan on the codebase. Checks dependency vulnerabilities, hardcoded secrets, SSL configuration, injection risks, and permission patterns. Security is a separate control loop from the general audit. Pass an optional focus area to narrow the scan. argument-hint: "[focus-area]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade-audit/skills/deepgrade-knowledge/SKILL.md b/plugins/deepgrade-audit/skills/deepgrade-knowledge/SKILL.md index a86e86c..b3b12de 100644 --- a/plugins/deepgrade-audit/skills/deepgrade-knowledge/SKILL.md +++ b/plugins/deepgrade-audit/skills/deepgrade-knowledge/SKILL.md @@ -1,6 +1,6 @@ --- name: deepgrade-knowledge -description: (deepgrade) Knowledge about the DeepGrade methodology for codebase audit and documentation. Covers enterprise best practices for discovery, risk assessment, and report generation. Use when auditing a codebase, assessing module risk, classifying finding severity, writing an audit report, or deciding phase boundaries for remediation work. +description: Knowledge about the DeepGrade methodology for codebase audit and documentation. Covers enterprise best practices for discovery, risk assessment, and report generation. Use when auditing a codebase, assessing module risk, classifying finding severity, writing an audit report, or deciding phase boundaries for remediation work. --- # DeepGrade Methodology diff --git a/plugins/deepgrade-audit/skills/governance-knowledge/SKILL.md b/plugins/deepgrade-audit/skills/governance-knowledge/SKILL.md index 1d0f614..a23033d 100644 --- a/plugins/deepgrade-audit/skills/governance-knowledge/SKILL.md +++ b/plugins/deepgrade-audit/skills/governance-knowledge/SKILL.md @@ -1,6 +1,6 @@ --- name: governance-knowledge -description: (deepgrade) Knowledge about enterprise governance patterns, DORA metrics, quality gates, confidence decay, delta tracking, and characterization testing. Use when comparing a codebase against a previous baseline, setting up CI quality gates or pre-commit hooks, running a security scan, generating golden-master tests before a refactor, or deciding whether an old finding is still trustworthy. +description: Knowledge about enterprise governance patterns, DORA metrics, quality gates, confidence decay, delta tracking, and characterization testing. Use when comparing a codebase against a previous baseline, setting up CI quality gates or pre-commit hooks, running a security scan, generating golden-master tests before a refactor, or deciding whether an old finding is still trustworthy. --- # Enterprise Governance Knowledge diff --git a/plugins/deepgrade-audit/skills/self-audit-knowledge/SKILL.md b/plugins/deepgrade-audit/skills/self-audit-knowledge/SKILL.md index a32a84d..75d0649 100644 --- a/plugins/deepgrade-audit/skills/self-audit-knowledge/SKILL.md +++ b/plugins/deepgrade-audit/skills/self-audit-knowledge/SKILL.md @@ -1,6 +1,6 @@ --- name: self-audit-knowledge -description: (deepgrade) Knowledge about LLM epistemic transparency, claim verification tiers, failure mode flags, cascade risk classification, and evidence basis formatting. Use when stating how confident a finding is, labelling a claim as verified or unverified, flagging an assumption, assessing whether one wrong conclusion invalidates others, or writing the evidence basis for an audit or plan review. +description: Knowledge about LLM epistemic transparency, claim verification tiers, failure mode flags, cascade risk classification, and evidence basis formatting. Use when stating how confident a finding is, labelling a claim as verified or unverified, flagging an assumption, assessing whether one wrong conclusion invalidates others, or writing the evidence basis for an audit or plan review. --- # LLM Self-Audit Framework diff --git a/plugins/deepgrade-guard/scripts/dg-session-stop.js b/plugins/deepgrade-guard/scripts/dg-session-stop.js index 01f3d20..b2efe99 100644 --- a/plugins/deepgrade-guard/scripts/dg-session-stop.js +++ b/plugins/deepgrade-guard/scripts/dg-session-stop.js @@ -21,6 +21,9 @@ function notify(message) { let payload = null; try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { payload = null; } +// A Stop fired because a previous Stop hook already continued the turn. Emitting again +// would re-post the same summary every cycle; exit before doing anything. +if (payload && payload.stop_hook_active === true) quiet(); // A session id is interpolated into a filename, so it is validated before use. @@ -35,6 +38,19 @@ function safeSessionId(v) { const sessionId = safeSessionId(payload && payload.session_id); const tmp = process.env.TMPDIR || process.env.TEMP || os.tmpdir(); +// Tracker files (dg-baseline/dg-test/dg-build-) were never removed, so they +// accumulated in TMPDIR forever. This session's files stay (Stop fires per turn and the +// runtime proof reads them afterwards); anything from other sessions older than a day +// is swept. Fail-open: a sweep error must never affect the Stop verdict. +try { + const cutoff = Date.now() - 24 * 60 * 60 * 1000; + for (const name of fs.readdirSync(tmp)) { + if (!/^dg-(baseline|test|build)-/.test(name) || name.endsWith('-' + sessionId)) continue; + const full = path.join(tmp, name); + try { if (fs.statSync(full).mtimeMs < cutoff) fs.unlinkSync(full); } catch {} + } +} catch {} + let text = '', obj = null; try { text = fs.readFileSync(path.join(tmp, `dg-baseline-${sessionId}`), 'utf8'); } catch { quiet(); } if (!text) quiet(); diff --git a/plugins/deepgrade-readiness/agents/baseline-scanner.md b/plugins/deepgrade-readiness/agents/baseline-scanner.md index 7b850c2..b648a66 100644 --- a/plugins/deepgrade-readiness/agents/baseline-scanner.md +++ b/plugins/deepgrade-readiness/agents/baseline-scanner.md @@ -62,8 +62,8 @@ find . -name "dependency-map.*" -o -name "feature-inventory.*" -o -name "api-sur Score: 0 = no machine-readable data, 1 = at least one structured data file **Output:** -Write results as JSON to docs/audit/readability/baseline-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema with all 4 checks. +Write results as JSON to docs/audit/readability/baseline-scan.json following the standard scanner output schema with all 4 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. **Constraints:** - Read-only. Do not modify any source files. diff --git a/plugins/deepgrade-readiness/agents/budget-scanner.md b/plugins/deepgrade-readiness/agents/budget-scanner.md index 51c2e91..8250a74 100644 --- a/plugins/deepgrade-readiness/agents/budget-scanner.md +++ b/plugins/deepgrade-readiness/agents/budget-scanner.md @@ -425,8 +425,8 @@ Scoring: - 0 = 3+ anti-patterns (significant context waste) **Output:** -Write results as JSON to docs/audit/readability/context-budget-scan.json following COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -the standard scanner output schema with all 8 checks. +Write results as JSON to docs/audit/readability/context-budget-scan.json following the standard scanner output schema with all 8 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. Each check must include: - id, name, status, points, max, evidence, details, remediation diff --git a/plugins/deepgrade-readiness/agents/context-scanner.md b/plugins/deepgrade-readiness/agents/context-scanner.md index 8b308bf..a184df7 100644 --- a/plugins/deepgrade-readiness/agents/context-scanner.md +++ b/plugins/deepgrade-readiness/agents/context-scanner.md @@ -263,8 +263,8 @@ Step 8 - Context coverage ratio (Check 2.4): ``` **Output:** -Write results as JSON to docs/audit/readability/context-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema with all 10 checks. +Write results as JSON to docs/audit/readability/context-scan.json following the standard scanner output schema with all 10 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. Each check must include: - id, name, status, points, max, evidence, details, remediation diff --git a/plugins/deepgrade-readiness/agents/convention-scanner.md b/plugins/deepgrade-readiness/agents/convention-scanner.md index 40fd91b..72ce9ba 100644 --- a/plugins/deepgrade-readiness/agents/convention-scanner.md +++ b/plugins/deepgrade-readiness/agents/convention-scanner.md @@ -96,8 +96,8 @@ ls .mcp.json mcp.json .claude/mcp.json 2>/dev/null Score: 0 = no MCP config, 1 = MCP config present **Output:** -Write results as JSON to docs/audit/readability/convention-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema with all 7 checks. +Write results as JSON to docs/audit/readability/convention-scan.json following the standard scanner output schema with all 7 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. **Constraints:** - Read-only. Do not modify any source files. diff --git a/plugins/deepgrade-readiness/agents/database-scanner.md b/plugins/deepgrade-readiness/agents/database-scanner.md index b7ea404..2e882c4 100644 --- a/plugins/deepgrade-readiness/agents/database-scanner.md +++ b/plugins/deepgrade-readiness/agents/database-scanner.md @@ -567,8 +567,8 @@ Scoring: --- **Output:** -Write results as JSON to docs/audit/readability/database-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema. +Write results as JSON to docs/audit/readability/database-scan.json following the standard scanner output schema. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. ```json { @@ -585,7 +585,7 @@ standard scanner output schema. "checks": [ { "id": "9.1", - "name": "Schema source of truth", + "name": "Schema source of truth exists", "priority": "critical", "status": "pass|partial|fail|skipped", "points": 0, diff --git a/plugins/deepgrade-readiness/agents/entry-scanner.md b/plugins/deepgrade-readiness/agents/entry-scanner.md index 2fd670e..02c1c86 100644 --- a/plugins/deepgrade-readiness/agents/entry-scanner.md +++ b/plugins/deepgrade-readiness/agents/entry-scanner.md @@ -91,8 +91,8 @@ Score 4.5: 0 = no agents, 1 = 1-2 agents, 2 = 3+ agents - For route files, note whether routes are annotated with descriptions/docs **Output:** -Write results as JSON to docs/audit/readability/entry-point-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema with all 5 checks. +Write results as JSON to docs/audit/readability/entry-point-scan.json following the standard scanner output schema with all 5 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. **Constraints:** - Read-only. Do not modify any source files. diff --git a/plugins/deepgrade-readiness/agents/feedback-scanner.md b/plugins/deepgrade-readiness/agents/feedback-scanner.md index 5ab5d3f..a6c6852 100644 --- a/plugins/deepgrade-readiness/agents/feedback-scanner.md +++ b/plugins/deepgrade-readiness/agents/feedback-scanner.md @@ -103,8 +103,8 @@ Compare the two. Do they match? Score: 0 = no CLAUDE.md or no test command in it, 1 = commands exist but don't match (WARN), 2 = commands match **Output:** -Write results as JSON to docs/audit/readability/feedback-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema with all 6 checks. +Write results as JSON to docs/audit/readability/feedback-scan.json following the standard scanner output schema with all 6 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. **Constraints:** - Read-only. Do not modify any source files. diff --git a/plugins/deepgrade-readiness/agents/structure-scanner.md b/plugins/deepgrade-readiness/agents/structure-scanner.md index 08ea006..15417cc 100644 --- a/plugins/deepgrade-readiness/agents/structure-scanner.md +++ b/plugins/deepgrade-readiness/agents/structure-scanner.md @@ -211,8 +211,8 @@ done | sort -rn Score: 0 = no barrel files, 1 = barrel files with 20+ exports (bloated), 2 = barrel files with < 20 exports (clean) **Output:** -Write results as JSON to docs/audit/readability/structure-scan.json following the COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. -standard scanner output schema with all 8 checks. +Write results as JSON to docs/audit/readability/structure-scan.json following the standard scanner output schema with all 8 checks. +COPY THE CHECK ID AND NAME FIELDS EXACTLY from the check list above. Do NOT rename any check. Fill in only score, evidence, and remediation values. **Constraints:** - NEVER use Read tool on source files. Only Bash and Glob. diff --git a/plugins/deepgrade-readiness/commands/readiness-generate.md b/plugins/deepgrade-readiness/commands/readiness-generate.md index 87b089e..105adf2 100644 --- a/plugins/deepgrade-readiness/commands/readiness-generate.md +++ b/plugins/deepgrade-readiness/commands/readiness-generate.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Generate missing AI readability artifacts based on the latest scan results. Creates CLAUDE.md, slash commands, agent definitions, rules files, and other artifacts that improve the codebase's AI readiness score. Usage - /deepgrade-readiness:readiness-generate [number] for a specific artifact, all-critical for every critical one, all for everything. +description: Generate missing AI readability artifacts based on the latest scan results. Creates CLAUDE.md, slash commands, agent definitions, rules files, and other artifacts that improve the codebase's AI readiness score. Usage - /deepgrade-readiness:readiness-generate [number] for a specific artifact, all-critical for every critical one, all for everything. argument-hint: "[number|all-critical|all]" allowed-tools: Read, Write, Glob, Grep, Bash, Task disable-model-invocation: true diff --git a/plugins/deepgrade-readiness/commands/readiness-scan.md b/plugins/deepgrade-readiness/commands/readiness-scan.md index 580cbd8..2894064 100644 --- a/plugins/deepgrade-readiness/commands/readiness-scan.md +++ b/plugins/deepgrade-readiness/commands/readiness-scan.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Run an AI Readiness scan on this codebase. Scores how well an AI agent can read and navigate the project across 52 checks in 9 categories. Produces a composite grade (A+ to F) and identifies what to fix first. Category 9 (Database) is conditional and only runs if the codebase uses a database. Use this BEFORE running deeper code quality audits. +description: Run an AI Readiness scan on this codebase. Scores how well an AI agent can read and navigate the project across 52 checks in 9 categories. Produces a composite grade (A+ to F) and identifies what to fix first. Category 9 (Database) is conditional and only runs if the codebase uses a database. Use this BEFORE running deeper code quality audits. allowed-tools: Read, Write, Glob, Grep, Bash, Task --- diff --git a/plugins/deepgrade-readiness/skills/readiness-scoring/SKILL.md b/plugins/deepgrade-readiness/skills/readiness-scoring/SKILL.md index 1264927..58398f0 100644 --- a/plugins/deepgrade-readiness/skills/readiness-scoring/SKILL.md +++ b/plugins/deepgrade-readiness/skills/readiness-scoring/SKILL.md @@ -1,6 +1,6 @@ --- name: readiness-scoring -description: (deepgrade) Knowledge about AI readiness scoring methodology, gate thresholds, confidence levels, and grading criteria. Use when running a readiness scan, interpreting a readiness score or letter grade, deciding whether a check passed, or explaining why a codebase scored the way it did. +description: Knowledge about AI readiness scoring methodology, gate thresholds, confidence levels, and grading criteria. Use when running a readiness scan, interpreting a readiness score or letter grade, deciding whether a check passed, or explaining why a codebase scored the way it did. --- # AI Readiness Scoring Methodology diff --git a/plugins/deepgrade/agents/plan-auditor.md b/plugins/deepgrade/agents/plan-auditor.md index cd6e079..c5a815f 100644 --- a/plugins/deepgrade/agents/plan-auditor.md +++ b/plugins/deepgrade/agents/plan-auditor.md @@ -235,7 +235,7 @@ If the plan references specific files, functions, or patterns: - For each verified claim: mark HIGH confidence - For each unverifiable claim: mark MEDIUM and tag [COULD NOT VERIFY] -## Step 4: Parallel Specialist Review (4 subagents) +## Step 4: Parallel Specialist Review (5 subagents) Deploy 4 specialist reviewers in parallel. Each gets the plan text + relevant codebase files + the deterministic pre-check results from Step 2. @@ -336,7 +336,7 @@ assessment, pattern-matching). This balances quality with cost (~2.5x vs 4x). ## Step 4.5: Verification Pass (False Positive Prevention) -After receiving all 4 subagent outputs: +After receiving all 5 subagent outputs: 1. Combine all gap findings into a single candidate list 2. For each gap, re-read the ENTIRE plan searching for related keywords @@ -353,7 +353,7 @@ Cross-reference between specialists: Report: "Verification: N candidate gaps -> M confirmed, K dropped (X% FP prevented)" -## Step 4: Identify Top Risks +## Step 5: Identify Top Risks Extract the 5 highest risks, whether the plan mentions them or not: - Risk description @@ -362,14 +362,14 @@ Extract the 5 highest risks, whether the plan mentions them or not: - Is it addressed in the plan? (YES / PARTIAL / NO) - Recommended mitigation -## Step 5: Generate Go/No-Go Criteria +## Step 6: Generate Go/No-Go Criteria Based on the audit, define: - GO conditions (what must be true to proceed) - NO-GO conditions (what would stop this project) - CONDITIONAL-GO (proceed with specific modifications) -## Step 5.5: Calibration Check +## Step 6.5: Calibration Check Before writing the final report, verify scoring consistency: @@ -389,7 +389,7 @@ Before writing the final report, verify scoring consistency: - Score range: [min]-[max] (spread of N) ``` -## Step 6: Write the Audit Report +## Step 7: Write the Audit Report Write the audit report to the location specified by the calling command. If called from /deepgrade:plan: write to docs/plans/{date}-{name}/audit.md diff --git a/plugins/deepgrade/agents/plan-scaffolder.md b/plugins/deepgrade/agents/plan-scaffolder.md index 9fab172..42653fd 100644 --- a/plugins/deepgrade/agents/plan-scaffolder.md +++ b/plugins/deepgrade/agents/plan-scaffolder.md @@ -32,7 +32,7 @@ and produce a structured plan at docs/specs/[plan-name].md. ## Step 1: Understand the Objective -Read $ARGUMENTS to understand what the user wants to accomplish. +Read the task description you were given to understand what the user wants to accomplish. Ask clarifying questions if the objective is too vague: - What is the desired end state? - What triggers this work? (bug, feature request, tech debt, leadership mandate) diff --git a/plugins/deepgrade/commands/codex-challenge.md b/plugins/deepgrade/commands/codex-challenge.md index 9d935ed..debe4a3 100644 --- a/plugins/deepgrade/commands/codex-challenge.md +++ b/plugins/deepgrade/commands/codex-challenge.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Adversarial review loop between Claude and OpenAI Codex CLI. Codex scores your plan across 8 dimensions (max 40), Claude optimizes until score reaches 36/40 GREEN. Implements the Evaluator-Optimizer pattern with score-driven convergence. Pass a plan name, file path, or leave empty for auto-detect. +description: Adversarial review loop between Claude and OpenAI Codex CLI. Codex scores your plan across 8 dimensions (max 40), Claude optimizes until score reaches 36/40 GREEN. Implements the Evaluator-Optimizer pattern with score-driven convergence. Pass a plan name, file path, or leave empty for auto-detect. argument-hint: "[plan-name or file-path] [--rounds N] [--model gpt-5.3-codex]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- @@ -20,8 +20,7 @@ training biases. Cross-model adversarial review catches gaps that same-model review misses. Codex operates independently (different training data, different architecture), providing a genuinely orthogonal perspective. -This command extends the existing one-shot `plan-review.js` hook into a multi-round -score-driven optimization loop following the Evaluator-Optimizer pattern from +This command runs a multi-round score-driven optimization loop following the Evaluator-Optimizer pattern from `docs/planning-techniques/02-evaluator-optimizer-loop.md`. The loop targets **36/40** (upper GREEN threshold from DeepGrade's plan-auditor rubric): @@ -525,9 +524,10 @@ Security layers: -/deepgrade:plan, /deepgrade:plan-status, /deepgrade:codex-challenge, /deepgrade:troubleshoot, -/deepgrade:quick-plan, /deepgrade:quick-audit, /deepgrade:quick-cleanup, /deepgrade:documentation, -/deepgrade-readiness:readiness-scan, /deepgrade-readiness:readiness-generate, /deepgrade-audit:codebase-audit, -/deepgrade-audit:codebase-security, /deepgrade-audit:codebase-delta, /deepgrade-audit:codebase-gates, -/deepgrade-audit:codebase-characterize, /deepgrade:help +/deepgrade:codex-challenge, /deepgrade:documentation, /deepgrade:help, /deepgrade:plan, +/deepgrade:plan-export, /deepgrade:plan-status, /deepgrade:quick-audit, /deepgrade:quick-cleanup, +/deepgrade:quick-plan, /deepgrade:troubleshoot, /deepgrade-audit:codebase-audit, +/deepgrade-audit:codebase-characterize, /deepgrade-audit:codebase-delta, +/deepgrade-audit:codebase-gates, /deepgrade-audit:codebase-security, +/deepgrade-readiness:readiness-generate, /deepgrade-readiness:readiness-scan diff --git a/plugins/deepgrade/commands/help.md b/plugins/deepgrade/commands/help.md index 6c2e2e5..6bf34b5 100644 --- a/plugins/deepgrade/commands/help.md +++ b/plugins/deepgrade/commands/help.md @@ -1,8 +1,8 @@ --- -description: (deepgrade) Show all DeepGrade Developer Toolkit commands, agents, and capabilities. Use when you need to see what's available or explain the toolkit to someone new. +description: Show all DeepGrade Developer Toolkit commands, agents, and capabilities. Use when you need to see what's available or explain the toolkit to someone new. --- -# DeepGrade Developer Toolkit (/tp) +# DeepGrade Developer Toolkit A planning + implementation assistant with codebase auditing. Stack-agnostic: works on React/TypeScript, C#/.NET, Python, Rust, and Go projects. @@ -141,15 +141,19 @@ Create and review technical plans for any engineering initiative. | plan-auditor | Scores any plan across 8 dimensions (problem, architecture, phasing, risk, rollback, timeline, testing, team). Produces go/no-go assessment. | | plan-scaffolder | Creates structured plans from vague objectives. Reads codebase + audit data to generate evidence-based phased plans. | -## Knowledge Skills (6) +## Knowledge Skills (7, across all four plugins) Auto-loaded contextual knowledge that guides agent behavior during scans and reports. +`plan` and `documentation` ship in deepgrade; `deepgrade-knowledge`, `governance-knowledge` +and `self-audit-knowledge` in deepgrade-audit (self-audit also in deepgrade); `readiness-scoring` +in deepgrade-readiness. | Skill | What It Provides | |-------|-----------------| | deepgrade-knowledge | DeepGrade methodology for codebase audit and documentation | | documentation | Document generation templates (ADR, BRD, PRD, README, release notes, spec) | | governance-knowledge | Enterprise governance patterns, DORA metrics, quality gates, confidence decay | +| plan | The `/deepgrade:plan` workflow: a router plus one file per phase, loaded on entry so late phases survive compaction | | mcp-research | When and how to use external MCP search tools (Ref, Exa, Perplexity): tool selection heuristics, token budget rules, graceful degradation | | readiness-scoring | AI readiness scoring methodology, gate thresholds, grading criteria | | self-audit-knowledge | LLM epistemic transparency, claim verification tiers (A/B/C), failure mode flags, cascade risk classification, evidence basis formatting | @@ -161,12 +165,12 @@ Powered by audit data when available. Suggests which document to create if you'r | Type | Command Example | What It Creates | |------|----------------|----------------| -| ADR | `doc adr credential rotation` | Architecture Decision Record | -| BRD | `doc brd Ordering` | Business Requirements Document | -| PRD | `doc prd refund processing` | Product Requirements Document | -| README | `doc readme BusinessLogic` | Project README | -| Release Notes | `doc release-notes v2.5.0` | Release notes from git history | -| Spec | `doc spec pricing engine extraction` | Technical Specification / Engineering Plan | +| ADR | `/deepgrade:documentation adr credential rotation` | Architecture Decision Record | +| BRD | `/deepgrade:documentation brd Ordering` | Business Requirements Document | +| PRD | `/deepgrade:documentation prd refund processing` | Product Requirements Document | +| README | `/deepgrade:documentation readme BusinessLogic` | Project README | +| Release Notes | `/deepgrade:documentation release-notes v2.5.0` | Release notes from git history | +| Spec | `/deepgrade:documentation spec pricing engine extraction` | Technical Specification / Engineering Plan | Don't know which format? Just say "I need to document X" and the skill will recommend the right type based on your context and audit data. diff --git a/plugins/deepgrade/commands/plan-export.md b/plugins/deepgrade/commands/plan-export.md index d88d51c..6a1339f 100644 --- a/plugins/deepgrade/commands/plan-export.md +++ b/plugins/deepgrade/commands/plan-export.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Export a plan as a self-contained zip package that another developer can use with vanilla Claude Code (no plugin required). Copies all referenced documents, redacts secrets, includes a CLAUDE.md that auto-bootstraps context, and verifies codebase compatibility on the receiving end. The developer unzips into their project root and Claude immediately understands the plan. +description: Export a plan as a self-contained zip package that another developer can use with vanilla Claude Code (no plugin required). Copies all referenced documents, redacts secrets, includes a CLAUDE.md that auto-bootstraps context, and verifies codebase compatibility on the receiving end. The developer unzips into their project root and Claude immediately understands the plan. argument-hint: "[plan-name]" allowed-tools: Read, Write, Grep, Glob, Bash, Task disable-model-invocation: true @@ -420,8 +420,10 @@ Vanilla Claude Code reads the CLAUDE.md and handles everything. -/deepgrade:plan, /deepgrade:plan-status, /deepgrade:plan-export, /deepgrade:troubleshoot, /deepgrade:quick-plan, -/deepgrade:quick-audit, /deepgrade:quick-cleanup, /deepgrade:documentation, /deepgrade-readiness:readiness-scan, -/deepgrade-readiness:readiness-generate, /deepgrade-audit:codebase-audit, /deepgrade-audit:codebase-security, -/deepgrade-audit:codebase-delta, /deepgrade-audit:codebase-gates, /deepgrade-audit:codebase-characterize, /deepgrade:help +/deepgrade:codex-challenge, /deepgrade:documentation, /deepgrade:help, /deepgrade:plan, +/deepgrade:plan-export, /deepgrade:plan-status, /deepgrade:quick-audit, /deepgrade:quick-cleanup, +/deepgrade:quick-plan, /deepgrade:troubleshoot, /deepgrade-audit:codebase-audit, +/deepgrade-audit:codebase-characterize, /deepgrade-audit:codebase-delta, +/deepgrade-audit:codebase-gates, /deepgrade-audit:codebase-security, +/deepgrade-readiness:readiness-generate, /deepgrade-readiness:readiness-scan diff --git a/plugins/deepgrade/commands/plan-status.md b/plugins/deepgrade/commands/plan-status.md index 6ad0e1c..ce95c65 100644 --- a/plugins/deepgrade/commands/plan-status.md +++ b/plugins/deepgrade/commands/plan-status.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Show status of all active plans or detailed status of a specific plan. Checks for staleness, shows progress, and recommends next action. Pass a plan name for details or no argument for overview. +description: Show status of all active plans or detailed status of a specific plan. Checks for staleness, shows progress, and recommends next action. Pass a plan name for details or no argument for overview. argument-hint: "[plan-name]" allowed-tools: Read, Grep, Glob, Bash --- diff --git a/plugins/deepgrade/commands/quick-audit.md b/plugins/deepgrade/commands/quick-audit.md index 75b9177..3f3d69a 100644 --- a/plugins/deepgrade/commands/quick-audit.md +++ b/plugins/deepgrade/commands/quick-audit.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Audit any technical plan, spec, or proposal for gaps, risks, and leadership readiness. Scores the plan across 8 dimensions (problem, architecture, phasing, risk, rollback, timeline, testing, team). Produces a go/no-go assessment and leadership presentation outline. Pass a file path or describe the plan. +description: Audit any technical plan, spec, or proposal for gaps, risks, and leadership readiness. Scores the plan across 8 dimensions (problem, architecture, phasing, risk, rollback, timeline, testing, team). Produces a go/no-go assessment and leadership presentation outline. Pass a file path or describe the plan. argument-hint: "[plan-file-path or description] [--plan plan-name]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade/commands/quick-cleanup.md b/plugins/deepgrade/commands/quick-cleanup.md index 98dd8da..5b743cd 100644 --- a/plugins/deepgrade/commands/quick-cleanup.md +++ b/plugins/deepgrade/commands/quick-cleanup.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Clean up a folder of messy documents (PDFs, images, text files, vendor manuals, meeting notes, legacy docs) into standardized markdown and JSON reference files. Guides you through understanding the data first, then cleans it into structured reference material. Automatically creates a plan homebase folder if one doesn't exist. This may be the only step in a plan, or the first step of a larger plan. +description: Clean up a folder of messy documents (PDFs, images, text files, vendor manuals, meeting notes, legacy docs) into standardized markdown and JSON reference files. Guides you through understanding the data first, then cleans it into structured reference material. Automatically creates a plan homebase folder if one doesn't exist. This may be the only step in a plan, or the first step of a larger plan. argument-hint: "[folder-path] [topic-name] [--plan plan-name]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade/commands/quick-plan.md b/plugins/deepgrade/commands/quick-plan.md index 7bb1da5..7fdd34e 100644 --- a/plugins/deepgrade/commands/quick-plan.md +++ b/plugins/deepgrade/commands/quick-plan.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) Create a structured technical plan from a vague objective. Analyzes the codebase, identifies risks, generates phased approach with timeline estimates, testing strategy, and rollback plan. The output is a plan that scores well on the plan auditor's 8 dimensions. Pass an objective or requirement description. +description: Create a structured technical plan from a vague objective. Analyzes the codebase, identifies risks, generates phased approach with timeline estimates, testing strategy, and rollback plan. The output is a plan that scores well on the plan auditor's 8 dimensions. Pass an objective or requirement description. argument-hint: "[objective description] [--plan plan-name]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- diff --git a/plugins/deepgrade/commands/troubleshoot.md b/plugins/deepgrade/commands/troubleshoot.md index f26f554..2dd5729 100644 --- a/plugins/deepgrade/commands/troubleshoot.md +++ b/plugins/deepgrade/commands/troubleshoot.md @@ -1,5 +1,5 @@ --- -description: (deepgrade) AI-guided troubleshooting using the 4-phase systematic debugging framework with severity-driven incident triage and containment. Enforces root cause investigation before suggesting fixes. For SEV1/SEV2 production incidents, temporary containment is allowed before investigation. Logs every step, builds a project knowledge base. Auto-links to active plan. Pass an error message, issue description, or just say what broke. +description: AI-guided troubleshooting using the 4-phase systematic debugging framework with severity-driven incident triage and containment. Enforces root cause investigation before suggesting fixes. For SEV1/SEV2 production incidents, temporary containment is allowed before investigation. Logs every step, builds a project knowledge base. Auto-links to active plan. Pass an error message, issue description, or just say what broke. argument-hint: "[error message or issue description] [--plan plan-name] [--severity SEV1|SEV2|SEV3|SEV4]" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- @@ -845,9 +845,10 @@ STOP and follow the 4-phase process if you catch yourself: -/deepgrade:plan, /deepgrade:plan-status, /deepgrade:codex-challenge, /deepgrade:troubleshoot, -/deepgrade:quick-plan, /deepgrade:quick-audit, /deepgrade:quick-cleanup, /deepgrade:documentation, -/deepgrade-readiness:readiness-scan, /deepgrade-readiness:readiness-generate, /deepgrade-audit:codebase-audit, -/deepgrade-audit:codebase-security, /deepgrade-audit:codebase-delta, /deepgrade-audit:codebase-gates, -/deepgrade-audit:codebase-characterize, /deepgrade:help +/deepgrade:codex-challenge, /deepgrade:documentation, /deepgrade:help, /deepgrade:plan, +/deepgrade:plan-export, /deepgrade:plan-status, /deepgrade:quick-audit, /deepgrade:quick-cleanup, +/deepgrade:quick-plan, /deepgrade:troubleshoot, /deepgrade-audit:codebase-audit, +/deepgrade-audit:codebase-characterize, /deepgrade-audit:codebase-delta, +/deepgrade-audit:codebase-gates, /deepgrade-audit:codebase-security, +/deepgrade-readiness:readiness-generate, /deepgrade-readiness:readiness-scan diff --git a/plugins/deepgrade/scripts/dg-subagent-stop.js b/plugins/deepgrade/scripts/dg-subagent-stop.js index 262a84d..0fa1997 100644 --- a/plugins/deepgrade/scripts/dg-subagent-stop.js +++ b/plugins/deepgrade/scripts/dg-subagent-stop.js @@ -15,6 +15,7 @@ function quiet() { process.exit(0); } let payload = null; try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { payload = null; } +if (payload && payload.stop_hook_active === true) quiet(); let plansDir = 'docs/plans'; if (!fs.existsSync(plansDir) && fs.existsSync('plans')) plansDir = 'plans'; diff --git a/plugins/deepgrade/skills/documentation/SKILL.md b/plugins/deepgrade/skills/documentation/SKILL.md index f2aa335..4a15eb7 100644 --- a/plugins/deepgrade/skills/documentation/SKILL.md +++ b/plugins/deepgrade/skills/documentation/SKILL.md @@ -1,6 +1,6 @@ --- name: documentation -description: (deepgrade) Generate project documentation (ADR, BRD, PRD, README, release notes, changelog, technical spec). Dispatches to the appropriate template based on document type. Also suggests which document to create based on context. Triggers on - create adr, create brd, create prd, create readme, generate documentation, architecture decision, business requirements, product requirements, release notes, changelog, version notes, release summary, prepare release, generate changelog, version history, release documentation, deployment notes, create spec, technical specification, write spec, engineering plan, design doc, RFC, migration plan. +description: Generate project documentation (ADR, BRD, PRD, README, release notes, changelog, technical spec). Dispatches to the appropriate template based on document type. Also suggests which document to create based on context. Triggers on - create adr, create brd, create prd, create readme, generate documentation, architecture decision, business requirements, product requirements, release notes, changelog, version notes, release summary, prepare release, generate changelog, version history, release documentation, deployment notes, create spec, technical specification, write spec, engineering plan, design doc, RFC, migration plan. --- # Documentation Generator @@ -52,7 +52,7 @@ Parse `$ARGUMENTS` to determine the document type and topic: ### Dispatch Logic -1. If `$ARGUMENTS` starts with a known subcommand, read the corresponding template and execute with the remaining text as the topic (`$1`). +1. If `$ARGUMENTS` starts with a known subcommand, read the corresponding template and execute with the remaining text as the topic. Templates refer to that topic with a literal dollar-one placeholder; substitute the remaining text wherever it appears. 2. If `$ARGUMENTS` is empty, show this menu: ``` @@ -164,7 +164,7 @@ This ensures documents don't exist in isolation. Every doc links to related docs ### Execution Read the selected `resources/*.md` template file and follow its instructions exactly, -treating the remaining arguments as `$1` (the topic/feature/domain/project name). +treating the remaining arguments as the topic (feature, domain, or project name) wherever the template shows its dollar-one placeholder. ### Command Reference Rule diff --git a/plugins/deepgrade/skills/documentation/resources/release-notes-template.md b/plugins/deepgrade/skills/documentation/resources/release-notes-template.md index b8d90e3..5060255 100644 --- a/plugins/deepgrade/skills/documentation/resources/release-notes-template.md +++ b/plugins/deepgrade/skills/documentation/resources/release-notes-template.md @@ -1,5 +1,14 @@ # Release Notes Generator +## Contents + +- Workflow +- Phase 1: Gather Context +- Phase 2: Analyze Git History +- Phase 3: Generate Draft (section skeleton) +- Phase 4: Refine +- Audience Customization, Integration Patterns, Best Practices, Example Commands + **Purpose:** Generate professional release notes by analyzing git history and commits. Interactive workflow allows refinement and customization. ## Workflow diff --git a/plugins/deepgrade/skills/documentation/resources/spec-template.md b/plugins/deepgrade/skills/documentation/resources/spec-template.md index 9b06ed6..24017ba 100644 --- a/plugins/deepgrade/skills/documentation/resources/spec-template.md +++ b/plugins/deepgrade/skills/documentation/resources/spec-template.md @@ -1,5 +1,13 @@ Generate a Technical Specification for "$1". +## Contents + +- Step 0: Disambiguate (extraction/migration vs feature) +- Spec document skeleton: Context, Goal, Architecture, Phases +- Shadow Mode / Validation Strategy, Risk Assessment, Hidden Dependencies +- Timeline, Team & Resources, Testing Strategy, Rollback Strategy +- Success Criteria, Open Questions, Critical Files, Verification + **Step 0: Disambiguate** Determine what kind of spec this is: diff --git a/plugins/deepgrade/skills/mcp-research/SKILL.md b/plugins/deepgrade/skills/mcp-research/SKILL.md index 417d616..b421eac 100644 --- a/plugins/deepgrade/skills/mcp-research/SKILL.md +++ b/plugins/deepgrade/skills/mcp-research/SKILL.md @@ -1,6 +1,6 @@ --- name: mcp-research -description: (deepgrade) Knowledge about when and how to use external MCP search tools (Ref, Exa, Perplexity) for documentation lookup, best practices search, code example discovery, and deep research. Use when looking up framework or library documentation, searching for how others solved a problem, finding code examples, checking whether an MCP search tool is available, or deciding which search tool fits a question. Teaches tool selection heuristics, token budget rules, suffix-matching for server-qualified tool names, and graceful degradation patterns. +description: Knowledge about when and how to use external MCP search tools (Ref, Exa, Perplexity) for documentation lookup, best practices search, code example discovery, and deep research. Use when looking up framework or library documentation, searching for how others solved a problem, finding code examples, checking whether an MCP search tool is available, or deciding which search tool fits a question. Teaches tool selection heuristics, token budget rules, suffix-matching for server-qualified tool names, and graceful degradation patterns. --- # MCP Research Tool Selection Guide @@ -99,7 +99,7 @@ three are the same tool. Comparing against the bare string `perplexity_search` matches nothing and wrongly triggers the graceful-degradation path below even when the server is connected. -## Tool Name Suffixes (verified 2026-07-29) +## Tool Name Suffixes (verify against the live tool listing at run time) **Ref Tools MCP:** - `ref_search_documentation` — search docs with a natural language query diff --git a/plugins/deepgrade/skills/plan/SKILL.md b/plugins/deepgrade/skills/plan/SKILL.md index a88332f..f635fa0 100644 --- a/plugins/deepgrade/skills/plan/SKILL.md +++ b/plugins/deepgrade/skills/plan/SKILL.md @@ -1,6 +1,6 @@ --- name: plan -description: (deepgrade) Start or resume a guided plan. Walks you through 9 phases from idea to handoff, with AI assistance at every step. Produces documents by default; codebase writes require your approval. Pass a plan name to start new or resume existing. Optionally pass source material with 'from'. Use when the user asks to plan a feature, start or resume a plan, or take an idea through brainstorm, research, audit, build, and handoff. +description: Start or resume a guided plan. Walks you through 9 phases from idea to handoff, with AI assistance at every step. Produces documents by default; codebase writes require your approval. Pass a plan name to start new or resume existing. Optionally pass source material with 'from'. Use when the user asks to plan a feature, start or resume a plan, or take an idea through brainstorm, research, audit, build, and handoff. argument-hint: "[plan-name] [from docs/path or 'idea: description']" allowed-tools: Read, Write, Grep, Glob, Bash, Task --- @@ -309,11 +309,11 @@ On resume, check freshness of all completed phases and report any staleness. -Only suggest these commands (all verified to exist as command files): -/deepgrade:plan, /deepgrade:plan-status, /deepgrade:quick-audit, -/deepgrade:quick-plan, /deepgrade:quick-cleanup, /deepgrade:documentation, -/deepgrade-audit:codebase-characterize, /deepgrade-readiness:readiness-scan, -/deepgrade-audit:codebase-audit, /deepgrade-audit:codebase-delta, -/deepgrade-audit:codebase-security, /deepgrade-audit:codebase-gates, -/deepgrade-readiness:readiness-generate, /deepgrade:help +Only suggest these (each exists as a command file or a skill): +/deepgrade:codex-challenge, /deepgrade:documentation, /deepgrade:help, /deepgrade:plan, +/deepgrade:plan-export, /deepgrade:plan-status, /deepgrade:quick-audit, /deepgrade:quick-cleanup, +/deepgrade:quick-plan, /deepgrade:troubleshoot, /deepgrade-audit:codebase-audit, +/deepgrade-audit:codebase-characterize, /deepgrade-audit:codebase-delta, +/deepgrade-audit:codebase-gates, /deepgrade-audit:codebase-security, +/deepgrade-readiness:readiness-generate, /deepgrade-readiness:readiness-scan diff --git a/plugins/deepgrade/skills/self-audit-knowledge/SKILL.md b/plugins/deepgrade/skills/self-audit-knowledge/SKILL.md index a32a84d..75d0649 100644 --- a/plugins/deepgrade/skills/self-audit-knowledge/SKILL.md +++ b/plugins/deepgrade/skills/self-audit-knowledge/SKILL.md @@ -1,6 +1,6 @@ --- name: self-audit-knowledge -description: (deepgrade) Knowledge about LLM epistemic transparency, claim verification tiers, failure mode flags, cascade risk classification, and evidence basis formatting. Use when stating how confident a finding is, labelling a claim as verified or unverified, flagging an assumption, assessing whether one wrong conclusion invalidates others, or writing the evidence basis for an audit or plan review. +description: Knowledge about LLM epistemic transparency, claim verification tiers, failure mode flags, cascade risk classification, and evidence basis formatting. Use when stating how confident a finding is, labelling a claim as verified or unverified, flagging an assumption, assessing whether one wrong conclusion invalidates others, or writing the evidence basis for an audit or plan review. --- # LLM Self-Audit Framework