@hustle-together/api-dev-tools 3.10.1 → 3.12.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,103 @@
+{
+  "name": "api-dev-tools",
+  "owner": {
+    "name": "Hustle Together",
+    "email": "contact@hustletogether.dev"
+  },
+  "description": "Interview-driven, research-first API development toolkit with 13-phase TDD workflow, enforcement hooks, and continuous verification loops. Includes 23 agent skills for API creation, testing, documentation, and deployment.",
+  "version": "3.11.0",
+  "repository": "https://github.com/hustle-together/api-dev-tools",
+  "license": "MIT",
+  "keywords": [
+    "api",
+    "tdd",
+    "workflow",
+    "research",
+    "interview",
+    "verification",
+    "hooks",
+    "mcp",
+    "agent-skills",
+    "testing",
+    "documentation"
+  ],
+  "plugins": [
+    {
+      "name": "api-dev-tools",
+      "source": ".",
+      "description": "Complete API development workflow with 13 phases, 23 skills, and 18 enforcement hooks",
+      "version": "3.11.0",
+      "author": {
+        "name": "Hustle Together",
+        "email": "contact@hustletogether.dev"
+      },
+      "category": "development",
+      "tags": ["api", "tdd", "workflow", "testing", "research"]
+    }
+  ],
+  "installation": {
+    "requirements": {
+      "claude_code": ">=1.0.0",
+      "python": ">=3.9",
+      "node": ">=18.0.0",
+      "pnpm": ">=10.11.0"
+    },
+    "mcp_servers": [
+      {
+        "name": "context7",
+        "description": "Documentation search and discovery",
+        "required": true,
+        "install": "Add to Claude Code MCP settings"
+      },
+      {
+        "name": "github",
+        "description": "GitHub integration for PRs and issues",
+        "required": true,
+        "install": "Add to Claude Code MCP settings"
+      }
+    ],
+    "post_install_instructions": [
+      "1. Copy .skills/_shared/hooks/ to .claude/hooks/ in your project",
+      "2. Copy .skills/_shared/settings.json to .claude/settings.json",
+      "3. Create .claude/api-dev-state.json from template",
+      "4. Create .claude/research/ directory",
+      "5. Install required MCP servers (Context7, GitHub)",
+      "6. Run '/api-status' to verify installation"
+    ]
+  },
+  "documentation": {
+    "readme": "https://github.com/hustle-together/api-dev-tools/blob/main/README.md",
+    "changelog": "https://github.com/hustle-together/api-dev-tools/blob/main/CHANGELOG.md",
+    "guides": {
+      "quickstart": "https://github.com/hustle-together/api-dev-tools/blob/main/.claude/commands/README.md",
+      "workflow": "https://github.com/hustle-together/api-dev-tools/blob/main/ENHANCEMENT_ROADMAP_v3.11.0.md",
+      "skills": "https://github.com/hustle-together/api-dev-tools/blob/main/.skills/README.md"
+    }
+  },
+  "skills": {
+    "api_development": [
+      "api-create",
+      "api-interview",
+      "api-research",
+      "api-verify",
+      "api-env",
+      "api-status"
+    ],
+    "tdd_workflow": ["red", "green", "refactor", "cycle"],
+    "planning": ["plan", "gap", "issue"],
+    "git_operations": [
+      "commit",
+      "pr",
+      "busycommit",
+      "worktree-add",
+      "worktree-cleanup"
+    ],
+    "workflow_utilities": [
+      "spike",
+      "beepboop",
+      "tdd",
+      "summarize",
+      "add-command"
+    ]
+  }
+}

package/.skills/README.md

@@ -0,0 +1,293 @@
+# API Development Tools - Agent Skills
+
+**Version:** 1.0.0
+**Standard:** [Agent Skills Open Format](https://agentskills.io)
+**Platform:** Cross-platform (Claude Code, VS Code, Cursor, ChatGPT, GitHub Copilot)
+
+## 🚀 Quick Start
+
+### Installation via Claude Code Plugin
+
+```bash
+/plugin marketplace add hustle-together/api-dev-tools
+/plugin install api-dev-tools
+```
+
+### Installation via NPM
+
+```bash
+npx @hustle-together/api-dev-tools --scope=project
+```
+
+### Manual Installation
+
+1. Clone the repository
+2. Copy `.skills/` to `~/.claude/skills/` (personal) or `.claude/skills/` (project)
+3. Copy `.skills/_shared/hooks/` to `.claude/hooks/` (for enforcement)
+4. Copy `.skills/_shared/settings.json` to `.claude/settings.json`
+5. Create `.claude/api-dev-state.json` (see template below)
+6. Create `.claude/research/` directory
+
+## 📚 Available Skills (23 Total)
+
+### API Development (6 skills)
+
+| Skill             | Usage                       | Description                                                                |
+| ----------------- | --------------------------- | -------------------------------------------------------------------------- |
+| **api-create**    | `/api-create [endpoint]`    | Complete 14-phase API workflow with interview, research, TDD, verification |
+| **api-interview** | `/api-interview [endpoint]` | Structured requirements gathering with questions FROM research findings    |
+| **api-research**  | `/api-research [library]`   | Adaptive documentation research with 7-day caching                         |
+| **api-verify**    | `/api-verify [endpoint]`    | Re-research after tests pass to catch implementation gaps                  |
+| **api-env**       | `/api-env [endpoint]`       | Check API keys and environment variables                                   |
+| **api-status**    | `/api-status [endpoint]`    | Track progress through 14 phases                                           |
+
+### TDD Workflow (4 skills)
+
+| Skill        | Usage                  | Description                                                    |
+| ------------ | ---------------------- | -------------------------------------------------------------- |
+| **red**      | `/red`                 | Write ONE failing test (defines success before implementation) |
+| **green**    | `/green`               | Minimal implementation to pass tests (no over-engineering)     |
+| **refactor** | `/refactor`            | Clean up code while keeping tests green                        |
+| **cycle**    | `/cycle [description]` | Complete Red → Green → Refactor loop                           |
+
+### Planning & Analysis (3 skills)
+
+| Skill     | Usage             | Description                                         |
+| --------- | ----------------- | --------------------------------------------------- |
+| **plan**  | `/plan [feature]` | Create implementation plan with PRD-style discovery |
+| **gap**   | `/gap`            | Analyze code vs requirements for missing pieces     |
+| **issue** | `/issue [url]`    | Create TDD plan from GitHub issue                   |
+
+### Git Operations (5 skills)
+
+| Skill                | Usage                          | Description                                    |
+| -------------------- | ------------------------------ | ---------------------------------------------- |
+| **commit**           | `/commit`                      | Semantic commit with co-author attribution     |
+| **pr**               | `/pr`                          | Create pull request with summary and test plan |
+| **busycommit**       | `/busycommit`                  | Multiple atomic commits for complex changesets |
+| **worktree-add**     | `/worktree-add [branch/issue]` | Add git worktree from branch or issue          |
+| **worktree-cleanup** | `/worktree-cleanup`            | Clean up merged worktrees                      |
+
+### Workflow Utilities (5 skills)
+
+| Skill           | Usage          | Description                          |
+| --------------- | -------------- | ------------------------------------ |
+| **spike**       | `/spike`       | Exploratory coding before formal TDD |
+| **tdd**         | `/tdd`         | Remind agent about TDD practices     |
+| **beepboop**    | `/beepboop`    | Transparent AI attribution markers   |
+| **summarize**   | `/summarize`   | Conversation progress summary        |
+| **add-command** | `/add-command` | Guide for creating new skills        |
+
+## 🏗️ Architecture
+
+### 14-Phase Workflow
+
+```
+Phase 1:  DISAMBIGUATION     - Clarify ambiguous terms before research
+Phase 2:  SCOPE              - Confirm understanding of endpoint
+Phase 3:  INITIAL RESEARCH   - 2-3 targeted searches (Context7, WebSearch)
+Phase 4:  INTERVIEW          - Questions FROM discovered params
+Phase 5:  DEEP RESEARCH      - Adaptive propose-approve searches
+Phase 6:  SCHEMA             - Zod schema from research + interview
+Phase 7:  ENVIRONMENT        - Verify API keys exist
+Phase 8:  TDD RED            - Write failing tests from schema
+Phase 9:  TDD GREEN          - Minimal implementation to pass
+Phase 10: VERIFY             - Re-research docs, compare to implementation
+Phase 11: CODE REVIEW        - Greptile AI review (bugs, security, performance)
+Phase 12: TDD REFACTOR       - Fix review issues, clean up code
+Phase 13: DOCUMENTATION      - Update manifests, cache research
+Phase 14: COMPLETION         - Final verification, commit
+```
+
+### Loop-Back Architecture
+
+Every verification phase can loop back if not successful:
+
+- Phase 1: Loop if disambiguation unclear
+- Phase 3: Loop if more research needed
+- Phase 4: Loop if interview incomplete
+- Phase 6: Loop if schema incorrect
+- Phase 8: Loop if test plan needs changes
+- Phase 10: Loop if gaps found in implementation
+- Phase 11: Loop if code review finds issues to fix
+- Phase 13: Loop if documentation incomplete
+
+### State Tracking
+
+All progress tracked in `.claude/api-dev-state.json`:
+
+```json
+{
+  "version": "3.0.0",
+  "endpoint": null,
+  "turn_count": 0,
+  "phases": {},
+  "research_index": {}
+}
+```
+
+### Research Cache
+
+Documentation cached in `.claude/research/` with 7-day freshness:
+
+```
+.claude/research/
+├── brandfetch/
+│   ├── 2025-12-08_initial.md
+│   ├── 2025-12-08_deep.md
+│   └── CURRENT.md
+└── index.json  ← Freshness tracking
+```
+
+## ⚙️ Requirements
+
+### Required
+
+- **Claude Code**: 1.0.0 or higher (or compatible platform)
+- **Python**: 3.9+ (for enforcement hooks)
+- **Node.js**: 18+ (for package management)
+- **pnpm**: 10.11.0+ (package manager)
+
+### MCP Servers (Recommended)
+
+- **Context7**: Documentation search and discovery
+- **GitHub**: PR and issue integration
+
+### Optional but Recommended
+
+- **Enforcement Hooks**: 22 Python scripts that enforce workflow rules
+- **Settings.json**: Hook registration for lifecycle events
+
+## 🔒 Enforcement Hooks (22 Total)
+
+For full workflow enforcement, install hooks to `hooks/`:
+
+### Hook Types
+
+| Event                | Hooks                                                                                                                          | Purpose                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| **SessionStart**     | session-startup.py                                                                                                             | Inject state context at session start                                             |
+| **UserPromptSubmit** | enforce-external-research.py                                                                                                   | Detect API terms, require research                                                |
+| **PreToolUse**       | enforce-research.py, enforce-interview.py, verify-implementation.py, enforce-component-type-confirm.py, notify-input-needed.py | Block writes until phases complete, inject decisions, confirm component type      |
+| **PostToolUse**      | track-tool-use.py, periodic-reground.py, verify-after-green.py, notify-phase-complete.py, track-token-usage.py                 | Log research, re-ground every 7 turns, trigger verification, notify, track tokens |
+| **Stop**             | api-workflow-check.py                                                                                                          | Block if phases incomplete                                                        |
+
+### What Hooks Enforce
+
+1. **Research Before Implementation**: Cannot write code without researching documentation
+2. **Interview Before Schema**: Cannot create Zod schema without user interview
+3. **Tests Before Implementation**: Cannot write route without test file
+4. **Verification After Green**: Automatically triggers re-research after tests pass
+5. **Documentation Completeness**: Blocks completion if docs not updated
+6. **7-Turn Re-grounding**: Prevents context dilution in long sessions
+
+## 🎯 Key Principles
+
+1. **Loop Until Green** - Every verification phase loops back if not successful
+2. **Questions FROM Research** - Never use generic template questions
+3. **Adaptive Research** - Propose searches based on context, not shotgun
+4. **7-Turn Re-grounding** - Context injected every 7 turns to prevent dilution
+5. **Verify After Green** - Re-research to catch memory-based implementation errors
+
+## 📖 Usage Examples
+
+### Example 1: Create New API Endpoint
+
+```bash
+# Fully automated workflow
+/api-create my-endpoint
+
+# Follows all 14 phases automatically
+# Asks for user input at each checkpoint
+# Loops back if verification fails
+# Creates tests, implementation, docs
+```
+
+### Example 2: Manual Step-by-Step
+
+```bash
+# Research external API
+/api-research stripe
+
+# Interview for requirements
+/api-interview payment
+
+# Check environment
+/api-env payment
+
+# TDD workflow
+/red
+/green
+/refactor
+
+# Verify implementation
+/api-verify payment
+
+# Commit
+/commit
+```
+
+### Example 3: From GitHub Issue
+
+```bash
+# Create plan from issue
+/issue https://github.com/org/repo/issues/123
+
+# Execute plan
+/cycle implement feature from issue
+
+# Create PR
+/pr
+```
+
+## 🌍 Platform Compatibility
+
+### ✅ Full Support (with hooks)
+
+- **Claude Code**: Complete workflow with all enforcement hooks
+
+### ✅ Partial Support (skills only)
+
+- **VS Code with GitHub Copilot**: Skills work, manual hook setup required
+- **Cursor**: Skills work, manual hook setup required
+- **ChatGPT**: Skills work, no hook support
+- **Any Agent Skills-compatible platform**: Basic skill usage
+
+### Hook Setup for Non-Claude Code Platforms
+
+1. Copy `.skills/_shared/hooks/` to your project
+2. Copy `.skills/_shared/settings.json` to your project
+3. Configure your IDE/platform to run hooks (varies by platform)
+4. Hooks are OPTIONAL for basic usage
+5. Hooks are REQUIRED for full workflow enforcement
+
+## 📦 Distribution
+
+- **GitHub**: [hustle-together/api-dev-tools](https://github.com/hustle-together/api-dev-tools)
+- **NPM**: [@hustle-together/api-dev-tools](https://npmjs.com/package/@hustle-together/api-dev-tools)
+- **SkillsMP**: [skillsmp.com](https://skillsmp.com) (pending submission)
+
+## 📄 License
+
+MIT License - See [LICENSE](../../LICENSE) file
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/hustle-together/api-dev-tools/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/hustle-together/api-dev-tools/discussions)
+- **Email**: contact@hustletogether.dev
+
+## 🔗 Resources
+
+- [Agent Skills Specification](https://agentskills.io/specification)
+- [Claude Code Documentation](https://code.claude.com/docs)
+- [Future Roadmap](../../ROADMAP.md)
+
+---
+
+**Built with ❤️ by Hustle Together**
+_Empowering developers with interview-driven, research-first API development_

package/.skills/_shared/convert-commands.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+Convert .claude/commands/*.md files to .skills/*/SKILL.md format
+Adds YAML frontmatter while preserving all original content
+"""
+import os
+import re
+from pathlib import Path
+
+# Skill metadata templates
+SKILL_METADATA = {
+    "api-interview": {
+        "description": "Structured interview for API requirements gathering. Questions generated FROM research findings, not templates. Use when you need to understand API parameter preferences, error handling, formats, and user decisions. Keywords: interview, requirements, api, questions, research, decisions",
+        "category": "development",
+        "tags": ["api", "interview", "requirements", "research"],
+    },
+    "api-research": {
+        "description": "Adaptive propose-approve research workflow for API documentation discovery. Use when researching external APIs, SDKs, or libraries. Caches research with 7-day freshness tracking. Keywords: research, documentation, api, discovery, cache, adaptive",
+        "category": "research",
+        "tags": ["api", "research", "documentation", "discovery", "cache"],
+    },
+    "api-verify": {
+        "description": "Manual Phase 10 verification - re-research documentation after tests pass to catch memory-based implementation errors. Compares implementation to docs, reports gaps. Use after TDD Green phase. Keywords: verification, testing, documentation, gaps, quality",
+        "category": "testing",
+        "tags": ["verification", "testing", "documentation", "quality"],
+    },
+    "api-env": {
+        "description": "Check required API keys and environment variables. Supports server env vars, NEXT_PUBLIC_ vars, and custom headers. Use before starting implementation. Keywords: environment, api-keys, configuration, setup, validation",
+        "category": "development",
+        "tags": ["environment", "api-keys", "configuration", "setup"],
+    },
+    "api-status": {
+        "description": "Track implementation progress through 13 phases. Shows completed, in-progress, and pending phases. Displays interview decisions and research cache info. Keywords: status, progress, tracking, phases, workflow",
+        "category": "workflow",
+        "tags": ["status", "progress", "tracking", "workflow"],
+    },
+    "red": {
+        "description": "TDD Red Phase - write ONE failing test that defines success before writing implementation. Use at the start of feature development to prevent over-engineering. Keywords: tdd, testing, red-phase, test-driven, failure",
+        "category": "testing",
+        "tags": ["tdd", "testing", "red-phase", "test-driven"],
+    },
+    "green": {
+        "description": "TDD Green Phase - write minimal implementation code to make the failing test pass. No over-engineering, just enough to pass. Use after writing failing tests. Keywords: tdd, testing, green-phase, implementation, minimal",
+        "category": "testing",
+        "tags": ["tdd", "testing", "green-phase", "implementation"],
+    },
+    "refactor": {
+        "description": "TDD Refactor Phase - improve code structure, readability, and performance while keeping all tests green. Use after tests pass to clean up code. Keywords: tdd, refactoring, cleanup, optimization, quality",
+        "category": "testing",
+        "tags": ["tdd", "refactoring", "cleanup", "optimization"],
+    },
+    "cycle": {
+        "description": "Execute complete TDD cycle - Red (write failing test) → Green (minimal implementation) → Refactor (cleanup). Use for feature development with single command. Keywords: tdd, cycle, workflow, testing, automation",
+        "category": "workflow",
+        "tags": ["tdd", "cycle", "workflow", "testing"],
+    },
+    "plan": {
+        "description": "Create implementation plan from feature or requirement with PRD-style discovery and TDD acceptance criteria. Generates step-by-step checklist. Use before starting complex features. Keywords: planning, prd, requirements, checklist, strategy",
+        "category": "planning",
+        "tags": ["planning", "prd", "requirements", "strategy"],
+    },
+    "gap": {
+        "description": "Analyze conversation context for unaddressed items and gaps. Scans code vs requirements to find missing pieces. Use during code review or planning. Keywords: analysis, gaps, requirements, review, completeness",
+        "category": "analysis",
+        "tags": ["analysis", "gaps", "requirements", "review"],
+    },
+    "issue": {
+        "description": "Analyze GitHub issue and create TDD implementation plan. Converts issue requirements into executable tasks with acceptance criteria. Use when starting work from issues. Keywords: github, issues, planning, tdd, requirements",
+        "category": "workflow",
+        "tags": ["github", "issues", "planning", "tdd"],
+    },
+    "commit": {
+        "description": "Create semantic git commit following project standards with co-author attribution. Analyzes staged changes, suggests commit message. Use after completing features. Keywords: git, commit, semantic, versioning, attribution",
+        "category": "git",
+        "tags": ["git", "commit", "semantic", "versioning"],
+    },
+    "pr": {
+        "description": "Create pull request using GitHub MCP. Generates PR summary from all commits, creates test plan. Use after pushing feature branch. Keywords: github, pull-request, pr, collaboration, review",
+        "category": "git",
+        "tags": ["github", "pull-request", "pr", "collaboration"],
+    },
+    "spike": {
+        "description": "Execute TDD Spike Phase - exploratory coding to understand problem space before formal TDD. Use when requirements are unclear or architecture needs exploration. Keywords: spike, exploration, prototyping, learning, architecture",
+        "category": "workflow",
+        "tags": ["spike", "exploration", "prototyping", "learning"],
+    },
+    "beepboop": {
+        "description": "Communicate AI-generated content with transparent attribution. Adds markers indicating AI authorship. Use when sharing AI-generated code or content. Keywords: attribution, transparency, ai-generated, ethics, communication",
+        "category": "workflow",
+        "tags": ["attribution", "transparency", "ai-generated", "ethics"],
+    },
+    "worktree-add": {
+        "description": "Add new git worktree from branch name or GitHub issue URL. Copies settings, installs deps, opens in IDE. Use for parallel feature development. Keywords: git, worktree, parallel, workflow, branches",
+        "category": "git",
+        "tags": ["git", "worktree", "parallel", "workflow"],
+    },
+    "worktree-cleanup": {
+        "description": "Clean up merged worktrees by verifying PR/issue status, consolidating settings, removing stale worktrees. Use after merging features. Keywords: git, worktree, cleanup, maintenance, branches",
+        "category": "git",
+        "tags": ["git", "worktree", "cleanup", "maintenance"],
+    },
+    "busycommit": {
+        "description": "Create multiple atomic git commits, one logical change at a time. Analyzes changes and separates into meaningful commits. Use for complex changesets. Keywords: git, commit, atomic, granular, organization",
+        "category": "git",
+        "tags": ["git", "commit", "atomic", "granular"],
+    },
+    "add-command": {
+        "description": "Guide for creating new slash commands or agent skills. Provides templates and best practices. Use when extending the toolkit. Keywords: meta, commands, skills, templates, development",
+        "category": "meta",
+        "tags": ["meta", "commands", "skills", "templates"],
+    },
+    "tdd": {
+        "description": "Remind agent about TDD approach and continue conversation. Reinforces test-first methodology. Use when agent deviates from TDD practices. Keywords: tdd, reminder, methodology, testing, practices",
+        "category": "workflow",
+        "tags": ["tdd", "reminder", "methodology", "testing"],
+    },
+    "summarize": {
+        "description": "Summarize conversation progress and next steps. Provides overview of completed work and remaining tasks. Use at end of sessions or before breaks. Keywords: summary, progress, overview, tracking, communication",
+        "category": "workflow",
+        "tags": ["summary", "progress", "overview", "tracking"],
+    },
+}
+
+def extract_title(content: str) -> str:
+    """Extract title from markdown heading"""
+    match = re.search(r'^#\s+(.+)$', content, re.MULTILINE)
+    return match.group(1) if match else "Untitled"
+
+def convert_command_to_skill(command_file: Path, skills_dir: Path):
+    """Convert a command .md file to SKILL.md format"""
+    # Read original command
+    content = command_file.read_text()
+
+    # Extract skill name from filename
+    skill_name = command_file.stem
+
+    # Skip README and already converted
+    if skill_name in ["README", "api-create"]:
+        print(f"⏭️  Skipping {skill_name}")
+        return
+
+    # Get metadata or use defaults
+    metadata = SKILL_METADATA.get(skill_name, {
+        "description": f"{skill_name} command. Use when working with {skill_name} related tasks.",
+        "category": "workflow",
+        "tags": [skill_name],
+    })
+
+    # Create YAML frontmatter
+    frontmatter = f"""---
+name: {skill_name}
+description: {metadata['description']}
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "{metadata['category']}"
+  tags: {metadata['tags']}
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+"""
+
+    # Combine frontmatter + original content
+    skill_content = frontmatter + content
+
+    # Create skill directory and write SKILL.md
+    skill_dir = skills_dir / skill_name
+    skill_dir.mkdir(exist_ok=True)
+    skill_file = skill_dir / "SKILL.md"
+    skill_file.write_text(skill_content)
+
+    print(f"✅ Converted {skill_name}")
+
+def main():
+    # Set up paths
+    repo_root = Path(__file__).parent.parent.parent
+    commands_dir = repo_root / ".claude" / "commands"
+    skills_dir = repo_root / ".skills"
+
+    print("🔄 Converting commands to Agent Skills format...\n")
+
+    # Convert all command files
+    for command_file in sorted(commands_dir.glob("*.md")):
+        convert_command_to_skill(command_file, skills_dir)
+
+    print("\n✨ Conversion complete!")
+    print(f"📁 Skills created in: {skills_dir}")
+
+if __name__ == "__main__":
+    main()