From c753cd35adf97d444f9e3e863f08a938053d92b5 Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 27 Jul 2026 14:32:22 -0400 Subject: [PATCH] Adopt native skill discovery --- .github/workflows/opencode-smoke.yml | 22 +++ THIRD_PARTY_NOTICES.md | 8 +- commands/agents-md-improver.md | 183 ------------------------- commands/agents-md-revise.md | 97 ------------- commands/code-architect.md | 59 -------- commands/code-explorer.md | 59 -------- commands/code-review.md | 135 ------------------ commands/code-reviewer.md | 117 ---------------- commands/feature-dev.md | 111 --------------- commands/frontend-design.md | 92 ------------- commands/mcp-builder.md | 153 --------------------- commands/security-review.md | 196 --------------------------- commands/skill-creator.md | 159 ---------------------- package.json | 8 +- scripts/opencode-smoke.mjs | 169 +++++++++++++++++++++++ tests/agents-md-revise.test.mjs | 6 - tests/frontend-design.test.mjs | 8 -- tests/opencode-smoke.test.mjs | 34 +++++ tests/package-surface.test.mjs | 38 ++++++ tests/provenance.test.mjs | 2 - tests/skill-lint.test.mjs | 14 -- tests/working-discipline.test.mjs | 4 - 22 files changed, 273 insertions(+), 1401 deletions(-) create mode 100644 .github/workflows/opencode-smoke.yml delete mode 100644 commands/agents-md-improver.md delete mode 100644 commands/agents-md-revise.md delete mode 100644 commands/code-architect.md delete mode 100644 commands/code-explorer.md delete mode 100644 commands/code-review.md delete mode 100644 commands/code-reviewer.md delete mode 100644 commands/feature-dev.md delete mode 100644 commands/frontend-design.md delete mode 100644 commands/mcp-builder.md delete mode 100644 commands/security-review.md delete mode 100644 commands/skill-creator.md create mode 100644 scripts/opencode-smoke.mjs create mode 100644 tests/opencode-smoke.test.mjs create mode 100644 tests/package-surface.test.mjs diff --git a/.github/workflows/opencode-smoke.yml b/.github/workflows/opencode-smoke.yml new file mode 100644 index 0000000..5b48fa1 --- /dev/null +++ b/.github/workflows/opencode-smoke.yml @@ -0,0 +1,22 @@ +name: OpenCode smoke + +on: + pull_request: + paths: + - ".opencode/**" + - "skills/**" + - "scripts/opencode-smoke.mjs" + - "package.json" + - ".github/workflows/opencode-smoke.yml" + workflow_dispatch: + +jobs: + opencode-1-18-7: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "24" + - run: node scripts/opencode-smoke.mjs 1.18.7 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index c10b4b9..34d1201 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -4,10 +4,10 @@ The repository wrapper, plugin integration, packaging, tests, and original documentation are licensed under the root MIT `LICENSE` unless a file states otherwise. -The skills and generated command prompts are modified derivatives of the -sources recorded in `UPSTREAMS.json`. They are not represented as original -work. Every entry records the immutable upstream commit, source path, Git blob, -license, and adaptation type reviewed for this distribution. +The skills are modified derivatives of the sources recorded in +`UPSTREAMS.json`. They are not represented as original work. Every entry +records the immutable upstream commit, source path, Git blob, license, and +adaptation type reviewed for this distribution. ## Anthropic Official Plugins diff --git a/commands/agents-md-improver.md b/commands/agents-md-improver.md deleted file mode 100644 index 787a4ed..0000000 --- a/commands/agents-md-improver.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -description: Audit and improve project-rules files (AGENTS.md, CLAUDE.md, .agents/instructions, local overrides) so the agent keeps accurate project context. Use when the user asks to check, audit, review, update, improve, or fix their AGENTS.md or CLAUDE.md, mentions "project rules maintenance" or "agent context optimization", or when the codebase has changed enough that the rules file may be stale. Scans the repository for every rules file, grades each against a quality rubric, outputs a quality report, and applies targeted edits only after user approval. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# AGENTS.md / CLAUDE.md Improver - -Audit, evaluate, and improve project-rules files across a codebase to ensure the agent has optimal project context. - -OpenCode resolves project rules **first-match-wins per directory**: when a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. Resolution walks from the working directory up to the git root, takes the first match at each level, and merges those with the global `~/.config/opencode/AGENTS.md` and any paths declared in the `instructions` field of `opencode.json`. Treat `AGENTS.md` as canonical when creating new files, and report any directory that contains both files as a finding, since its `CLAUDE.md` is silently ignored. - -**This skill can write to project-rules files.** After presenting a quality report and getting user approval, it updates the files with targeted improvements. - -## Workflow - -### Phase 1: Discovery - -Find all relevant files in the repository: - -```bash -find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" -o -name ".agents.local.md" \) 2>/dev/null | head -50 -``` - -**File types and locations:** - -| Type | Location | Purpose | -|------|----------|---------| -| Project root (OpenCode native) | `./AGENTS.md` | Primary project context (committed, shared) | -| Project root (Claude compat) | `./CLAUDE.md` | Same purpose; OpenCode reads it as fallback | -| Local overrides | `./.agents.local.md` or `./.claude.local.md` | Personal/local settings (gitignored) | -| Global defaults | `~/.config/opencode/AGENTS.md` or `~/.claude/CLAUDE.md` | User-wide defaults | -| Package-specific | `./packages/*/AGENTS.md` | Module-level context in monorepos | -| Subdirectory | Any nested location | Feature/domain-specific context | - -OpenCode walks up from the working directory toward the git root, loading any matching rules files along the way, so monorepos and nested projects work automatically. - -### Phase 2: Quality assessment - -For each rules file, evaluate against the criteria below. - -**Quick assessment checklist:** - -| Criterion | Weight | Check | -|-----------|--------|-------| -| Commands / workflows documented | High | Are build / test / deploy commands present? | -| Architecture clarity | High | Can the agent understand the codebase structure? | -| Non-obvious patterns | Medium | Are gotchas and quirks documented? | -| Conciseness | Medium | No verbose explanations or obvious info? | -| Currency | High | Does it reflect the current codebase state? | -| Actionability | High | Are instructions executable, not vague? | - -**Quality scores:** - -- **A (90–100)** — Comprehensive, current, actionable. -- **B (70–89)** — Good coverage, minor gaps. -- **C (50–69)** — Basic info, missing key sections. -- **D (30–49)** — Sparse or outdated. -- **F (0–29)** — Missing or severely outdated. - -### Phase 3: Quality-report output - -**Always output the quality report BEFORE making any updates.** - -Format: - -``` -## Project-Rules Quality Report - -### Summary -- Files found: X -- Average score: X/100 -- Files needing update: X - -### File-by-File Assessment - -#### 1. ./AGENTS.md (Project Root) -**Score: XX/100 (Grade: X)** - -| Criterion | Score | Notes | -|-----------|-------|-------| -| Commands / workflows | X/20 | ... | -| Architecture clarity | X/20 | ... | -| Non-obvious patterns | X/15 | ... | -| Conciseness | X/15 | ... | -| Currency | X/15 | ... | -| Actionability | X/15 | ... | - -**Issues:** -- [List specific problems] - -**Recommended additions:** -- [List what should be added] - -#### 2. ./packages/api/AGENTS.md (Package-specific) -... -``` - -### Phase 4: Targeted updates - -After the quality report, ask the user for confirmation before updating. - -**Update guidelines (critical):** - -1. **Propose targeted additions only.** Focus on genuinely useful info: - - Commands or workflows discovered during analysis - - Gotchas or non-obvious patterns found in code - - Package relationships that were unclear - - Testing approaches that work - - Configuration quirks - -2. **Keep it minimal.** Avoid: - - Restating what is obvious from the code - - Generic best practices already covered - - One-off fixes unlikely to recur - - Verbose explanations when a one-liner suffices - -3. **Show diffs.** For each change, show: - - Which file to update - - The specific addition (diff or quoted block) - - A brief explanation of why this helps future sessions - -**Diff format:** - -````markdown -### Update: ./AGENTS.md - -**Why:** Build command was missing, causing confusion about how to run the project. - -```diff -+ ## Quick Start -+ -+ ```bash -+ npm install -+ npm run dev # Start development server on port 3000 -+ ``` -``` -```` - -### Phase 5: Apply updates - -After user approval, apply changes using the editor tool. Preserve the existing content structure; only add what was approved. - -## Common issues to flag - -1. **Stale commands** — build commands that no longer work. -2. **Missing dependencies** — required tools not mentioned. -3. **Outdated architecture** — file structure that has changed. -4. **Missing environment setup** — required env vars or config. -5. **Broken test commands** — test scripts that have changed. -6. **Undocumented gotchas** — non-obvious patterns not captured. -7. **Shadowed `CLAUDE.md`** — a directory that contains both `AGENTS.md` and `CLAUDE.md`. OpenCode loads only `AGENTS.md`, so the `CLAUDE.md` is silently ignored; merge its contents into `AGENTS.md` or remove it. - -## What makes a great rules file - -**Key principles:** - -- Concise and human-readable. -- Actionable commands that can be copy-pasted. -- Project-specific patterns, not generic advice. -- Non-obvious gotchas and warnings. - -**Recommended sections** (use only what is relevant): - -- Commands (build, test, dev, lint) -- Architecture (directory structure) -- Key files (entry points, config) -- Code style (project conventions) -- Environment (required vars, setup) -- Testing (commands, patterns) -- Gotchas (quirks, common mistakes) -- Workflow (when to do what) - -## Tips to share with the user - -- **Keep it concise** — the rules file is part of the prompt, so brevity matters. Dense is better than verbose. -- **Actionable commands** — all documented commands should be copy-paste ready. -- **Use a `.local` override** — for personal preferences not shared with the team (add to `.gitignore`). -- **Global defaults** — put user-wide preferences in `~/.config/opencode/AGENTS.md` (or `~/.claude/CLAUDE.md`). -- **Prefer `AGENTS.md`.** Use `AGENTS.md` for new rules files: OpenCode reads it natively and Claude Code reads it as a fallback. Do not add an `AGENTS.md` alongside an existing `CLAUDE.md` — under first-match-wins, OpenCode would load only the `AGENTS.md` and ignore the `CLAUDE.md` entirely. Either keep maintaining the `CLAUDE.md` in place, or migrate its contents into `AGENTS.md` and remove it. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/agents-md-revise.md b/commands/agents-md-revise.md deleted file mode 100644 index 3ca925c..0000000 --- a/commands/agents-md-revise.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -description: Capture learnings from the current session into the project-rules file (AGENTS.md, CLAUDE.md, or local override) so future sessions benefit. Use when the user says "revise the rules", "update AGENTS.md / CLAUDE.md with what we just learned", "save this to project memory", "remember this for next time", or at the end of a productive session when valuable context has emerged that is not yet documented. This is the COMPLEMENT to agents-md-improver: improver audits, this one captures. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# AGENTS.md / CLAUDE.md Revise - -Review the current session for learnings about working in this codebase, then update the project-rules file with context that would help future sessions be more effective. - -OpenCode resolves project rules first-match-wins per directory: if a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. When capturing learnings, prefer `AGENTS.md` for a new file; if both already exist in the same directory, write to `AGENTS.md` — never into the shadowed `CLAUDE.md`, or the notes land in a file OpenCode ignores. If only `CLAUDE.md` exists, update it in place (and consider migrating it to `AGENTS.md`). - -## Step 1 — Reflect - -Look back over the session and identify what context was missing that would have helped the agent work more effectively. Examples: - -- Bash commands that were used or discovered -- Code-style patterns followed -- Testing approaches that worked -- Environment / configuration quirks -- Warnings or gotchas encountered -- Build steps that surprised you -- Tool versions that mattered -- Project-specific conventions that took time to figure out - -Be selective. Only capture things that: - -1. Will recur in future sessions (not one-off fixes). -2. Would have saved time if known up front. -3. Cannot be derived by reading the code. - -## Step 2 — Find rules files - -```bash -find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".agents.local.md" -o -name ".claude.local.md" \) 2>/dev/null | head -20 -``` - -Decide where each addition belongs: - -- **`AGENTS.md` / `CLAUDE.md`** — team-shared, committed to git. Use for project-wide conventions, build commands, architectural notes. -- **`.agents.local.md` / `.claude.local.md`** — personal / local only, gitignored. Use for personal preferences that should not affect teammates. - -If both `AGENTS.md` and `CLAUDE.md` exist in the same directory, target `AGENTS.md` — OpenCode ignores the co-located `CLAUDE.md`, so anything written there is lost. - -If no rules file exists yet, propose creating `AGENTS.md` at the project root. - -## Step 3 — Draft additions - -**Keep it concise.** The rules file is part of every prompt, so brevity matters. One line per concept when possible. - -Format: ` — ` - -**Avoid:** - -- Verbose explanations -- Obvious information that any reader of the code would already know -- One-off fixes unlikely to recur -- Restating what is already documented elsewhere in the rules file - -**Prefer:** - -- Imperative commands ("Run `pnpm i --frozen-lockfile` after pulling") -- Concrete gotchas ("The `dev` script binds to port 3000 — kill any other process on that port first") -- Project-specific patterns ("All dates are stored in UTC; convert at the boundary") - -## Step 4 — Show proposed changes - -For each addition, show the user the diff before applying. Format: - -````markdown -### Update: ./AGENTS.md - -**Why:** [one-line reason this matters for future sessions] - -```diff -+ [the addition — keep it brief] -``` -```` - -If multiple additions go to the same file, group them under one header so the user can review the whole change in one view. - -## Step 5 — Apply with approval - -Ask the user explicitly: *"Apply these changes?"* Edit only files they approve. - -Preserve the existing structure. Place additions in the most relevant section (e.g., a new build command goes under "Commands" if that section exists). If no obvious section fits, create one with a clear header. - -If the user rejects an addition, do not retry it in the same session — they may have a reason. Move on. - -## Notes - -- This skill **writes** to project files. Always show the diff first and wait for approval. -- Pair this skill with `agents-md-improver` for the full maintenance loop: improver audits and identifies gaps; this one captures fresh session-specific learnings. -- Do not include sensitive information (API keys, tokens, internal URLs) in committed rules files. Put those in `.agents.local.md` / `.claude.local.md` or in environment variables. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-architect.md b/commands/code-architect.md deleted file mode 100644 index e2c3c67..0000000 --- a/commands/code-architect.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Architect - -You are a senior software architect who delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident architectural decisions. - -## Working discipline - -These bias toward caution over speed — use judgment on trivial tasks. - -- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so. -- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases. -- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. -- **Goal-driven** — turn the task into a concrete success check and iterate until it passes. - -## Core process - -### 1. Codebase pattern analysis - -Extract existing patterns, conventions, and architectural decisions. Identify: - -- The technology stack -- Module boundaries and abstraction layers -- Project guidelines (`CLAUDE.md` / `AGENTS.md`) -- Similar features already implemented — how were they structured? -- Key abstractions the codebase already provides - -### 2. Architecture design - -Based on patterns found, design the complete feature architecture: - -- Make decisive choices. Pick one approach and commit to it. -- Ensure seamless integration with existing code. -- Design for testability, performance, and maintainability. - -### 3. Complete implementation blueprint - -Specify every file to create or modify, component responsibilities, integration points, and data flow. Break the implementation into clear phases. - -## Output - -Deliver a decisive, complete architecture blueprint. Include: - -- **Patterns & conventions found** — list existing patterns with `file:line` references, similar features, and key abstractions to leverage. -- **Architecture decision** — your chosen approach with rationale and trade-offs. -- **Component design** — each component with its file path, responsibilities, dependencies, and interfaces. -- **Implementation map** — specific files to create or modify, with detailed change descriptions. -- **Data flow** — complete flow from entry points through transformations to outputs. -- **Build sequence** — phased implementation steps as a checklist. -- **Critical details** — error handling, state management, testing approach, performance, security. - -Make confident architectural choices. Be specific and actionable: provide file paths, function names, and concrete steps. Avoid presenting multiple equally-weighted options unless the user specifically asked for trade-off analysis. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-explorer.md b/commands/code-explorer.md deleted file mode 100644 index fcb15c9..0000000 --- a/commands/code-explorer.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase". -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Explorer - -You are an expert code analyst specializing in tracing and understanding feature implementations across codebases. - -## Core mission - -Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers. - -## Analysis approach - -### 1. Feature discovery - -- Find entry points: APIs, UI components, CLI commands. -- Locate core implementation files. -- Map feature boundaries and configuration surface. - -### 2. Code-flow tracing - -- Follow call chains from entry to output. -- Trace data transformations at each step. -- Identify all dependencies and integrations. -- Document state changes and side effects. - -### 3. Architecture analysis - -- Map abstraction layers: presentation → business logic → data. -- Identify design patterns and architectural decisions. -- Document interfaces between components. -- Note cross-cutting concerns: auth, logging, caching, observability. - -### 4. Implementation details - -- Key algorithms and data structures. -- Error handling and edge cases. -- Performance considerations. -- Technical debt or improvement areas. - -## Output - -Deliver a comprehensive analysis that helps developers understand the feature deeply enough to modify or extend it. Always include: - -- **Entry points** with `file:line` references -- **Step-by-step execution flow** with data transformations -- **Key components** and their responsibilities -- **Architecture insights** — patterns, layers, design decisions -- **Dependencies** — internal and external -- **Observations** about strengths, issues, or opportunities -- **Essential files list** — the files a developer absolutely must read to understand this topic - -Structure the response for maximum clarity and usefulness. Always cite specific file paths and line numbers. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-review.md b/commands/code-review.md deleted file mode 100644 index a7f2f8e..0000000 --- a/commands/code-review.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -description: Review a pull request or a set of code changes for bugs, logic errors, and project-convention violations using a confidence-filtered, multi-agent process. Use this skill when the user asks to review a PR, audit pending changes, or inspect a diff for problems before merging. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Review - -Provide a high-signal code review for a pull request or set of pending changes. The goal is to surface only issues that are clearly real and actionable, while filtering out noise, nitpicks, and false positives. - -## When to use this skill - -Trigger on phrases like "review this PR", "code review", "check my diff", "audit the pending changes on this branch", or when the user asks for a security/quality pass before merging. - -## High-level process - -Follow these steps in order. Use OpenCode's parallel sub-task dispatch where the original Claude Code workflow used parallel agents. - -### 1. Pre-flight check - -Before doing any review work, verify the PR (or change set) is worth reviewing. Skip the review and stop early if any of the following hold: - -- The PR is closed -- The PR is a draft -- The change is trivial (single-line typo, formatting, automated dependency bump) and obviously correct -- A previous review by the agent already exists on this PR - -Use `gh pr view ` (or the local `git diff` for non-PR review) to gather state. - -### 2. Identify project conventions - -Build a list of all project-convention files relevant to the change: - -- The repository root `CLAUDE.md` / `AGENTS.md` (whichever exists) -- Any nested `CLAUDE.md` / `AGENTS.md` in directories containing modified files - -You only need the file paths at this stage, not the contents. - -### 3. Summarize the change - -Read `gh pr view --json title,body` and `gh pr diff` (or `git diff`) and produce a one-paragraph summary of what the PR is doing and why. This grounds the rest of the review. - -### 4. Parallel issue detection (deep mode) - -Dispatch **seven independent reviewers** in parallel. Each returns a list of candidate issues, where each issue includes a description, a reason category, an initial confidence (0–100), and a one-sentence failure scenario explaining how this would manifest in practice. - -- **Reviewer 1 + Reviewer 2 — Convention compliance.** Audit the diff against the relevant `CLAUDE.md` / `AGENTS.md` rules. Only consider rule files that apply to the file being reviewed (same path or ancestor directory). Quote the exact rule being violated. -- **Reviewer 3 — Diff-only bug scan.** Scan the diff for obvious bugs without reading surrounding files. Flag only clear issues that do not need unseen context. -- **Reviewer 4 — Deep-context bug scan.** Read the **full file(s)** for each changed function, not just the diff hunks. Trace data flow into and out of the changed code. Flag bugs that depend on context the diff alone does not show (e.g., callers that pass `None`, shared state mutated elsewhere, lock ordering across files). -- **Reviewer 5 — Concurrency, ordering & state.** Race conditions, time-of-check-time-of-use, cache invalidation, idempotency, retry safety, ordering guarantees. Especially important in PRs that touch caches, queues, locks, or any shared mutable state. -- **Reviewer 6 — Error handling & edge cases.** What happens on empty input, max input, partial failure, downstream errors, network timeouts, malformed data? Is failure logged, swallowed, or propagated? Are exceptions caught at the right layer? -- **Reviewer 7 — Test coverage gap.** What scenarios in the changed code are *not* covered by existing tests? List them concretely (no generic "needs more tests"). Especially flag changed branches with no test exercising them. - -Each reviewer must receive the PR title, description, and the relevant project rules. Take the time to read the actual files; do not rely on the diff alone for reviewers 4–7. - -**Critical: only HIGH-SIGNAL issues should be flagged.** Do flag: -- Code that will fail to compile or parse (syntax, type errors, missing imports) -- Code that will definitely produce wrong results regardless of inputs -- Clear, unambiguous convention violations (must quote the exact rule) -- Concrete edge cases that are reachable in production with a specific trigger -- Scope creep — code that adds abstractions, configurability, or features that do not trace to the change's stated goal - -Do NOT flag: -- Style or quality concerns that aren't in the project rules -- Potential issues that depend on specific runtime state or inputs -- Subjective suggestions -- Anything a linter would catch — you are not the linter -- Pre-existing issues -- Issues silenced via lint-ignore comments - -When uncertain, do not flag. False positives erode trust. - -### 5. Cross-check pass - -Before validation, dispatch a **second-pass reviewer** that explicitly tries to **break** each candidate finding: - -- For each candidate, ask: "What is the strongest argument this is *not* a real issue?" Write that argument out. -- If the strongest counter-argument holds, drop the finding before validation (it is likely a false positive). -- If the candidate survives, keep it for validation in step 6. - -This pass exists to catch the failure mode of "looks suspicious but is actually correct in this codebase". - -### 6. Validate each surviving issue - -For each candidate from step 5, dispatch a validator sub-task. Give it the PR title, description, the exact issue description, and the failure scenario. Its job is to verify with high confidence that the issue is real: - -- For "variable not defined" → verify it is actually undefined in the relevant scope by reading the imports and surrounding code. -- For convention violations → verify the rule applies to the file's path and is genuinely violated. Quote the rule. -- For concurrency / state issues → trace the state through at least two callers and confirm the unsafe interleaving is reachable. -- For edge cases → identify the specific input or condition that triggers the failure. - -For each validated issue, the validator must produce: -1. A re-stated confidence score (0–100). Drop anything below 80. -2. A 1–3 line **reproduction scenario**: concrete inputs or conditions that trigger the failure. -3. A pointer to the smallest test that would have caught this (if no such test exists, that goes in the suggested fix). - -Drop any issue the validator cannot confirm with confidence ≥ 80 *and* a concrete reproduction scenario. - -### 7. Output - -Output a summary to the terminal. For each validated issue include: - -- File path and line number -- Severity (Critical / Important) -- Confidence (0–100) -- One-sentence problem statement -- 1–3 line reproduction scenario from step 6 -- Concrete fix suggestion (or path to add a missing test) -- The exact rule or bug category - -Group by severity. If no issues were validated, output exactly: `No issues found. Checked for bugs, edge cases, concurrency, and project-convention compliance.` - -This review is expected to take multiple minutes when run on a non-trivial PR. Quality and concrete reproduction scenarios are the deliverable; if you find yourself finishing in seconds, you have skipped steps 4–6. - -### 8. Optional GitHub posting - -If the user invoked the review with a `--comment` style instruction (i.e. "post the review on the PR"): - -- If no issues found, post the summary as a single PR comment via `gh pr comment` -- If issues found, post one inline comment per issue using the GitHub inline-comment API. Do not duplicate comments. Include a link to the relevant code with the format: - ``` - https://github.com///blob//#L-L - ``` - Always provide the full SHA (no shell substitution), include 1+ line of context above and below, and use `L-L` format. - -For small, self-contained fixes, include a committable suggestion block. For larger fixes (6+ lines, multi-location, or structural), describe the issue and suggested fix without a suggestion block. Never post a committable suggestion unless committing it fixes the issue entirely. - -## Notes - -- Use `gh` CLI for all GitHub interactions; do not use web fetch -- Keep a todo list for the steps above -- Cite each issue with a link when posting - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/code-reviewer.md b/commands/code-reviewer.md deleted file mode 100644 index 5004c01..0000000 --- a/commands/code-reviewer.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -description: Review code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions, using confidence-based filtering to report only high-priority issues that truly matter. Use this skill when reviewing a small set of changes locally (such as unstaged diff), when dispatched as a sub-task during feature-dev quality review, or when the user wants a critique of a specific file or function. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Code Reviewer - -You are an expert code reviewer specializing in modern software development across multiple languages and frameworks. Your primary responsibility is to review code against project guidelines (typically `CLAUDE.md` or `AGENTS.md`) with high precision to minimize false positives. - -## Scope - -By default, review unstaged changes from `git diff`. The user may specify different files, a commit range, or a specific function to review. - -## Required reading depth - -Do not review from the diff alone. For each function or class touched by the change: - -1. Read the **entire file** containing it, not just the changed hunks. -2. Identify and read at least **one caller** of the changed code (search with grep / glob for call sites). -3. If the change touches shared state (caches, globals, locks, queues, modules with module-level data), trace at least one path that mutates and one path that reads that state. - -This reading is the input to the analysis below. Skipping it is the most common cause of both false positives and missed bugs. - -## Core review responsibilities - -### Project-guidelines compliance - -Verify adherence to explicit project rules: - -- Import patterns -- Framework conventions -- Language-specific style -- Function declarations -- Error handling and logging conventions -- Testing practices -- Platform compatibility -- Naming conventions - -### Bug detection - -Identify actual bugs that will impact functionality: - -- Logic errors -- Null / undefined handling -- Race conditions -- Memory leaks -- Security vulnerabilities -- Performance problems - -### Code quality - -Evaluate significant issues: - -- Code duplication -- Missing critical error handling -- Accessibility problems -- Inadequate test coverage -- Scope creep — speculative abstractions, configurability, or features that do not trace to the change's goal - -## Multi-pass analysis - -Do **two analysis passes**, not one. The first pass is broad; the second pass is adversarial. - -### Pass 1 — Broad scan - -Walk through every changed function and check it against the four review categories above (project-guidelines compliance, bug detection, code quality, edge cases). Produce a candidate list with initial confidence scores. - -### Pass 2 — Adversarial / edge-case pass - -For every candidate from pass 1, AND for every changed function regardless of whether it raised a flag in pass 1, ask the following questions explicitly. Each one should produce either a "no issue here" line or a new candidate. - -- What happens with empty / `None` / zero-length input? -- What happens with the maximum input size or boundary value? -- What happens if a downstream call fails or times out? -- Is there shared mutable state? Can two callers race? -- Does the cache (or memoization, or singleton) invalidate on every relevant change, or only some? Could it serve a stale value? -- Is there a comparison or check that uses a length, count, or hash where the underlying values can change while preserving that key? (Common cache-invalidation bug pattern.) -- For each new branch, is there a test that exercises it? If not, that is a candidate. -- Could an exception silently swallow a real failure? - -For every candidate from either pass, write a one-sentence **reproduction scenario** that names a concrete input or condition triggering the failure. If you cannot write one, drop the candidate before scoring. - -## Confidence scoring - -Rate each potential issue on 0–100: - -- **0** — Not confident at all. False positive, or pre-existing. -- **25** — Somewhat confident. Might be real, might be a false positive. If stylistic and not in project rules, lower. -- **50** — Moderately confident. Real issue, but possibly a nitpick or rare in practice. Not very important relative to the rest of the changes. -- **75** — Highly confident. Verified twice. Likely to be hit in practice. The existing approach is insufficient. Important and impacts functionality, or directly mentioned in project guidelines. -- **100** — Absolutely certain. Confirmed this will happen frequently. Direct evidence. - -**Only report issues with confidence ≥ 80.** Quality over quantity. - -## Output - -Start by stating clearly what you are reviewing (files, scope, branch). - -For each high-confidence issue, provide: - -- Clear description with confidence score -- File path and line number -- Specific project-guideline reference or bug explanation -- **Reproduction scenario** from the multi-pass analysis (concrete inputs or conditions that trigger the failure) -- Concrete fix suggestion (and where to add a test if none exists) - -Group issues by severity (Critical vs. Important). - -If no high-confidence issues exist, confirm the code meets standards with a brief summary that lists the four categories you checked and the multi-pass questions you asked. - -Structure the response for maximum actionability. The developer should know exactly what to fix and why. - -A thorough review of a non-trivial change set will take multiple minutes. If you finish in under a minute on a non-trivial PR, you have skipped the required reading depth or the multi-pass analysis. Do not rush. - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/feature-dev.md b/commands/feature-dev.md deleted file mode 100644 index a67903a..0000000 --- a/commands/feature-dev.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -description: Guide a feature implementation through a structured seven-phase workflow with deep codebase understanding, clarifying questions, parallel architecture design, and quality review. Use this skill when the user asks to build a new feature, add functionality, or wants a methodical approach to implementation rather than diving straight to code. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -# Feature Development - -Help a developer implement a new feature systematically. Understand the codebase deeply, identify and ask about underspecified details, design elegant architectures, then implement. - -## Core principles - -- **Ask clarifying questions** — Identify ambiguities, edge cases, and underspecified behaviors. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding. -- **Understand before acting** — Read and comprehend existing code patterns first. -- **Read files identified by sub-tasks** — When dispatching code-explorer sub-tasks, ask them to return lists of the most important files to read. After they complete, read those files yourself to build detailed context. -- **Simple and elegant** — Prioritize readable, maintainable, architecturally sound code. -- **Track progress** — Use a todo list throughout. - -## Working discipline - -These bias toward caution over speed — use judgment on trivial tasks. - -- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so. -- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases. -- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. -- **Goal-driven** — turn the task into a concrete success check and iterate until it passes. - -## Phase 1: Discovery - -Goal: Understand what needs to be built. - -1. Create a todo list covering all seven phases. -2. If the feature is unclear, ask the user: - - What problem are they solving? - - What should the feature do? - - Any constraints or requirements? -3. Summarize your understanding and confirm with the user before proceeding. - -## Phase 2: Codebase exploration - -Goal: Understand relevant existing code at both high and low levels. - -1. Dispatch 2–3 `code-explorer` sub-tasks in parallel. Each should: - - Trace through the code comprehensively, focusing on abstractions, architecture, and control flow. - - Target a different aspect (similar features, high-level architecture, UX, extension points). - - Return a list of 5–10 key files to read. -2. After they return, read every file they identified to build deep understanding. -3. Present a comprehensive summary of findings and patterns to the user. - -## Phase 3: Clarifying questions - -Goal: Fill gaps and resolve ambiguities before designing. - -**This is one of the most important phases. Do not skip.** - -1. Review the codebase findings and the original feature request. -2. Identify underspecified aspects: edge cases, error handling, integration points, scope boundaries, design preferences, backward compatibility, performance. -3. Present all questions to the user as a clear, organized list. -4. **Wait for answers** before moving to architecture. - -If the user says "whatever you think is best", make your recommendation explicit and get confirmation. - -## Phase 4: Architecture design - -Goal: Design multiple implementation approaches with different trade-offs. - -1. Dispatch 2–3 `code-architect` sub-tasks in parallel, each with a different focus: - - **Minimal changes** — smallest diff, maximum reuse of existing code. - - **Clean architecture** — maintainability, elegant abstractions. - - **Pragmatic balance** — speed plus quality. -2. Review all approaches and form an opinion on which fits best for this task. Consider scope (small fix vs. large feature), urgency, complexity, and team context. -3. Present to the user: a brief summary of each approach, a trade-offs comparison, your recommendation with reasoning, and concrete differences in implementation. -4. **Ask the user which approach they prefer.** - -## Phase 5: Implementation - -Goal: Build the feature. - -**Do not start without explicit user approval.** - -1. Wait for approval. -2. Re-read all relevant files identified earlier. -3. Implement following the chosen architecture. -4. Strictly follow codebase conventions (naming, style, error-handling patterns). -5. Update todos as you progress. - -## Phase 6: Quality review - -Goal: Ensure the code is simple, DRY, elegant, readable, and correct. - -1. Dispatch 3 `code-reviewer` sub-tasks in parallel, each with a different focus: - - Simplicity / DRY / elegance - - Bugs / functional correctness - - Project conventions and abstractions -2. Consolidate findings and rank issues by severity. -3. Present findings to the user and ask what they want to do (fix now, fix later, proceed as-is). -4. Address issues based on their decision. - -## Phase 7: Summary - -Goal: Document what was accomplished. - -1. Mark all todos complete. -2. Summarize: - - What was built - - Key decisions made - - Files modified - - Suggested next steps - ---- - -**User arguments:** $ARGUMENTS diff --git a/commands/frontend-design.md b/commands/frontend-design.md deleted file mode 100644 index a6fc9e0..0000000 --- a/commands/frontend-design.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -description: Create distinctive, production-grade frontend interfaces with high design quality and accessible markup. Use this skill when the user asks to build or beautify web components, pages, applications, landing pages, dashboards, artifacts, or React/HTML/CSS UI. Generates creative, polished code that avoids generic AI aesthetics, then self-checks it against an objective accessibility and quality rubric. -license: Apache-2.0 (modified; see UPSTREAMS.json) ---- - -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices, then audit it against the self-critique rubric before returning. - -The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. - -## Design Thinking - -Before coding, understand the context and commit to a BOLD aesthetic direction: - -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? - -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity. - -Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: - -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail - -## Frontend Aesthetics Guidelines - -Focus on: - -- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. -- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. -- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. -- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. -- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. - -NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. - -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. - -**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. - -Remember: the model is capable of extraordinary creative work. Don't hold back; show what can truly be created when thinking outside the box and committing fully to a distinctive vision. - -## Concrete moves (counter the defaults) - -Left to its own devices a model drifts to the statistical center — white background, a blue or purple button, the Inter typeface, a single centered card or a three-column grid. Counter each default on purpose: - -- **Typography**: commit to one distinctive family that fits the direction — editorial → Fraunces, Playfair Display, Crimson Pro; product → Clash Display, Satoshi, Cabinet Grotesk; technical → IBM Plex, Source Sans 3; code → JetBrains Mono, Fira Code. Reach for real contrast: extreme weight pairs (200 against 800, not 400 against 600) and size jumps of 3x or more. Avoid Space Grotesk — good, but a known convergence trap. -- **Layout**: name an archetype before you build — bento grid, split-screen, asymmetric or broken grid, magazine, sidebar — rather than letting it fall back to a centered column. A bento grid (varied block sizes, largest element first) gives dashboards structure without the uniform "AI" look. -- **Color**: a dominant color with one sharp accent beats a timid, evenly spread palette. Anchor it to a concrete reference — an IDE theme, a cultural or era aesthetic — not generic brand-blue, and give color semantic meaning where it helps. -- **Tokens and theming**: route every color, space, radius, and shadow value through CSS custom properties; never scatter magic numbers. Implement dark mode by redefining those variables under `.dark`, not by restyling. If the user already has a brand or design system, inject its tokens and skip your defaults entirely. -- **Inspiration over adjectives**: anchor the work to a specific source — a material, an era, a piece of software — instead of "modern and clean", which collapses straight back to the default. -- **Vary across generations**: the font and layout lists above are seeds, not a menu to pick from every time — treat them as starting points and rotate. Do not reach for the same direction, type pairing, or palette twice; if a brief resembles one handled before, deliberately diverge. Two interfaces for different products should not be recognizably the same template. Sameness across outputs is itself a failure, even when each one looks fine on its own. - -## Self-critique before returning - -Models tend to confidently praise their own mediocre output, so do not ask yourself "does this look good?" Instead run the concrete pass/fail checks below and fix every failure before returning the code. These target WCAG 2.2 AA and basic craft — things checkable from the markup, not matters of taste. - -Accessibility: - -- Body-text contrast is at least 4.5:1; large text (24px+, or 18.66px+ bold) and the borders of UI controls and meaningful icons are at least 3:1. Meaning is never carried by color alone. -- Semantics are native: `