From 867df4fed04bc568f1f812dcf27fa191a4ec43ca Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 09:06:46 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + commands/review.md | 114 ++++ commands/spec.md | 124 ++++ commands/spec/create.md | 55 ++ commands/spec/design.md | 26 + commands/spec/execute.md | 29 + commands/spec/list.md | 14 + commands/spec/requirements.md | 25 + commands/spec/tasks.md | 26 + plugin.lock.json | 109 ++++ skills/brainstorming/SKILL.md | 213 +++++++ skills/code-quality/SKILL.md | 463 +++++++++++++++ skills/documentation/SKILL.md | 569 ++++++++++++++++++ skills/git-workflow/SKILL.md | 593 +++++++++++++++++++ skills/skill-maker/SKILL.md | 657 +++++++++++++++++++++ skills/spec-driven-implementation/SKILL.md | 585 ++++++++++++++++++ skills/spec-driven-planning/SKILL.md | 341 +++++++++++ skills/systematic-testing/SKILL.md | 621 +++++++++++++++++++ skills/test-driven-development/SKILL.md | 397 +++++++++++++ 20 files changed, 4979 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/review.md create mode 100644 commands/spec.md create mode 100644 commands/spec/create.md create mode 100644 commands/spec/design.md create mode 100644 commands/spec/execute.md create mode 100644 commands/spec/list.md create mode 100644 commands/spec/requirements.md create mode 100644 commands/spec/tasks.md create mode 100644 plugin.lock.json create mode 100644 skills/brainstorming/SKILL.md create mode 100644 skills/code-quality/SKILL.md create mode 100644 skills/documentation/SKILL.md create mode 100644 skills/git-workflow/SKILL.md create mode 100644 skills/skill-maker/SKILL.md create mode 100644 skills/spec-driven-implementation/SKILL.md create mode 100644 skills/spec-driven-planning/SKILL.md create mode 100644 skills/systematic-testing/SKILL.md create mode 100644 skills/test-driven-development/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..aaf06bd --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "dev-workflow", + "description": "Integrated development lifecycle combining spec-driven development with code quality, git workflow, documentation, and systematic testing", + "version": "1.0.0", + "author": { + "name": "Kisune", + "email": "kisune@example.com" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5ff77d4 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# dev-workflow + +Integrated development lifecycle combining spec-driven development with code quality, git workflow, documentation, and systematic testing diff --git a/commands/review.md b/commands/review.md new file mode 100644 index 0000000..77626d5 --- /dev/null +++ b/commands/review.md @@ -0,0 +1,114 @@ +--- +description: Trigger comprehensive code review with quality checks +--- + +Activate the `code-quality` skill to perform systematic code review using comprehensive checklist covering code structure, error handling, security, performance, and testing. + +## Review Process + +1. **Ask What to Review** + Present options: + - Current staged changes (`git diff --cached`) + - Current unstaged changes (`git diff`) + - Specific file or directory + - Entire feature (all changes in current branch) + - Recent commits + +2. **Run Appropriate Command** + ```bash + # For staged changes + git diff --cached + + # For unstaged changes + git diff + + # For specific file + # Read the file directly + + # For entire feature + git diff main...HEAD + ``` + +3. **Perform Comprehensive Review** + Use checklist from `code-quality` skill: + - Code Structure (SRP, DRY, function length, naming, magic numbers) + - Error Handling (all errors caught, no silent failures, logging, edge cases) + - Security (input validation, SQL injection, XSS, sensitive data, secrets) + - Performance (N+1 queries, caching, indexes, unnecessary computations, memory leaks) + - Testing (tests exist, edge cases tested, happy path tested, error conditions, maintainability) + +4. **Generate Review Report** + Format: + ```markdown + ## Code Review: [File/Feature Name] + + ### βœ… Strengths + [What's done well] + + ### ⚠️ Issues Found + + #### Priority: High - Must Fix Before Merge + [Critical issues with location, problem, risk, and fix] + + #### Priority: Medium - Should Address + [Important improvements] + + #### Priority: Low - Consider Improving + [Optional enhancements] + + ### πŸ’‘ Refactoring Suggestions + [Specific improvements with before/after code examples] + + ### πŸ“Š Code Metrics + - Complexity: [Low/Medium/High] + - Test Coverage: [X%] + - Maintainability: [A/B/C/D/F] + + ### 🎯 Action Items + - [ ] Fix high-priority issues + - [ ] Address medium-priority items + - [ ] Consider refactoring suggestions + + **Overall Assessment:** [Summary] + **Recommendation:** [Approve/Request Changes/Reject] + + [Confidence: X.X] + ``` + +5. **Suggest Next Steps** + - If critical issues: Must fix before commit + - If medium issues: Should address before merge + - If low issues: Optional improvements + - If clean: Ready to commit/merge + +## Argument Handling + +**If user provides file path as argument:** +``` +/dev-workflow:review src/auth/login.js +``` +β†’ Review that specific file directly + +**If user provides directory as argument:** +``` +/dev-workflow:review src/auth/ +``` +β†’ Review all files in that directory + +**If user provides "." as argument:** +``` +/dev-workflow:review . +``` +β†’ Review all changes in current directory (recursive) + +**If no argument provided:** +``` +/dev-workflow:review +``` +β†’ Ask user what to review (staged, unstaged, specific file, etc.) + +## Examples + +**Example 1: Review staged changes** +``` +User: /dev-workflow:review \ No newline at end of file diff --git a/commands/spec.md b/commands/spec.md new file mode 100644 index 0000000..828181c --- /dev/null +++ b/commands/spec.md @@ -0,0 +1,124 @@ +--- +description: Launch spec-driven development workflow for features +--- + +Route to the appropriate spec-driven skill based on phase: +- **Planning phases** (create, requirements, design): Activate `spec-driven-planning` skill +- **Implementation phases** (tasks, execute): Activate `spec-driven-implementation` skill +- **Utility** (list): Show feature status directly + +## Interactive Menu + +Present this menu to the user: + +``` +πŸ“‹ Spec-Driven Development Workflow + +Planning Phase: +1. Create new feature +2. Define requirements (EARS format) +3. Generate technical design + +Implementation Phase: +4. Break down into tasks (TDD) +5. Execute implementation + +Utility: +6. List all features + +What would you like to do? (1-6) +``` + +## Argument Handling & Routing + +**Planning Phase Arguments:** +``` +/dev-workflow:spec create β†’ Activate spec-driven-planning (Phase 1) +/dev-workflow:spec "feature-name" β†’ Activate spec-driven-planning (Phase 1) +/dev-workflow:spec requirements β†’ Activate spec-driven-planning (Phase 2) +/dev-workflow:spec design β†’ Activate spec-driven-planning (Phase 3) +``` + +**Implementation Phase Arguments:** +``` +/dev-workflow:spec tasks β†’ Activate spec-driven-implementation (Phase 4) +/dev-workflow:spec execute β†’ Activate spec-driven-implementation (Phase 5) +``` + +**Utility Arguments:** +``` +/dev-workflow:spec list β†’ Show all features with status +``` + +## Routing Logic + +**IMPORTANT:** Always use the Skill tool to explicitly invoke skills. This ensures correct skill activation even when conflicting global commands exist. + +Based on user's menu choice or argument: + +**Options 1-3** or args **[create, feature-name, requirements, design]:** +β†’ Use the Skill tool to invoke: `dev-workflow:spec-driven-planning` + +**Options 4-5** or args **[tasks, execute]:** +β†’ Use the Skill tool to invoke: `dev-workflow:spec-driven-implementation` + +**Option 6** or arg **[list]:** +β†’ List features directly with status (no skill needed) + +## Phase Details + +**Planning Phases (1-3)** are handled by `spec-driven-planning` skill: +- Phase 1: Feature Creation - Create directory structure and templates +- Phase 2: Requirements Definition - Use EARS format for clear requirements +- Phase 3: Technical Design - Propose architectural approaches with trade-offs + +**Implementation Phases (4-5)** are handled by `spec-driven-implementation` skill: +- Phase 4: Task Breakdown - Break design into TDD tasks (Red-Green-Refactor) +- Phase 5: Execution - Execute tasks systematically with quality gates + +See respective skill documentation for detailed phase execution instructions. + +## Examples + +**Example 1: Interactive Menu** +``` +User: /dev-workflow:spec + +Assistant presents interactive menu showing planning and implementation phases. +User selects option 1-3 β†’ Assistant uses Skill tool to invoke spec-driven-planning +User selects option 4-5 β†’ Assistant uses Skill tool to invoke spec-driven-implementation +``` + +**Example 2: Start Planning New Feature** +``` +User: /dev-workflow:spec "user authentication" + +Assistant uses Skill tool to invoke: dev-workflow:spec-driven-planning +Skill activates at Phase 1 (Feature Creation) +Creates feature structure and begins requirements gathering. +``` + +**Example 3: Jump to Design Phase** +``` +User: /dev-workflow:spec design + +Assistant uses Skill tool to invoke: dev-workflow:spec-driven-planning +Skill activates at Phase 3 (Design) +Finds most recent feature and proposes architectural approaches. +``` + +**Example 4: Start Implementation** +``` +User: /dev-workflow:spec tasks + +Assistant uses Skill tool to invoke: dev-workflow:spec-driven-implementation +Skill activates at Phase 4 (Task Breakdown) +Reads completed design and breaks into TDD tasks. +``` + +**Example 5: List Features** +``` +User: /dev-workflow:spec list + +Assistant lists all features in docx/features/ with current status. +``` diff --git a/commands/spec/create.md b/commands/spec/create.md new file mode 100644 index 0000000..b315ac7 --- /dev/null +++ b/commands/spec/create.md @@ -0,0 +1,55 @@ +--- +description: Create new feature specification +--- + +Activate the `spec-driven-planning` skill to execute Phase 1 (Feature Creation). + +**Instructions:** + +1. Extract feature name from $ARGUMENTS + - If $ARGUMENTS provided: Use it as the feature name + - If $ARGUMENTS empty: Ask user "What feature would you like to create?" + +2. Use the Skill tool to invoke: `dev-workflow:spec-driven-planning` + +3. Tell the skill: + "Create a new feature called [feature-name]. Execute Phase 1 (Feature Creation): + - Check existing features in docx/features/ + - Create directory structure: docx/features/[NN-feature-name]/ + - Copy all templates (requirements.md, design.md, tasks.md) + - Initialize with feature name + + After creating the feature structure, ask if I'm ready to proceed with Phase 2 (Requirements Definition)." + +**What Gets Created:** + +The following files will be created with comprehensive templates: + +1. **requirements.md** (135 lines) + - EARS format structure (Event, State, Ubiquitous, Conditional, Optional) + - Non-functional requirements (Performance, Security, Usability) + - Constraints, acceptance criteria, out-of-scope items + - Dependencies, risks, and assumptions + +2. **design.md** (434 lines) + - Architecture overview and system context + - Component structure with interfaces + - Data flow diagrams and API contracts + - Error handling, security, and performance strategies + - Testing strategy and deployment plan + +3. **tasks.md** (427 lines) + - TDD task breakdown (Red-Green-Refactor cycles) + - Integration, error handling, and performance tasks + - Documentation and quality assurance tasks + - Progress tracking with checkboxes + +**After creation, show the user:** +``` +βœ… Created: docx/features/[NN-feature-name]/ + - requirements.md (ready to fill in) + - design.md (ready to fill in) + - tasks.md (ready to fill in) + +πŸ“‹ Next: Define requirements using /dev-workflow:spec:requirements +``` diff --git a/commands/spec/design.md b/commands/spec/design.md new file mode 100644 index 0000000..f4a403b --- /dev/null +++ b/commands/spec/design.md @@ -0,0 +1,26 @@ +--- +description: Generate technical design +--- + +Activate the `spec-driven-planning` skill to execute Phase 3 (Technical Design). + +**Instructions:** + +1. Determine target feature: + - If $ARGUMENTS provided: Use it as feature name/number + - If $ARGUMENTS empty: Find most recent feature in docx/features/ + +2. Use the Skill tool to invoke: `dev-workflow:spec-driven-planning` + +3. Tell the skill: + "Execute Phase 3 (Technical Design) for feature [feature-name]: + - Read requirements from docx/features/[NN-feature-name]/requirements.md + - Propose 2-3 architectural approaches with trade-offs + - Recommend best approach with reasoning + - Update docx/features/[NN-feature-name]/design.md with comprehensive design + + After design is complete, ask if I'm ready to proceed with Phase 4 (Task Breakdown)." + +**Expected Outcome:** +- design.md populated with architecture, components, data flow, and API contracts +- User prompted for next phase diff --git a/commands/spec/execute.md b/commands/spec/execute.md new file mode 100644 index 0000000..0d4f524 --- /dev/null +++ b/commands/spec/execute.md @@ -0,0 +1,29 @@ +--- +description: Execute implementation with TDD +--- + +Activate the `spec-driven-implementation` skill to execute Phase 5 (Execution). + +**Instructions:** + +1. Determine target feature: + - If $ARGUMENTS provided: Use it as feature name/number + - If $ARGUMENTS empty: Find most recent feature in docx/features/ + +2. Use the Skill tool to invoke: `dev-workflow:spec-driven-implementation` + +3. Tell the skill: + "Execute Phase 5 (Implementation) for feature [feature-name]: + - Read tasks from docx/features/[NN-feature-name]/tasks.md + - Execute tasks systematically following TDD (Red-Green-Refactor) + - Update checkboxes as tasks complete + - Integrate with code-quality and git-workflow skills + - Run quality gates before marking tasks complete + + Work through all tasks until feature is complete." + +**Expected Outcome:** +- All tasks executed with TDD discipline +- Checkboxes updated in tasks.md +- Code quality verified +- Feature implementation complete diff --git a/commands/spec/list.md b/commands/spec/list.md new file mode 100644 index 0000000..d40d32b --- /dev/null +++ b/commands/spec/list.md @@ -0,0 +1,14 @@ +--- +description: List all features with status +--- + +List all features in `docx/features/` directory with their current status: + +1. Find all feature directories: `docx/features/[NN-feature-name]/` +2. For each feature, show: + - Feature number and name + - Completion status (βœ… Complete, πŸ”„ In Progress, ⏳ Not Started) + - Files present: requirements.md, design.md, tasks.md + - Task progress if tasks.md exists: X/Y tasks complete + +Format as table or bulleted list. diff --git a/commands/spec/requirements.md b/commands/spec/requirements.md new file mode 100644 index 0000000..44e8245 --- /dev/null +++ b/commands/spec/requirements.md @@ -0,0 +1,25 @@ +--- +description: Define requirements using EARS format +--- + +Activate the `spec-driven-planning` skill to execute Phase 2 (Requirements Definition). + +**Instructions:** + +1. Determine target feature: + - If $ARGUMENTS provided: Use it as feature name/number + - If $ARGUMENTS empty: Find most recent feature in docx/features/ + +2. Use the Skill tool to invoke: `dev-workflow:spec-driven-planning` + +3. Tell the skill: + "Execute Phase 2 (Requirements Definition) for feature [feature-name]: + - Use EARS format for all requirements + - Ask systematic questions to elicit clear requirements + - Update docx/features/[NN-feature-name]/requirements.md + + After requirements are complete, ask if I'm ready to proceed with Phase 3 (Design)." + +**Expected Outcome:** +- requirements.md populated with EARS-formatted requirements +- User prompted for next phase diff --git a/commands/spec/tasks.md b/commands/spec/tasks.md new file mode 100644 index 0000000..36397de --- /dev/null +++ b/commands/spec/tasks.md @@ -0,0 +1,26 @@ +--- +description: Break down design into TDD tasks +--- + +Activate the `spec-driven-implementation` skill to execute Phase 4 (Task Breakdown). + +**Instructions:** + +1. Determine target feature: + - If $ARGUMENTS provided: Use it as feature name/number + - If $ARGUMENTS empty: Find most recent feature in docx/features/ + +2. Use the Skill tool to invoke: `dev-workflow:spec-driven-implementation` + +3. Tell the skill: + "Execute Phase 4 (Task Breakdown) for feature [feature-name]: + - Read design from docx/features/[NN-feature-name]/design.md + - Break down into TDD tasks following Red-Green-Refactor cycle + - Create checkbox list for tracking progress + - Update docx/features/[NN-feature-name]/tasks.md + + After tasks are defined, ask if I'm ready to proceed with Phase 5 (Execution)." + +**Expected Outcome:** +- tasks.md populated with TDD task breakdown and checkboxes +- User prompted for execution phase diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..c9bfb82 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,109 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:xbklairith/kisune:dev-workflow", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "e51820c74f92b03e9cc67e6e325099f68c2c35eb", + "treeHash": "f8d87fe3d839a782f6f1c299d5cf08fa0b15209ef314f0cbe37972da6c403feb", + "generatedAt": "2025-11-28T10:29:04.940160Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "dev-workflow", + "description": "Integrated development lifecycle combining spec-driven development with code quality, git workflow, documentation, and systematic testing", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "eb7c464e5d53a94ee42223164bec979deccbba276cc03912438965d74c8b41ba" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "90fbcf477369b258b6c75212499feba6ecf03f164285427e9309c34b7e1c36a7" + }, + { + "path": "commands/spec.md", + "sha256": "30dfa762861d29eb9aa37992cacf14721de2dee0f898a45fe562983921f1f220" + }, + { + "path": "commands/review.md", + "sha256": "441a915f0ccfed44a5bba52789715cc7e54281b09acc0d0b0260430d9505f64f" + }, + { + "path": "commands/spec/requirements.md", + "sha256": "8e8cc18dcaef5e561d22075578ff705b12c44c995833d369ccd3a2d471a17bfc" + }, + { + "path": "commands/spec/list.md", + "sha256": "248652eb2312eee1b941d079de8cbef383fe124a9b53556d82a70a0f5e995257" + }, + { + "path": "commands/spec/tasks.md", + "sha256": "8bb2306597edfdb6dd1923a0052a8a3c5767dc0b6be07da24b231d269398dea0" + }, + { + "path": "commands/spec/create.md", + "sha256": "65eff9b7957bc91063a35d249f1fa86e82aa4eaa8b9a370d1fa1c4f2d33501f9" + }, + { + "path": "commands/spec/design.md", + "sha256": "e58dcf2a90b5de174eb5db3f279e7ee05fae9370ca134f92ba62e4c701a1913e" + }, + { + "path": "commands/spec/execute.md", + "sha256": "49d72434253056f32406bfafe8d9d0b02be07ff0ae942f433f991fb457625c25" + }, + { + "path": "skills/spec-driven-implementation/SKILL.md", + "sha256": "81cfeadda7f6dc54cecb95bee41ceb35836482e8d39487054bc09d46db01c985" + }, + { + "path": "skills/skill-maker/SKILL.md", + "sha256": "bd8863c9dac3dd4160c8b22b1782ac95573ecc76b1935ae22c5e5650b7492ffe" + }, + { + "path": "skills/documentation/SKILL.md", + "sha256": "858640acb0ccb4747bef4d9cff2ba9673aa9ef8450a3b1161c7619c6b50c6a33" + }, + { + "path": "skills/test-driven-development/SKILL.md", + "sha256": "f54357e14e948eecae8c0b5457b24f0562e91d8eadc74c28033abf17bfe11abc" + }, + { + "path": "skills/git-workflow/SKILL.md", + "sha256": "fd838342277f55e2e21bcb796fd46a1bc52b83b1a86db73d2b7c840c309c8f33" + }, + { + "path": "skills/systematic-testing/SKILL.md", + "sha256": "526f0586d847aa53d1bfb06e1f062f78eef7f0303830cd2e523d6dbe599263e8" + }, + { + "path": "skills/spec-driven-planning/SKILL.md", + "sha256": "4f82b4450f79071ea205d06bf2206847a016e13b078c57f5af7ea1e4003a5c78" + }, + { + "path": "skills/brainstorming/SKILL.md", + "sha256": "4a4f0b5fb82eb2ecd42fef3637d00cac2f4a12965c494b21f25b26c31d93c9d6" + }, + { + "path": "skills/code-quality/SKILL.md", + "sha256": "8471374342d2b95b766230b7faa134f83fadbd096fbebe433b045e8a2d613522" + } + ], + "dirSha256": "f8d87fe3d839a782f6f1c299d5cf08fa0b15209ef314f0cbe37972da6c403feb" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..7fb3017 --- /dev/null +++ b/skills/brainstorming/SKILL.md @@ -0,0 +1,213 @@ +--- +name: brainstorming +description: Use when exploring unclear requirements or architectural decisions - refines rough ideas into clear requirements/designs through collaborative questioning (one at a time), explores alternatives, validates incrementally. Activates when user has vague feature idea, mentions "not sure about", "exploring options", "what approach", or during spec-driven requirements/design phases. +allowed-tools: Read, Write, Glob, Grep +--- + +# Brainstorming Ideas Into Designs + +## Overview + +Help turn ideas into fully formed designs and specs through natural collaborative dialogue. + +Start by understanding the current project context, 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. + +## When to Activate + +Activate this skill when: +- User has a rough idea that needs refinement +- User is uncertain about scope or approach +- User says "I'm not sure what we need" or "I'm not sure how to approach this" +- During Phase 2 (Requirements) to explore WHAT to build +- During Phase 3 (Technical Design) to explore HOW to build it + +**Phase 2 Focus (Requirements):** +- Clarifying what the feature should do +- Exploring different requirement scopes +- Understanding user needs and constraints +- Determining must-haves vs. nice-to-haves + +**Phase 3 Focus (Design):** +- Exploring architectural approaches +- Comparing technical solutions +- Analyzing implementation trade-offs + +## The Process + +**Understanding the idea:** +- Check out the current project state first (files, docs, recent commits) +- 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 + +**When to UltraThink:** +Before proposing architectural approaches, activate deep thinking if: +- Multiple valid solutions exist with significant trade-offs +- Decision has long-term architectural implications +- Requirements involve complex system interactions +- Security or performance are critical concerns + +> πŸ—£ Say: "Let me ultrathink this before proposing approaches. I'll question fundamentals and consider implications from first principles." + +**During UltraThink:** +- Question assumptions about requirements +- Consider second-order effects of each approach +- Think about what could go wrong (pre-mortem) +- Evaluate against similar systems you've seen +- Consider future maintainability and evolution + +**After UltraThink:** Provide approaches with clear reasoning about trade-offs and long-term implications. + +**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: + - Complexity (Low/Medium/High) + - Maintainability + - Performance implications + - Security considerations + - 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: architecture, components, data flow, error handling, testing +- Be ready to go back and clarify if something doesn't make sense + +## After Brainstorming + +**For Requirements (Phase 2):** +- Write validated requirements to `docx/features/[NN-feature-name]/requirements.md` +- Use EARS format (Event-Driven, State-Driven, Ubiquitous, Conditional, Optional) +- Include: + - Overview + - Functional requirements + - Non-functional requirements (performance, security, usability) + - Constraints + - Acceptance criteria + - Out of scope items +- Ask: "Requirements complete. Ready for design phase?" + +**For Design (Phase 3):** +- Write the validated design to `docx/features/[NN-feature-name]/design.md` +- Include: + - Architecture Overview + - Component Structure + - Data Flow + - API Contracts + - Error Handling Strategy + - Security Considerations + - Performance Considerations + - Testing Strategy +- Ask: "Design complete. Ready for task breakdown?" + +**Transition:** +- After requirements β†’ Proceed to Phase 3 (Technical Design) +- After design β†’ Transition to `spec-driven-implementation` skill for task breakdown + +## 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 +- **Think about testing** - Good designs are testable designs +- **Consider security** - Build security in, don't bolt it on later + +## Example Questioning Flow + +**Understanding Purpose:** +``` +Q: "What's the primary goal of this authentication feature?" +β†’ User answers + +Q: "Should it support multiple auth methods (email/password, OAuth, etc.) + or just one method initially?" +β†’ User answers + +Q: "What happens when a session expires - force re-login or offer refresh?" +β†’ User answers +``` + +**Exploring Approaches:** +``` +Based on your requirements, I see 3 main approaches: + +**Option A: JWT-Based Authentication** [RECOMMENDED] +Pros: Stateless, scalable, works across services, standard +Cons: Token invalidation complexity, larger payload +Complexity: Medium +Best for: Microservices, APIs, future scalability + +**Option B: Session-Based Authentication** +Pros: Simple invalidation, smaller cookies, familiar +Cons: Requires session storage, scaling challenges +Complexity: Low +Best for: Monolithic apps, simple use cases + +**Option C: Hybrid Approach** +Pros: Combines benefits of both +Cons: More complex, harder to maintain +Complexity: High +Best for: Complex enterprise requirements + +I recommend Option A (JWT) because your requirements mention +potential API integrations and future mobile app support. +JWT is industry-standard for this use case. + +Does this align with your thinking? +``` + +**Presenting Design Incrementally:** +``` +Let me present the architecture in sections: + +**Section 1: High-Level Flow** +[200-300 words describing auth flow] + +Does this look right so far? +β†’ User validates or requests changes + +**Section 2: Component Structure** +[200-300 words describing components] + +How does this look? +β†’ Continue... +``` + +## Integration with Spec-Driven Workflow + +This skill can be used in two phases: + +**Phase 2 (Requirements):** +- Use when user has rough idea but unclear requirements +- Helps clarify what to build vs. what's out of scope +- Explores different feature scopes and priorities +- Outputs to `requirements.md` in EARS format + +**Phase 3 (Technical Design):** +- Use after requirements are defined +- Helps explore how to build the feature +- Compares architectural approaches with trade-offs +- Outputs to `design.md` with complete technical specs + +After brainstorming completes: +- Phase 2 β†’ Proceed to Phase 3 (Technical Design) +- Phase 3 β†’ Transition to `spec-driven-implementation` for task breakdown + +## Notes + +- **Phase 2:** Focus on "what" (what should system do? what's in/out of scope?) +- **Phase 3:** Focus on "how" (how should we build it? what are trade-offs?) +- Always present multiple options before recommending +- Validate incrementally - don't dump everything at once +- Be ready to backtrack if something doesn't make sense +- One question at a time - let user think and respond +- Good requirements lead to good designs +- Good designs enable good tests - think about testability +- Security and error handling are not afterthoughts diff --git a/skills/code-quality/SKILL.md b/skills/code-quality/SKILL.md new file mode 100644 index 0000000..5ce50ab --- /dev/null +++ b/skills/code-quality/SKILL.md @@ -0,0 +1,463 @@ +--- +name: code-quality +description: Use when reviewing code or before commits - runs 25-point quality checklist (structure, errors, security, performance, testing), identifies code smells, suggests refactorings with examples. Activates when user says "review this", "check my code", mentions "refactor", "optimize", "code quality", or before git commits. +--- + +# Code Quality Skill + +## Purpose + +Perform systematic code reviews, identify issues, suggest refactorings, and enforce best practices. Acts as an automated code reviewer catching problems before they reach production. + +## Activation Triggers + +Activate this skill when: +- User says "review this code" +- User asks "can this be improved?" +- User mentions "refactoring", "optimization", or "code smell" +- Before git commits (pre-commit review) +- After completing a feature +- User uses `/dev-workflow:review` command +- User says "is this code good?" + +## Comprehensive Review Checklist + +### 1. Code Structure + +**Single Responsibility Principle (SRP)** +- βœ… Check: Each function/class has one clear purpose +- ❌ Red Flag: Functions doing multiple unrelated things +- πŸ’‘ Suggestion: Split into focused, single-purpose functions + +**DRY (Don't Repeat Yourself)** +- βœ… Check: No duplicated logic +- ❌ Red Flag: Copy-pasted code blocks +- πŸ’‘ Suggestion: Extract to shared function/utility + +**Function Length** +- βœ… Check: Functions under 50 lines (prefer under 30) +- ❌ Red Flag: Functions over 100 lines +- πŸ’‘ Suggestion: Break into smaller, composable functions + +**Naming Clarity** +- βœ… Check: Names clearly describe purpose +- ❌ Red Flag: Vague names (data, info, temp, x, y) +- πŸ’‘ Suggestion: Use descriptive, intention-revealing names + +**Magic Numbers** +- βœ… Check: Constants are named +- ❌ Red Flag: Unexplained numbers in code +- πŸ’‘ Suggestion: Extract to named constants + +### 2. Error Handling + +**All Errors Caught** +- βœ… Check: Try-catch blocks around risky operations +- ❌ Red Flag: Unhandled promise rejections, missing error handling +- πŸ’‘ Suggestion: Add comprehensive error handling + +**No Silent Failures** +- βœ… Check: Errors are logged or surfaced +- ❌ Red Flag: Empty catch blocks, ignored errors +- πŸ’‘ Suggestion: Log errors with context, alert user appropriately + +**User-Friendly Error Messages** +- βœ… Check: Errors explain what went wrong and what to do +- ❌ Red Flag: Technical jargon exposed to users +- πŸ’‘ Suggestion: Translate technical errors to user language + +**Logging for Debugging** +- βœ… Check: Appropriate logging at key points +- ❌ Red Flag: No logging or excessive logging +- πŸ’‘ Suggestion: Add structured logging with context + +**Edge Cases Covered** +- βœ… Check: Boundary conditions handled (null, undefined, empty, zero) +- ❌ Red Flag: Assumptions about inputs +- πŸ’‘ Suggestion: Add defensive checks and validation + +### 3. Security + +**Input Validation** +- βœ… Check: All user inputs validated and sanitized +- ❌ Red Flag: Raw user input used directly +- πŸ’‘ Suggestion: Add validation with schema libraries (Zod, Joi, etc.) + +**SQL Injection Prevention** +- βœ… Check: Parameterized queries or ORM used +- ❌ Red Flag: String concatenation in SQL +- πŸ’‘ Suggestion: Use prepared statements or ORM methods + +**XSS Prevention** +- βœ… Check: HTML output escaped, CSP headers set +- ❌ Red Flag: innerHTML with user content +- πŸ’‘ Suggestion: Use textContent or framework's safe rendering + +**Sensitive Data Handling** +- βœ… Check: Passwords hashed, PII encrypted, secure transmission +- ❌ Red Flag: Plain text secrets, sensitive data in logs +- πŸ’‘ Suggestion: Use bcrypt, encrypt at rest, sanitize logs + +**Environment Variables for Secrets** +- βœ… Check: API keys, credentials in .env files +- ❌ Red Flag: Hardcoded credentials in code +- πŸ’‘ Suggestion: Move to environment variables, use secret managers + +### 4. Performance + +**No N+1 Queries** +- βœ… Check: Batch queries, eager loading used +- ❌ Red Flag: Query inside loop +- πŸ’‘ Suggestion: Use includes/joins, batch operations + +**Appropriate Caching** +- βœ… Check: Expensive operations cached +- ❌ Red Flag: Repeated identical API calls or computations +- πŸ’‘ Suggestion: Add caching layer (Redis, in-memory, etc.) + +**Database Indexes** +- βœ… Check: Indexed columns used in WHERE/JOIN clauses +- ❌ Red Flag: Full table scans on large tables +- πŸ’‘ Suggestion: Add indexes on frequently queried columns + +**Unnecessary Computations** +- βœ… Check: Early returns, lazy evaluation +- ❌ Red Flag: Work done before checking preconditions +- πŸ’‘ Suggestion: Move expensive operations after validation + +**Memory Leak Prevention** +- βœ… Check: Event listeners cleaned up, connections closed +- ❌ Red Flag: Growing arrays, unclosed connections +- πŸ’‘ Suggestion: Add cleanup in finally blocks, use weak references + +### 5. Testing + +**Tests Exist** +- βœ… Check: Tests cover new functionality +- ❌ Red Flag: No tests for new code +- πŸ’‘ Suggestion: Write tests for all new functions/components + +**Edge Cases Tested** +- βœ… Check: Boundary conditions, null/undefined handled +- ❌ Red Flag: Only happy path tested +- πŸ’‘ Suggestion: Add tests for edge cases and error conditions + +**Happy Path Tested** +- βœ… Check: Normal operation verified +- ❌ Red Flag: No positive test cases +- πŸ’‘ Suggestion: Add tests for expected behavior + +**Error Conditions Tested** +- βœ… Check: Invalid inputs, failures handled +- ❌ Red Flag: Error paths not verified +- πŸ’‘ Suggestion: Add tests for error scenarios + +**Tests Are Maintainable** +- βœ… Check: Clear test names, minimal duplication +- ❌ Red Flag: Complex test setup, brittle assertions +- πŸ’‘ Suggestion: Extract test helpers, use clear assertions + +## Review Process + +### Step 1: Determine Scope + +Ask user what to review: +1. Current staged changes (`git diff --cached`) +2. Current unstaged changes (`git diff`) +3. Specific file or directory +4. Entire feature +5. Recent commits + +### Step 2: Analyze Code + +Run appropriate git diff or read files: +```bash +# For staged changes +git diff --cached + +# For unstaged changes +git diff + +# For specific file +Read file_path + +# For feature +git diff main...HEAD +``` + +### Step 3: Apply Checklist + +Systematically go through: +1. Code Structure (5 checks) +2. Error Handling (5 checks) +3. Security (5 checks) +4. Performance (5 checks) +5. Testing (5 checks) + +**UltraThink Architectural Issues:** +If review reveals fundamental architectural problems, activate deep thinking: + +> πŸ—£ Say: "This code has architectural issues. Let me ultrathink whether refactoring or redesign is needed." + +**When to UltraThink:** +- Code violates multiple principles (SRP, DRY, YAGNI) +- Tight coupling makes testing difficult +- Similar logic duplicated across multiple files +- Error handling is scattered and inconsistent +- Performance issues suggest wrong data structure/algorithm + +**Question deeply:** +- Is this a symptom of wrong architecture? +- Would refactoring fix root cause or just move complexity? +- What would this look like if designed from scratch? +- What's preventing clean separation of concerns? +- Is the domain model wrong? + +**After UltraThink:** Recommend tactical fixes (refactor) vs. strategic redesign with clear reasoning. + +### Step 4: Generate Review Report + +## Review Output Format + +```markdown +## Code Review: [File/Feature Name] + +### βœ… Strengths + +[List what's done well - be specific and encouraging] +- Clear function naming in authentication module +- Comprehensive error handling for API calls +- Good test coverage (87%) + +### ⚠️ Issues Found + +#### Priority: High - Must Fix Before Merge +1. **[Issue Title]** + - **Location:** `file.js:42` + - **Problem:** [Specific description] + - **Risk:** [What could go wrong] + - **Fix:** [How to resolve] + +#### Priority: Medium - Should Address +1. **[Issue Title]** + - **Location:** `file.js:78` + - **Problem:** [Description] + - **Impact:** [Effect on code quality] + - **Suggestion:** [Improvement approach] + +#### Priority: Low - Consider Improving +1. **[Issue Title]** + - **Location:** `file.js:120` + - **Note:** [Observation] + - **Enhancement:** [Optional improvement] + +### πŸ’‘ Refactoring Suggestions + +#### Suggestion 1: [Title] +**Current Code:** +```javascript +// Show problematic code +``` + +**Refactored Code:** +```javascript +// Show improved version +``` + +**Benefits:** +- [Benefit 1] +- [Benefit 2] + +#### Suggestion 2: [Title] +[Similar format] + +### πŸ“Š Code Metrics + +- **Complexity:** [Low/Medium/High] +- **Test Coverage:** [X%] +- **Maintainability:** [A/B/C/D/F] +- **Lines of Code:** [N] +- **Duplicated Code:** [X%] + +### 🎯 Action Items + +- [ ] Fix high-priority issues +- [ ] Address medium-priority items +- [ ] Consider refactoring suggestions +- [ ] Add tests for uncovered paths +- [ ] Update documentation + +--- + +**Overall Assessment:** [Summary statement] +**Recommendation:** [Approve/Request Changes/Reject] + +[Confidence: X.X] +``` + +## Examples + +### Example 1: Pre-Commit Review + +**User:** "I'm about to commit, can you review my changes?" + +**Assistant:** +``` +Activating code-quality skill for pre-commit review. + +Running: git diff --cached + +Found changes in: +- src/auth/login.js +- src/auth/session.js +- tests/auth/login.test.js + +Performing comprehensive review... + +## Code Review: Authentication Changes + +### βœ… Strengths +- Comprehensive test coverage for login flow +- Clear separation of concerns between login and session +- Good use of async/await for API calls + +### ⚠️ Issues Found + +#### Priority: High - Must Fix Before Merge +1. **Missing Input Validation** + - **Location:** `src/auth/login.js:23` + - **Problem:** Email and password not validated before API call + - **Risk:** Invalid inputs could crash backend or expose security issue + - **Fix:** Add validation with Zod schema + +**Current Code:** +```javascript +const login = async (email, password) => { + const response = await api.post('/auth/login', { email, password }); + return response.data; +}; +``` + +**Suggested Fix:** +```javascript +import { z } from 'zod'; + +const loginSchema = z.object({ + email: z.string().email('Invalid email format'), + password: z.string().min(8, 'Password must be at least 8 characters') +}); + +const login = async (email, password) => { + // Validate inputs + const validated = loginSchema.parse({ email, password }); + + const response = await api.post('/auth/login', validated); + return response.data; +}; +``` + +#### Priority: Medium - Should Address +1. **Missing Error Handling** + - **Location:** `src/auth/login.js:23` + - **Problem:** No try-catch for API call + - **Impact:** Unhandled promise rejections + - **Suggestion:** Add error handling with user-friendly messages + +[...continues with full review...] + +**Overall Assessment:** Good implementation with solid test coverage, but needs input validation and error handling before commit. + +**Recommendation:** Request Changes - Fix high-priority issues before committing. + +[Confidence: 0.9] +``` + +### Example 2: Refactoring Request + +**User:** "Can you suggest improvements for src/utils/calculator.js?" + +**Assistant:** +``` +Activating code-quality skill for refactoring analysis. + +Reading: src/utils/calculator.js + +Analyzing code structure and quality... + +## Code Review: Calculator Utility + +### βœ… Strengths +- Pure functions, no side effects +- Good mathematical accuracy + +### πŸ’‘ Refactoring Suggestions + +#### Suggestion 1: Extract Magic Numbers +**Current Code:** +```javascript +function calculateFee(amount) { + return amount * 0.029 + 0.30; +} +``` + +**Refactored Code:** +```javascript +const STRIPE_PERCENTAGE_FEE = 0.029; +const STRIPE_FIXED_FEE = 0.30; + +function calculateFee(amount) { + return amount * STRIPE_PERCENTAGE_FEE + STRIPE_FIXED_FEE; +} +``` + +**Benefits:** +- Self-documenting code +- Easier to update fees +- Clearer business logic + +#### Suggestion 2: Add Input Validation +**Current Code:** +```javascript +function calculateFee(amount) { + return amount * 0.029 + 0.30; +} +``` + +**Refactored Code:** +```javascript +function calculateFee(amount) { + if (typeof amount !== 'number' || amount < 0) { + throw new Error('Amount must be a non-negative number'); + } + return amount * STRIPE_PERCENTAGE_FEE + STRIPE_FIXED_FEE; +} +``` + +**Benefits:** +- Prevents calculation errors +- Fails fast with clear error +- Self-validating function + +[...continues with more suggestions...] + +Would you like me to apply these refactorings? + +[Confidence: 0.9] +``` + +## Integration Points + +- Works with `spec-driven` skill during execution phase +- Works with `git-workflow` skill for pre-commit reviews +- Works with `systematic-testing` skill to verify test quality +- Triggered automatically before commits if integrated + +## Notes + +- Be thorough but constructive +- Prioritize issues appropriately +- Always provide specific code examples +- Explain WHY something is an issue, not just WHAT +- Offer concrete solutions, not just criticism +- Balance between perfectionism and pragmatism +- Focus on high-impact improvements diff --git a/skills/documentation/SKILL.md b/skills/documentation/SKILL.md new file mode 100644 index 0000000..3a4e6f3 --- /dev/null +++ b/skills/documentation/SKILL.md @@ -0,0 +1,569 @@ +--- +name: documentation +description: Use when writing or updating documentation - generates function docs, API specs, architecture diagrams (Mermaid), READMEs, code explanations. Activates when user says "document this", "write README", "explain this code", mentions "docs", "documentation", "API docs", or asks "how does this work?". +--- + +# Documentation Skill + +## Purpose + +Generate comprehensive, maintainable documentation including code docstrings, API specifications, architecture diagrams, README files, and clear code explanations. Makes code understandable for future developers (including future you). + +## Activation Triggers + +Activate this skill when: +- User says "document this" +- User asks "how does this work?" +- User asks "explain this code" +- User mentions "README", "docs", or "documentation" +- After completing a feature +- When API endpoints are created +- User says "write comments for this" +- User asks "what does this function do?" + +## Documentation Types + +### 1. Code Documentation (Docstrings) + +**Goal:** Clear, comprehensive function/class documentation + +**Example Format:** + +```python +def function_name(param1: Type, param2: Type) -> ReturnType: + """ + Brief one-line description. + + Detailed explanation of purpose, behavior, and context. + + Args: + param1: Description with type and example values + param2: Description with constraints + + Returns: + Description of return value and meaning + + Example: + >>> function_name(example_value1, example_value2) + expected_output + + Raises: + ErrorType: When and why this error occurs + + Note: + Important details, gotchas, performance considerations + """ +``` + +**Key Components:** +- **Brief description** (one line) +- **Detailed explanation** (purpose and behavior) +- **Args/Parameters** (types, constraints, examples) +- **Returns** (type and meaning) +- **Example** (realistic usage) +- **Raises/Throws** (error conditions) +- **Note** (implementation details) + +**Language-Specific:** +- **Python:** Use `"""triple quotes"""`, Args/Returns/Raises format +- **JavaScript/TypeScript:** Use JSDoc `/** */`, @param/@returns/@throws tags +- **Java:** Use Javadoc `/** */`, @param/@return/@throws tags +- **C#:** Use XML comments `/// ` + +### 2. API Documentation + +**Goal:** Complete API reference for endpoints + +**REST API Example:** + +```markdown +## Authentication API + +### POST /api/auth/login + +Authenticate user and return JWT access token. + +**Request:** + +```json +{ + "email": "user@example.com", + "password": "SecureP@ss123" +} +``` + +**Request Schema:** +- `email` (string, required): Valid email address +- `password` (string, required): User password, min 8 characters + +**Response (200 OK):** + +```json +{ + "success": true, + "data": { + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "expiresIn": 3600, + "user": { + "id": "uuid-here", + "email": "user@example.com", + "name": "John Doe" + } + } +} +``` + +**Response Schema:** +- `success` (boolean): Operation status +- `data.accessToken` (string): JWT access token (1 hour expiry) +- `data.refreshToken` (string): Refresh token (30 days expiry) +- `data.expiresIn` (number): Access token expiry in seconds +- `data.user` (object): User profile information + +**Error Responses:** + +**401 Unauthorized - Invalid Credentials:** +```json +{ + "success": false, + "error": { + "code": "INVALID_CREDENTIALS", + "message": "Email or password is incorrect" + } +} +``` + +**400 Bad Request - Validation Error:** +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "Invalid email format", + "details": { + "field": "email", + "value": "invalid-email" + } + } +} +``` + +**429 Too Many Requests - Rate Limited:** +```json +{ + "success": false, + "error": { + "code": "RATE_LIMITED", + "message": "Too many login attempts. Try again in 15 minutes.", + "retryAfter": 900 + } +} +``` + +**Example Usage:** + +```bash +# cURL +curl -X POST https://api.example.com/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"user@example.com","password":"SecureP@ss123"}' + +# JavaScript (fetch) +const response = await fetch('https://api.example.com/api/auth/login', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + email: 'user@example.com', + password: 'SecureP@ss123' + }) +}); + +const data = await response.json(); +console.log(data.data.accessToken); +``` + +**Security Notes:** +- Always use HTTPS in production +- Passwords must never be logged +- Rate limiting: 5 attempts per 15 minutes per IP +- Access tokens expire in 1 hour +- Refresh tokens expire in 30 days +``` + +### 3. Architecture Documentation + +**Goal:** Clear system overview and component relationships + +**Example:** + +```markdown +# System Architecture: Trading Platform + +## Overview + +High-performance trading platform built with microservices architecture, +supporting real-time market data, automated strategy execution, and +portfolio management. + +## System Diagram + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Frontend β”‚ + β”‚ (React SPA) β”‚ + β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ HTTPS/WSS + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ API Gateway β”‚ + β”‚ (Auth, Rate Limiting) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Auth Service β”‚ β”‚ Trading Service β”‚ + β”‚ (JWT, Sessions) β”‚ β”‚ (Orders, Trades) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + β”‚ β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ User Database β”‚ β”‚ Trading Database β”‚ + β”‚ (PostgreSQL) β”‚ β”‚ (PostgreSQL) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Market Data β”‚ + β”‚ (WebSocket) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Core Components + +### 1. API Gateway +**Responsibility:** Entry point for all client requests + +**Functions:** +- Request routing to appropriate service +- JWT token validation +- Rate limiting (100 req/min per user) +- Request/response logging +- CORS handling + +**Technology:** Node.js + Express +**Scaling:** Horizontal (3+ instances behind load balancer) + +### 2. Auth Service +**Responsibility:** User authentication and session management + +**Functions:** +- User registration and login +- JWT token generation (access + refresh) +- Session management with Redis +- Password hashing with bcrypt +- OAuth integration (Google, GitHub) + +**Technology:** Node.js + PostgreSQL + Redis +**Scaling:** Stateless, horizontal scaling + +### 3. Trading Service +**Responsibility:** Order execution and portfolio management + +**Functions:** +- Place/cancel orders +- Real-time position tracking +- P&L calculations +- Risk management checks +- Strategy execution + +**Technology:** Node.js + PostgreSQL + WebSocket +**Scaling:** Horizontal with sticky sessions + +## Data Flow + +### Login Flow +1. User submits email/password to Frontend +2. Frontend sends POST /api/auth/login to API Gateway +3. API Gateway routes to Auth Service +4. Auth Service validates credentials against User Database +5. Auth Service generates JWT tokens +6. Tokens cached in Redis for fast validation +7. Tokens returned to Frontend +8. Frontend stores tokens in memory/localStorage + +### Order Placement Flow +1. User creates order in Frontend +2. Frontend sends POST /api/orders with JWT +3. API Gateway validates JWT +4. Request routed to Trading Service +5. Trading Service validates order parameters +6. Trading Service checks account balance/positions +7. Trading Service applies risk management rules +8. Order saved to Trading Database +9. Order sent to market via Market Data service +10. Confirmation returned to Frontend +11. WebSocket update sent to Frontend with execution status + +## Integration Points + +### External Services +- **Alpaca API**: Market data and order execution +- **Redis Cloud**: Session caching (512MB) +- **Supabase**: Database hosting (PostgreSQL) +- **Vercel**: Frontend hosting and API routes + +### Internal APIs +- Auth Service β†’ Trading Service: User validation +- Trading Service β†’ Market Data: Real-time prices +- All Services β†’ API Gateway: Centralized routing + +## Security Architecture + +### Authentication +- JWT tokens with RS256 signing +- Access tokens: 1 hour expiry +- Refresh tokens: 30 days expiry +- Tokens stored in httpOnly cookies (production) + +### Authorization +- Role-based access control (user, admin) +- Resource-level permissions +- API key authentication for service-to-service + +### Data Protection +- All passwords hashed with bcrypt (cost 12) +- PII encrypted at rest (AES-256) +- TLS 1.3 for all external communication +- Database connection pooling with SSL + +## Performance Considerations + +### Caching Strategy +- Session tokens cached in Redis (1 hour TTL) +- Market data cached in memory (1 second TTL) +- User profiles cached (5 minute TTL) + +### Database Optimization +- Indexes on frequently queried columns +- Connection pooling (max 20 connections) +- Read replicas for reporting queries + +### Scaling Strategy +- Horizontal scaling for stateless services +- Vertical scaling for database +- CDN for static assets +- Background jobs for heavy computations + +## Monitoring & Observability + +### Metrics +- Request latency (p50, p95, p99) +- Error rates by endpoint +- Active user sessions +- Order execution time + +### Logging +- Structured JSON logs +- Centralized logging (CloudWatch) +- Correlation IDs for request tracing + +### Alerts +- High error rate (>1% for 5 minutes) +- Slow responses (>500ms p95) +- Database connection pool exhaustion +- Failed authentication attempts spike +``` + +### 4. README Generation + +**Goal:** Comprehensive project README + +**Essential Sections:** + +```markdown +# [Project Name] + +[One-line description] - [What problem it solves] + +## Features +- Key feature 1 +- Key feature 2 +- Key feature 3 + +## Installation +\`\`\`bash +git clone [repo-url] +cd [repo-name] +npm install # or pip install -r requirements.txt +cp .env.example .env # Configure environment +npm run dev +\`\`\` + +## Usage +\`\`\`javascript +// Basic example showing main functionality +const result = await mainFunction(params); +\`\`\` + +## Configuration +| Variable | Description | Required | +|----------|-------------|----------| +| `DATABASE_URL` | DB connection string | Yes | +| `API_KEY` | External API key | Yes | + +## Development +\`\`\`bash +npm test # Run tests +npm run lint # Check code style +npm run build # Production build +\`\`\` + +## License +MIT - see [LICENSE](LICENSE) +``` + +**Optional Sections** (add as needed): +- **Demo:** Link to live demo or screenshots +- **API Reference:** Detailed API docs +- **Project Structure:** Directory layout +- **Deployment:** Docker/cloud deployment steps +- **Contributing:** How to contribute +- **Acknowledgments:** Credits and thanks + +### 5. Code Explanations + +**Goal:** Clear explanations of complex code + +**Process:** + +1. **High-Level Purpose** + - What problem does this solve? + - Where does it fit in the system? + +2. **Step-by-Step Logic** + - Break down into phases + - Explain each step clearly + - Use analogies when helpful + +3. **Key Algorithms/Patterns** + - Identify important algorithms + - Explain why this approach + - Note time/space complexity + +4. **Edge Cases** + - What unusual inputs are handled? + - What assumptions are made? + - What validation is performed? + +**Example Explanation:** + +```markdown +## Explanation: Position Size Calculator + +### Purpose +This function calculates how many shares to buy based on risk management +principles. It ensures that no single trade risks more than a specified +percentage of the account balance. + +### How It Works + +**Step 1: Validate Inputs** +First, we check that all inputs make sense: +- Account balance must be positive (can't trade with $0) +- Risk percentage must be between 0-100% (but really should be 1-5%) +- Entry price can't equal stop loss (would mean no risk defined) + +**Step 2: Calculate Dollar Risk** +We determine how much money we're willing to lose: +``` +risk_amount = account_balance * risk_percentage +``` +Example: $10,000 account Γ— 2% = $200 risk + +**Step 3: Calculate Risk Per Share** +We figure out how much we'd lose per share if stopped out: +``` +risk_per_share = |entry_price - stop_loss| +``` +Example: |$150.50 - $148.00| = $2.50 per share + +**Step 4: Calculate Position Size** +Divide total risk by per-share risk: +``` +position_size = risk_amount / risk_per_share +``` +Example: $200 Γ· $2.50 = 80 shares + +### Why This Approach? + +This is the "fixed percentage risk" method, which is standard in trading +because: +1. **Consistency**: Every trade risks the same percentage +2. **Scalability**: Works as account grows/shrinks +3. **Protection**: Limits damage from losing trades +4. **Simplicity**: Easy to understand and implement + +### Edge Cases Handled + +- **Entry equals stop**: Raises error (infinite position size) +- **Negative prices**: Absolute value prevents issues +- **Fractional shares**: Rounds down to whole shares +- **Zero risk**: Would cause division by zero, caught by validation + +### Alternative Approaches + +We could also use: +1. **Fixed dollar risk**: Risk same $ amount every trade (doesn't scale) +2. **Kelly Criterion**: Math-based optimal position (requires win rate data) +3. **Volatility-based**: Use ATR instead of stop distance (more complex) + +We chose fixed percentage for simplicity and reliability. +``` + +## When to Document + +**Always Document:** +- Public APIs and endpoints +- Complex algorithms +- Non-obvious logic +- Security-sensitive code +- Performance-critical sections +- Error handling strategies + +**Consider Documenting:** +- Helper functions with multiple params +- Class constructors +- Configuration options +- Database schema + +**Don't Bother Documenting:** +- Trivial getters/setters +- Self-explanatory code +- Temporary/experimental code + +## Best Practices + +1. **Write for Future You**: Assume you'll forget everything in 6 months +2. **Explain Why, Not What**: Code shows what, docs explain why +3. **Keep Examples Current**: Update examples when code changes +4. **Use Consistent Format**: Follow language conventions +5. **Be Concise**: Every word should add value +6. **Use Active Voice**: "Returns user" not "User is returned" +7. **Include Edge Cases**: Document unusual inputs and outputs +8. **Update With Code**: Outdated docs are worse than no docs + +## Integration Points + +- Works with `spec-driven` skill for feature documentation +- Works with `code-quality` skill to verify docs exist +- Auto-triggered after feature completion + +## Notes + +- Default to clear code over comments (code is always correct, comments lie) +- Good naming reduces need for documentation +- Complex logic deserves explanation +- APIs require comprehensive documentation +- When in doubt, document it diff --git a/skills/git-workflow/SKILL.md b/skills/git-workflow/SKILL.md new file mode 100644 index 0000000..d20b5ee --- /dev/null +++ b/skills/git-workflow/SKILL.md @@ -0,0 +1,593 @@ +--- +name: git-workflow +description: Use when working with git operations - generates smart commit messages (present tense, imperative), manages branches, creates PRs with summaries, follows git best practices. Activates when user says "commit this", "create PR", "push changes", mentions "git", "branch", "merge", or before committing code. +--- + +# Git Workflow Skill + +## Purpose + +Manage git operations with best practices, generating meaningful commit messages, managing branches safely, creating comprehensive pull requests, and preventing common git mistakes. + +## Activation Triggers + +Activate this skill when: +- User says "commit my changes" +- User mentions "create a branch" +- User asks to "create a PR" or "pull request" +- User says "push to remote" +- Before any destructive git operation +- User mentions git or version control + +## Core Capabilities + +### 1. Smart Commits + +**Goal:** Generate meaningful, consistent commit messages that explain WHY changes were made + +**Process:** + +1. **Analyze Changes** + ```bash + # Check what files changed + git status + + # See actual changes + git diff + ``` + +2. **Understand Intent** + - What was added, modified, or removed? + - What problem does this solve? + - What feature does this enable? + +3. **Generate Commit Message** + Follow this format: + ``` + [type]: [concise description in present tense] + ``` + + **Commit Types:** + - `feat` - New feature + - `fix` - Bug fix + - `refactor` - Code restructuring without behavior change + - `test` - Adding or updating tests + - `docs` - Documentation changes + - `chore` - Maintenance tasks (deps, config, etc.) + - `style` - Code formatting (no logic change) + - `perf` - Performance improvements + + **Message Guidelines:** + - Present tense, imperative mood ("Add" not "Added" or "Adds") + - Concise but descriptive + - Focus on WHAT and WHY, not HOW + - Under 72 characters for first line + - No period at the end + +4. **Show and Confirm** + Present the commit message to user: + ``` + Proposed commit message: + feat: Add JWT authentication with refresh tokens + + This will commit: + - src/auth/jwt.js + - src/auth/refresh.js + - tests/auth/jwt.test.js + + Proceed with this commit? + ``` + +5. **Execute and Verify** + ```bash + # Stage files if not already staged + git add [files] + + # Commit with generated message + git commit -m "feat: Add JWT authentication with refresh tokens" + + # Verify commit + git log -1 --oneline + ``` + +**Examples of Good Commit Messages:** +``` +feat: Add RSI indicator to market analysis +fix: Handle division by zero in position sizing +refactor: Extract strategy validation into separate function +test: Add edge cases for order execution +docs: Update API documentation with new endpoints +chore: Update dependencies to latest versions +perf: Optimize database queries with indexes +``` + +**Examples of Bad Commit Messages (Avoid):** +``` +updated files ❌ Too vague +fixed bug ❌ Which bug? +WIP ❌ Not descriptive +asdfgh ❌ Nonsense +Added new stuff ❌ Past tense, vague +implemented feature ❌ Past tense, which feature? +``` + +### 2. Branch Management + +**Branch Naming Conventions:** + +Follow this structure: `[type]/[description]` + +**Branch Types:** +- `feature/[feature-name]` - New features +- `fix/[issue-description]` - Bug fixes +- `refactor/[component-name]` - Code restructuring +- `experiment/[idea-name]` - Experimental work +- `hotfix/[critical-issue]` - Urgent production fixes + +**Examples:** +``` +feature/user-authentication +fix/login-timeout-error +refactor/payment-processing +experiment/ml-price-prediction +hotfix/security-vulnerability +``` + +**Branch Operations:** + +**Creating Branch:** +```bash +# Create and switch to new branch +git checkout -b feature/user-authentication + +# Or with newer syntax +git switch -c feature/user-authentication +``` + +**Switching Branches:** +```bash +# Switch to existing branch +git checkout feature/user-authentication + +# Or with newer syntax +git switch feature/user-authentication +``` + +**Listing Branches:** +```bash +# Local branches +git branch + +# All branches (including remote) +git branch -a + +# With last commit info +git branch -v +``` + +**Deleting Branches:** +```bash +# Delete local branch (safe - prevents deleting unmerged) +git branch -d feature/old-feature + +# Force delete (use with caution) +git branch -D feature/abandoned-work + +# Delete remote branch +git push origin --delete feature/old-feature +``` + +**Safety Warnings:** + +Before dangerous operations, warn user: +``` +⚠️ WARNING: You're about to push to main/master +This is generally discouraged. Consider: +1. Creating a feature branch +2. Opening a pull request for review + +Proceed anyway? (yes/no) +``` + +### 3. Pull Request Creation + +**Goal:** Create comprehensive PRs with clear context and checklists + +**Process:** + +1. **Analyze All Commits** + ```bash + # See all commits in this branch + git log main..HEAD --oneline + + # See detailed changes + git diff main...HEAD + ``` + +2. **Review Changes** + - What's the overall purpose? + - What are the key changes? + - Are there breaking changes? + - What needs testing? + +3. **Generate PR Description** + Use this template: + + ```markdown + ## Summary + [Brief overview of what this PR does and why] + + ## Changes + - [Key change 1] + - [Key change 2] + - [Key change 3] + + ## Type of Change + - [ ] Bug fix (non-breaking change which fixes an issue) + - [ ] New feature (non-breaking change which adds functionality) + - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) + - [ ] Documentation update + + ## Testing + - [ ] Unit tests pass + - [ ] Integration tests pass + - [ ] Manual testing completed + - [ ] Edge cases tested + + ## Code Quality + - [ ] Code follows project style guidelines + - [ ] Self-review completed + - [ ] Comments added for complex logic + - [ ] No console.log or debug code left + - [ ] Documentation updated + + ## Screenshots (if applicable) + [Add screenshots for UI changes] + + ## Related Issues + Closes #[issue number] + ``` + +4. **Create PR with gh CLI** + ```bash + # Create PR with title and body + gh pr create --title "[Type]: Brief description" --body "$(cat <<'EOF' + ## Summary + [Description] + + ## Changes + - [Change 1] + - [Change 2] + + ## Testing + - [ ] All tests pass + EOF + )" + ``` + +5. **Return PR URL** + ``` + βœ… Pull Request Created! + + URL: https://github.com/user/repo/pull/42 + Title: feat: Add user authentication system + + Next steps: + - Request reviewers + - Wait for CI/CD checks + - Address review feedback + ``` + +### 4. Safety Checks + +**Pre-Commit Safety:** + +Before allowing commit, check: + +1. **No Secrets** + ```bash + # Look for potential secrets + git diff --cached | grep -i "api_key\|secret\|password\|token" + ``` + + If found: + ``` + ⚠️ SECURITY WARNING: Potential secrets detected! + + Found suspicious patterns: + - API_KEY on line 23 of config.js + + DO NOT commit secrets to version control! + + Actions: + 1. Add to .gitignore + 2. Use environment variables + 3. Use secret management tools + + Abort commit? (yes/no) + ``` + +2. **Tests Pass** + ```bash + # Run test suite + npm test + ``` + + If tests fail: + ``` + ⚠️ TEST FAILURE: Cannot commit with failing tests + + Failed tests: + - auth.test.js: login should return token + - auth.test.js: invalid password should reject + + Fix tests before committing. + ``` + +3. **Large Commits Warning** + If more than 10 files changed: + ``` + ⚠️ LARGE COMMIT WARNING + + This commit changes 23 files. + Consider breaking into smaller, focused commits: + + Example: + 1. Commit core logic changes + 2. Commit test updates + 3. Commit documentation + + Proceed with large commit anyway? (yes/no) + ``` + +**Pre-Push Safety:** + +Before pushing: + +1. **Check Current Branch** + ```bash + git branch --show-current + ``` + + If on main/master: + ``` + ⚠️ DANGER: You're on the main branch! + + Direct pushes to main are discouraged. + Recommended workflow: + 1. Create feature branch + 2. Make changes + 3. Open pull request + 4. Merge after review + + Proceed with push to main? (yes/no) + ``` + +2. **Force Push Warning** + If user attempts `git push --force`: + ``` + 🚨 CRITICAL WARNING: Force push detected! + + Force push to main/master is DESTRUCTIVE and will: + - Rewrite history for all collaborators + - Potentially lose work from others + - Break ongoing pull requests + + This should ONLY be done if you know exactly what you're doing. + + Branch: [branch-name] + Target: origin/[branch-name] + + Type "I understand the risks" to proceed: + ``` + +**Pre-Merge Safety:** + +Before merging: + +1. **Check for Conflicts** + ```bash + git merge --no-commit --no-ff [branch] + git merge --abort + ``` + +2. **Verify CI Status** + ```bash + gh pr checks + ``` + +3. **Confirm Approvals** + ```bash + gh pr view --json reviews + ``` + +## Workflow Examples + +### Example 1: Standard Feature Development + +**User:** "I've finished the authentication feature, let's commit" + +**Assistant:** +``` +Activating git-workflow skill for smart commit. + +Analyzing changes... +$ git status +$ git diff + +Changes detected: +- src/auth/login.js (new file, 150 lines) +- src/auth/session.js (new file, 80 lines) +- tests/auth/login.test.js (new file, 200 lines) +- package.json (modified, +2 dependencies) + +Commit type: feat (new feature) + +Proposed commit message: +feat: Add JWT authentication with session management + +This includes: +- Login endpoint with JWT generation +- Session management with refresh tokens +- Comprehensive test coverage + +Proceed with this commit? (yes/no) +``` + +**User:** "yes" + +**Assistant:** +``` +Running pre-commit checks... +βœ… No secrets detected +βœ… Tests passing (52/52) +βœ… Linter clean + +Committing... +$ git add src/auth tests/auth package.json +$ git commit -m "feat: Add JWT authentication with session management" + +βœ… Commit successful! + +[feature/user-authentication a1b2c3d] feat: Add JWT authentication with session management + 4 files changed, 432 insertions(+) + +Next steps: +- Push to remote: git push -u origin feature/user-authentication +- Create pull request + +Would you like me to push and create a PR? + +[Confidence: 0.9] +``` + +### Example 2: Creating Pull Request + +**User:** "Create a PR for my authentication feature" + +**Assistant:** +``` +Activating git-workflow skill for PR creation. + +Analyzing branch changes... +$ git log main..HEAD --oneline + +Commits to include: +a1b2c3d feat: Add JWT authentication with session management +b2c3d4e test: Add edge cases for token expiration +c3d4e5f docs: Update API documentation for auth endpoints + +$ git diff main...HEAD --stat + +Files changed: +- src/auth/ (6 files, 430 additions) +- tests/auth/ (4 files, 350 additions) +- docs/api.md (45 additions) + +Generating PR description... + +## Summary +Implements JWT-based authentication system with session management and refresh token support. Provides secure user login, token validation, and automatic session renewal. + +## Changes +- JWT token generation and validation +- Refresh token mechanism for extended sessions +- Session middleware for protected routes +- Comprehensive test suite with edge cases +- API documentation updates + +## Type of Change +- [x] New feature (non-breaking change which adds functionality) + +## Testing +- [x] Unit tests pass (52/52) +- [x] Integration tests pass (12/12) +- [x] Manual testing completed +- [x] Edge cases tested (token expiration, invalid tokens) + +## Code Quality +- [x] Code follows project style guidelines +- [x] Self-review completed +- [x] Comments added for complex logic +- [x] No debug code left +- [x] Documentation updated + +Creating PR... +$ gh pr create --title "feat: Add JWT authentication system" --body "[body]" + +βœ… Pull Request Created! + +URL: https://github.com/user/repo/pull/42 +Title: feat: Add JWT authentication system +Status: Open + +Next steps: +1. Request reviewers: gh pr review --request @reviewer +2. Monitor CI checks: gh pr checks +3. Address feedback when reviews come in + +[Confidence: 0.9] +``` + +### Example 3: Preventing Dangerous Operation + +**User:** "Push my changes to main" + +**Assistant:** +``` +Activating git-workflow skill for safety check. + +$ git branch --show-current +main + +⚠️ DANGER: You're about to push directly to main! + +This is generally discouraged because: +- No code review before merging +- Potential to break production +- No CI/CD verification gate +- Difficult to revert if issues arise + +Recommended workflow: +1. Create feature branch: git checkout -b feature/your-feature +2. Push to feature branch: git push -u origin feature/your-feature +3. Create pull request: gh pr create +4. Get code review +5. Merge via PR after approval + +Alternative: If this is your personal project and you're certain, you can: +- Ensure all tests pass first +- Review your own changes carefully +- Proceed with direct push + +What would you like to do? +1. Create feature branch and PR (recommended) +2. Run tests then push to main (risky) +3. Cancel operation + +[Confidence: 1.0] +``` + +## Integration Points + +- Works with `code-quality` skill for pre-commit reviews +- Works with `spec-driven` skill for commit messages during execution +- Works with `systematic-testing` skill to verify tests before commit + +## Best Practices + +1. **Commit Often**: Small, frequent commits are better than large, infrequent ones +2. **One Concern Per Commit**: Each commit should represent one logical change +3. **Write Good Messages**: Future you will thank present you +4. **Review Before Push**: Always review your own changes first +5. **Use Branches**: Never work directly on main +6. **Create PRs**: Always use pull requests, even for solo projects +7. **Keep History Clean**: Use meaningful commits, not "WIP" or "fix" + +## Notes + +- Always prioritize safety over convenience +- Default to the safer option when in doubt +- Educate user on git best practices +- Prevent destructive operations with clear warnings +- Make it easy to do the right thing diff --git a/skills/skill-maker/SKILL.md b/skills/skill-maker/SKILL.md new file mode 100644 index 0000000..9ae90a3 --- /dev/null +++ b/skills/skill-maker/SKILL.md @@ -0,0 +1,657 @@ +--- +name: skill-maker +description: Use when creating new skills or editing existing skills - combines official skill authoring best practices with TDD methodology (test with subagents before deployment, iterate until bulletproof). Activates when user wants to create/update a skill that extends Claude's capabilities. +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +--- + +# Skill Maker + +## Overview + +**Creating skills IS Test-Driven Development applied to process documentation.** + +This skill combines official Anthropic skill authoring best practices with TDD methodology. Write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes). + +**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. + +## What is a Skill? + +Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasksβ€”they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge. + +**Skills provide:** +1. Specialized workflows - Multi-step procedures for specific domains +2. Tool integrations - Instructions for working with specific file formats or APIs +3. Domain expertise - Company-specific knowledge, schemas, business logic +4. Bundled resources - Scripts, references, and assets for complex tasks + +**Skills are:** Reusable techniques, patterns, tools, reference guides + +**Skills are NOT:** Narratives about how you solved a problem once, one-off solutions, or project-specific conventions + +## When to Create a Skill + +**Create when:** +- Technique wasn't intuitively obvious to you +- You'd reference this again across projects +- Pattern applies broadly (not project-specific) +- Others would benefit +- You want to ensure consistent behavior across Claude instances + +**Don't create for:** +- One-off solutions +- Standard practices well-documented elsewhere +- Project-specific conventions (put those in project CLAUDE.md) + +## Skill Types + +### Technique +Concrete method with steps to follow (testing patterns, refactoring workflows) + +### Pattern +Way of thinking about problems (architectural approaches, design principles) + +### Reference +API docs, syntax guides, tool documentation (library references, command docs) + +### Discipline-Enforcing +Rules and requirements (TDD enforcement, code quality standards) + +--- + +## Skill Anatomy + +Every skill consists of a required SKILL.md file and optional bundled resources: + +``` +skill-name/ +β”œβ”€β”€ SKILL.md (required) +β”‚ β”œβ”€β”€ YAML frontmatter metadata (required) +β”‚ β”‚ β”œβ”€β”€ name: (required, lowercase-with-hyphens) +β”‚ β”‚ β”œβ”€β”€ description: (required, max 1024 chars) +β”‚ β”‚ └── allowed-tools: (optional, restricts tool access) +β”‚ └── Markdown instructions (required) +└── Bundled Resources (optional) + β”œβ”€β”€ scripts/ - Executable code (Python/Bash/etc.) + β”œβ”€β”€ references/ - Documentation loaded as needed + └── assets/ - Files used in output (templates, icons) +``` + +### SKILL.md (required) + +**Frontmatter requirements:** +- `name`: Letters, numbers, hyphens only (max 64 chars) +- `description`: Third-person, includes BOTH what it does AND when to use it (max 1024 chars) +- `allowed-tools`: Optional list restricting tool access for safety + +**Writing style:** Use **imperative/infinitive form** (verb-first instructions), not second person +- βœ… Good: "To accomplish X, do Y" +- ❌ Bad: "You should do X" + +### Bundled Resources (optional) + +#### Scripts (`scripts/`) +**When to include:** When the same code is rewritten repeatedly or deterministic reliability is needed +- Token efficient (not loaded unless referenced) +- Deterministic behavior +- May be executed without loading into context +- Example: `scripts/rotate_pdf.py` + +#### References (`references/`) +**When to include:** For documentation that Claude should reference while working +- Database schemas, API documentation +- Domain knowledge, company policies +- Detailed workflow guides +- Keeps SKILL.md lean (<5k words) +- **Best practice:** If files are large (>10k words), include grep search patterns in SKILL.md +- **Avoid duplication:** Information should live in either SKILL.md or references, not both + +#### Assets (`assets/`) +**When to include:** Files used within the output Claude produces +- Templates, images, icons +- Boilerplate code (React templates, HTML starters) +- Sample documents +- Not loaded into context, just used directly + +### Progressive Disclosure Principle + +Skills use a three-level loading system to manage context efficiently: + +1. **Metadata (name + description)** - Always in context (~100 words) +2. **SKILL.md body** - When skill triggers (<5k words, keep lean) +3. **Bundled resources** - As needed by Claude (scripts, references, assets) + +--- + +## The Iron Law + +``` +NO SKILL WITHOUT A FAILING TEST FIRST +``` + +This applies to NEW skills AND EDITS to existing skills. + +Write skill before testing? Delete it. Start over. +Edit skill without testing? Same violation. + +**No exceptions:** +- Not for "simple additions" +- Not for "just adding a section" +- Not for "documentation updates" +- Don't keep untested changes as "reference" +- Delete means delete + +--- + +## RED-GREEN-REFACTOR for Skills + +Follow the TDD cycle adapted for documentation: + +### RED: Write Failing Test (Baseline) + +Run pressure scenario WITHOUT the skill. Document exact behavior: +- What choices did the agent make? +- What rationalizations did they use (verbatim)? +- Which pressures triggered violations? + +**How to test:** +1. Create a new conversation/subagent +2. Present a scenario that would benefit from the skill +3. Apply pressure (time constraints, sunk cost, complexity) +4. Document failures, workarounds, rationalizations + +This is "watch the test fail" - you must see what agents naturally do before writing the skill. + +### GREEN: Write Minimal Skill + +Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases. + +Run same scenarios WITH skill present. Agent should now comply. + +**Verification:** +1. Create a new conversation with skill loaded +2. Run identical scenarios +3. Agent should follow skill guidance +4. Document any new violations + +### REFACTOR: Close Loopholes + +Agent found new rationalization? Add explicit counter. Re-test until bulletproof. + +**For discipline-enforcing skills:** +- Build rationalization table from all test iterations +- Create "Red Flags" list of common violations +- Add explicit "No exceptions" counters +- Address "spirit vs letter" arguments upfront + +--- + +## Skill Creation Process + +### Step 1: Understanding with Concrete Examples + +To create an effective skill, clearly understand concrete examples of how it will be used. + +**Ask questions like:** +- "What functionality should this skill support?" +- "Can you give examples of how this skill would be used?" +- "What would a user say that should trigger this skill?" +- "Are there other ways you imagine this skill being used?" + +**Avoid overwhelming:** Ask most important questions first, follow up as needed. + +**Conclude when:** Clear sense of the functionality the skill should support. + +**UltraThink Skill Design:** +Before creating skill structure, activate deep thinking: + +> πŸ—£ Say: "Let me ultrathink what this skill should really accomplish and how it fits the ecosystem." + +**Question fundamentals:** +- Is this really a skill, or project-specific documentation? +- What's the reusable pattern vs. one-off solution? +- How will future Claude discover and activate this skill? +- What could go wrong if agents misinterpret this skill? +- Are we solving the right problem? +- What similar skills exist, and how does this differ? +- What are we NOT including, and why? + +**For discipline-enforcing skills, ultrathink:** +- What rationalizations will agents use to circumvent this? +- How can we make the "right thing" the easy thing? +- What pressure scenarios will test this skill? + +**After UltraThink:** Create skill that addresses reusable patterns with clear activation triggers. + +### Step 2: Planning Reusable Contents + +For each concrete example, analyze: +1. How would you execute this from scratch? +2. What scripts, references, and assets would help when executing repeatedly? + +**Examples:** + +**PDF editing:** "Rotate this PDF" +- Analysis: Rotating requires re-writing same code each time +- Resource: `scripts/rotate_pdf.py` + +**BigQuery queries:** "How many users logged in today?" +- Analysis: Requires re-discovering table schemas each time +- Resource: `references/schema.md` + +**Frontend apps:** "Build me a todo app" +- Analysis: Requires same boilerplate HTML/React each time +- Resource: `assets/hello-world/` template + +### Step 3: Initialize Skill Structure + +Create skill directory manually: + +```bash +mkdir -p dev-workflow/skills/skill-name/{scripts,references,assets} +``` + +Create `SKILL.md` with frontmatter template: + +```markdown +--- +name: skill-name +description: Use when [specific triggers] - [what it does and how it helps] +allowed-tools: Read, Write, Edit, Glob, Grep # Adjust as needed +--- + +# Skill Name + +## Overview +[Core principle in 1-2 sentences] + +## When to Use +[Activation triggers and symptoms] +[When NOT to use] + +## [Main content sections] +... +``` + +### Step 4: Baseline Testing (RED Phase) + +**BEFORE writing skill content:** + +1. Create pressure scenarios (3+ combined pressures for discipline skills) +2. Run scenarios WITHOUT skill present +3. Document baseline behavior verbatim: + - What did agent do? + - What rationalizations did they use? + - What mistakes were made? + +**Pressure types:** +- Time constraints ("quickly", "urgent") +- Sunk cost ("already spent X hours") +- Authority ("the client insists") +- Exhaustion ("we're almost done, just...") + +### Step 5: Write Skill Content (GREEN Phase) + +Answer these three questions in SKILL.md: + +1. **What is the purpose?** (A few sentences in Overview) +2. **When should it be used?** (Activation triggers) +3. **How should Claude use it?** (Procedural instructions, reference bundled resources) + +**Address specific baseline failures** identified in RED phase. + +**Structure recommendation:** + +```markdown +## Overview +Core principle + +## When to Use +- Trigger 1 +- Trigger 2 +- When NOT to use + +## Core Pattern/Process +[Main methodology or workflow] + +## Quick Reference +[Table or bullets for scanning] + +## Implementation/Examples +[Inline code or link to separate file] + +## Common Mistakes +What goes wrong + fixes + +## Red Flags (for discipline skills) +- Flag 1 +- Flag 2 +``` + +### Step 6: Verify Testing (GREEN Phase) + +Run same scenarios WITH skill present: +- Agent should now comply with guidance +- Document any new violations or gaps +- Verify skill addresses original baseline failures + +### Step 7: Close Loopholes (REFACTOR Phase) + +For each new violation: +1. Identify the rationalization +2. Add explicit counter in skill +3. Re-test until bulletproof + +**For discipline-enforcing skills, add:** + +**Rationalization Table:** +```markdown +| Excuse | Reality | +|--------|---------| +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | +``` + +**Red Flags Section:** +```markdown +## Red Flags - STOP and Start Over + +- Code before test +- "I already manually tested it" +- "It's about spirit not ritual" +- "This is different because..." + +**All of these mean: Delete code. Start over with TDD.** +``` + +**Principle Statement:** +```markdown +**Violating the letter of the rules is violating the spirit of the rules.** +``` + +### Step 8: Iteration + +After deploying: +1. Use the skill on real tasks +2. Notice struggles or inefficiencies +3. Identify how SKILL.md or bundled resources should be updated +4. Run baseline tests again (RED phase) +5. Update skill (GREEN phase) +6. Verify fixes (REFACTOR phase) + +--- + +## Claude Search Optimization (CSO) + +**Critical for discovery:** Future Claude needs to FIND your skill. + +### 1. Rich Description Field + +**Format:** Start with "Use when..." to focus on triggering conditions + +**Content:** +- Use concrete triggers, symptoms, and situations +- Describe the *problem* not language-specific symptoms +- Keep triggers technology-agnostic unless skill is tech-specific +- Write in third person + +```yaml +# ❌ BAD: Too abstract, doesn't include when to use +description: For async testing + +# ❌ BAD: First person +description: I can help you with async tests when they're flaky + +# βœ… GOOD: Starts with "Use when", describes problem and solution +description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests + +# βœ… GOOD: Technology-specific with explicit trigger +description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management +``` + +### 2. Keyword Coverage + +Use words Claude would search for: +- Error messages: "Hook timed out", "race condition" +- Symptoms: "flaky", "hanging", "inconsistent" +- Synonyms: "timeout/hang/freeze", "cleanup/teardown" +- Tools: Actual commands, library names, file types + +### 3. Descriptive Naming + +**Use active voice, verb-first:** +- βœ… `creating-skills` not `skill-creation` +- βœ… `testing-async-code` not `async-code-testing` +- βœ… `condition-based-waiting` not `waiting-conditions` + +**Gerunds (-ing) work well for processes:** +- `creating-skills`, `testing-skills`, `debugging-with-logs` + +### 4. Token Efficiency + +**Target word counts:** +- Frequently-loaded skills: <500 words +- Other skills: <1000 words (still be concise) +- Getting-started workflows: <200 words + +**Techniques:** + +**Move details to references:** +```markdown +# ❌ BAD: All details in SKILL.md +[50 lines of API documentation] + +# βœ… GOOD: Reference external file +For complete API documentation, see references/api-docs.md +``` + +**Cross-reference skills:** +```markdown +# ❌ BAD: Repeat workflow details +When testing, follow these 20 steps... + +# βœ… GOOD: Reference other skill +Use test-driven-development skill for testing workflow. +``` + +**Compress examples:** +- One excellent example beats many mediocre ones +- Complete and runnable +- Well-commented explaining WHY +- From real scenario + +--- + +## Testing Different Skill Types + +### Discipline-Enforcing Skills + +**Examples:** TDD enforcement, code quality requirements + +**Test with:** +- Academic questions: Do they understand the rules? +- Pressure scenarios: Do they comply under stress? +- Multiple pressures combined: time + sunk cost + exhaustion + +**Success criteria:** Agent follows rule under maximum pressure + +### Technique Skills + +**Examples:** Refactoring patterns, debugging workflows + +**Test with:** +- Application scenarios: Can they apply correctly? +- Variation scenarios: Do they handle edge cases? +- Missing information tests: Do instructions have gaps? + +**Success criteria:** Agent successfully applies technique to new scenario + +### Pattern Skills + +**Examples:** Architectural approaches, design principles + +**Test with:** +- Recognition scenarios: Do they recognize when pattern applies? +- Application scenarios: Can they use the mental model? +- Counter-examples: Do they know when NOT to apply? + +**Success criteria:** Agent correctly identifies when/how to apply pattern + +### Reference Skills + +**Examples:** API documentation, command references + +**Test with:** +- Retrieval scenarios: Can they find the right information? +- Application scenarios: Can they use what they found correctly? +- Gap testing: Are common use cases covered? + +**Success criteria:** Agent finds and correctly applies reference information + +--- + +## File Organization Patterns + +### Self-Contained Skill +``` +skill-name/ + SKILL.md # Everything inline +``` +**When:** All content fits, no heavy reference needed + +### Skill with Reusable Tool +``` +skill-name/ + SKILL.md # Overview + patterns + helpers.ts # Working code to adapt +``` +**When:** Tool is reusable code, not just narrative + +### Skill with Heavy Reference +``` +skill-name/ + SKILL.md # Overview + workflows + references/ + api-docs.md # 600 lines API reference + schemas.md # 500 lines database schemas + scripts/ + helper.py # Executable tools +``` +**When:** Reference material too large for inline + +--- + +## Common Rationalizations for Skipping Testing + +| Excuse | Reality | +|--------|---------| +| "Skill is obviously clear" | Clear to you β‰  clear to other agents. Test it. | +| "It's just a reference" | References can have gaps. Test retrieval. | +| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | +| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. | +| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. | +| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. | +| "Academic review is enough" | Reading β‰  using. Test application scenarios. | +| "No time to test" | Deploying untested skill wastes more time fixing it later. | + +**All of these mean: Test before deploying. No exceptions.** + +--- + +## Skill Creation Checklist + +Use TodoWrite to create todos for EACH checklist item below. + +**RED Phase - Write Failing Test:** +- [ ] Create pressure scenarios (3+ combined pressures for discipline skills) +- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim +- [ ] Identify patterns in rationalizations/failures + +**GREEN Phase - Write Minimal Skill:** +- [ ] Name uses only letters, numbers, hyphens (max 64 chars) +- [ ] YAML frontmatter with name, description, allowed-tools (max 1024 chars total) +- [ ] Description starts with "Use when..." and includes specific triggers/symptoms +- [ ] Description written in third person +- [ ] Keywords throughout for search (errors, symptoms, tools) +- [ ] Clear overview with core principle +- [ ] Address specific baseline failures identified in RED +- [ ] Code inline OR link to separate file +- [ ] One excellent example (not multi-language) +- [ ] Run scenarios WITH skill - verify agents now comply + +**REFACTOR Phase - Close Loopholes:** +- [ ] Identify NEW rationalizations from testing +- [ ] Add explicit counters (if discipline skill) +- [ ] Build rationalization table from all test iterations +- [ ] Create red flags list +- [ ] Re-test until bulletproof + +**Quality Checks:** +- [ ] Overview answers: What? When? How? +- [ ] Quick reference table or bullets +- [ ] Common mistakes section +- [ ] No narrative storytelling +- [ ] Supporting files only for tools or heavy reference +- [ ] Token count <500 words for frequent skills, <1000 for others + +**Deployment:** +- [ ] Commit skill to git +- [ ] Update skill documentation if needed +- [ ] Consider adding slash command if skill warrants it + +--- + +## Anti-Patterns to Avoid + +### ❌ Narrative Example +"In session 2025-10-03, we found empty projectDir caused..." +**Why bad:** Too specific, not reusable + +### ❌ Multi-Language Dilution +example-js.js, example-py.py, example-go.go +**Why bad:** Mediocre quality, maintenance burden + +### ❌ Generic Labels +helper1, helper2, step3, pattern4 +**Why bad:** Labels should have semantic meaning + +### ❌ Untested Skills +Writing skill without baseline testing +**Why bad:** Guarantees issues in production use + +### ❌ Vague Descriptions +"Helps with coding tasks" +**Why bad:** Claude won't know when to activate it + +--- + +## Integration with Dev-Workflow + +Skills created with this skill-maker should integrate with dev-workflow ecosystem: + +**Leverage existing skills:** +- Use `test-driven-development` for testing methodology examples +- Use `code-quality` for code review patterns +- Use `documentation` for documentation examples +- Use `brainstorming` for design exploration patterns + +**Consider activation context:** +- When should skill activate in the workflow? +- Does it fit planning, implementation, or quality phase? +- Should it auto-activate or require explicit invocation? + +**Tool restrictions:** +- Planning skills: `Read, Write, Glob, Grep` (docs only) +- Implementation skills: `Read, Write, Edit, Glob, Grep, Bash` (full access) +- Quality skills: `Read, Grep, Glob` (analysis only) + +--- + +## The Bottom Line + +**Creating skills IS TDD for process documentation.** + +Same Iron Law: No skill without failing test first. +Same cycle: RED (baseline) β†’ GREEN (write skill) β†’ REFACTOR (close loopholes). +Same benefits: Better quality, fewer surprises, bulletproof results. + +If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation. diff --git a/skills/spec-driven-implementation/SKILL.md b/skills/spec-driven-implementation/SKILL.md new file mode 100644 index 0000000..73a92fb --- /dev/null +++ b/skills/spec-driven-implementation/SKILL.md @@ -0,0 +1,585 @@ +--- +name: spec-driven-implementation +description: Use when ready to implement designed features - breaks design into TDD tasks (Red-Green-Refactor), tracks progress with checkboxes in tasks.md, enforces strict testing discipline. Activates when user says "implement this", "let's code", "start execution", mentions "tasks", "TDD", or uses /dev-workflow:spec commands (tasks, execute). +allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, TodoWrite, TodoRead +--- + +# Spec-Driven Implementation Skill + +## Purpose + +Guide feature implementation through two structured phases: Task Breakdown (TDD) β†’ Execution. This systematic approach ensures test-driven development, quality gates, and tracked progress from design to working code. + +## Activation Triggers + +Activate this skill when: +- User says "implement this feature" or "let's code this" +- User mentions "tasks", "TDD", or "execution" +- User uses `/dev-workflow:spec` command with implementation options (tasks, execute) +- User is ready to start implementation after design approval +- User says "break this down into tasks" +- Design phase is complete and approved + +## Prerequisites + +This skill requires completed planning from `spec-driven-planning` skill: +- [ ] Feature directory exists: `docx/features/[NN-feature-name]/` +- [ ] `requirements.md` is complete with EARS requirements +- [ ] `design.md` is complete and approved + +**If prerequisites are missing:** +> "Implementation requires completed planning. Run `/dev-workflow:spec` and complete options 1-3 first (Feature Creation, Requirements, Design)." + +--- + +## Two-Phase Implementation Workflow + +### Phase 4: Task Breakdown (TDD Focus) + +**Goal:** Break design into small, testable tasks following Red-Green-Refactor + +**Task Structure:** + +Each task follows TDD cycle: +``` +[ ] Task N: [Description] + [ ] RED: Write failing test for [functionality] + [ ] GREEN: Implement minimal code to pass test + [ ] REFACTOR: Clean up and optimize + + Acceptance Criteria: + [ ] [Specific criterion 1] + [ ] [Specific criterion 2] +``` + +**Task Sizing Guidelines:** +- Each task should take 30-60 minutes +- If longer, break into subtasks +- Each task must be independently testable +- Each task produces working, tested code + +**UltraThink Before Task Breakdown:** +Before breaking design into tasks, activate deep thinking if: +- Design involves complex algorithms or data structures +- Integration points between components are unclear +- Multiple implementation strategies are possible +- Edge cases and error handling are non-trivial + +> πŸ—£ Say: "Let me ultrathink the implementation strategy before breaking this into tasks." + +**Questions to ultrathink:** +- What's the simplest implementation that satisfies requirements? +- Which parts are most likely to change? +- Where are the hidden complexities? +- What assumptions might break during implementation? +- How will we test each component in isolation? +- What could we build incrementally vs. all at once? + +**After UltraThink:** Create focused, testable tasks that validate assumptions early. + +**Task Categories:** + +1. **Component Tasks** + - Implement individual components + - One component per task or split if large + +2. **Integration Tasks** + - Connect components + - Test component interactions + - Verify data flow + +3. **Error Handling Tasks** + - Implement error scenarios + - Test edge cases + - Verify error messages + +4. **Documentation Tasks** + - Write docstrings + - Update README + - Create API docs + +5. **Final Verification Tasks** + - Code review + - Performance testing + - Security review + - Manual testing + +**Output:** +Update `docx/features/[NN-feature-name]/tasks.md` with: +- Implementation approach summary +- Organized task list with checkboxes +- Acceptance criteria for each task +- Notes section for implementation considerations + +**User Confirmation:** +> "Tasks defined with TDD cycle. Ready to begin implementation?" + +--- + +### Phase 5: Execution + +**Goal:** Execute tasks systematically with quality gates + +**Execution Workflow:** + +For each task: + +1. **Mark Task as In Progress** + + **Use Edit tool** on `docx/features/[NN-feature-name]/tasks.md`: + + - Find the task header: `[ ] Task N: [description]` + - Replace with: `[β†’] Task N: [description]` + - Also mark the RED phase checkbox as `[β†’]` + + **Example Edit call:** + ``` + Edit tool: + file: docx/features/01-user-auth/tasks.md + old_string: "[ ] Task 3: Implement JWT validation" + new_string: "[β†’] Task 3: Implement JWT validation" + ``` + +2. **RED Phase** + + - Write failing test for the specific functionality + - Run test suite to verify failure (test MUST fail) + - **Use Edit tool** to check off RED phase: `[ ] RED: ...` β†’ `[x] RED: ...` + - Commit: `test: Add test for [functionality]` + +3. **GREEN Phase** + + - Write minimal implementation to make test pass + - Run tests until passing (all tests MUST pass) + - Don't optimize yet (just make it work) + - **Use Edit tool** to check off GREEN phase: `[ ] GREEN: ...` β†’ `[x] GREEN: ...` + - Commit: `feat: Implement [functionality]` + +4. **REFACTOR Phase** + + - Clean up code (remove duplication, improve naming) + - Run tests to ensure still passing + - **Use Edit tool** to check off REFACTOR phase: `[ ] REFACTOR: ...` β†’ `[x] REFACTOR: ...` + - Commit: `refactor: Optimize [component]` + +5. **Mark Task Complete** + + **Use Edit tool** on `docx/features/[NN-feature-name]/tasks.md`: + + - Change task header: `[β†’] Task N: ...` β†’ `[x] Task N: ...` + - Verify all acceptance criteria are checked: `[x]` + - Update Progress Summary section (see instructions below) + +### Task Tracking Protocol + +**CRITICAL: Use Edit tool to update tasks.md - don't just announce progress.** + +#### Workflow Summary + +``` +Start Phase 5 + ↓ +Edit: Status "Not Started" β†’ "In Progress" + ↓ +For each task: + ↓ + Edit: [ ] Task N β†’ [β†’] Task N + Edit: [ ] RED β†’ [β†’] RED + ↓ + Write failing test + ↓ + Edit: [β†’] RED β†’ [x] RED + Edit: [ ] GREEN β†’ [β†’] GREEN + ↓ + Implement code + ↓ + Edit: [β†’] GREEN β†’ [x] GREEN + Edit: [ ] REFACTOR β†’ [β†’] REFACTOR + ↓ + Refactor code + ↓ + Edit: [β†’] REFACTOR β†’ [x] REFACTOR + Edit: [β†’] Task N β†’ [x] Task N + Edit: Update Progress Summary + ↓ +Next task or finish + ↓ +Edit: Status "In Progress" β†’ "Complete" +``` + +#### Edit Tool Usage Pattern + +**Always follow this pattern for every task:** + +1. **Before starting any task:** + ``` + Use Edit tool to change [ ] β†’ [β†’] in tasks.md + ``` + +2. **After completing each phase (RED/GREEN/REFACTOR):** + ``` + Use Edit tool to change [β†’] β†’ [x] for that phase + Use Edit tool to change [ ] β†’ [β†’] for next phase + ``` + +3. **After completing full task:** + ``` + Use Edit tool to change [β†’] β†’ [x] for task header + Use Edit tool to update Progress Summary counts + ``` + +4. **Don't skip these Edit calls** - they're not optional suggestions, they're required operations. + +#### Announcing vs. Modifying + +**Wrong (Just Announcing):** +``` +βœ… Task 1 complete +Moving to Task 2... +``` + +**Right (Actually Modifying + Announcing):** +``` +[Using Edit tool to mark Task 1 complete: [β†’] β†’ [x]] +[Using Edit tool to update Progress Summary: Completed 1/10] +βœ… Task 1 complete + +[Using Edit tool to mark Task 2 in progress: [ ] β†’ [β†’]] +Starting Task 2: JWT token generation... +``` + +#### Progress Summary Maintenance + +The Progress Summary section must stay synchronized: + +**Before any tasks start:** +```markdown +- Total Tasks: 10 +- Completed: 0/10 +- In Progress: None +``` + +**After Task 1 starts:** +```markdown +- Total Tasks: 10 +- Completed: 0/10 +- In Progress: Task 1 - User model with password hashing +``` + +**After Task 1 completes:** +```markdown +- Total Tasks: 10 +- Completed: 1/10 +- In Progress: Task 2 - JWT token generation +``` + +**Use Edit tool** to update these fields after every task completion. + +--- + +**Status Checkpoints:** + +Every 2-3 completed tasks, provide status update: + +``` +πŸ”„ Checkpoint Update: +- βœ… Tests: [N/N] passing +- βœ… Type check: No errors +- βœ… Lint: Clean +- πŸ“ Completed tasks: [X/Y] +- 🎯 Next: [Next task description] + +[Confidence: X.X] +``` + +--- + +### Quick Reference + +**Edit patterns already detailed above. Key reminders:** +- Update Status header when starting/completing implementation +- Use Grep to count tasks if needed: `grep -c "^\- \[x\] Task" tasks.md` +- Update test coverage optionally: Run `npm run test:coverage` and Edit tasks.md + +--- + +**Auto-Trigger Code Quality Review:** + +Before each commit: +- Use Skill tool to invoke: `dev-workflow:code-quality` +- Review changes for issues +- Address critical findings before commit + +**How to activate:** +``` +Use Skill tool: Skill(skill: "dev-workflow:code-quality") +``` + +**Integration Points:** + +- Use Skill tool to invoke: `dev-workflow:test-driven-development` for strict TDD guidance +- Use Skill tool to invoke: `dev-workflow:git-workflow` for smart commits +- Use Skill tool to invoke: `dev-workflow:code-quality` for pre-commit reviews + +**How to activate integration skills:** +``` +# For TDD enforcement +Use Skill tool: Skill(skill: "dev-workflow:test-driven-development") + +# For git operations +Use Skill tool: Skill(skill: "dev-workflow:git-workflow") + +# For code review +Use Skill tool: Skill(skill: "dev-workflow:code-quality") +``` + +**Completion Criteria:** + +Feature is complete when: +- [ ] All tasks checked off +- [ ] All tests passing +- [ ] No linter errors +- [ ] No type errors +- [ ] Code review passed +- [ ] Documentation updated +- [ ] Manual testing complete + +**Final Output:** +``` +βœ… Feature Complete: [Feature Name] + +Summary: +- Total tasks: [N] +- Tests added: [N] +- Test coverage: [X%] +- Commits: [N] +- Files changed: [N] + +Ready to create PR or merge to main? +``` + +--- + +## Test-Driven Development (TDD) Principles + +### The Red-Green-Refactor Cycle + +**RED (Write Failing Test):** +``` +Write a test that describes what the code should do. +The test MUST fail because the code doesn't exist yet. +This proves the test is actually testing something. +``` + +**GREEN (Make Test Pass):** +``` +Write the MINIMUM code needed to make the test pass. +Don't worry about elegance or optimization. +Just make it work. +``` + +**REFACTOR (Improve Code):** +``` +Now that tests pass, improve the code: +- Remove duplication +- Improve naming +- Simplify logic +- Optimize performance +Run tests after each change to ensure they still pass. +``` + +### TDD Best Practices + +**DO:** +- Write test before production code (always RED first) +- Write smallest test possible +- Run tests frequently +- Commit at each phase (RED, GREEN, REFACTOR) +- Keep tests fast and independent + +**DON'T:** +- Write production code without a failing test +- Write multiple tests before implementation +- Skip the refactor phase +- Test implementation details (test behavior) +- Let tests become slow or flaky + +--- + +## Examples + +### Example 1: Starting Task Breakdown + +**User:** "/dev-workflow:spec tasks" + +**Assistant:** +``` +Activating spec-driven-implementation skill at Phase 4: Task Breakdown + +Found feature: docx/features/01-user-authentication/ +βœ… requirements.md exists +βœ… design.md exists + +Reading design to create TDD tasks... + +Breaking down into testable tasks: + +[ ] Task 1: User model with password hashing + [ ] RED: Test password hashing on save + [ ] GREEN: Implement bcrypt hashing + [ ] REFACTOR: Extract hashing to utility + + Acceptance Criteria: + [ ] Passwords are hashed before storage + [ ] Original password is not stored + [ ] Hash is verifiable + +[ ] Task 2: JWT token generation + [ ] RED: Test token generation with user ID + [ ] GREEN: Implement JWT signing + [ ] REFACTOR: Extract to auth service + + Acceptance Criteria: + [ ] Token contains user ID + [ ] Token expires in 24 hours + [ ] Token is properly signed + +[...8 more tasks...] + +Tasks defined. Ready to begin implementation? +``` + +### Example 2: Executing Implementation + +**User:** "Yes, let's start" + +**Assistant:** +``` +Activating Phase 5: Execution + +[Using Edit tool on docx/features/01-user-authentication/tasks.md] +[Changing "**Status:** Not Started" to "**Status:** In Progress"] + +[Using Edit tool to mark Task 1 in progress] +[Changing "[ ] Task 1: User model with password hashing" to "[β†’] Task 1: User model with password hashing"] + +[Using Edit tool to mark RED phase in progress] +[Changing " [ ] RED: Test password hashing on save" to " [β†’] RED: Test password hashing on save"] + +Starting Task 1: User model with password hashing + +RED Phase: Writing failing test... +[Creates test file tests/models/user.test.js with failing test] +Running tests... ❌ 1 failing (expected) + +[Using Edit tool to check off RED phase] +[Changing " [β†’] RED: Test password hashing on save" to " [x] RED: Test password hashing on save"] + +Commit: test: Add test for user password hashing + +[Using Edit tool to mark GREEN phase in progress] +[Changing " [ ] GREEN: Implement bcrypt hashing" to " [β†’] GREEN: Implement bcrypt hashing"] + +GREEN Phase: Implementing minimal code... +[Implements password hashing in src/models/user.js] +Running tests... βœ… All passing + +[Using Edit tool to check off GREEN phase] +[Changing " [β†’] GREEN: Implement bcrypt hashing" to " [x] GREEN: Implement bcrypt hashing"] + +Commit: feat: Implement user password hashing with bcrypt + +[Using Edit tool to mark REFACTOR phase in progress] +[Changing " [ ] REFACTOR: Extract hashing to utility" to " [β†’] REFACTOR: Extract hashing to utility"] + +REFACTOR Phase: Extracting to utility... +[Refactors code to src/utils/crypto.js] +Running tests... βœ… All passing + +[Using Edit tool to check off REFACTOR phase] +[Changing " [β†’] REFACTOR: Extract hashing to utility" to " [x] REFACTOR: Extract hashing to utility"] + +Commit: refactor: Extract password hashing to utility module + +[Using Edit tool to mark Task 1 complete] +[Changing "[β†’] Task 1: User model with password hashing" to "[x] Task 1: User model with password hashing"] + +[Using Edit tool to update Progress Summary] +[Changing "- Completed: 0/10" to "- Completed: 1/10"] +[Changing "- In Progress: Task 1 - User model with password hashing" to "- In Progress: Task 2 - JWT token generation"] + +βœ… Task 1 complete + +πŸ”„ Checkpoint Update: +- βœ… Tests: 3/3 passing +- βœ… Type check: No errors +- βœ… Lint: Clean +- πŸ“ Completed tasks: 1/10 +- 🎯 Next: Task 2 - JWT token generation + +[Confidence: 0.9] + +Continue to Task 2? +``` + +--- + +## Back to Planning + +If during implementation you discover: +- Missing requirements +- Design needs changes +- Unclear specifications + +**STOP implementation and return to planning:** +> "Implementation blocked: [issue]. Need to revisit [requirements/design]. Use `/dev-workflow:spec [requirements/design]` to update planning documents." + +Then use Skill tool to invoke: `dev-workflow:spec-driven-planning` to update planning documents before continuing implementation. + +**How to return to planning:** +``` +Use Skill tool: Skill(skill: "dev-workflow:spec-driven-planning") +``` + +--- + +## Notes + +### Critical Requirements + +- **NEVER write production code without a failing test first** +- **ALWAYS use Edit tool to update tasks.md checkboxes** - don't just announce progress +- **ALWAYS use Edit tool to update Progress Summary** after each task completion +- **Use Edit tool to update Status header** when starting/completing implementation + +### Task Tracking Best Practices + +- **Mark in progress:** Use Edit tool to change `[ ]` β†’ `[β†’]` before starting task +- **Mark complete:** Use Edit tool to change `[β†’]` β†’ `[x]` after finishing task +- **Update Progress Summary:** Use Edit tool after every task to keep counts accurate +- **File updates are mandatory:** Actually modify tasks.md, don't just announce + +### Implementation Guidelines + +- Provide checkpoint updates every 2-3 tasks +- Use Skill tool to invoke: `dev-workflow:code-quality` before commits +- Use Skill tool to invoke: `dev-workflow:git-workflow` for smart commit messages +- Follow TDD cycle religiously (RED β†’ GREEN β†’ REFACTOR) +- Stop and return to planning if design issues discovered + +### Remember + +**Announcing progress β‰  Updating files** + +Wrong: +``` +βœ… Task 1 complete +Moving to Task 2... +``` + +Right: +``` +[Using Edit tool to mark Task 1 complete: [β†’] β†’ [x]] +[Using Edit tool to update Progress Summary] +βœ… Task 1 complete +``` diff --git a/skills/spec-driven-planning/SKILL.md b/skills/spec-driven-planning/SKILL.md new file mode 100644 index 0000000..0ad16a6 --- /dev/null +++ b/skills/spec-driven-planning/SKILL.md @@ -0,0 +1,341 @@ +--- +name: spec-driven-planning +description: Use when planning new features or need structured requirements - creates feature structure, elicits EARS requirements through systematic questioning, proposes architectural approaches with trade-offs. Activates when user mentions "new feature", "requirements", "specs", "design", "architecture", or uses /dev-workflow:spec commands (create, requirements, design). +allowed-tools: Read, Write, Glob, Grep +--- + +# Spec-Driven Planning Skill + +## Purpose + +Guide feature planning through three structured phases: Feature Creation β†’ Requirements (EARS) β†’ Technical Design. This systematic approach ensures clear requirements and thoughtful design before implementation begins. + +## Activation Triggers + +Activate this skill when: +- User says "create a new feature" +- User mentions "requirements", "specifications", or "specs" +- User uses `/dev-workflow:spec` command with planning options +- User asks to plan or design a feature +- User says "I need to build [feature]" +- User mentions "architecture" or "technical design" + +## Three-Phase Planning Workflow + +### Phase 1: Feature Creation + +**Goal:** Establish feature structure and placeholder files + +**Process:** +1. Parse feature name from user input +2. Check existing features using Bash tool: `ls docx/features/` +3. Determine next number (NN) for feature directory +4. Create directory using Bash tool: `mkdir -p docx/features/[NN-feature-name]` +5. Copy templates from plugin to feature directory: + - Use Read tool: `dev-workflow/templates/requirements.md` + - Use Write tool: `docx/features/[NN-feature-name]/requirements.md` (replace [Feature Name] with actual name) + - Use Read tool: `dev-workflow/templates/design.md` + - Use Write tool: `docx/features/[NN-feature-name]/design.md` (replace [Feature Name] with actual name) + - Use Read tool: `dev-workflow/templates/tasks.md` + - Use Write tool: `docx/features/[NN-feature-name]/tasks.md` (replace [Feature Name] with actual name) + +**Output:** +``` +Created feature: docx/features/[NN-feature-name]/ +- requirements.md (from template) +- design.md (from template) +- tasks.md (from template) + +Next step: Define requirements using EARS format +``` + +**User Confirmation:** +> "Feature structure created. Ready to define requirements?" + +--- + +### Phase 2: Requirements Definition (EARS Format) + +**Goal:** Capture clear, testable requirements using EARS methodology + +**Brainstorming Integration (Optional):** +- If user has rough idea but unclear requirements, use Skill tool to invoke: `dev-workflow:brainstorming` +- Helps clarify what to build vs. what's out of scope +- Explores different feature scopes through collaborative questioning +- Determines must-haves vs. nice-to-haves + +**How to activate:** +``` +Use Skill tool: Skill(skill: "dev-workflow:brainstorming") +``` + +**EARS Format Explained:** + +EARS (Easy Approach to Requirements Syntax) provides five templates for unambiguous requirements: + +1. **Ubiquitous Requirements** - Always true + - Template: "The system SHALL [requirement]" + - Example: "The system SHALL validate all user inputs before processing" + +2. **Event-Driven Requirements** - Triggered by events + - Template: "WHEN [trigger] THEN the system SHALL [response]" + - Example: "WHEN user clicks submit THEN the system SHALL validate form data" + +3. **State-Driven Requirements** - Active during specific states + - Template: "WHILE [state] the system SHALL [requirement]" + - Example: "WHILE processing payment the system SHALL display loading indicator" + +4. **Conditional Requirements** - Based on conditions + - Template: "IF [condition] THEN the system SHALL [requirement]" + - Example: "IF user role is admin THEN the system SHALL show management panel" + +5. **Optional Requirements** - Feature toggles + - Template: "WHERE [feature included] the system SHALL [requirement]" + - Example: "WHERE premium subscription is active the system SHALL enable advanced analytics" + +**Systematic Questioning Approach:** + +Ask the user these questions to elicit requirements: + +1. **Core Functionality** + - "What is the primary purpose of this feature?" + - "What problem does it solve?" + +2. **Event-Driven Requirements** + - "What user actions trigger this feature?" + - "What system events are involved?" + +3. **State-Driven Requirements** + - "Are there different states or modes?" + - "What should happen during each state?" + +4. **Conditional Requirements** + - "Are there different behaviors for different users/roles?" + - "What conditions affect functionality?" + +5. **Performance Requirements** + - "Are there response time requirements?" + - "What's the expected load/scale?" + +6. **Security Requirements** + - "What data needs protection?" + - "Who should have access?" + +7. **Error Handling** + - "What can go wrong?" + - "How should errors be handled?" + +8. **Edge Cases** + - "What are the boundary conditions?" + - "What happens at extremes?" + +**Best Practices:** +- Use "SHALL" for mandatory requirements +- Be specific and measurable (avoid "quickly", use "within 2 seconds") +- One requirement per statement +- Avoid ambiguous terms ("appropriate", "reasonable", "user-friendly") +- Use active voice + +**Output Format:** +Update `docx/features/[NN-feature-name]/requirements.md` with: +- Overview section +- Functional requirements (organized by EARS type) +- Non-functional requirements (performance, security, usability) +- Constraints +- Acceptance criteria (checkboxes) +- Out of scope items + +**User Confirmation:** +> "Requirements complete. Ready for design phase?" + +--- + +### Phase 3: Technical Design + +**Goal:** Create comprehensive technical design with architectural decisions + +**Process:** + +1. **Brainstorming Integration** + - Use Skill tool to invoke: `dev-workflow:brainstorming` for collaborative design exploration + - Explore 2-3 different architectural approaches + - Discuss trade-offs for each approach + + **How to activate:** + ``` + Use Skill tool: Skill(skill: "dev-workflow:brainstorming") + ``` + +**UltraThink for Complex Designs:** +Before proposing technical approaches, activate deep thinking when: +- Architecture involves multiple services or complex data flows +- Trade-offs between approaches aren't obvious +- Design impacts security, performance, or scalability +- Requirements seem contradictory or incomplete + +> πŸ—£ Say: "This design requires deep thinking. Let me ultrathink the architectural fundamentals before proposing approaches." + +**During UltraThink, question:** +- Are we solving the right problem? +- What are we assuming that might be wrong? +- What could break at scale? +- What's the simplest architecture that works? +- What are the hidden costs of each approach? +- What would we do differently if starting from scratch? + +**After UltraThink:** Present approaches with explicit reasoning about architectural trade-offs and scalability considerations. + +2. **Approach Comparison** + Present options with trade-offs: + + **Option A: [Approach Name]** + - Pros: [Advantages] + - Cons: [Disadvantages] + - Complexity: Low/Medium/High + - Timeline: [Estimate] + + **Option B: [Approach Name]** + - Pros: [Advantages] + - Cons: [Disadvantages] + - Complexity: Low/Medium/High + - Timeline: [Estimate] + +3. **Recommendation** + - State recommended approach + - Provide clear reasoning + - Explain why it best fits requirements + +4. **Design Document Structure** + Create comprehensive `design.md` covering: + + **Architecture Overview** + - How feature fits into system + - High-level component diagram (ASCII art) + + **Component Structure** + - List components with responsibilities + - Define dependencies between components + - Specify public interfaces + + **Data Flow** + - Step-by-step data movement + - Diagram showing flow + + **API Contracts** + - Input/output schemas + - Error responses + - Example requests/responses + + **Error Handling** + - Error scenarios and handling strategy + - Fallback behaviors + + **Security Considerations** + - Authentication/authorization + - Input validation + - Data protection + + **Performance Considerations** + - Optimization strategies + - Caching approach + - Database indexing needs + + **Testing Strategy** + - Unit test areas + - Integration test scenarios + - E2E test workflows + +**Approval Gate:** +> "Design complete. Ready for task breakdown?" + +Wait for explicit user approval before proceeding. + +--- + +## Next Steps + +After design approval, use `/dev-workflow:spec tasks` or `/dev-workflow:spec execute` to activate the `spec-driven-implementation` skill, which will: +- Break down your design into TDD tasks with Red-Green-Refactor cycles +- Guide systematic execution with quality gates +- Track progress with checkbox updates +- Integrate with code-quality and git-workflow skills + +--- + +## Examples + +### Example 1: Creating User Authentication Feature + +**User:** "I need to add user authentication" + +**Assistant:** +``` +Activating spec-driven-planning skill for feature planning. + +Let me create the feature structure: + +Created feature: docx/features/01-user-authentication/ +- requirements.md +- design.md +- tasks.md + +Phase 1 Complete. Ready to define requirements? +``` + +**User:** "Yes" + +**Assistant:** +``` +Phase 2: Requirements Definition (EARS Format) + +Let me ask some questions to capture clear requirements: + +1. Core Functionality: + - What authentication methods should be supported? (email/password, OAuth, etc.) + - Should there be session management? + +2. Events: + - What happens when user tries to log in? + - What happens when session expires? + +[...continues with systematic questioning...] +``` + +### Example 2: Resuming at Design Phase + +**User:** "/dev-workflow:spec design" + +**Assistant:** +``` +Activating spec-driven-planning skill at Phase 3: Design + +Found latest feature: docx/features/01-user-authentication/ + +Requirements already defined. Let me propose architectural approaches: + +**Option A: JWT-Based Authentication** +Pros: Stateless, scalable, works across services +Cons: Token invalidation complexity, larger payload +Complexity: Medium + +**Option B: Session-Based Authentication** +Pros: Simple invalidation, smaller cookies, familiar pattern +Cons: Requires session storage, scaling challenges +Complexity: Low + +Recommendation: Option A (JWT-Based) +Reasoning: Better for microservices, future-proof, industry standard + +Proceed with JWT-based design? +``` + +--- + +## Notes + +- Always request explicit approval between phases +- Use EARS format strictly for requirements +- Focus on "what" and "how", not "doing" +- Create clear, complete documentation before implementation +- Explore multiple architectural options before recommending one +- Wait for user approval before activating implementation skill diff --git a/skills/systematic-testing/SKILL.md b/skills/systematic-testing/SKILL.md new file mode 100644 index 0000000..e7df8f8 --- /dev/null +++ b/skills/systematic-testing/SKILL.md @@ -0,0 +1,621 @@ +--- +name: systematic-testing +description: Use when writing tests, debugging failures, or investigating bugs - provides TDD guidance, test generation patterns, systematic debugging framework. Activates when user says "write tests", "this test fails", "debug this", mentions "TDD", "test coverage", or encounters errors/bugs. +--- + +# Systematic Testing Skill + +## Purpose + +Guide test-driven development (TDD), generate comprehensive test suites, and provide systematic debugging frameworks. Ensures code is well-tested and bugs are resolved methodically rather than through trial-and-error. + +## Activation Triggers + +Activate this skill when: +- User implements new functionality (auto-suggest tests) +- Tests fail (activate debugging framework) +- User says "write tests for this" +- User mentions "TDD" or "test-driven" +- User asks about debugging or troubleshooting +- User says "this bug..." or "error..." +- Before marking feature complete (verify test coverage) + +## Core Capabilities + +### 1. Test-Driven Development (TDD) + +**For complete TDD workflow, use Skill tool to invoke: `dev-workflow:test-driven-development`** + +**How to activate:** +``` +Use Skill tool: Skill(skill: "dev-workflow:test-driven-development") +``` + +The `test-driven-development` skill provides: +- Full RED-GREEN-REFACTOR cycle explanation +- Strict TDD enforcement and discipline +- Anti-patterns and rationalizations to avoid +- Detailed examples and verification checklist + +**Quick TDD Summary:** +1. **RED:** Write failing test first +2. **GREEN:** Write minimal code to pass +3. **REFACTOR:** Clean up while tests stay green + +This skill focuses on test generation strategies and systematic debugging. For TDD methodology details, use the dedicated skill. + +--- + +### 2. Test Generation + +**Goal:** Generate comprehensive test suites covering all scenarios + +### Test Categories + +#### Normal Cases (Happy Path) + +Test expected, typical usage: + +```javascript +describe('calculatePositionSize', () => { + it('should calculate correct position size for valid inputs', () => { + const result = calculatePositionSize( + 10000, // account balance + 0.02, // 2% risk + 150.50, // entry price + 148.00 // stop loss + ); + + expect(result).toBe(80); // $200 risk / $2.50 per share + }); + + it('should handle large account balances', () => { + const result = calculatePositionSize( + 1000000, // $1M account + 0.01, // 1% risk + 100, + 99 + ); + + expect(result).toBe(10000); + }); +}); +``` + +#### Edge Cases (Boundary Conditions) + +Test limits and boundaries: + +```javascript +describe('calculatePositionSize - edge cases', () => { + it('should handle very small risk percentage', () => { + const result = calculatePositionSize( + 10000, + 0.001, // 0.1% risk + 100, + 99 + ); + + expect(result).toBe(10); // $10 risk / $1 per share + }); + + it('should handle entry price equal to stop loss', () => { + expect(() => { + calculatePositionSize(10000, 0.02, 100, 100); + }).toThrow('Entry price cannot equal stop loss'); + }); + + it('should handle very small price differences', () => { + const result = calculatePositionSize( + 10000, + 0.02, + 100.10, + 100.00 + ); + + expect(result).toBe(2000); // $200 / $0.10 + }); + + it('should round down fractional shares', () => { + const result = calculatePositionSize( + 10000, + 0.02, + 150.75, // Creates fractional result + 148.00 + ); + + // Should be whole number, not fractional + expect(Number.isInteger(result)).toBe(true); + }); +}); +``` + +#### Error Cases (Invalid Inputs) + +Test error handling: + +```javascript +describe('calculatePositionSize - error cases', () => { + it('should reject negative account balance', () => { + expect(() => { + calculatePositionSize(-10000, 0.02, 100, 99); + }).toThrow('Account balance must be positive'); + }); + + it('should reject zero account balance', () => { + expect(() => { + calculatePositionSize(0, 0.02, 100, 99); + }).toThrow('Account balance must be positive'); + }); + + it('should reject risk percentage over 100%', () => { + expect(() => { + calculatePositionSize(10000, 1.5, 100, 99); + }).toThrow('Risk percentage must be between 0 and 1'); + }); + + it('should reject negative risk percentage', () => { + expect(() => { + calculatePositionSize(10000, -0.02, 100, 99); + }).toThrow('Risk percentage must be between 0 and 1'); + }); + + it('should handle null inputs gracefully', () => { + expect(() => { + calculatePositionSize(null, 0.02, 100, 99); + }).toThrow(); + }); + + it('should handle undefined inputs gracefully', () => { + expect(() => { + calculatePositionSize(undefined, 0.02, 100, 99); + }).toThrow(); + }); +}); +``` + +#### Integration Cases + +Test component interactions: + +```javascript +describe('login flow - integration', () => { + it('should complete full authentication flow', async () => { + // Test entire flow from request to response + const response = await request(app) + .post('/api/auth/login') + .send({ + email: 'user@example.com', + password: 'SecureP@ss123' + }); + + // Verify response + expect(response.status).toBe(200); + expect(response.body.data.accessToken).toBeTruthy(); + + // Verify token is valid + const decoded = jwt.verify( + response.body.data.accessToken, + process.env.JWT_SECRET + ); + expect(decoded.id).toBeTruthy(); + + // Verify user can access protected route + const protectedResponse = await request(app) + .get('/api/user/profile') + .set('Authorization', `Bearer ${response.body.data.accessToken}`); + + expect(protectedResponse.status).toBe(200); + }); + + it('should prevent access with expired token', async () => { + // Create expired token + const expiredToken = jwt.sign( + { id: 'user-id' }, + process.env.JWT_SECRET, + { expiresIn: '-1h' } // Already expired + ); + + // Attempt to access protected route + const response = await request(app) + .get('/api/user/profile') + .set('Authorization', `Bearer ${expiredToken}`); + + expect(response.status).toBe(401); + expect(response.body.error.code).toBe('TOKEN_EXPIRED'); + }); +}); +``` + +### Test Generation Template + +```javascript +describe('[Component/Function Name]', () => { + // Setup and teardown + beforeEach(() => { + // Reset state, create test data + }); + + afterEach(() => { + // Clean up, reset mocks + }); + + // NORMAL CASES + describe('normal operation', () => { + it('should [expected behavior for typical input]', () => { + // Test implementation + }); + }); + + // EDGE CASES + describe('edge cases', () => { + it('should handle [boundary condition]', () => { + // Test implementation + }); + }); + + // ERROR CASES + describe('error handling', () => { + it('should reject [invalid input]', () => { + expect(() => { + // Call with invalid input + }).toThrow('Expected error message'); + }); + }); + + // INTEGRATION + describe('integration', () => { + it('should work with [other component]', () => { + // Test interaction + }); + }); +}); +``` + +--- + +## 3. Systematic Debugging Framework + +**Goal:** Resolve bugs methodically, not through random trial-and-error + +**Four-Phase Framework:** + +### Phase 1: Root Cause Investigation + +**Goal:** Understand exactly what's going wrong + +**Process:** + +1. **Reproduce Bug Consistently** + ``` + Steps to reproduce: + 1. Navigate to login page + 2. Enter email: user@example.com + 3. Enter password: TestPass123 + 4. Click submit + 5. Observe: Error message "Network request failed" + + Reproducibility: 10/10 attempts failed + ``` + +2. **Identify Symptoms** + - What's the visible error? + - What error messages appear? + - What's the expected vs actual behavior? + +3. **Gather Evidence** + ```bash + # Check logs + tail -f logs/app.log + + # Check network requests (browser dev tools) + # Check console errors + # Check server logs + ``` + + Collect: + - Error messages (full text) + - Stack traces + - Log entries + - Network requests/responses + - Input values that trigger bug + +4. **Form Initial Hypothesis** + ``` + Hypothesis: API endpoint is returning 500 error instead of 400 + + Evidence: + - Console shows "Network request failed" + - Server logs show 500 error at time of attempt + - Database logs show constraint violation + + Next step: Check what's causing the 500 + ``` + +### Phase 2: Pattern Analysis + +**Goal:** Identify when bug occurs and when it doesn't + +**Questions to Answer:** + +1. **When Does It Fail?** + - Specific inputs? + - Certain users? + - Particular time of day? + - After specific sequence of actions? + +2. **When Does It Work?** + - Any inputs that succeed? + - Any users unaffected? + - Worked before, broken now? + +3. **What Changed Recently?** + ```bash + # Check recent commits + git log --since="2 days ago" --oneline + + # Check what changed in specific file + git log -p path/to/file.js + + # See when bug was introduced + git bisect + ``` + +4. **Environmental Factors?** + - Works locally, fails in production? + - Browser-specific? + - Network conditions? + - Load-related (works with 1 user, fails with 100)? + +**Pattern Analysis Example:** +``` +Bug Pattern Analysis: + +FAILS when: +- Email contains + symbol (e.g., user+test@example.com) +- Password is exactly 8 characters +- User account was created after 2025-01-01 + +WORKS when: +- Email is standard format (user@example.com) +- Password is 9+ characters +- User account is older + +Pattern identified: Email validation regex doesn't handle + symbol +``` + +### Phase 3: Hypothesis Testing + +**Goal:** Test theories systematically until root cause found + +**Process:** + +1. **Create Minimal Test Case** + ```javascript + // Isolate the bug + it('should accept email with plus symbol', () => { + const email = 'user+test@example.com'; + const result = validateEmail(email); + expect(result).toBe(true); // Currently fails + }); + ``` + +2. **Add Instrumentation** + ```javascript + function validateEmail(email) { + console.log('Input email:', email); + + const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; + const isValid = regex.test(email); + + console.log('Regex test result:', isValid); + console.log('Regex used:', regex); + + return isValid; + } + ``` + +3. **Test Hypothesis** + ```javascript + // Hypothesis: Regex doesn't handle + symbol + + // Test with minimal input + validateEmail('user+test@example.com'); + // Output: + // Input email: user+test@example.com + // Regex test result: true + // + // Hypothesis REJECTED: Regex accepts + symbol + + // Form new hypothesis: Something else is rejecting it + + // Check database constraint + // Found: Database column has CHECK constraint excluding + + // Hypothesis CONFIRMED! + ``` + +4. **Iterate Until Root Cause Found** + Keep forming and testing hypotheses until you identify exact cause. + +### Phase 4: Implementation + +**Goal:** Fix bug permanently with regression protection + +**Process:** + +1. **Write Test Reproducing Bug** + ```javascript + // This test should FAIL before fix + it('should accept email with plus symbol', async () => { + const email = 'user+test@example.com'; + const password = 'SecureP@ss123'; + + const response = await request(app) + .post('/api/auth/register') + .send({ email, password }); + + expect(response.status).toBe(201); + expect(response.body.user.email).toBe(email); + }); + ``` + + Run test - verify it fails: + ```bash + npm test + # βœ— should accept email with plus symbol + # Expected: 201, Received: 400 + ``` + +2. **Fix the Bug** + ```sql + -- Remove overly restrictive database constraint + ALTER TABLE users DROP CONSTRAINT email_format_check; + + -- Or update to correct constraint + ALTER TABLE users ADD CONSTRAINT email_format_check + CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$'); + ``` + +3. **Verify Test Passes** + ```bash + npm test + # βœ“ should accept email with plus symbol + ``` + +4. **Add Regression Tests** + ```javascript + // Add more tests for similar edge cases + describe('email validation - special characters', () => { + const validEmails = [ + 'user+test@example.com', + 'user.name@example.com', + 'user_name@example.com', + 'user-name@example.com', + 'user123@example.com' + ]; + + validEmails.forEach(email => { + it(`should accept ${email}`, async () => { + const response = await request(app) + .post('/api/auth/register') + .send({ email, password: 'SecureP@ss123' }); + + expect(response.status).toBe(201); + }); + }); + }); + ``` + +5. **Document Root Cause** + ```javascript + /* + * Bug Fix: Email validation now accepts RFC-compliant characters + * + * Root Cause: + * Database CHECK constraint was too restrictive, excluding the + symbol + * which is valid in email addresses per RFC 5322. + * + * Fix: + * Updated CHECK constraint to use proper regex pattern matching RFC 5322. + * + * Date: 2025-01-17 + * Related Issue: #234 + */ + ``` + +6. **Commit Fix with Context** + ```bash + git add migrations/003_fix_email_constraint.sql + git add tests/auth/register.test.js + git commit -m "fix: Accept + symbol in email addresses + + Database CHECK constraint was rejecting valid emails containing + the + symbol. Updated constraint to match RFC 5322 standard. + + Closes #234" + ``` + +--- + +## Test Coverage Analysis + +**Goal:** Identify untested code + +**Check Coverage:** +```bash +# Generate coverage report +npm run test:coverage + +# Typical output: +# File | % Stmts | % Branch | % Funcs | % Lines | +# ---------------|---------|----------|---------|---------| +# src/auth.js | 87.5 | 75.0 | 100.0 | 87.5 | +# src/orders.js | 45.2 | 33.3 | 60.0 | 45.2 | +``` + +**Identify Gaps:** +- Functions without any tests +- Branches not covered (if statements, error paths) +- Edge cases not tested +- Integration paths missing + +**Prioritize:** +1. Critical business logic (highest priority) +2. Security-sensitive code +3. Complex algorithms +4. Error handling paths +5. Edge cases + +## Best Practices + +### TDD Best Practices +1. **Always write test first**: No exceptions +2. **One test at a time**: Don't write multiple tests before implementing +3. **Smallest possible step**: Each cycle should be quick (5-10 minutes) +4. **Test behavior, not implementation**: Don't test private methods +5. **Keep tests simple**: Tests should be easier to understand than code + +### Test Quality +1. **Clear test names**: Should read like documentation +2. **Arrange-Act-Assert**: Structure tests consistently +3. **One assertion per test**: Makes failures clear +4. **No logic in tests**: Tests should be simple data +5. **Independent tests**: No test depends on another + +### Debugging Best Practices +1. **Reproduce first**: Can't fix what you can't reproduce +2. **Understand before fixing**: Don't guess and check +3. **Fix root cause**: Don't just treat symptoms +4. **Add regression test**: Prevent bug from returning +5. **Document why**: Help future debuggers + +## Integration with Superpowers + +**If `superpowers:test-driven-development` available:** +- Use for guided TDD workflow +- Enhanced RED-GREEN-REFACTOR cycle +- Additional TDD best practices + +**If `superpowers:systematic-debugging` available:** +- Use for complex debugging scenarios +- Root cause tracing framework +- Advanced instrumentation guidance + +## Common Anti-Patterns to Avoid + +❌ Writing tests after implementation +❌ Changing tests to match implementation +❌ Testing implementation details instead of behavior +❌ Skipping refactor phase +❌ Testing code that's already tested (overwriting working tests) +❌ Making multiple changes before testing +❌ Debugging by randomly changing code +❌ Committing "console.log" debugging code + +## Notes + +- TDD is slower initially but faster overall (fewer bugs, less debugging) +- Good tests are documentation that never gets outdated +- Debugging is detective work, not guessing +- Always add regression tests after fixing bugs +- Test coverage is a minimum bar, not a goal diff --git a/skills/test-driven-development/SKILL.md b/skills/test-driven-development/SKILL.md new file mode 100644 index 0000000..9da57f9 --- /dev/null +++ b/skills/test-driven-development/SKILL.md @@ -0,0 +1,397 @@ +--- +name: test-driven-development +description: Use when implementing features/bugfixes to enforce strict TDD discipline - enforces RED (write failing test), GREEN (minimal code), REFACTOR cycle with no exceptions. Prevents "test after" trap, catches rationalizations. Activates when user says "implement", "let's code", "write this feature", mentions "TDD", or during spec-driven execution phase. +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +--- + +# Test-Driven Development (TDD) + +## Overview + +Write the test first. Watch it fail. Write minimal code to pass. + +**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing. + +**Violating the letter of the rules is violating the spirit of the rules.** + +## When to Use + +**Always:** +- New features +- Bug fixes +- Refactoring +- Behavior changes + +**Exceptions (ask your human partner):** +- Throwaway prototypes +- Generated code +- Configuration files + +Thinking "skip TDD just this once"? Stop. That's rationalization. + +## The Iron Law + +``` +NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST +``` + +Write code before the test? Delete it. Start over. + +**No exceptions:** +- Don't keep it as "reference" +- Don't "adapt" it while writing tests +- Don't look at it +- Delete means delete + +Implement fresh from tests. Period. + +## Red-Green-Refactor + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ RED β”‚ Write failing test +β”‚ Write test β”‚ describing desired behavior +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Verify RED β”‚ Run test - MUST fail +β”‚ Watch fail β”‚ for expected reason +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ GREEN β”‚ Write minimal code +β”‚ Make it passβ”‚ to make test pass +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚Verify GREEN β”‚ Run test - MUST pass +β”‚ Watch pass β”‚ all tests stay green +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ REFACTOR β”‚ Clean up code while +β”‚ Clean up β”‚ keeping tests green +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό Repeat for next behavior +``` + +### RED - Write Failing Test + +Write one minimal test showing what should happen. + + +```typescript +test('retries failed operations 3 times', async () => { + let attempts = 0; + const operation = () => { + attempts++; + if (attempts < 3) throw new Error('fail'); + return 'success'; + }; + + const result = await retryOperation(operation); + + expect(result).toBe('success'); + expect(attempts).toBe(3); +}); +``` +Clear name, tests real behavior, one thing + + + +```typescript +test('retry works', async () => { + const mock = jest.fn() + .mockRejectedValueOnce(new Error()) + .mockRejectedValueOnce(new Error()) + .mockResolvedValueOnce('success'); + await retryOperation(mock); + expect(mock).toHaveBeenCalledTimes(3); +}); +``` +Vague name, tests mock not code + + +**Requirements:** +- One behavior +- Clear name +- Real code (no mocks unless unavoidable) + +### Verify RED - Watch It Fail + +**MANDATORY. Never skip.** + +```bash +npm test path/to/test.test.ts +``` + +Confirm: +- Test fails (not errors) +- Failure message is expected +- Fails because feature missing (not typos) + +**Test passes?** You're testing existing behavior. Fix test. + +**Test errors?** Fix error, re-run until it fails correctly. + +### GREEN - Minimal Code + +Write simplest code to pass the test. + + +```typescript +async function retryOperation(fn: () => Promise): Promise { + for (let i = 0; i < 3; i++) { + try { + return await fn(); + } catch (e) { + if (i === 2) throw e; + } + } + throw new Error('unreachable'); +} +``` +Just enough to pass + + + +```typescript +async function retryOperation( + fn: () => Promise, + options?: { + maxRetries?: number; + backoff?: 'linear' | 'exponential'; + onRetry?: (attempt: number) => void; + } +): Promise { + // YAGNI +} +``` +Over-engineered + + +Don't add features, refactor other code, or "improve" beyond the test. + +### Verify GREEN - Watch It Pass + +**MANDATORY.** + +```bash +npm test path/to/test.test.ts +``` + +Confirm: +- Test passes +- Other tests still pass +- Output pristine (no errors, warnings) + +**Test fails?** Fix code, not test. + +**Other tests fail?** Fix now. + +### REFACTOR - Clean Up + +After green only: +- Remove duplication +- Improve names +- Extract helpers + +Keep tests green. Don't add behavior. + +### Repeat + +Next failing test for next feature. + +## Good Tests + +| Quality | Good | Bad | +|---------|------|-----| +| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` | +| **Clear** | Name describes behavior | `test('test1')` | +| **Shows intent** | Demonstrates desired API | Obscures what code should do | + +## Why Order Matters + +**"I'll write tests after to verify it works"** + +Tests written after code pass immediately. Passing immediately proves nothing: +- Might test wrong thing +- Might test implementation, not behavior +- Might miss edge cases you forgot +- You never saw it catch the bug + +Test-first forces you to see the test fail, proving it actually tests something. + +**"I already manually tested all the edge cases"** + +Manual testing is ad-hoc. You think you tested everything but: +- No record of what you tested +- Can't re-run when code changes +- Easy to forget cases under pressure +- "It worked when I tried it" β‰  comprehensive + +Automated tests are systematic. They run the same way every time. + +**"Deleting X hours of work is wasteful"** + +Sunk cost fallacy. The time is already gone. Your choice now: +- Delete and rewrite with TDD (X more hours, high confidence) +- Keep it and add tests after (30 min, low confidence, likely bugs) + +The "waste" is keeping code you can't trust. Working code without real tests is technical debt. + +**"TDD is dogmatic, being pragmatic means adapting"** + +TDD IS pragmatic: +- Finds bugs before commit (faster than debugging after) +- Prevents regressions (tests catch breaks immediately) +- Documents behavior (tests show how to use code) +- Enables refactoring (change freely, tests catch breaks) + +"Pragmatic" shortcuts = debugging in production = slower. + +**"Tests after achieve the same goals - it's spirit not ritual"** + +No. Tests-after answer "What does this do?" Tests-first answer "What should this do?" + +Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones. + +Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't). + +30 minutes of tests after β‰  TDD. You get coverage, lose proof tests work. + +## Common Rationalizations + +| Excuse | Reality | +|--------|---------| +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | +| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | +| "Already manually tested" | Ad-hoc β‰  systematic. No record, can't re-run. | +| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. | +| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | +| "Need to explore first" | Fine. Throw away exploration, start with TDD. | +| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. | +| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. | +| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. | +| "Existing code has no tests" | You're improving it. Add tests for existing code. | + +## Red Flags - STOP and Start Over + +- Code before test +- Test after implementation +- Test passes immediately +- Can't explain why test failed +- Tests added "later" +- Rationalizing "just this once" +- "I already manually tested it" +- "Tests after achieve the same purpose" +- "It's about spirit not ritual" +- "Keep as reference" or "adapt existing code" +- "Already spent X hours, deleting is wasteful" +- "TDD is dogmatic, I'm being pragmatic" +- "This is different because..." + +**All of these mean: Delete code. Start over with TDD.** + +## Example: Bug Fix + +**Bug:** Empty email accepted + +**RED** +```typescript +test('rejects empty email', async () => { + const result = await submitForm({ email: '' }); + expect(result.error).toBe('Email required'); +}); +``` + +**Verify RED** +```bash +$ npm test +FAIL: expected 'Email required', got undefined +``` + +**GREEN** +```typescript +function submitForm(data: FormData) { + if (!data.email?.trim()) { + return { error: 'Email required' }; + } + // ... +} +``` + +**Verify GREEN** +```bash +$ npm test +PASS +``` + +**REFACTOR** +Extract validation for multiple fields if needed. + +## Verification Checklist + +Before marking work complete: + +- [ ] Every new function/method has a test +- [ ] Watched each test fail before implementing +- [ ] Each test failed for expected reason (feature missing, not typo) +- [ ] Wrote minimal code to pass each test +- [ ] All tests pass +- [ ] Output pristine (no errors, warnings) +- [ ] Tests use real code (mocks only if unavoidable) +- [ ] Edge cases and errors covered + +Can't check all boxes? You skipped TDD. Start over. + +## When Stuck + +| Problem | Solution | +|---------|----------| +| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. | +| Test too complicated | Design too complicated. Simplify interface. | +| Must mock everything | Code too coupled. Use dependency injection. | +| Test setup huge | Extract helpers. Still complex? Simplify design. | + +## Debugging Integration + +Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression. + +Never fix bugs without a test. + +## Integration with Spec-Driven Workflow + +This skill is core to Phase 5 (Execution) of spec-driven implementation: + +**During Task Breakdown (Phase 4):** +- Each task is structured as RED β†’ GREEN β†’ REFACTOR +- Tasks include explicit test-first steps + +**During Execution (Phase 5):** +- Follow TDD cycle for every task +- Mark RED, GREEN, REFACTOR sub-tasks as complete +- Commit after each phase: + - `test: Add test for [functionality]` + - `feat: Implement [functionality]` + - `refactor: Optimize [component]` + +**Quality Gates:** +- All tests must pass before proceeding +- No code without tests +- Code-quality skill reviews before commits + +## Final Rule + +``` +Production code β†’ test exists and failed first +Otherwise β†’ not TDD +``` + +No exceptions without your human partner's permission.