diff --git a/.claude/skills/brainstorming/SKILL.md b/.claude/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..b9b378f --- /dev/null +++ b/.claude/skills/brainstorming/SKILL.md @@ -0,0 +1,53 @@ +--- +name: brainstorming +description: 'Use before any creative work - designing features, adding API coverage, improving developer experience, or modifying SDK behavior. Explores intent, requirements, and design before implementation.' +--- + +# Brainstorming Ideas Into Designs + +## Overview + +Help turn ideas into fully formed designs and specs through natural collaborative dialogue. + +Start by understanding the current SDK state and Montonio API coverage, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far. + +## The Process + +**Understanding the idea:** + +- Check out the current project state first (source files, tests, recent commits, Montonio API docs) +- Ask questions one at a time to refine the idea +- Prefer multiple choice questions when possible, but open-ended is fine too +- Only one question per message - if a topic needs more exploration, break it into multiple questions +- Focus on understanding: purpose, constraints, success criteria + +**Exploring approaches:** + +- Propose 2-3 different approaches with trade-offs +- Present options conversationally with your recommendation and reasoning +- Lead with your recommended option and explain why +- Consider: API coverage gaps, type safety, developer ergonomics, backwards compatibility, testability + +**Presenting the design:** + +- Once you believe you understand what you're building, present the design +- Break it into sections of 200-300 words +- Ask after each section whether it looks right so far +- Cover: public API surface, request/response models, error handling, JWT/auth concerns, testing strategy +- Be ready to go back and clarify if something doesn't make sense + +## After the Design + +**Documentation:** + +- Write the design document to `docs/plans/YYYY-MM-DD--design.md` + +## Key Principles + +- **One question at a time** - Don't overwhelm with multiple questions +- **Multiple choice preferred** - Easier to answer than open-ended when possible +- **YAGNI ruthlessly** - Remove unnecessary features from all designs +- **Explore alternatives** - Always propose 2-3 approaches before settling +- **Incremental validation** - Present design in sections, validate each +- **Be flexible** - Go back and clarify when something doesn't make sense +- **Backwards compatibility** - Consider impact on existing SDK consumers diff --git a/.claude/skills/issue-triage/SKILL.md b/.claude/skills/issue-triage/SKILL.md new file mode 100644 index 0000000..1c264fa --- /dev/null +++ b/.claude/skills/issue-triage/SKILL.md @@ -0,0 +1,98 @@ +--- +name: issue-triage +description: 'Classify, prioritize, and label incoming GitHub issues. Identifies duplicates, suggests labels, and recommends affected areas of the codebase.' +--- + +# Issue Triaging + +## Overview + +Help classify, prioritize, and label incoming GitHub issues for the Montonio Java SDK. Produces a structured triage summary that can be applied directly to the issue. + +## Input + +A GitHub issue number or URL. If not provided, list recent open untriaged issues. + +## Step 1: Gather Context + +1. **Read the issue** using `gh issue view` +2. **Check for duplicates or related issues** by searching existing open and closed issues for similar keywords +3. **Identify affected code** by searching the codebase for classes, methods, or packages mentioned in the issue + +## Step 2: Classify the Issue + +Assign exactly one **type**: + +| Type | When to use | +| --------------- | ------------------------------------------------------------ | +| `bug` | Something is broken or behaves incorrectly | +| `feature` | A wholly new capability that doesn't exist yet | +| `enhancement` | An improvement to existing functionality | +| `question` | A usage question or request for clarification | +| `documentation` | Missing or incorrect documentation | + +## Step 3: Assess Priority + +Assign a **priority** based on impact and urgency: + +| Priority | Criteria | +| ---------- | --------------------------------------------------------------- | +| `critical` | Breaks core payment flow, data loss, or security vulnerability | +| `high` | Significant functionality broken, no workaround | +| `medium` | Functionality impaired but workaround exists | +| `low` | Minor inconvenience, cosmetic, or nice-to-have | + +## Step 4: Identify Affected Areas + +Map the issue to one or more areas of the SDK: + +- **api-client** - HTTP client, request/response handling +- **payment-orders** - Payment order creation, lifecycle +- **payment-methods** - Payment method discovery +- **webhooks** - JWT validation, webhook/return handling +- **auth** - Authentication, JWT signing +- **models** - Request/response DTOs +- **configuration** - SDK configuration, builder +- **testing** - Test infrastructure, test utilities +- **build** - Gradle, CI/CD, publishing + +## Step 5: Present Triage Summary + +Output the triage in this format: + +```markdown +## Triage Summary + +**Type:** +**Priority:** +**Areas:** +**Duplicates/Related:** + +### Analysis + +<2-3 sentence summary of the issue and its impact> + +### Affected Code + +- `` - +- ... + +### Suggested Labels + +, priority/, area/> + +### Recommended Next Steps + +<1-3 actionable items for addressing the issue> +``` + +## Step 6: Apply Labels (if requested) + +If the user confirms, apply the suggested labels to the issue using `gh issue edit`. + +## Key Principles + +- **Be specific** - Point to exact files and code paths, not vague areas +- **Check for duplicates first** - Avoid duplicate work by linking related issues +- **Prioritize by user impact** - Payment flow issues are always higher priority +- **Stay neutral** - Classify based on evidence in the issue, not assumptions diff --git a/CLAUDE.md b/CLAUDE.md index 8382e33..4a22653 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,6 +23,11 @@ Requires Java 17 (managed via `.sdkmanrc`). Uses Gradle 9.4.1 with Groovy DSL. A devcontainer configuration is provided in `.devcontainer/devcontainer.json`. It includes Java 17 (Temurin), Gradle (via wrapper), and GitHub CLI. Open the project in any devcontainer-compatible tool (VS Code, IntelliJ, GitHub Codespaces, Claude Code) to get a ready-to-use environment. +## Skills + +- `/brainstorming` — Collaborative design session for new features, API coverage, or SDK improvements. Asks questions one at a time, proposes approaches with trade-offs, then outputs a design document to `docs/plans/`. +- `/issue-triage` — Classify, prioritize, and label a GitHub issue. Pass an issue number or URL (e.g. `/issue-triage 12`), or run without an argument to triage recent untriaged issues; returns a structured summary with type, priority, affected code areas, and suggested labels. + ## Gradle Structure Build is split across files following BitWeb conventions: