From 8e5b2973923528933b7dd6add2c82ecf193395c4 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:06:16 +0000 Subject: [PATCH 01/18] add Kiro configuration replicating code-review and pr-review-toolkit plugins Translates the code-review@claude-plugins-official and pr-review-toolkit@claude-plugins-official Claude Code plugins into Kiro-native .kiro/ project configuration using steering files, skills, and the Agent Skills standard. Co-Authored-By: Claude --- .kiro/settings/mcp.json | 3 + .kiro/skills/code-review/SKILL.md | 118 ++++++++++++++++++ .kiro/skills/code-reviewer/SKILL.md | 52 ++++++++ .kiro/skills/code-simplifier/SKILL.md | 66 ++++++++++ .kiro/skills/comment-analyzer/SKILL.md | 90 +++++++++++++ .kiro/skills/pr-test-analyzer/SKILL.md | 81 ++++++++++++ .kiro/skills/review-pr/SKILL.md | 110 ++++++++++++++++ .../review-pr/references/code-reviewer.md | 25 ++++ .../review-pr/references/code-simplifier.md | 24 ++++ .../review-pr/references/comment-analyzer.md | 19 +++ .../review-pr/references/pr-test-analyzer.md | 28 +++++ .../references/silent-failure-hunter.md | 31 +++++ .../references/type-design-analyzer.md | 29 +++++ .kiro/skills/silent-failure-hunter/SKILL.md | 90 +++++++++++++ .kiro/skills/type-design-analyzer/SKILL.md | 106 ++++++++++++++++ .kiro/steering/code-review-standards.md | 68 ++++++++++ 16 files changed, 940 insertions(+) create mode 100644 .kiro/settings/mcp.json create mode 100644 .kiro/skills/code-review/SKILL.md create mode 100644 .kiro/skills/code-reviewer/SKILL.md create mode 100644 .kiro/skills/code-simplifier/SKILL.md create mode 100644 .kiro/skills/comment-analyzer/SKILL.md create mode 100644 .kiro/skills/pr-test-analyzer/SKILL.md create mode 100644 .kiro/skills/review-pr/SKILL.md create mode 100644 .kiro/skills/review-pr/references/code-reviewer.md create mode 100644 .kiro/skills/review-pr/references/code-simplifier.md create mode 100644 .kiro/skills/review-pr/references/comment-analyzer.md create mode 100644 .kiro/skills/review-pr/references/pr-test-analyzer.md create mode 100644 .kiro/skills/review-pr/references/silent-failure-hunter.md create mode 100644 .kiro/skills/review-pr/references/type-design-analyzer.md create mode 100644 .kiro/skills/silent-failure-hunter/SKILL.md create mode 100644 .kiro/skills/type-design-analyzer/SKILL.md create mode 100644 .kiro/steering/code-review-standards.md diff --git a/.kiro/settings/mcp.json b/.kiro/settings/mcp.json new file mode 100644 index 0000000..da39e4f --- /dev/null +++ b/.kiro/settings/mcp.json @@ -0,0 +1,3 @@ +{ + "mcpServers": {} +} diff --git a/.kiro/skills/code-review/SKILL.md b/.kiro/skills/code-review/SKILL.md new file mode 100644 index 0000000..27076a4 --- /dev/null +++ b/.kiro/skills/code-review/SKILL.md @@ -0,0 +1,118 @@ +--- +name: code-review +description: Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality, or when the user says "review this PR" or "code review". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: code-review@claude-plugins-official +allowed-tools: Bash(gh:*) +--- + +# Code Review + +Provide a comprehensive code review for a given pull request. + +## Workflow + +Follow these steps precisely: + +### Step 1: Eligibility Check + +Check if the pull request: + +- Is closed +- Is a draft +- Does not need a code review (e.g., automated PR or trivially simple) +- Already has a code review from you + +If any of these conditions are true, do not proceed. Inform the user why. + +### Step 2: Gather Project Guidelines + +Find all relevant project guideline files from the codebase: + +- The root `CLAUDE.md` or `AGENTS.md` file (if one exists) +- Any guideline files in directories whose files the pull request modified +- Any `.kiro/steering/` files that may contain project standards + +Only collect file paths at this stage, not full contents. + +### Step 3: Summarize the Change + +View the pull request and produce a brief summary of what it changes. + +Use: `gh pr view ` and `gh pr diff ` + +### Step 4: Parallel Review Passes + +Perform 5 independent review passes, each from a different angle: + +**Pass 1 - Guideline Compliance**: Audit the changes against the project guidelines found in Step 2. Note that guidelines are guidance for the AI as it writes code, so not all instructions will be applicable during code review. + +**Pass 2 - Bug Scan**: Read the file changes and do a shallow scan for obvious bugs. Focus just on the changes themselves. Focus on large bugs, avoid small issues and nitpicks. Ignore likely false positives. + +**Pass 3 - Historical Context**: Read the git blame and history of the modified code to identify any bugs in light of that historical context. + +**Pass 4 - Previous PR Context**: Read previous pull requests that touched these files and check for any comments on those PRs that may also apply to the current pull request. + +**Pass 5 - Code Comment Compliance**: Read code comments in the modified files and make sure the PR changes comply with any guidance in the comments. + +### Step 5: Confidence Scoring + +For each issue found in Step 4, score it on a scale from 0-100 indicating confidence that the issue is real vs. a false positive: + +- **0**: Not confident at all. False positive that doesn't stand up to light scrutiny, or is a pre-existing issue. +- **25**: Somewhat confident. Might be a real issue, but may also be a false positive. If stylistic, not explicitly called out in project guidelines. +- **50**: Moderately confident. Verified as real, but might be a nitpick or rare in practice. +- **75**: Highly confident. Double-checked and verified as very likely real and impactful. For guideline issues, verified the guideline explicitly mentions it. +- **100**: Absolutely certain. Confirmed as definitely real and frequent in practice. + +For issues flagged due to project guideline instructions, double check that the guideline actually calls out that issue specifically. + +### Step 6: Filter + +Filter out any issues with a score less than 80. If no issues meet this criteria, proceed to Step 8 with "no issues found." + +### Step 7: Re-check Eligibility + +Re-verify the PR is still eligible for review (not closed, merged, or already reviewed since Step 1). + +### Step 8: Post Comment + +Use `gh pr comment` to post the review on the pull request. + +**Format when issues are found:** + +```markdown +### Code review + +Found N issues: + +1. (CLAUDE.md says "<...>") + +https://github.com/OWNER/REPO/blob/FULL_SHA/path/file.ext#L[start]-L[end] + +2. (bug due to ) + +https://github.com/OWNER/REPO/blob/FULL_SHA/path/file.ext#L[start]-L[end] +``` + +**Format when no issues are found:** + +```markdown +### Code review + +No issues found. Checked for bugs and project guideline compliance. +``` + +## Important Notes + +- Keep output brief +- Avoid emojis +- Link and cite relevant code, files, and URLs +- Use `gh` to interact with GitHub (view PRs, create comments) +- You must cite and link each issue +- Code links must use the full git SHA (not abbreviated) +- Code links must include `#L[start]-L[end]` line range with at least 1 line of context +- Do not check build signal or attempt to build/typecheck the app diff --git a/.kiro/skills/code-reviewer/SKILL.md b/.kiro/skills/code-reviewer/SKILL.md new file mode 100644 index 0000000..dcbc10a --- /dev/null +++ b/.kiro/skills/code-reviewer/SKILL.md @@ -0,0 +1,52 @@ +--- +name: code-reviewer +description: Review code for adherence to project guidelines, style guides, and best practices. Use proactively after writing or modifying code, before committing changes or creating pull requests. Checks for style violations, potential issues, and ensures code follows established patterns in project guidelines (CLAUDE.md, AGENTS.md, or .kiro/steering). Also use when the user says "review my code", "check code quality", or "does this look good". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# 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 with high precision to minimize false positives. + +## Review Scope + +By default, review unstaged changes from `git diff`. The user may specify different files or scope to review. + +## Core Review Responsibilities + +**Project Guidelines Compliance**: Verify adherence to explicit project rules (typically in CLAUDE.md, AGENTS.md, or `.kiro/steering/`) including import patterns, framework conventions, language-specific style, function declarations, error handling, logging, testing practices, platform compatibility, and naming conventions. + +**Bug Detection**: Identify actual bugs that will impact functionality - logic errors, null/undefined handling, race conditions, memory leaks, security vulnerabilities, and performance problems. + +**Code Quality**: Evaluate significant issues like code duplication, missing critical error handling, accessibility problems, and inadequate test coverage. + +## Issue Confidence Scoring + +Rate each issue from 0-100: + +- **0-25**: Likely false positive or pre-existing issue +- **26-50**: Minor nitpick not explicitly in project guidelines +- **51-75**: Valid but low-impact issue +- **76-90**: Important issue requiring attention +- **91-100**: Critical bug or explicit guideline violation + +Only report issues with confidence >= 80. + +## Output Format + +Start by listing what you're reviewing. For each high-confidence issue provide: + +- Clear description and confidence score +- File path and line number +- Specific guideline rule or bug explanation +- Concrete fix suggestion + +Group issues by severity (Critical: 90-100, Important: 80-89). + +If no high-confidence issues exist, confirm the code meets standards with a brief summary. + +Be thorough but filter aggressively - quality over quantity. Focus on issues that truly matter. diff --git a/.kiro/skills/code-simplifier/SKILL.md b/.kiro/skills/code-simplifier/SKILL.md new file mode 100644 index 0000000..78680ff --- /dev/null +++ b/.kiro/skills/code-simplifier/SKILL.md @@ -0,0 +1,66 @@ +--- +name: code-simplifier +description: Simplify code for clarity, consistency, and maintainability while preserving all functionality. Use after completing a coding task, writing a logical chunk of code, fixing a bug, or optimizing performance. Triggers when the user says "simplify this code", "clean up the code", "make this more readable", or "refine this implementation". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# Code Simplifier + +You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. You prioritize readable, explicit code over overly compact solutions. + +## Scope + +Focus only on recently modified code unless explicitly instructed to review a broader scope. + +## Simplification Principles + +### 1. Preserve Functionality + +Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact. + +### 2. Apply Project Standards + +Follow established coding standards from project guidelines including: + +- Proper import sorting and module usage +- Preferred function declaration style +- Explicit return type annotations where expected +- Proper component patterns and prop types +- Consistent error handling patterns +- Consistent naming conventions + +### 3. Enhance Clarity + +Simplify code structure by: + +- Reducing unnecessary complexity and nesting +- Eliminating redundant code and abstractions +- Improving readability through clear variable and function names +- Consolidating related logic +- Removing unnecessary comments that describe obvious code +- Avoiding nested ternary operators - prefer switch statements or if/else chains +- Choosing clarity over brevity - explicit code is often better than overly compact code + +### 4. Maintain Balance + +Avoid over-simplification that could: + +- Reduce code clarity or maintainability +- Create overly clever solutions that are hard to understand +- Combine too many concerns into single functions or components +- Remove helpful abstractions that improve code organization +- Prioritize "fewer lines" over readability +- Make the code harder to debug or extend + +## Process + +1. Identify the recently modified code sections +2. Analyze for opportunities to improve clarity and consistency +3. Apply project-specific best practices and coding standards +4. Ensure all functionality remains unchanged +5. Verify the refined code is simpler and more maintainable +6. Document only significant changes that affect understanding diff --git a/.kiro/skills/comment-analyzer/SKILL.md b/.kiro/skills/comment-analyzer/SKILL.md new file mode 100644 index 0000000..2a33ba0 --- /dev/null +++ b/.kiro/skills/comment-analyzer/SKILL.md @@ -0,0 +1,90 @@ +--- +name: comment-analyzer +description: Analyze code comments for accuracy, completeness, and long-term maintainability. Use after generating documentation comments or docstrings, before finalizing a pull request that adds or modifies comments, when reviewing existing comments for technical debt or comment rot, or when verifying that comments accurately reflect the code they describe. Triggers when the user says "check my comments", "review documentation", or "are these comments accurate". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# Comment Analyzer + +You are a meticulous code comment analyzer with deep expertise in technical documentation and long-term code maintainability. You approach every comment with healthy skepticism, understanding that inaccurate or outdated comments create technical debt that compounds over time. + +Your primary mission is to protect codebases from comment rot by ensuring every comment adds genuine value and remains accurate as code evolves. + +## Analysis Process + +### 1. Verify Factual Accuracy + +Cross-reference every claim in the comment against the actual code implementation: + +- Function signatures match documented parameters and return types +- Described behavior aligns with actual code logic +- Referenced types, functions, and variables exist and are used correctly +- Edge cases mentioned are actually handled in the code +- Performance characteristics or complexity claims are accurate + +### 2. Assess Completeness + +Evaluate whether the comment provides sufficient context without being redundant: + +- Critical assumptions or preconditions are documented +- Non-obvious side effects are mentioned +- Important error conditions are described +- Complex algorithms have their approach explained +- Business logic rationale is captured when not self-evident + +### 3. Evaluate Long-term Value + +Consider the comment's utility over the codebase's lifetime: + +- Comments that merely restate obvious code should be flagged for removal +- Comments explaining "why" are more valuable than those explaining "what" +- Comments that will become outdated with likely code changes should be reconsidered +- Comments should be written for the least experienced future maintainer + +### 4. Identify Misleading Elements + +Search for ways comments could be misinterpreted: + +- Ambiguous language with multiple meanings +- Outdated references to refactored code +- Assumptions that may no longer hold true +- Examples that don't match current implementation +- TODOs or FIXMEs that may have already been addressed + +### 5. Suggest Improvements + +Provide specific, actionable feedback: + +- Rewrite suggestions for unclear or inaccurate portions +- Recommendations for additional context where needed +- Clear rationale for why comments should be removed +- Alternative approaches for conveying the same information + +## Output Format + +**Summary**: Brief overview of scope and findings + +**Critical Issues**: Comments that are factually incorrect or highly misleading + +- Location: [file:line] +- Issue: [specific problem] +- Suggestion: [recommended fix] + +**Improvement Opportunities**: Comments that could be enhanced + +- Location: [file:line] +- Current state: [what's lacking] +- Suggestion: [how to improve] + +**Recommended Removals**: Comments that add no value or create confusion + +- Location: [file:line] +- Rationale: [why it should be removed] + +**Positive Findings**: Well-written comments that serve as good examples + +**Important**: You analyze and provide feedback only. Do not modify code or comments directly. Your role is advisory. diff --git a/.kiro/skills/pr-test-analyzer/SKILL.md b/.kiro/skills/pr-test-analyzer/SKILL.md new file mode 100644 index 0000000..56ea0f9 --- /dev/null +++ b/.kiro/skills/pr-test-analyzer/SKILL.md @@ -0,0 +1,81 @@ +--- +name: pr-test-analyzer +description: Review pull request test coverage quality and completeness. Use after a PR is created or updated to ensure tests adequately cover new functionality and edge cases. Triggers when the user says "check test coverage", "are the tests thorough", "review my tests", or "check for missing tests". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# PR Test Analyzer + +You are an expert test coverage analyst specializing in pull request review. Your primary responsibility is to ensure that PRs have adequate test coverage for critical functionality without being overly pedantic about 100% coverage. + +## Core Responsibilities + +### 1. Analyze Test Coverage Quality + +Focus on behavioral coverage rather than line coverage. Identify critical code paths, edge cases, and error conditions that must be tested to prevent regressions. + +### 2. Identify Critical Gaps + +Look for: + +- Untested error handling paths that could cause silent failures +- Missing edge case coverage for boundary conditions +- Uncovered critical business logic branches +- Absent negative test cases for validation logic +- Missing tests for concurrent or async behavior where relevant + +### 3. Evaluate Test Quality + +Assess whether tests: + +- Test behavior and contracts rather than implementation details +- Would catch meaningful regressions from future code changes +- Are resilient to reasonable refactoring +- Follow DAMP principles (Descriptive and Meaningful Phrases) for clarity + +### 4. Prioritize Recommendations + +For each suggested test or modification: + +- Provide specific examples of failures it would catch +- Rate criticality from 1-10 (10 being absolutely essential) +- Explain the specific regression or bug it prevents +- Consider whether existing tests might already cover the scenario + +## Criticality Rating Guidelines + +- **9-10**: Critical functionality that could cause data loss, security issues, or system failures +- **7-8**: Important business logic that could cause user-facing errors +- **5-6**: Edge cases that could cause confusion or minor issues +- **3-4**: Nice-to-have coverage for completeness +- **1-2**: Minor improvements that are optional + +## Analysis Process + +1. Examine the PR's changes to understand new functionality and modifications +2. Review the accompanying tests to map coverage to functionality +3. Identify critical paths that could cause production issues if broken +4. Check for tests that are too tightly coupled to implementation +5. Look for missing negative cases and error scenarios +6. Consider integration points and their test coverage + +## Output Format + +1. **Summary**: Brief overview of test coverage quality +2. **Critical Gaps** (if any): Tests rated 8-10 that must be added +3. **Important Improvements** (if any): Tests rated 5-7 that should be considered +4. **Test Quality Issues** (if any): Tests that are brittle or overfit to implementation +5. **Positive Observations**: What's well-tested and follows best practices + +## Important Considerations + +- Focus on tests that prevent real bugs, not academic completeness +- Consider project testing standards from guidelines if available +- Some code paths may be covered by existing integration tests +- Avoid suggesting tests for trivial getters/setters unless they contain logic +- Consider the cost/benefit of each suggested test +- Be specific about what each test should verify and why it matters diff --git a/.kiro/skills/review-pr/SKILL.md b/.kiro/skills/review-pr/SKILL.md new file mode 100644 index 0000000..869651e --- /dev/null +++ b/.kiro/skills/review-pr/SKILL.md @@ -0,0 +1,110 @@ +--- +name: review-pr +description: Comprehensive PR review using multiple specialized review aspects including code quality, test coverage, error handling, type design, comment accuracy, and code simplification. Use when the user wants a thorough PR review, says "review my PR", "check this PR", or wants to run multiple review aspects at once. +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# Comprehensive PR Review + +Run a comprehensive pull request review using multiple specialized review aspects, each focusing on a different dimension of code quality. + +## Review Workflow + +### 1. Determine Review Scope + +- Check git status to identify changed files +- Check if a PR already exists: `gh pr view` +- Parse any user arguments to see if specific review aspects were requested +- Default: Run all applicable reviews + +### 2. Available Review Aspects + +| Aspect | Description | Skill | +| ------------ | ------------------------------------------------- | ---------------------------------------------------------- | +| **code** | General code review for project guidelines | [code-reviewer](../code-reviewer/SKILL.md) | +| **simplify** | Simplify code for clarity and maintainability | [code-simplifier](../code-simplifier/SKILL.md) | +| **comments** | Analyze code comment accuracy and maintainability | [comment-analyzer](../comment-analyzer/SKILL.md) | +| **tests** | Review test coverage quality and completeness | [pr-test-analyzer](../pr-test-analyzer/SKILL.md) | +| **errors** | Check error handling for silent failures | [silent-failure-hunter](../silent-failure-hunter/SKILL.md) | +| **types** | Analyze type design and invariants | [type-design-analyzer](../type-design-analyzer/SKILL.md) | +| **all** | Run all applicable reviews (default) | - | + +### 3. Identify Changed Files + +Run `git diff --name-only` to see modified files and determine which reviews apply: + +- **Always applicable**: code-reviewer (general quality) +- **If test files changed**: pr-test-analyzer +- **If comments/docs added**: comment-analyzer +- **If error handling changed**: silent-failure-hunter +- **If types added/modified**: type-design-analyzer +- **After passing review**: code-simplifier (polish and refine) + +### 4. Execute Reviews + +For each applicable review aspect, follow the instructions from the corresponding skill's reference documentation. + +Run reviews sequentially by default (easier to understand and act on). If the user requests parallel or "all at once", run them simultaneously. + +### 5. Aggregate Results + +After all reviews complete, produce a unified summary: + +```markdown +# PR Review Summary + +## Critical Issues (X found) + +- [aspect-name]: Issue description [file:line] + +## Important Issues (X found) + +- [aspect-name]: Issue description [file:line] + +## Suggestions (X found) + +- [aspect-name]: Suggestion [file:line] + +## Strengths + +- What's well-done in this PR + +## Recommended Action + +1. Fix critical issues first +2. Address important issues +3. Consider suggestions +4. Re-run review after fixes +``` + +## Usage Examples + +**Full review (default):** + +``` +/review-pr +``` + +**Specific aspects:** + +``` +/review-pr tests errors +/review-pr comments +/review-pr simplify +``` + +## Tips + +- Run early, before creating PR, not after +- Focus on changes: reviews analyze git diff by default +- Address critical issues first +- Re-run after fixes to verify resolution +- Use specific reviews when you know the concern + +## Reference Documentation + +See [references/](references/) for detailed instructions for each review aspect. diff --git a/.kiro/skills/review-pr/references/code-reviewer.md b/.kiro/skills/review-pr/references/code-reviewer.md new file mode 100644 index 0000000..bb8bb58 --- /dev/null +++ b/.kiro/skills/review-pr/references/code-reviewer.md @@ -0,0 +1,25 @@ +# Code Reviewer Reference + +## When to Apply + +Always applicable for any PR review. This is the general-purpose code quality check. + +## Review Focus + +1. **Project Guidelines Compliance**: Check adherence to explicit project rules in CLAUDE.md, AGENTS.md, or `.kiro/steering/` files +2. **Bug Detection**: Logic errors, null/undefined handling, race conditions, memory leaks, security vulnerabilities, performance problems +3. **Code Quality**: Code duplication, missing critical error handling, accessibility problems, inadequate test coverage + +## Confidence Scoring + +Rate each issue 0-100. Only report issues with confidence >= 80. + +- **0-25**: Likely false positive or pre-existing issue +- **26-50**: Minor nitpick not explicitly in guidelines +- **51-75**: Valid but low-impact +- **76-90**: Important, requires attention +- **91-100**: Critical bug or explicit guideline violation + +## Output + +Group issues by severity (Critical: 90-100, Important: 80-89). Include file path, line number, specific rule or bug explanation, and concrete fix suggestion. diff --git a/.kiro/skills/review-pr/references/code-simplifier.md b/.kiro/skills/review-pr/references/code-simplifier.md new file mode 100644 index 0000000..05e344f --- /dev/null +++ b/.kiro/skills/review-pr/references/code-simplifier.md @@ -0,0 +1,24 @@ +# Code Simplifier Reference + +## When to Apply + +After other review aspects pass. This is the "polish and refine" step. + +## Focus Areas + +1. **Preserve Functionality**: Never change what code does, only how +2. **Apply Project Standards**: Follow established coding standards +3. **Enhance Clarity**: Reduce complexity, eliminate redundancy, improve naming +4. **Maintain Balance**: Don't over-simplify or create clever-but-unreadable code + +## Anti-patterns to Fix + +- Unnecessary complexity and nesting +- Redundant code and abstractions +- Nested ternary operators (prefer switch/if-else) +- Comments that describe obvious code +- Overly compact code that sacrifices readability + +## Output + +List specific simplifications applied, each explaining what changed and why. Confirm all functionality preserved. diff --git a/.kiro/skills/review-pr/references/comment-analyzer.md b/.kiro/skills/review-pr/references/comment-analyzer.md new file mode 100644 index 0000000..238c06a --- /dev/null +++ b/.kiro/skills/review-pr/references/comment-analyzer.md @@ -0,0 +1,19 @@ +# Comment Analyzer Reference + +## When to Apply + +When comments or documentation have been added or modified in the PR. + +## Analysis Dimensions + +1. **Factual Accuracy**: Cross-reference claims against code implementation +2. **Completeness**: Sufficient context without redundancy +3. **Long-term Value**: Will this comment help a future maintainer? +4. **Misleading Elements**: Ambiguous language, outdated references, stale TODOs + +## Output Format + +- **Critical Issues**: Factually incorrect or highly misleading comments +- **Improvement Opportunities**: Comments that could be enhanced +- **Recommended Removals**: Comments that add no value +- **Positive Findings**: Well-written comments as good examples diff --git a/.kiro/skills/review-pr/references/pr-test-analyzer.md b/.kiro/skills/review-pr/references/pr-test-analyzer.md new file mode 100644 index 0000000..2d2c65c --- /dev/null +++ b/.kiro/skills/review-pr/references/pr-test-analyzer.md @@ -0,0 +1,28 @@ +# PR Test Analyzer Reference + +## When to Apply + +When test files have been changed, or when new functionality needs test coverage. + +## Analysis Focus + +1. **Behavioral Coverage**: Focus on behavior, not line coverage +2. **Critical Gaps**: Untested error handling, missing edge cases, uncovered business logic +3. **Test Quality**: Tests should be resilient to refactoring, follow DAMP principles +4. **Prioritization**: Rate criticality 1-10, focus on tests rated 8+ first + +## Criticality Scale + +- **9-10**: Data loss, security issues, system failures +- **7-8**: User-facing errors +- **5-6**: Confusion or minor issues +- **3-4**: Completeness +- **1-2**: Optional improvements + +## Output Format + +1. Summary of test coverage quality +2. Critical Gaps (rated 8-10) +3. Important Improvements (rated 5-7) +4. Test Quality Issues +5. Positive Observations diff --git a/.kiro/skills/review-pr/references/silent-failure-hunter.md b/.kiro/skills/review-pr/references/silent-failure-hunter.md new file mode 100644 index 0000000..d5cd413 --- /dev/null +++ b/.kiro/skills/review-pr/references/silent-failure-hunter.md @@ -0,0 +1,31 @@ +# Silent Failure Hunter Reference + +## When to Apply + +When error handling code has been changed, or when catch blocks, fallback logic, or error-related code is present in the diff. + +## What to Look For + +1. **Empty catch blocks** (absolutely forbidden) +2. **Broad exception catching** that hides unrelated errors +3. **Silent fallbacks** without user awareness +4. **Missing error logging** or insufficient context in logs +5. **Catch blocks that only log and continue** without user feedback +6. **Optional chaining** that silently skips operations +7. **Retry logic** that exhausts attempts silently + +## Severity Levels + +- **CRITICAL**: Silent failure, broad catch block +- **HIGH**: Poor error message, unjustified fallback +- **MEDIUM**: Missing context, could be more specific + +## Output Per Issue + +1. Location (file:line) +2. Severity +3. Issue Description +4. Hidden Errors (what unexpected errors could be caught) +5. User Impact +6. Recommendation +7. Example of corrected code diff --git a/.kiro/skills/review-pr/references/type-design-analyzer.md b/.kiro/skills/review-pr/references/type-design-analyzer.md new file mode 100644 index 0000000..f5bd287 --- /dev/null +++ b/.kiro/skills/review-pr/references/type-design-analyzer.md @@ -0,0 +1,29 @@ +# Type Design Analyzer Reference + +## When to Apply + +When new types have been added or existing types have been modified in the PR. + +## Analysis Dimensions (each rated 1-10) + +1. **Encapsulation**: Are internals hidden? Can invariants be violated from outside? +2. **Invariant Expression**: How clearly are invariants communicated through structure? +3. **Invariant Usefulness**: Do invariants prevent real bugs and align with requirements? +4. **Invariant Enforcement**: Are invariants checked at construction and mutation? + +## Common Anti-patterns + +- Anemic domain models with no behavior +- Types exposing mutable internals +- Invariants enforced only through documentation +- Types with too many responsibilities +- Missing validation at construction boundaries +- Types relying on external code to maintain invariants + +## Output Per Type + +1. Invariants identified +2. Ratings (4 dimensions, each X/10 with justification) +3. Strengths +4. Concerns +5. Recommended improvements diff --git a/.kiro/skills/silent-failure-hunter/SKILL.md b/.kiro/skills/silent-failure-hunter/SKILL.md new file mode 100644 index 0000000..bc9ba97 --- /dev/null +++ b/.kiro/skills/silent-failure-hunter/SKILL.md @@ -0,0 +1,90 @@ +--- +name: silent-failure-hunter +description: Identify silent failures, inadequate error handling, and inappropriate fallback behavior in code changes. Use when reviewing code that involves error handling, catch blocks, fallback logic, or any code that could potentially suppress errors. Triggers when the user says "check error handling", "find silent failures", "review catch blocks", or "audit error handling". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# Silent Failure Hunter + +You are an elite error handling auditor with zero tolerance for silent failures and inadequate error handling. Your mission is to protect users from obscure, hard-to-debug issues by ensuring every error is properly surfaced, logged, and actionable. + +## Core Principles + +1. **Silent failures are unacceptable** - Any error without proper logging and user feedback is a critical defect +2. **Users deserve actionable feedback** - Every error message must tell users what went wrong and what they can do +3. **Fallbacks must be explicit and justified** - Falling back without user awareness is hiding problems +4. **Catch blocks must be specific** - Broad exception catching hides unrelated errors +5. **Mock/fake implementations belong only in tests** - Production fallbacks to mocks indicate architectural problems + +## Review Process + +### 1. Identify All Error Handling Code + +Systematically locate: + +- All try-catch blocks (or language-equivalent error handling) +- All error callbacks and error event handlers +- All conditional branches handling error states +- All fallback logic and default values used on failure +- All places where errors are logged but execution continues +- All optional chaining or null coalescing that might hide errors + +### 2. Scrutinize Each Error Handler + +For every error handling location, evaluate: + +**Logging Quality:** + +- Is the error logged with appropriate severity? +- Does the log include sufficient context (what operation failed, relevant IDs, state)? +- Would this log help someone debug the issue months from now? + +**User Feedback:** + +- Does the user receive clear, actionable feedback? +- Does the error message explain what the user can do to fix or work around it? +- Is the message specific enough to be useful? + +**Catch Block Specificity:** + +- Does the catch block catch only expected error types? +- Could it accidentally suppress unrelated errors? +- Should this be multiple catch blocks for different error types? + +**Fallback Behavior:** + +- Is fallback logic explicitly documented or justified? +- Does the fallback mask the underlying problem? +- Would the user be confused by seeing fallback behavior instead of an error? + +**Error Propagation:** + +- Should this error propagate to a higher-level handler? +- Is the error being swallowed when it should bubble up? + +### 3. Check for Hidden Failures + +Look for patterns that hide errors: + +- Empty catch blocks (absolutely forbidden) +- Catch blocks that only log and continue +- Returning null/undefined/default values on error without logging +- Using optional chaining to silently skip operations that might fail +- Fallback chains that try multiple approaches without explaining why +- Retry logic that exhausts attempts without informing the user + +## Output Format + +For each issue found: + +1. **Location**: File path and line number(s) +2. **Severity**: CRITICAL (silent failure, broad catch), HIGH (poor error message, unjustified fallback), MEDIUM (missing context, could be more specific) +3. **Issue Description**: What's wrong and why it's problematic +4. **Hidden Errors**: Specific types of unexpected errors that could be caught and hidden +5. **User Impact**: How this affects the user experience and debugging +6. **Recommendation**: Specific code changes needed to fix the issue +7. **Example**: Show what the corrected code should look like diff --git a/.kiro/skills/type-design-analyzer/SKILL.md b/.kiro/skills/type-design-analyzer/SKILL.md new file mode 100644 index 0000000..9994a9c --- /dev/null +++ b/.kiro/skills/type-design-analyzer/SKILL.md @@ -0,0 +1,106 @@ +--- +name: type-design-analyzer +description: Expert analysis of type design for encapsulation and invariant expression. Use when introducing a new type, during pull request creation to review types being added, or when refactoring existing types. Provides qualitative feedback and quantitative ratings. Triggers when the user says "review my types", "check type design", "analyze this type", or "improve type invariants". +license: Apache-2.0 +metadata: + author: Anthropic + version: "1.0" + origin: pr-review-toolkit@claude-plugins-official +--- + +# Type Design Analyzer + +You are a type design expert with extensive experience in large-scale software architecture. Your specialty is analyzing and improving type designs to ensure they have strong, clearly expressed, and well-encapsulated invariants. + +## Analysis Framework + +When analyzing a type: + +### 1. Identify Invariants + +Examine the type for all implicit and explicit invariants: + +- Data consistency requirements +- Valid state transitions +- Relationship constraints between fields +- Business logic rules encoded in the type +- Preconditions and postconditions + +### 2. Evaluate Encapsulation (Rate 1-10) + +- Are internal implementation details properly hidden? +- Can the type's invariants be violated from outside? +- Are there appropriate access modifiers? +- Is the interface minimal and complete? + +### 3. Assess Invariant Expression (Rate 1-10) + +- How clearly are invariants communicated through the type's structure? +- Are invariants enforced at compile-time where possible? +- Is the type self-documenting through its design? +- Are edge cases and constraints obvious from the type definition? + +### 4. Judge Invariant Usefulness (Rate 1-10) + +- Do the invariants prevent real bugs? +- Are they aligned with business requirements? +- Do they make the code easier to reason about? +- Are they neither too restrictive nor too permissive? + +### 5. Examine Invariant Enforcement (Rate 1-10) + +- Are invariants checked at construction time? +- Are all mutation points guarded? +- Is it impossible to create invalid instances? +- Are runtime checks appropriate and comprehensive? + +## Output Format + +``` +## Type: [TypeName] + +### Invariants Identified +- [List each invariant with a brief description] + +### Ratings +- **Encapsulation**: X/10 + [Brief justification] + +- **Invariant Expression**: X/10 + [Brief justification] + +- **Invariant Usefulness**: X/10 + [Brief justification] + +- **Invariant Enforcement**: X/10 + [Brief justification] + +### Strengths +[What the type does well] + +### Concerns +[Specific issues that need attention] + +### Recommended Improvements +[Concrete, actionable suggestions] +``` + +## Key Principles + +- Prefer compile-time guarantees over runtime checks when feasible +- Value clarity and expressiveness over cleverness +- Consider the maintenance burden of suggested improvements +- Recognize that perfect is the enemy of good - suggest pragmatic improvements +- Types should make illegal states unrepresentable +- Constructor validation is crucial for maintaining invariants +- Immutability often simplifies invariant maintenance + +## Common Anti-patterns to Flag + +- Anemic domain models with no behavior +- Types that expose mutable internals +- Invariants enforced only through documentation +- Types with too many responsibilities +- Missing validation at construction boundaries +- Inconsistent enforcement across mutation methods +- Types that rely on external code to maintain invariants diff --git a/.kiro/steering/code-review-standards.md b/.kiro/steering/code-review-standards.md new file mode 100644 index 0000000..ba2983b --- /dev/null +++ b/.kiro/steering/code-review-standards.md @@ -0,0 +1,68 @@ +--- +inclusion: auto +name: code-review-standards +description: Code review standards and confidence scoring methodology. Use when performing code reviews, reviewing pull requests, or evaluating code changes. +--- + +# Code Review Standards + +## Confidence Scoring + +When reviewing code, rate each issue on a scale from 0-100: + +- **0**: Not confident at all. False positive that doesn't stand up to light scrutiny, or is a pre-existing issue. +- **25**: Somewhat confident. Might be a real issue, but may also be a false positive. If stylistic, not explicitly called out in project guidelines. +- **50**: Moderately confident. Verified as a real issue, but might be a nitpick or not happen very often in practice. +- **75**: Highly confident. Double-checked and verified as very likely a real issue that will be hit in practice. The existing approach is insufficient. +- **100**: Absolutely certain. Confirmed as definitely a real issue that will happen frequently in practice. + +**Only report issues with a score of 80 or higher.** + +## False Positives to Filter + +- Pre-existing issues not introduced in the PR +- Something that looks like a bug but is not actually a bug +- Pedantic nitpicks that a senior engineer wouldn't call out +- Issues that a linter, typechecker, or compiler would catch +- General code quality issues unless explicitly required in project guidelines +- Issues called out in guidelines but explicitly silenced in code (e.g., lint ignore comments) +- Changes in functionality that are likely intentional or directly related to the broader change +- Real issues on lines that the user did not modify in their pull request + +## Review Output Format + +When posting review results, follow this format: + +```markdown +### Code review + +Found N issues: + +1. (guideline says "<...>") + + + +2. (bug due to ) + + +``` + +If no issues found: + +```markdown +### Code review + +No issues found. Checked for bugs and project guideline compliance. +``` + +## Link Format + +When linking to code, use this exact format: + +``` +https://github.com/OWNER/REPO/blob/FULL_SHA/path/file.ext#L[start]-L[end] +``` + +- Must use full git SHA (not abbreviated) +- Must use `#L` notation with line range +- Provide at least 1 line of context before and after From 2b8e09a46d6b84d5a4b5349f76862287506f1fd7 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:15:01 +0000 Subject: [PATCH 02/18] remove non-standard license and metadata fields from skill frontmatter The project schema (skill-frontmatter.schema.json) and existing plugins only use name and description. Remove license and metadata fields to match repo conventions. --- .kiro/skills/code-review/SKILL.md | 5 ----- .kiro/skills/code-reviewer/SKILL.md | 5 ----- .kiro/skills/code-simplifier/SKILL.md | 5 ----- .kiro/skills/comment-analyzer/SKILL.md | 5 ----- .kiro/skills/pr-test-analyzer/SKILL.md | 5 ----- .kiro/skills/review-pr/SKILL.md | 5 ----- .kiro/skills/silent-failure-hunter/SKILL.md | 5 ----- .kiro/skills/type-design-analyzer/SKILL.md | 5 ----- 8 files changed, 40 deletions(-) diff --git a/.kiro/skills/code-review/SKILL.md b/.kiro/skills/code-review/SKILL.md index 27076a4..1adda77 100644 --- a/.kiro/skills/code-review/SKILL.md +++ b/.kiro/skills/code-review/SKILL.md @@ -1,11 +1,6 @@ --- name: code-review description: Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality, or when the user says "review this PR" or "code review". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: code-review@claude-plugins-official allowed-tools: Bash(gh:*) --- diff --git a/.kiro/skills/code-reviewer/SKILL.md b/.kiro/skills/code-reviewer/SKILL.md index dcbc10a..7ef78df 100644 --- a/.kiro/skills/code-reviewer/SKILL.md +++ b/.kiro/skills/code-reviewer/SKILL.md @@ -1,11 +1,6 @@ --- name: code-reviewer description: Review code for adherence to project guidelines, style guides, and best practices. Use proactively after writing or modifying code, before committing changes or creating pull requests. Checks for style violations, potential issues, and ensures code follows established patterns in project guidelines (CLAUDE.md, AGENTS.md, or .kiro/steering). Also use when the user says "review my code", "check code quality", or "does this look good". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # Code Reviewer diff --git a/.kiro/skills/code-simplifier/SKILL.md b/.kiro/skills/code-simplifier/SKILL.md index 78680ff..ba5902f 100644 --- a/.kiro/skills/code-simplifier/SKILL.md +++ b/.kiro/skills/code-simplifier/SKILL.md @@ -1,11 +1,6 @@ --- name: code-simplifier description: Simplify code for clarity, consistency, and maintainability while preserving all functionality. Use after completing a coding task, writing a logical chunk of code, fixing a bug, or optimizing performance. Triggers when the user says "simplify this code", "clean up the code", "make this more readable", or "refine this implementation". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # Code Simplifier diff --git a/.kiro/skills/comment-analyzer/SKILL.md b/.kiro/skills/comment-analyzer/SKILL.md index 2a33ba0..5400b76 100644 --- a/.kiro/skills/comment-analyzer/SKILL.md +++ b/.kiro/skills/comment-analyzer/SKILL.md @@ -1,11 +1,6 @@ --- name: comment-analyzer description: Analyze code comments for accuracy, completeness, and long-term maintainability. Use after generating documentation comments or docstrings, before finalizing a pull request that adds or modifies comments, when reviewing existing comments for technical debt or comment rot, or when verifying that comments accurately reflect the code they describe. Triggers when the user says "check my comments", "review documentation", or "are these comments accurate". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # Comment Analyzer diff --git a/.kiro/skills/pr-test-analyzer/SKILL.md b/.kiro/skills/pr-test-analyzer/SKILL.md index 56ea0f9..6a31e4c 100644 --- a/.kiro/skills/pr-test-analyzer/SKILL.md +++ b/.kiro/skills/pr-test-analyzer/SKILL.md @@ -1,11 +1,6 @@ --- name: pr-test-analyzer description: Review pull request test coverage quality and completeness. Use after a PR is created or updated to ensure tests adequately cover new functionality and edge cases. Triggers when the user says "check test coverage", "are the tests thorough", "review my tests", or "check for missing tests". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # PR Test Analyzer diff --git a/.kiro/skills/review-pr/SKILL.md b/.kiro/skills/review-pr/SKILL.md index 869651e..965a6d7 100644 --- a/.kiro/skills/review-pr/SKILL.md +++ b/.kiro/skills/review-pr/SKILL.md @@ -1,11 +1,6 @@ --- name: review-pr description: Comprehensive PR review using multiple specialized review aspects including code quality, test coverage, error handling, type design, comment accuracy, and code simplification. Use when the user wants a thorough PR review, says "review my PR", "check this PR", or wants to run multiple review aspects at once. -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # Comprehensive PR Review diff --git a/.kiro/skills/silent-failure-hunter/SKILL.md b/.kiro/skills/silent-failure-hunter/SKILL.md index bc9ba97..19a47a6 100644 --- a/.kiro/skills/silent-failure-hunter/SKILL.md +++ b/.kiro/skills/silent-failure-hunter/SKILL.md @@ -1,11 +1,6 @@ --- name: silent-failure-hunter description: Identify silent failures, inadequate error handling, and inappropriate fallback behavior in code changes. Use when reviewing code that involves error handling, catch blocks, fallback logic, or any code that could potentially suppress errors. Triggers when the user says "check error handling", "find silent failures", "review catch blocks", or "audit error handling". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # Silent Failure Hunter diff --git a/.kiro/skills/type-design-analyzer/SKILL.md b/.kiro/skills/type-design-analyzer/SKILL.md index 9994a9c..dd6687b 100644 --- a/.kiro/skills/type-design-analyzer/SKILL.md +++ b/.kiro/skills/type-design-analyzer/SKILL.md @@ -1,11 +1,6 @@ --- name: type-design-analyzer description: Expert analysis of type design for encapsulation and invariant expression. Use when introducing a new type, during pull request creation to review types being added, or when refactoring existing types. Provides qualitative feedback and quantitative ratings. Triggers when the user says "review my types", "check type design", "analyze this type", or "improve type invariants". -license: Apache-2.0 -metadata: - author: Anthropic - version: "1.0" - origin: pr-review-toolkit@claude-plugins-official --- # Type Design Analyzer From b445fe890c5e4f9b1470b52d9c3605b0a0b464fd Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:17:53 +0000 Subject: [PATCH 03/18] point review-pr aspect links to local references instead of sibling skills Kiro skills don't dynamically load other skills by reference. Use the bundled reference docs which already contain the condensed instructions. --- .kiro/skills/review-pr/SKILL.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.kiro/skills/review-pr/SKILL.md b/.kiro/skills/review-pr/SKILL.md index 965a6d7..3d451a8 100644 --- a/.kiro/skills/review-pr/SKILL.md +++ b/.kiro/skills/review-pr/SKILL.md @@ -20,12 +20,12 @@ Run a comprehensive pull request review using multiple specialized review aspect | Aspect | Description | Skill | | ------------ | ------------------------------------------------- | ---------------------------------------------------------- | -| **code** | General code review for project guidelines | [code-reviewer](../code-reviewer/SKILL.md) | -| **simplify** | Simplify code for clarity and maintainability | [code-simplifier](../code-simplifier/SKILL.md) | -| **comments** | Analyze code comment accuracy and maintainability | [comment-analyzer](../comment-analyzer/SKILL.md) | -| **tests** | Review test coverage quality and completeness | [pr-test-analyzer](../pr-test-analyzer/SKILL.md) | -| **errors** | Check error handling for silent failures | [silent-failure-hunter](../silent-failure-hunter/SKILL.md) | -| **types** | Analyze type design and invariants | [type-design-analyzer](../type-design-analyzer/SKILL.md) | +| **code** | General code review for project guidelines | [reference](references/code-reviewer.md) | +| **simplify** | Simplify code for clarity and maintainability | [reference](references/code-simplifier.md) | +| **comments** | Analyze code comment accuracy and maintainability | [reference](references/comment-analyzer.md) | +| **tests** | Review test coverage quality and completeness | [reference](references/pr-test-analyzer.md) | +| **errors** | Check error handling for silent failures | [reference](references/silent-failure-hunter.md) | +| **types** | Analyze type design and invariants | [reference](references/type-design-analyzer.md) | | **all** | Run all applicable reviews (default) | - | ### 3. Identify Changed Files From 5fd9728daab607105beab64b8589063d473fb425 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:17:58 +0000 Subject: [PATCH 04/18] remove empty mcp.json placeholder No MCP servers are needed for the review skills. An empty config adds noise without value. --- .kiro/settings/mcp.json | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 .kiro/settings/mcp.json diff --git a/.kiro/settings/mcp.json b/.kiro/settings/mcp.json deleted file mode 100644 index da39e4f..0000000 --- a/.kiro/settings/mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -} From db14e670b5ce3a6e27c447e60388020dad635b4c Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:18:26 +0000 Subject: [PATCH 05/18] deduplicate confidence scoring, reference steering file instead The steering file code-review-standards.md is auto-included. Remove duplicated scoring scales from code-review, code-reviewer, and the review-pr code-reviewer reference to save context tokens. --- .kiro/skills/code-review/SKILL.md | 12 ++---------- .kiro/skills/code-reviewer/SKILL.md | 10 +--------- .kiro/skills/review-pr/references/code-reviewer.md | 8 +------- 3 files changed, 4 insertions(+), 26 deletions(-) diff --git a/.kiro/skills/code-review/SKILL.md b/.kiro/skills/code-review/SKILL.md index 1adda77..68350ae 100644 --- a/.kiro/skills/code-review/SKILL.md +++ b/.kiro/skills/code-review/SKILL.md @@ -55,19 +55,11 @@ Perform 5 independent review passes, each from a different angle: ### Step 5: Confidence Scoring -For each issue found in Step 4, score it on a scale from 0-100 indicating confidence that the issue is real vs. a false positive: - -- **0**: Not confident at all. False positive that doesn't stand up to light scrutiny, or is a pre-existing issue. -- **25**: Somewhat confident. Might be a real issue, but may also be a false positive. If stylistic, not explicitly called out in project guidelines. -- **50**: Moderately confident. Verified as real, but might be a nitpick or rare in practice. -- **75**: Highly confident. Double-checked and verified as very likely real and impactful. For guideline issues, verified the guideline explicitly mentions it. -- **100**: Absolutely certain. Confirmed as definitely real and frequent in practice. - -For issues flagged due to project guideline instructions, double check that the guideline actually calls out that issue specifically. +For each issue found in Step 4, apply the confidence scoring methodology from project standards. For issues flagged due to project guideline instructions, double check that the guideline actually calls out that issue specifically. ### Step 6: Filter -Filter out any issues with a score less than 80. If no issues meet this criteria, proceed to Step 8 with "no issues found." +Filter out any issues below the threshold defined in project standards. If no issues meet the criteria, proceed to Step 8 with "no issues found." ### Step 7: Re-check Eligibility diff --git a/.kiro/skills/code-reviewer/SKILL.md b/.kiro/skills/code-reviewer/SKILL.md index 7ef78df..530674b 100644 --- a/.kiro/skills/code-reviewer/SKILL.md +++ b/.kiro/skills/code-reviewer/SKILL.md @@ -21,15 +21,7 @@ By default, review unstaged changes from `git diff`. The user may specify differ ## Issue Confidence Scoring -Rate each issue from 0-100: - -- **0-25**: Likely false positive or pre-existing issue -- **26-50**: Minor nitpick not explicitly in project guidelines -- **51-75**: Valid but low-impact issue -- **76-90**: Important issue requiring attention -- **91-100**: Critical bug or explicit guideline violation - -Only report issues with confidence >= 80. +Apply the confidence scoring methodology from project standards. Only report issues with confidence >= 80. ## Output Format diff --git a/.kiro/skills/review-pr/references/code-reviewer.md b/.kiro/skills/review-pr/references/code-reviewer.md index bb8bb58..07a6841 100644 --- a/.kiro/skills/review-pr/references/code-reviewer.md +++ b/.kiro/skills/review-pr/references/code-reviewer.md @@ -12,13 +12,7 @@ Always applicable for any PR review. This is the general-purpose code quality ch ## Confidence Scoring -Rate each issue 0-100. Only report issues with confidence >= 80. - -- **0-25**: Likely false positive or pre-existing issue -- **26-50**: Minor nitpick not explicitly in guidelines -- **51-75**: Valid but low-impact -- **76-90**: Important, requires attention -- **91-100**: Critical bug or explicit guideline violation +Apply the confidence scoring methodology from project standards. Only report issues with confidence >= 80. ## Output From 83a6c0ad2360e5e5c0cddd45bc925b80c65a1869 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 2 Mar 2026 22:20:25 +0000 Subject: [PATCH 06/18] replace CLAUDE.md reference with generic guideline reference Align code-review output template with the steering file convention which already uses 'guideline says' instead of 'CLAUDE.md says'. --- .kiro/skills/code-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.kiro/skills/code-review/SKILL.md b/.kiro/skills/code-review/SKILL.md index 68350ae..7b9350b 100644 --- a/.kiro/skills/code-review/SKILL.md +++ b/.kiro/skills/code-review/SKILL.md @@ -76,7 +76,7 @@ Use `gh pr comment` to post the review on the pull request. Found N issues: -1. (CLAUDE.md says "<...>") +1. (guideline says "<...>") https://github.com/OWNER/REPO/blob/FULL_SHA/path/file.ext#L[start]-L[end] From 1439e8abebc1c07301def3a2f90fb007fef81acc Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 20:52:48 +0000 Subject: [PATCH 07/18] fix: linted SKILL Signed-off-by: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> --- .kiro/skills/review-pr/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.kiro/skills/review-pr/SKILL.md b/.kiro/skills/review-pr/SKILL.md index 3d451a8..a0d2820 100644 --- a/.kiro/skills/review-pr/SKILL.md +++ b/.kiro/skills/review-pr/SKILL.md @@ -18,15 +18,15 @@ Run a comprehensive pull request review using multiple specialized review aspect ### 2. Available Review Aspects -| Aspect | Description | Skill | -| ------------ | ------------------------------------------------- | ---------------------------------------------------------- | +| Aspect | Description | Skill | +| ------------ | ------------------------------------------------- | ------------------------------------------------ | | **code** | General code review for project guidelines | [reference](references/code-reviewer.md) | | **simplify** | Simplify code for clarity and maintainability | [reference](references/code-simplifier.md) | | **comments** | Analyze code comment accuracy and maintainability | [reference](references/comment-analyzer.md) | | **tests** | Review test coverage quality and completeness | [reference](references/pr-test-analyzer.md) | | **errors** | Check error handling for silent failures | [reference](references/silent-failure-hunter.md) | | **types** | Analyze type design and invariants | [reference](references/type-design-analyzer.md) | -| **all** | Run all applicable reviews (default) | - | +| **all** | Run all applicable reviews (default) | - | ### 3. Identify Changed Files From fa410f95cb050dbc044a05c8e09eac7c912c013b Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 22:29:32 +0000 Subject: [PATCH 08/18] refactor(kiro): convert code-review and review-pr skills to custom agents - Convert code-review skill to custom agent with explicit shell tool access for gh CLI (replaces Claude Code-specific allowed-tools) - Convert review-pr orchestrator skill to custom agent using subagent pattern for parallel review execution - Keep 6 individual review skills (code-reviewer, code-simplifier, comment-analyzer, pr-test-analyzer, silent-failure-hunter, type-design-analyzer) as skills loaded via skill:// resources - Remove references/ directory (duplicated content eliminated by subagents loading skills directly) - Agent prompts stored in .kiro/agents/prompts/ via file:// URI Refs: https://kiro.dev/docs/cli/chat/subagents/ Refs: https://kiro.dev/docs/cli/custom-agents/creating/ --- .kiro/agents/code-review.json | 11 ++++ .../prompts/code-review.md} | 6 -- .../SKILL.md => agents/prompts/review-pr.md} | 58 +++++++------------ .kiro/agents/review-pr.json | 18 ++++++ .../review-pr/references/code-reviewer.md | 19 ------ .../review-pr/references/code-simplifier.md | 24 -------- .../review-pr/references/comment-analyzer.md | 19 ------ .../review-pr/references/pr-test-analyzer.md | 28 --------- .../references/silent-failure-hunter.md | 31 ---------- .../references/type-design-analyzer.md | 29 ---------- 10 files changed, 49 insertions(+), 194 deletions(-) create mode 100644 .kiro/agents/code-review.json rename .kiro/{skills/code-review/SKILL.md => agents/prompts/code-review.md} (91%) rename .kiro/{skills/review-pr/SKILL.md => agents/prompts/review-pr.md} (58%) create mode 100644 .kiro/agents/review-pr.json delete mode 100644 .kiro/skills/review-pr/references/code-reviewer.md delete mode 100644 .kiro/skills/review-pr/references/code-simplifier.md delete mode 100644 .kiro/skills/review-pr/references/comment-analyzer.md delete mode 100644 .kiro/skills/review-pr/references/pr-test-analyzer.md delete mode 100644 .kiro/skills/review-pr/references/silent-failure-hunter.md delete mode 100644 .kiro/skills/review-pr/references/type-design-analyzer.md diff --git a/.kiro/agents/code-review.json b/.kiro/agents/code-review.json new file mode 100644 index 0000000..dd63f45 --- /dev/null +++ b/.kiro/agents/code-review.json @@ -0,0 +1,11 @@ +{ + "name": "code-review", + "description": "Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality.", + "prompt": "file://./prompts/code-review.md", + "tools": ["read", "shell", "write", "code", "subagent"], + "allowedTools": ["read", "code"], + "resources": [ + "file://../steering/code-review-standards.md", + "file://../../AGENTS.md" + ] +} diff --git a/.kiro/skills/code-review/SKILL.md b/.kiro/agents/prompts/code-review.md similarity index 91% rename from .kiro/skills/code-review/SKILL.md rename to .kiro/agents/prompts/code-review.md index 7b9350b..104247f 100644 --- a/.kiro/skills/code-review/SKILL.md +++ b/.kiro/agents/prompts/code-review.md @@ -1,9 +1,3 @@ ---- -name: code-review -description: Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality, or when the user says "review this PR" or "code review". -allowed-tools: Bash(gh:*) ---- - # Code Review Provide a comprehensive code review for a given pull request. diff --git a/.kiro/skills/review-pr/SKILL.md b/.kiro/agents/prompts/review-pr.md similarity index 58% rename from .kiro/skills/review-pr/SKILL.md rename to .kiro/agents/prompts/review-pr.md index a0d2820..a598c5f 100644 --- a/.kiro/skills/review-pr/SKILL.md +++ b/.kiro/agents/prompts/review-pr.md @@ -1,11 +1,6 @@ ---- -name: review-pr -description: Comprehensive PR review using multiple specialized review aspects including code quality, test coverage, error handling, type design, comment accuracy, and code simplification. Use when the user wants a thorough PR review, says "review my PR", "check this PR", or wants to run multiple review aspects at once. ---- - # Comprehensive PR Review -Run a comprehensive pull request review using multiple specialized review aspects, each focusing on a different dimension of code quality. +Run a comprehensive pull request review using multiple specialized subagents, each focusing on a different dimension of code quality. ## Review Workflow @@ -18,15 +13,15 @@ Run a comprehensive pull request review using multiple specialized review aspect ### 2. Available Review Aspects -| Aspect | Description | Skill | -| ------------ | ------------------------------------------------- | ------------------------------------------------ | -| **code** | General code review for project guidelines | [reference](references/code-reviewer.md) | -| **simplify** | Simplify code for clarity and maintainability | [reference](references/code-simplifier.md) | -| **comments** | Analyze code comment accuracy and maintainability | [reference](references/comment-analyzer.md) | -| **tests** | Review test coverage quality and completeness | [reference](references/pr-test-analyzer.md) | -| **errors** | Check error handling for silent failures | [reference](references/silent-failure-hunter.md) | -| **types** | Analyze type design and invariants | [reference](references/type-design-analyzer.md) | -| **all** | Run all applicable reviews (default) | - | +| Aspect | Description | Skill | +| ------------ | ------------------------------------------------- | ------------------------ | +| **code** | General code review for project guidelines | code-reviewer | +| **simplify** | Simplify code for clarity and maintainability | code-simplifier | +| **comments** | Analyze code comment accuracy and maintainability | comment-analyzer | +| **tests** | Review test coverage quality and completeness | pr-test-analyzer | +| **errors** | Check error handling for silent failures | silent-failure-hunter | +| **types** | Analyze type design and invariants | type-design-analyzer | +| **all** | Run all applicable reviews (default) | - | ### 3. Identify Changed Files @@ -41,13 +36,20 @@ Run `git diff --name-only` to see modified files and determine which reviews app ### 4. Execute Reviews -For each applicable review aspect, follow the instructions from the corresponding skill's reference documentation. +For each applicable review aspect, spawn a subagent with the task. Each subagent has access to the corresponding skill via its resources. + +Spawn subagents in parallel for efficiency. Each subagent should: -Run reviews sequentially by default (easier to understand and act on). If the user requests parallel or "all at once", run them simultaneously. +1. Read the changed files relevant to its review aspect +2. Apply the methodology from its skill +3. Apply confidence scoring from the code-review-standards steering file +4. Return findings with file paths and line numbers + +Use the `code-review` agent as a subagent for the 5-pass automated code review. ### 5. Aggregate Results -After all reviews complete, produce a unified summary: +After all subagents complete, produce a unified summary: ```markdown # PR Review Summary @@ -76,22 +78,6 @@ After all reviews complete, produce a unified summary: 4. Re-run review after fixes ``` -## Usage Examples - -**Full review (default):** - -``` -/review-pr -``` - -**Specific aspects:** - -``` -/review-pr tests errors -/review-pr comments -/review-pr simplify -``` - ## Tips - Run early, before creating PR, not after @@ -99,7 +85,3 @@ After all reviews complete, produce a unified summary: - Address critical issues first - Re-run after fixes to verify resolution - Use specific reviews when you know the concern - -## Reference Documentation - -See [references/](references/) for detailed instructions for each review aspect. diff --git a/.kiro/agents/review-pr.json b/.kiro/agents/review-pr.json new file mode 100644 index 0000000..f1a4ca6 --- /dev/null +++ b/.kiro/agents/review-pr.json @@ -0,0 +1,18 @@ +{ + "name": "review-pr", + "description": "Comprehensive PR review using multiple specialized subagents for code quality, test coverage, error handling, type design, comment accuracy, and code simplification.", + "prompt": "file://./prompts/review-pr.md", + "tools": ["read", "shell", "code", "subagent"], + "allowedTools": ["read", "code"], + "toolsSettings": { + "subagent": { + "trustedAgents": ["code-review"], + "availableAgents": ["code-review"] + } + }, + "resources": [ + "file://../steering/code-review-standards.md", + "file://../../AGENTS.md", + "skill://../skills/**/SKILL.md" + ] +} diff --git a/.kiro/skills/review-pr/references/code-reviewer.md b/.kiro/skills/review-pr/references/code-reviewer.md deleted file mode 100644 index 07a6841..0000000 --- a/.kiro/skills/review-pr/references/code-reviewer.md +++ /dev/null @@ -1,19 +0,0 @@ -# Code Reviewer Reference - -## When to Apply - -Always applicable for any PR review. This is the general-purpose code quality check. - -## Review Focus - -1. **Project Guidelines Compliance**: Check adherence to explicit project rules in CLAUDE.md, AGENTS.md, or `.kiro/steering/` files -2. **Bug Detection**: Logic errors, null/undefined handling, race conditions, memory leaks, security vulnerabilities, performance problems -3. **Code Quality**: Code duplication, missing critical error handling, accessibility problems, inadequate test coverage - -## Confidence Scoring - -Apply the confidence scoring methodology from project standards. Only report issues with confidence >= 80. - -## Output - -Group issues by severity (Critical: 90-100, Important: 80-89). Include file path, line number, specific rule or bug explanation, and concrete fix suggestion. diff --git a/.kiro/skills/review-pr/references/code-simplifier.md b/.kiro/skills/review-pr/references/code-simplifier.md deleted file mode 100644 index 05e344f..0000000 --- a/.kiro/skills/review-pr/references/code-simplifier.md +++ /dev/null @@ -1,24 +0,0 @@ -# Code Simplifier Reference - -## When to Apply - -After other review aspects pass. This is the "polish and refine" step. - -## Focus Areas - -1. **Preserve Functionality**: Never change what code does, only how -2. **Apply Project Standards**: Follow established coding standards -3. **Enhance Clarity**: Reduce complexity, eliminate redundancy, improve naming -4. **Maintain Balance**: Don't over-simplify or create clever-but-unreadable code - -## Anti-patterns to Fix - -- Unnecessary complexity and nesting -- Redundant code and abstractions -- Nested ternary operators (prefer switch/if-else) -- Comments that describe obvious code -- Overly compact code that sacrifices readability - -## Output - -List specific simplifications applied, each explaining what changed and why. Confirm all functionality preserved. diff --git a/.kiro/skills/review-pr/references/comment-analyzer.md b/.kiro/skills/review-pr/references/comment-analyzer.md deleted file mode 100644 index 238c06a..0000000 --- a/.kiro/skills/review-pr/references/comment-analyzer.md +++ /dev/null @@ -1,19 +0,0 @@ -# Comment Analyzer Reference - -## When to Apply - -When comments or documentation have been added or modified in the PR. - -## Analysis Dimensions - -1. **Factual Accuracy**: Cross-reference claims against code implementation -2. **Completeness**: Sufficient context without redundancy -3. **Long-term Value**: Will this comment help a future maintainer? -4. **Misleading Elements**: Ambiguous language, outdated references, stale TODOs - -## Output Format - -- **Critical Issues**: Factually incorrect or highly misleading comments -- **Improvement Opportunities**: Comments that could be enhanced -- **Recommended Removals**: Comments that add no value -- **Positive Findings**: Well-written comments as good examples diff --git a/.kiro/skills/review-pr/references/pr-test-analyzer.md b/.kiro/skills/review-pr/references/pr-test-analyzer.md deleted file mode 100644 index 2d2c65c..0000000 --- a/.kiro/skills/review-pr/references/pr-test-analyzer.md +++ /dev/null @@ -1,28 +0,0 @@ -# PR Test Analyzer Reference - -## When to Apply - -When test files have been changed, or when new functionality needs test coverage. - -## Analysis Focus - -1. **Behavioral Coverage**: Focus on behavior, not line coverage -2. **Critical Gaps**: Untested error handling, missing edge cases, uncovered business logic -3. **Test Quality**: Tests should be resilient to refactoring, follow DAMP principles -4. **Prioritization**: Rate criticality 1-10, focus on tests rated 8+ first - -## Criticality Scale - -- **9-10**: Data loss, security issues, system failures -- **7-8**: User-facing errors -- **5-6**: Confusion or minor issues -- **3-4**: Completeness -- **1-2**: Optional improvements - -## Output Format - -1. Summary of test coverage quality -2. Critical Gaps (rated 8-10) -3. Important Improvements (rated 5-7) -4. Test Quality Issues -5. Positive Observations diff --git a/.kiro/skills/review-pr/references/silent-failure-hunter.md b/.kiro/skills/review-pr/references/silent-failure-hunter.md deleted file mode 100644 index d5cd413..0000000 --- a/.kiro/skills/review-pr/references/silent-failure-hunter.md +++ /dev/null @@ -1,31 +0,0 @@ -# Silent Failure Hunter Reference - -## When to Apply - -When error handling code has been changed, or when catch blocks, fallback logic, or error-related code is present in the diff. - -## What to Look For - -1. **Empty catch blocks** (absolutely forbidden) -2. **Broad exception catching** that hides unrelated errors -3. **Silent fallbacks** without user awareness -4. **Missing error logging** or insufficient context in logs -5. **Catch blocks that only log and continue** without user feedback -6. **Optional chaining** that silently skips operations -7. **Retry logic** that exhausts attempts silently - -## Severity Levels - -- **CRITICAL**: Silent failure, broad catch block -- **HIGH**: Poor error message, unjustified fallback -- **MEDIUM**: Missing context, could be more specific - -## Output Per Issue - -1. Location (file:line) -2. Severity -3. Issue Description -4. Hidden Errors (what unexpected errors could be caught) -5. User Impact -6. Recommendation -7. Example of corrected code diff --git a/.kiro/skills/review-pr/references/type-design-analyzer.md b/.kiro/skills/review-pr/references/type-design-analyzer.md deleted file mode 100644 index f5bd287..0000000 --- a/.kiro/skills/review-pr/references/type-design-analyzer.md +++ /dev/null @@ -1,29 +0,0 @@ -# Type Design Analyzer Reference - -## When to Apply - -When new types have been added or existing types have been modified in the PR. - -## Analysis Dimensions (each rated 1-10) - -1. **Encapsulation**: Are internals hidden? Can invariants be violated from outside? -2. **Invariant Expression**: How clearly are invariants communicated through structure? -3. **Invariant Usefulness**: Do invariants prevent real bugs and align with requirements? -4. **Invariant Enforcement**: Are invariants checked at construction and mutation? - -## Common Anti-patterns - -- Anemic domain models with no behavior -- Types exposing mutable internals -- Invariants enforced only through documentation -- Types with too many responsibilities -- Missing validation at construction boundaries -- Types relying on external code to maintain invariants - -## Output Per Type - -1. Invariants identified -2. Ratings (4 dimensions, each X/10 with justification) -3. Strengths -4. Concerns -5. Recommended improvements From f1cc5d28f258716a9901bd452f07317c47b79ef4 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 22:37:48 +0000 Subject: [PATCH 09/18] feat(kiro): add steering and skills for development workflow guidance - Add .kiro/steering/development-workflow.md (auto-loaded) with mise build commands, boundaries, and git worktree workflow from AGENTS.md - Add design-guidelines skill pointing to docs/DESIGN_GUIDELINES.md - Add development-guide skill pointing to docs/DEVELOPMENT_GUIDE.md - Add troubleshooting skill pointing to docs/TROUBLESHOOTING.md - Fix dprint formatting in review-pr prompt Skills use on-demand loading: metadata loaded at startup, full content loaded when the agent determines it is needed. The steering file is auto-included so agents always have build commands and boundaries. --- .kiro/agents/prompts/review-pr.md | 18 +++++------ .kiro/skills/design-guidelines/SKILL.md | 42 ++++++++++++++++++++++++ .kiro/skills/development-guide/SKILL.md | 43 +++++++++++++++++++++++++ .kiro/skills/troubleshooting/SKILL.md | 34 +++++++++++++++++++ .kiro/steering/development-workflow.md | 43 +++++++++++++++++++++++++ 5 files changed, 171 insertions(+), 9 deletions(-) create mode 100644 .kiro/skills/design-guidelines/SKILL.md create mode 100644 .kiro/skills/development-guide/SKILL.md create mode 100644 .kiro/skills/troubleshooting/SKILL.md create mode 100644 .kiro/steering/development-workflow.md diff --git a/.kiro/agents/prompts/review-pr.md b/.kiro/agents/prompts/review-pr.md index a598c5f..a791138 100644 --- a/.kiro/agents/prompts/review-pr.md +++ b/.kiro/agents/prompts/review-pr.md @@ -13,15 +13,15 @@ Run a comprehensive pull request review using multiple specialized subagents, ea ### 2. Available Review Aspects -| Aspect | Description | Skill | -| ------------ | ------------------------------------------------- | ------------------------ | -| **code** | General code review for project guidelines | code-reviewer | -| **simplify** | Simplify code for clarity and maintainability | code-simplifier | -| **comments** | Analyze code comment accuracy and maintainability | comment-analyzer | -| **tests** | Review test coverage quality and completeness | pr-test-analyzer | -| **errors** | Check error handling for silent failures | silent-failure-hunter | -| **types** | Analyze type design and invariants | type-design-analyzer | -| **all** | Run all applicable reviews (default) | - | +| Aspect | Description | Skill | +| ------------ | ------------------------------------------------- | --------------------- | +| **code** | General code review for project guidelines | code-reviewer | +| **simplify** | Simplify code for clarity and maintainability | code-simplifier | +| **comments** | Analyze code comment accuracy and maintainability | comment-analyzer | +| **tests** | Review test coverage quality and completeness | pr-test-analyzer | +| **errors** | Check error handling for silent failures | silent-failure-hunter | +| **types** | Analyze type design and invariants | type-design-analyzer | +| **all** | Run all applicable reviews (default) | - | ### 3. Identify Changed Files diff --git a/.kiro/skills/design-guidelines/SKILL.md b/.kiro/skills/design-guidelines/SKILL.md new file mode 100644 index 0000000..94f5290 --- /dev/null +++ b/.kiro/skills/design-guidelines/SKILL.md @@ -0,0 +1,42 @@ +--- +name: design-guidelines +description: Plugin design best practices for authoring skills, MCP integrations, and reference files. Use when creating a new plugin, writing SKILL.md files, structuring reference documentation, adding YAML frontmatter, or reviewing plugin design quality. Triggers on "create a plugin", "write a skill", "plugin best practices", or "design guidelines". +--- + +# Plugin Design Guidelines + +For the full design guidelines, read `docs/DESIGN_GUIDELINES.md` in the repository root. + +## Key Principles + +1. **Minimize context usage** - Keep SKILL.md under 300 lines, reference files under 100 lines +2. **Write for agents, not humans** - Explicit, unambiguous instructions; no vague language +3. **Single responsibility per skill** - Each skill does one thing well +4. **Keep plugins focused** - Clear, cohesive purpose; don't bundle unrelated features + +## YAML Frontmatter (Agent Skills Spec) + +Required: `name`, `description`. Optional: `license`, `compatibility`, `metadata`, `allowed-tools`. + +- `name`: 1-64 chars, lowercase, hyphens only, must match directory name +- `description`: Max 1024 chars, include trigger phrases and keywords + +## File Organization + +``` +skills/myskill/ + SKILL.md # Main workflow (200-300 lines max) + references/ + defaults.md # Default selections (50-100 lines max) + patterns.md # Common patterns +``` + +## Review Checklist + +- [ ] SKILL.md under 300 lines with proper frontmatter +- [ ] Reference files under 100 lines each +- [ ] Descriptions include trigger conditions +- [ ] All defaults explicitly specified +- [ ] Error handling documented +- [ ] No vague language ("maybe", "probably", "consider") +- [ ] Full build passes (`mise run build`) diff --git a/.kiro/skills/development-guide/SKILL.md b/.kiro/skills/development-guide/SKILL.md new file mode 100644 index 0000000..a3a5648 --- /dev/null +++ b/.kiro/skills/development-guide/SKILL.md @@ -0,0 +1,43 @@ +--- +name: development-guide +description: Development environment setup, build commands, and contribution workflow for the agent-plugins repository. Use when setting up the project, running builds, preparing contributions, or troubleshooting the development environment. Triggers on "how to build", "setup development", "run tests", "contribution workflow", or "development guide". +--- + +# Development Guide + +For the full development guide, read `docs/DEVELOPMENT_GUIDE.md` in the repository root. + +## Prerequisites + +- [Mise](https://mise.jdx.dev/) >= 2026.2.4 + +## Quick Setup + +```bash +cd agent-plugins +mise install # Install all tools +mise run build # Full build: lint + fmt:check + security +``` + +## Build Commands + +```bash +mise run fmt # Format with dprint +mise run fmt:check # Check formatting (CI) +mise run lint # All linters (markdown, manifests, cross-refs) +mise run security # All security scans (Bandit, SemGrep, Gitleaks, Checkov, Grype) +mise run build # Complete build +``` + +## Contribution Workflow + +1. Fork the repository +2. Clone and `cd agent-plugins` +3. `mise install` to set up tools +4. Make changes +5. `mise run build` before committing +6. Create PR back to `main` + +## Security Scanning + +Gitleaks false positives: regenerate baseline with `gitleaks git --config=.gitleaks.toml --report-format=json . > .gitleaks-baseline.json` and commit the updated file. diff --git a/.kiro/skills/troubleshooting/SKILL.md b/.kiro/skills/troubleshooting/SKILL.md new file mode 100644 index 0000000..e50ced9 --- /dev/null +++ b/.kiro/skills/troubleshooting/SKILL.md @@ -0,0 +1,34 @@ +--- +name: troubleshooting +description: Troubleshooting guide for plugin installation, skill auto-triggering, MCP server connections, and CI issues. Use when debugging plugin problems, fixing installation errors, or resolving build failures. Triggers on "plugin not working", "skill not triggering", "MCP connection failed", "troubleshoot", or "CI failed". +--- + +# Plugin Troubleshooting + +For the full troubleshooting guide, read `docs/TROUBLESHOOTING.md` in the repository root. + +## Common Issues + +### Skill Not Auto-Triggering + +1. Verify skill is loaded: `/skills` +2. Use explicit trigger phrases from the skill description +3. Check plugin installation: `/plugin list` + +### MCP Server Connection Issues + +1. Check logs: `~/.cache/claude-code/logs/` +2. Toggle the MCP server off/on via `/plugin` UI + +### Plugin Installation Issues + +```bash +/plugin marketplace remove agent-plugins-for-aws +/plugin marketplace add awslabs/agent-plugins +/plugin install deploy-on-aws@agent-plugins-for-aws +``` + +### CI Failed Jobs + +- Repository collaborators: use "Re-run failed jobs" in GitHub UI +- Fork contributors: push empty commit (`git commit --allow-empty -m "retry CI"`) or ask a maintainer diff --git a/.kiro/steering/development-workflow.md b/.kiro/steering/development-workflow.md new file mode 100644 index 0000000..ee57d68 --- /dev/null +++ b/.kiro/steering/development-workflow.md @@ -0,0 +1,43 @@ +--- +inclusion: auto +name: development-workflow +description: Development workflow, build commands, and contribution boundaries for the agent-plugins repository. Use when writing code, making changes, committing, or running builds. +--- + +# Development Workflow + +## Build System + +This project uses [mise](https://mise.jdx.dev) for tool versions and tasks. Always use mise commands. + +```bash +mise install # Install tools (first time) +mise run fmt # Format with dprint +mise run fmt:check # Check formatting (CI) +mise run lint:md # Lint Markdown (incl. SKILL.md) +mise run lint:md:fix # Lint Markdown with auto-fix +mise run lint:manifests # Validate JSON manifests +mise run lint:cross-refs # Validate cross-references between manifests +mise run lint # All linters +mise run security # All security scans +mise run build # Full build: lint + fmt:check + security +``` + +## Boundaries + +- ALWAYS use `git worktree add .tmp/` for new work. NEVER switch branches in the main worktree. +- ALWAYS use mise commands to interact with the codebase. If a command is not available, add it. +- NEVER add new dependencies without asking first. +- ALWAYS run a full build (`mise run build`) when done with a task before committing. +- ALWAYS ask first before modifying existing files in a major way. + +## Git Worktree Workflow + +```bash +git worktree add .tmp/ -b # New work +git worktree add .tmp/ # Existing branch +git worktree list # List worktrees +git worktree remove .tmp/ # Clean up after merge +``` + +All worktrees live under `.tmp/` (already in `.gitignore`). From 9ce3e86ef7ffae2f5b2113e42f61d87c77760ac8 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 22:42:12 +0000 Subject: [PATCH 10/18] feat(kiro): add maintainers-guide skill for PR review and merge workflows On-demand skill pointing to docs/MAINTAINERS_GUIDE.md with PR review criteria, merge rules, labels, and stale automation summary. --- .kiro/skills/maintainers-guide/SKILL.md | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .kiro/skills/maintainers-guide/SKILL.md diff --git a/.kiro/skills/maintainers-guide/SKILL.md b/.kiro/skills/maintainers-guide/SKILL.md new file mode 100644 index 0000000..968cd7f --- /dev/null +++ b/.kiro/skills/maintainers-guide/SKILL.md @@ -0,0 +1,39 @@ +--- +name: maintainers-guide +description: Repository reviewer, maintainer, and admin workflows including PR review criteria, merge rules, CI/CD overview, labels, and release process. Use when reviewing PRs, triaging issues, managing releases, or understanding CI workflows. Triggers on "review criteria", "merge rules", "how to merge", "CI workflow", "release process", or "maintainers guide". +--- + +# Maintainers Guide + +For the full maintainers guide, read `docs/MAINTAINERS_GUIDE.md` in the repository root. + +## PR Review Criteria + +1. CI is green (all required checks pass) +2. PR title follows conventional commits (`fix:`, `feat:`, `chore:`, etc.) +3. Contributor statement present in PR body +4. Design quality per review checklist in `docs/DESIGN_GUIDELINES.md` +5. Versioning follows semver +6. New plugins must include: CODEOWNERS entry, marketplace manifest entry, README table entry, `new-plugin` label +7. No secrets or sensitive data in diff + +## Merge Rules + +- Passing status checks required +- `do-not-merge` label blocks merging +- `HALT_MERGES` repo variable: `0` = allowed, `-1` = all blocked, `` = only that PR + +## Labels + +| Label | Purpose | +| -------------- | ------------------------------------ | +| `do-not-merge` | Blocks PR from merging (CI-enforced) | +| `new-plugin` | PR adds a new plugin | +| `backlog` | Exempts from stale automation | +| `stale` | Auto-applied to inactive PRs/issues | + +## Stale Automation + +- PRs: stale after 14 days, closed 2 days later +- Issues: stale after 60 days, closed 7 days later +- Add `backlog` label to exempt From b8430d17623d6ff1ad16846c510408ad8cd021be Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 22:44:35 +0000 Subject: [PATCH 11/18] fix(kiro): remove duplicated content from doc skills, reference originals Skills now contain only frontmatter (name + description for intent matching) and a pointer to the actual docs/*.md file. Eliminates content duplication and risk of drift. --- .kiro/skills/design-guidelines/SKILL.md | 36 +----------------------- .kiro/skills/development-guide/SKILL.md | 37 +------------------------ .kiro/skills/maintainers-guide/SKILL.md | 33 +--------------------- .kiro/skills/troubleshooting/SKILL.md | 28 +------------------ 4 files changed, 4 insertions(+), 130 deletions(-) diff --git a/.kiro/skills/design-guidelines/SKILL.md b/.kiro/skills/design-guidelines/SKILL.md index 94f5290..07517cb 100644 --- a/.kiro/skills/design-guidelines/SKILL.md +++ b/.kiro/skills/design-guidelines/SKILL.md @@ -5,38 +5,4 @@ description: Plugin design best practices for authoring skills, MCP integrations # Plugin Design Guidelines -For the full design guidelines, read `docs/DESIGN_GUIDELINES.md` in the repository root. - -## Key Principles - -1. **Minimize context usage** - Keep SKILL.md under 300 lines, reference files under 100 lines -2. **Write for agents, not humans** - Explicit, unambiguous instructions; no vague language -3. **Single responsibility per skill** - Each skill does one thing well -4. **Keep plugins focused** - Clear, cohesive purpose; don't bundle unrelated features - -## YAML Frontmatter (Agent Skills Spec) - -Required: `name`, `description`. Optional: `license`, `compatibility`, `metadata`, `allowed-tools`. - -- `name`: 1-64 chars, lowercase, hyphens only, must match directory name -- `description`: Max 1024 chars, include trigger phrases and keywords - -## File Organization - -``` -skills/myskill/ - SKILL.md # Main workflow (200-300 lines max) - references/ - defaults.md # Default selections (50-100 lines max) - patterns.md # Common patterns -``` - -## Review Checklist - -- [ ] SKILL.md under 300 lines with proper frontmatter -- [ ] Reference files under 100 lines each -- [ ] Descriptions include trigger conditions -- [ ] All defaults explicitly specified -- [ ] Error handling documented -- [ ] No vague language ("maybe", "probably", "consider") -- [ ] Full build passes (`mise run build`) +Read `docs/DESIGN_GUIDELINES.md` for the full guide. diff --git a/.kiro/skills/development-guide/SKILL.md b/.kiro/skills/development-guide/SKILL.md index a3a5648..dd6124a 100644 --- a/.kiro/skills/development-guide/SKILL.md +++ b/.kiro/skills/development-guide/SKILL.md @@ -5,39 +5,4 @@ description: Development environment setup, build commands, and contribution wor # Development Guide -For the full development guide, read `docs/DEVELOPMENT_GUIDE.md` in the repository root. - -## Prerequisites - -- [Mise](https://mise.jdx.dev/) >= 2026.2.4 - -## Quick Setup - -```bash -cd agent-plugins -mise install # Install all tools -mise run build # Full build: lint + fmt:check + security -``` - -## Build Commands - -```bash -mise run fmt # Format with dprint -mise run fmt:check # Check formatting (CI) -mise run lint # All linters (markdown, manifests, cross-refs) -mise run security # All security scans (Bandit, SemGrep, Gitleaks, Checkov, Grype) -mise run build # Complete build -``` - -## Contribution Workflow - -1. Fork the repository -2. Clone and `cd agent-plugins` -3. `mise install` to set up tools -4. Make changes -5. `mise run build` before committing -6. Create PR back to `main` - -## Security Scanning - -Gitleaks false positives: regenerate baseline with `gitleaks git --config=.gitleaks.toml --report-format=json . > .gitleaks-baseline.json` and commit the updated file. +Read `docs/DEVELOPMENT_GUIDE.md` for the full guide. diff --git a/.kiro/skills/maintainers-guide/SKILL.md b/.kiro/skills/maintainers-guide/SKILL.md index 968cd7f..54e90b4 100644 --- a/.kiro/skills/maintainers-guide/SKILL.md +++ b/.kiro/skills/maintainers-guide/SKILL.md @@ -5,35 +5,4 @@ description: Repository reviewer, maintainer, and admin workflows including PR r # Maintainers Guide -For the full maintainers guide, read `docs/MAINTAINERS_GUIDE.md` in the repository root. - -## PR Review Criteria - -1. CI is green (all required checks pass) -2. PR title follows conventional commits (`fix:`, `feat:`, `chore:`, etc.) -3. Contributor statement present in PR body -4. Design quality per review checklist in `docs/DESIGN_GUIDELINES.md` -5. Versioning follows semver -6. New plugins must include: CODEOWNERS entry, marketplace manifest entry, README table entry, `new-plugin` label -7. No secrets or sensitive data in diff - -## Merge Rules - -- Passing status checks required -- `do-not-merge` label blocks merging -- `HALT_MERGES` repo variable: `0` = allowed, `-1` = all blocked, `` = only that PR - -## Labels - -| Label | Purpose | -| -------------- | ------------------------------------ | -| `do-not-merge` | Blocks PR from merging (CI-enforced) | -| `new-plugin` | PR adds a new plugin | -| `backlog` | Exempts from stale automation | -| `stale` | Auto-applied to inactive PRs/issues | - -## Stale Automation - -- PRs: stale after 14 days, closed 2 days later -- Issues: stale after 60 days, closed 7 days later -- Add `backlog` label to exempt +Read `docs/MAINTAINERS_GUIDE.md` for the full guide. diff --git a/.kiro/skills/troubleshooting/SKILL.md b/.kiro/skills/troubleshooting/SKILL.md index e50ced9..84a3da8 100644 --- a/.kiro/skills/troubleshooting/SKILL.md +++ b/.kiro/skills/troubleshooting/SKILL.md @@ -5,30 +5,4 @@ description: Troubleshooting guide for plugin installation, skill auto-triggerin # Plugin Troubleshooting -For the full troubleshooting guide, read `docs/TROUBLESHOOTING.md` in the repository root. - -## Common Issues - -### Skill Not Auto-Triggering - -1. Verify skill is loaded: `/skills` -2. Use explicit trigger phrases from the skill description -3. Check plugin installation: `/plugin list` - -### MCP Server Connection Issues - -1. Check logs: `~/.cache/claude-code/logs/` -2. Toggle the MCP server off/on via `/plugin` UI - -### Plugin Installation Issues - -```bash -/plugin marketplace remove agent-plugins-for-aws -/plugin marketplace add awslabs/agent-plugins -/plugin install deploy-on-aws@agent-plugins-for-aws -``` - -### CI Failed Jobs - -- Repository collaborators: use "Re-run failed jobs" in GitHub UI -- Fork contributors: push empty commit (`git commit --allow-empty -m "retry CI"`) or ask a maintainer +Read `docs/TROUBLESHOOTING.md` for the full guide. From b21bfd44e65397237caf99966ed52aa82f319047 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:13:35 +0000 Subject: [PATCH 12/18] fix(kiro): expand allowedTools for code-review and review-pr agents - code-review: add shell to allowedTools (needed for gh CLI) - review-pr: add shell and subagent to allowedTools (needed for gh CLI and spawning code-review subagents) --- .kiro/agents/code-review.json | 2 +- .kiro/agents/review-pr.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.kiro/agents/code-review.json b/.kiro/agents/code-review.json index dd63f45..b47f8b3 100644 --- a/.kiro/agents/code-review.json +++ b/.kiro/agents/code-review.json @@ -3,7 +3,7 @@ "description": "Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality.", "prompt": "file://./prompts/code-review.md", "tools": ["read", "shell", "write", "code", "subagent"], - "allowedTools": ["read", "code"], + "allowedTools": ["read", "code", "shell"], "resources": [ "file://../steering/code-review-standards.md", "file://../../AGENTS.md" diff --git a/.kiro/agents/review-pr.json b/.kiro/agents/review-pr.json index f1a4ca6..ac5230f 100644 --- a/.kiro/agents/review-pr.json +++ b/.kiro/agents/review-pr.json @@ -3,7 +3,7 @@ "description": "Comprehensive PR review using multiple specialized subagents for code quality, test coverage, error handling, type design, comment accuracy, and code simplification.", "prompt": "file://./prompts/review-pr.md", "tools": ["read", "shell", "code", "subagent"], - "allowedTools": ["read", "code"], + "allowedTools": ["read", "code", "shell", "subagent"], "toolsSettings": { "subagent": { "trustedAgents": ["code-review"], From f1015b894e29e58a576f51aa4369d5bbbc4588cf Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:13:40 +0000 Subject: [PATCH 13/18] feat(kiro): expand doc skills with inline summaries and symlinked references Replace stub 'Read docs/...' content with actionable workflow summaries. Add references/full-guide.md symlinks pointing to the original docs/ files to avoid content duplication while keeping the skill structure intact. --- .kiro/skills/design-guidelines/SKILL.md | 29 ++++++++++++++++++- .../references/full-guide.md | 1 + .kiro/skills/development-guide/SKILL.md | 28 +++++++++++++++++- .../references/full-guide.md | 1 + .kiro/skills/maintainers-guide/SKILL.md | 26 ++++++++++++++++- .../references/full-guide.md | 1 + .kiro/skills/troubleshooting/SKILL.md | 26 ++++++++++++++++- .../troubleshooting/references/full-guide.md | 1 + 8 files changed, 109 insertions(+), 4 deletions(-) create mode 120000 .kiro/skills/design-guidelines/references/full-guide.md create mode 120000 .kiro/skills/development-guide/references/full-guide.md create mode 120000 .kiro/skills/maintainers-guide/references/full-guide.md create mode 120000 .kiro/skills/troubleshooting/references/full-guide.md diff --git a/.kiro/skills/design-guidelines/SKILL.md b/.kiro/skills/design-guidelines/SKILL.md index 07517cb..293e202 100644 --- a/.kiro/skills/design-guidelines/SKILL.md +++ b/.kiro/skills/design-guidelines/SKILL.md @@ -5,4 +5,31 @@ description: Plugin design best practices for authoring skills, MCP integrations # Plugin Design Guidelines -Read `docs/DESIGN_GUIDELINES.md` for the full guide. +## Workflow + +### Step 1: Scope the Plugin + +- One plugin = one focused purpose +- If the description uses "and" more than once, consider splitting + +### Step 2: Create the Structure + +- `plugin.json` manifest with name, version, description +- `.mcp.json` for any MCP server integrations +- `skills//SKILL.md` (≤300 lines) with `references/` for details (≤100 lines each) + +### Step 3: Author SKILL.md + +- YAML frontmatter: `name` and `description` required +- Include trigger phrases and 3–7 keywords in description +- Write numbered workflow steps with explicit defaults +- Document error handling for every failure scenario (especially MCP) +- No vague language ("maybe", "probably", "consider") + +### Step 4: Validate + +1. `mise run lint:manifests` — validate JSON manifests +2. `mise run lint:cross-refs` — check cross-references +3. `mise run build` — full build before committing + +For anti-patterns, MCP integration, review checklist, and examples, see references/full-guide.md. diff --git a/.kiro/skills/design-guidelines/references/full-guide.md b/.kiro/skills/design-guidelines/references/full-guide.md new file mode 120000 index 0000000..81600a1 --- /dev/null +++ b/.kiro/skills/design-guidelines/references/full-guide.md @@ -0,0 +1 @@ +../../../../docs/DESIGN_GUIDELINES.md \ No newline at end of file diff --git a/.kiro/skills/development-guide/SKILL.md b/.kiro/skills/development-guide/SKILL.md index dd6124a..1a1de7e 100644 --- a/.kiro/skills/development-guide/SKILL.md +++ b/.kiro/skills/development-guide/SKILL.md @@ -5,4 +5,30 @@ description: Development environment setup, build commands, and contribution wor # Development Guide -Read `docs/DEVELOPMENT_GUIDE.md` for the full guide. +## Workflow + +### Step 1: Environment Setup + +- Install [mise](https://mise.jdx.dev/) >= 2026.2.4 +- Run `mise install` to install all project tools + +### Step 2: Development + +- Fork the repo and clone locally +- Use `git worktree add .tmp/ -b ` for new work +- Use mise commands for all build interactions + +### Step 3: Build and Validate + +- `mise run fmt` — format code +- `mise run lint` — all linters +- `mise run security` — security scans +- `mise run build` — full build (required before committing) + +### Step 4: Contribute + +- PR title must follow conventional commits (`fix:`, `feat:`, `chore:`) +- PR body must include license contribution acknowledgment +- All CI checks must pass + +For Claude Code setup, gitleaks handling, and detailed steps, see references/full-guide.md. diff --git a/.kiro/skills/development-guide/references/full-guide.md b/.kiro/skills/development-guide/references/full-guide.md new file mode 120000 index 0000000..0088141 --- /dev/null +++ b/.kiro/skills/development-guide/references/full-guide.md @@ -0,0 +1 @@ +../../../../docs/DEVELOPMENT_GUIDE.md \ No newline at end of file diff --git a/.kiro/skills/maintainers-guide/SKILL.md b/.kiro/skills/maintainers-guide/SKILL.md index 54e90b4..d99ace4 100644 --- a/.kiro/skills/maintainers-guide/SKILL.md +++ b/.kiro/skills/maintainers-guide/SKILL.md @@ -5,4 +5,28 @@ description: Repository reviewer, maintainer, and admin workflows including PR r # Maintainers Guide -Read `docs/MAINTAINERS_GUIDE.md` for the full guide. +## Workflow + +### Reviewing a PR + +1. Verify CI is green (build, lint, security, CodeQL) +2. Check PR title follows conventional commits format +3. Confirm contributor statement is present in PR body +4. Review design quality (see design-guidelines skill for checklist) +5. Verify version changes follow semver +6. For new plugins: require CODEOWNERS entry, marketplace manifest entry, README table entry, `new-plugin` label + +### Merge Rules + +- All status checks must pass +- `do-not-merge` label blocks merging +- `HALT_MERGES` repo variable: `0` = allow all, `-1` = block all, `` = only that PR + +### Labels + +- `do-not-merge` — blocks merge (CI-enforced) +- `new-plugin` — PR adds a new plugin +- `backlog` — exempts from stale automation +- `stale` — auto-applied to inactive PRs/issues + +For roles, plugin team onboarding, CI/CD details, release process, and stale automation, see references/full-guide.md. diff --git a/.kiro/skills/maintainers-guide/references/full-guide.md b/.kiro/skills/maintainers-guide/references/full-guide.md new file mode 120000 index 0000000..6689603 --- /dev/null +++ b/.kiro/skills/maintainers-guide/references/full-guide.md @@ -0,0 +1 @@ +../../../../docs/MAINTAINERS_GUIDE.md \ No newline at end of file diff --git a/.kiro/skills/troubleshooting/SKILL.md b/.kiro/skills/troubleshooting/SKILL.md index 84a3da8..59e80c2 100644 --- a/.kiro/skills/troubleshooting/SKILL.md +++ b/.kiro/skills/troubleshooting/SKILL.md @@ -5,4 +5,28 @@ description: Troubleshooting guide for plugin installation, skill auto-triggerin # Plugin Troubleshooting -Read `docs/TROUBLESHOOTING.md` for the full guide. +## Workflow + +### Step 1: Identify the Problem Category + +- **Plugin installation** — marketplace not found, plugin not found +- **Skill not triggering** — skill not loaded, phrasing too vague +- **MCP server failure** — connection issues, server not starting +- **CI failure** — flaky jobs, permission issues on forks + +### Step 2: Quick Fixes + +- Plugin issues: remove and re-add marketplace, then reinstall plugin +- Skill issues: verify with `/skills`, try explicit trigger phrases, check `/plugin list` +- MCP issues: check logs at `~/.cache/claude-code/logs/`, toggle server off/on via `/plugin` +- CI issues: re-run failed jobs via GitHub UI or `gh api` + +### Step 3: Full Reset (if quick fixes fail) + +1. Remove marketplace via `/plugin` → Marketplaces → Remove +2. Exit Claude Code and close terminal +3. `rm -rf ~/.claude/plugins/cache` +4. Clean entries from `~/.claude/plugins/installed_plugins.json` and `known_marketplaces.json` +5. Restart and re-add: `/plugin marketplace add awslabs/agent-plugins` + +For detailed steps, verification commands, CI re-run instructions, and debug mode, see references/full-guide.md. diff --git a/.kiro/skills/troubleshooting/references/full-guide.md b/.kiro/skills/troubleshooting/references/full-guide.md new file mode 120000 index 0000000..06155c3 --- /dev/null +++ b/.kiro/skills/troubleshooting/references/full-guide.md @@ -0,0 +1 @@ +../../../../docs/TROUBLESHOOTING.md \ No newline at end of file From 6e841ff35bef638b7d36693ae5bd73587fceaa68 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:14:06 +0000 Subject: [PATCH 14/18] fix: use POSIX-compatible case conversion in checkov task Replace bash-only ${LOG_LEVEL,,} with tr for /bin/sh compatibility. --- mise.toml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/mise.toml b/mise.toml index 9d994ab..4e1ad53 100644 --- a/mise.toml +++ b/mise.toml @@ -83,9 +83,13 @@ run = [ [tasks."security:checkov"] description = "Run Checkov" -run = [ - "checkov --quiet --directory . " -] +run = ''' +log_level=$(echo "$LOG_LEVEL" | tr '[:upper:]' '[:lower:]') +if [ "$log_level" = "trace" ]; then + export LOG_LEVEL=DEBUG +fi +checkov --quiet --directory . +''' [tasks."security:gitleaks"] description = "Run GitLeaks" From 1554f1ec3579f9c6fe713daeba679f46e0f479be Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:14:18 +0000 Subject: [PATCH 15/18] fix(kiro): remove write and subagent from code-review agent tools code-review is a read-only agent that posts comments via gh CLI. It does not need write (file modification) or subagent capabilities. --- .kiro/agents/code-review.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.kiro/agents/code-review.json b/.kiro/agents/code-review.json index b47f8b3..bedc922 100644 --- a/.kiro/agents/code-review.json +++ b/.kiro/agents/code-review.json @@ -2,7 +2,7 @@ "name": "code-review", "description": "Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality.", "prompt": "file://./prompts/code-review.md", - "tools": ["read", "shell", "write", "code", "subagent"], + "tools": ["read", "shell", "code"], "allowedTools": ["read", "code", "shell"], "resources": [ "file://../steering/code-review-standards.md", From e8a11786ce397d93cfecf6d9d61deb2ee30696c7 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:28:22 +0000 Subject: [PATCH 16/18] fix(kiro): add .kiro/ CODEOWNERS entry, remove redundant allowedTools, reorder guideline sources --- .github/CODEOWNERS | 1 + .kiro/agents/code-review.json | 1 - .kiro/agents/prompts/code-review.md | 4 ++-- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e2256f7..f32c96b 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -8,6 +8,7 @@ .bandit-baseline.json @awslabs/agent-plugins-admins .claude-plugin/ @awslabs/agent-plugins-admins +.kiro/ @awslabs/agent-plugins-admins .github/ @awslabs/agent-plugins-admins .gitignore @awslabs/agent-plugins-admins .gitleaks-baseline.json @awslabs/agent-plugins-admins diff --git a/.kiro/agents/code-review.json b/.kiro/agents/code-review.json index bedc922..5943d6a 100644 --- a/.kiro/agents/code-review.json +++ b/.kiro/agents/code-review.json @@ -3,7 +3,6 @@ "description": "Automated code review for pull requests using multiple specialized review passes with confidence-based scoring to filter false positives. Use when reviewing a pull request, performing code review, checking PR quality.", "prompt": "file://./prompts/code-review.md", "tools": ["read", "shell", "code"], - "allowedTools": ["read", "code", "shell"], "resources": [ "file://../steering/code-review-standards.md", "file://../../AGENTS.md" diff --git a/.kiro/agents/prompts/code-review.md b/.kiro/agents/prompts/code-review.md index 104247f..7357fa3 100644 --- a/.kiro/agents/prompts/code-review.md +++ b/.kiro/agents/prompts/code-review.md @@ -21,9 +21,9 @@ If any of these conditions are true, do not proceed. Inform the user why. Find all relevant project guideline files from the codebase: -- The root `CLAUDE.md` or `AGENTS.md` file (if one exists) -- Any guideline files in directories whose files the pull request modified - Any `.kiro/steering/` files that may contain project standards +- The root `AGENTS.md` or `CLAUDE.md` file (if one exists) +- Any guideline files in directories whose files the pull request modified Only collect file paths at this stage, not full contents. From 58453c0e711b592909937537cab5ac61e51ce7b9 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:43:35 +0000 Subject: [PATCH 17/18] fix(kiro): CODEOWNERS ordering, remove redundant allowedTools, document checkov TRACE remap --- .github/CODEOWNERS | 2 +- .kiro/agents/review-pr.json | 1 - mise.toml | 3 +++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f32c96b..a37f36c 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -8,12 +8,12 @@ .bandit-baseline.json @awslabs/agent-plugins-admins .claude-plugin/ @awslabs/agent-plugins-admins -.kiro/ @awslabs/agent-plugins-admins .github/ @awslabs/agent-plugins-admins .gitignore @awslabs/agent-plugins-admins .gitleaks-baseline.json @awslabs/agent-plugins-admins .gitleaks.toml @awslabs/agent-plugins-admins .gitleaksignore @awslabs/agent-plugins-admins +.kiro/ @awslabs/agent-plugins-admins .markdownlint-cli2.yaml @awslabs/agent-plugins-admins AGENTS.md @awslabs/agent-plugins-admins CLAUDE.md @awslabs/agent-plugins-admins diff --git a/.kiro/agents/review-pr.json b/.kiro/agents/review-pr.json index ac5230f..0847b48 100644 --- a/.kiro/agents/review-pr.json +++ b/.kiro/agents/review-pr.json @@ -3,7 +3,6 @@ "description": "Comprehensive PR review using multiple specialized subagents for code quality, test coverage, error handling, type design, comment accuracy, and code simplification.", "prompt": "file://./prompts/review-pr.md", "tools": ["read", "shell", "code", "subagent"], - "allowedTools": ["read", "code", "shell", "subagent"], "toolsSettings": { "subagent": { "trustedAgents": ["code-review"], diff --git a/mise.toml b/mise.toml index 4e1ad53..c308f88 100644 --- a/mise.toml +++ b/mise.toml @@ -84,6 +84,9 @@ run = [ [tasks."security:checkov"] description = "Run Checkov" run = ''' +# Checkov uses LOG_LEVEL internally but treats "TRACE" as unknown and crashes. +# Remap TRACE to DEBUG (the closest supported level) so mise's verbose tracing +# doesn't break the checkov run. log_level=$(echo "$LOG_LEVEL" | tr '[:upper:]' '[:lower:]') if [ "$log_level" = "trace" ]; then export LOG_LEVEL=DEBUG From 94c6fe9397aa6837891351ea32dcba524d9835d1 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Wed, 4 Mar 2026 23:58:53 +0000 Subject: [PATCH 18/18] fix(kiro): reorder guideline sources, clarify subagent scope, harden checkov LOG_LEVEL - code-reviewer: list .kiro/steering/ first in guideline source order - review-pr: clarify only code-review runs as subagent, other skills run inline using loaded resources - mise.toml: unset LOG_LEVEL entirely instead of only remapping TRACE --- .kiro/agents/prompts/review-pr.md | 12 +++++------- .kiro/skills/code-reviewer/SKILL.md | 4 ++-- mise.toml | 10 +++------- 3 files changed, 10 insertions(+), 16 deletions(-) diff --git a/.kiro/agents/prompts/review-pr.md b/.kiro/agents/prompts/review-pr.md index a791138..dbc8021 100644 --- a/.kiro/agents/prompts/review-pr.md +++ b/.kiro/agents/prompts/review-pr.md @@ -36,16 +36,14 @@ Run `git diff --name-only` to see modified files and determine which reviews app ### 4. Execute Reviews -For each applicable review aspect, spawn a subagent with the task. Each subagent has access to the corresponding skill via its resources. +Use the `code-review` agent as a subagent for the 5-pass automated code review. -Spawn subagents in parallel for efficiency. Each subagent should: +For the remaining review aspects (code-simplifier, comment-analyzer, pr-test-analyzer, silent-failure-hunter, type-design-analyzer), perform the reviews inline using the loaded skill resources. For each: -1. Read the changed files relevant to its review aspect -2. Apply the methodology from its skill +1. Read the changed files relevant to the review aspect +2. Apply the methodology from the corresponding skill 3. Apply confidence scoring from the code-review-standards steering file -4. Return findings with file paths and line numbers - -Use the `code-review` agent as a subagent for the 5-pass automated code review. +4. Collect findings with file paths and line numbers ### 5. Aggregate Results diff --git a/.kiro/skills/code-reviewer/SKILL.md b/.kiro/skills/code-reviewer/SKILL.md index 530674b..345c29a 100644 --- a/.kiro/skills/code-reviewer/SKILL.md +++ b/.kiro/skills/code-reviewer/SKILL.md @@ -1,6 +1,6 @@ --- name: code-reviewer -description: Review code for adherence to project guidelines, style guides, and best practices. Use proactively after writing or modifying code, before committing changes or creating pull requests. Checks for style violations, potential issues, and ensures code follows established patterns in project guidelines (CLAUDE.md, AGENTS.md, or .kiro/steering). Also use when the user says "review my code", "check code quality", or "does this look good". +description: Review code for adherence to project guidelines, style guides, and best practices. Use proactively after writing or modifying code, before committing changes or creating pull requests. Checks for style violations, potential issues, and ensures code follows established patterns in project guidelines (.kiro/steering/, AGENTS.md, or CLAUDE.md). Also use when the user says "review my code", "check code quality", or "does this look good". --- # Code Reviewer @@ -13,7 +13,7 @@ By default, review unstaged changes from `git diff`. The user may specify differ ## Core Review Responsibilities -**Project Guidelines Compliance**: Verify adherence to explicit project rules (typically in CLAUDE.md, AGENTS.md, or `.kiro/steering/`) including import patterns, framework conventions, language-specific style, function declarations, error handling, logging, testing practices, platform compatibility, and naming conventions. +**Project Guidelines Compliance**: Verify adherence to explicit project rules (typically in `.kiro/steering/`, AGENTS.md, or CLAUDE.md) including import patterns, framework conventions, language-specific style, function declarations, error handling, logging, testing practices, platform compatibility, and naming conventions. **Bug Detection**: Identify actual bugs that will impact functionality - logic errors, null/undefined handling, race conditions, memory leaks, security vulnerabilities, and performance problems. diff --git a/mise.toml b/mise.toml index c308f88..79e9e7b 100644 --- a/mise.toml +++ b/mise.toml @@ -84,13 +84,9 @@ run = [ [tasks."security:checkov"] description = "Run Checkov" run = ''' -# Checkov uses LOG_LEVEL internally but treats "TRACE" as unknown and crashes. -# Remap TRACE to DEBUG (the closest supported level) so mise's verbose tracing -# doesn't break the checkov run. -log_level=$(echo "$LOG_LEVEL" | tr '[:upper:]' '[:lower:]') -if [ "$log_level" = "trace" ]; then - export LOG_LEVEL=DEBUG -fi +# Checkov uses LOG_LEVEL internally and crashes on values it doesn't recognize +# (e.g. mise's TRACE). Unset it and let checkov use its own default. +unset LOG_LEVEL checkov --quiet --directory . '''