@hustle-together/api-dev-tools 3.12.3 → 4.5.1

package/.skills/api-research/SKILL.md

@@ -42,6 +42,103 @@ Run 2-3 targeted searches:
 - WebSearch: "site:[domain] api reference" (if known domain)
 ```
 
+### Table of Contents Scraping (CRITICAL)
+
+**Always fetch and parse the documentation Table of Contents first!**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    TOC DISCOVERY FLOW                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Step 1: Find Docs Root                                        │
+│  ├─ WebSearch: "[name] documentation"                          │
+│  └─ Extract: docs.example.com or example.com/docs              │
+│                                                                 │
+│  Step 2: Fetch TOC Page                                        │
+│  ├─ WebFetch: docs.example.com + look for sidebar/nav          │
+│  ├─ WebFetch: docs.example.com/api-reference                   │
+│  └─ WebFetch: docs.example.com/sitemap.xml (if available)      │
+│                                                                 │
+│  Step 3: Extract All Sections                                  │
+│  ├─ Getting Started                                            │
+│  ├─ Authentication                                             │
+│  ├─ API Reference                                              │
+│  │   ├─ Endpoints                                              │
+│  │   ├─ Parameters                                             │
+│  │   ├─ Response Codes                                         │
+│  │   └─ Webhooks                                               │
+│  ├─ SDKs & Libraries                                           │
+│  ├─ Rate Limits                                                │
+│  ├─ Errors                                                     │
+│  └─ Changelog                                                  │
+│                                                                 │
+│  Step 4: Prioritize for Interview                              │
+│  ├─ Which sections have parameters we need to ask about?       │
+│  ├─ Which sections have optional features?                     │
+│  └─ Which sections have configuration options?                 │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Comprehensive Discovery Checklist
+
+Before proceeding to interview, ensure we've discovered:
+
+```markdown
+## Pre-Interview Discovery Checklist
+
+### Authentication & Authorization
+- [ ] Auth method (API key, OAuth, Bearer token, Basic)
+- [ ] Where to get credentials (dashboard URL)
+- [ ] Token refresh mechanism
+- [ ] Scopes/permissions available
+
+### Endpoints
+- [ ] All available endpoints listed
+- [ ] HTTP methods for each
+- [ ] Path parameters identified
+- [ ] Query parameters with types
+- [ ] Request body schemas
+
+### Parameters (CRITICAL for Interview)
+- [ ] Required vs optional distinction
+- [ ] Parameter types (string, number, enum, array)
+- [ ] Enum values listed
+- [ ] Default values documented
+- [ ] Validation rules/constraints
+- [ ] Continuous parameters (ranges for testing)
+
+### Response Schemas
+- [ ] Success response structure
+- [ ] Error response format
+- [ ] HTTP status codes used
+- [ ] Pagination format
+
+### Rate Limits & Quotas
+- [ ] Requests per minute/hour/day
+- [ ] Rate limit headers
+- [ ] Retry behavior
+- [ ] Quota types (per key, per user)
+
+### Webhooks (if applicable)
+- [ ] Available webhook events
+- [ ] Payload structure
+- [ ] Signature verification
+- [ ] Retry behavior
+
+### SDKs & Libraries
+- [ ] Official SDK availability
+- [ ] npm/pip/cargo package names
+- [ ] TypeScript types available?
+- [ ] Version compatibility
+
+### Errors
+- [ ] Error code catalog
+- [ ] Error message format
+- [ ] Troubleshooting steps
+```
+
 Present initial summary:
 
 ```
@@ -367,4 +464,37 @@ All research is tracked in `.claude/api-dev-state.json`:
 - Phase 5 uses adaptive proposal flow
 - Phase 10 (Verify) triggers re-research
 - Freshness check prevents stale data
+
+## ADR Integration (Automatic)
+
+When research discovers **multiple options for a significant decision**, the
+`generate-adr-options.py` hook automatically:
+
+1. Detects significant decisions (database, auth, cache, hosting, etc.)
+2. Creates a research request in `.claude/adr-requests/pending-{category}.json`
+3. Injects context telling you to run `/adr-deep-research {category}`
+
+**You should then run the deep research skill to:**
+
+- Spawn parallel agents to research each option
+- Fetch official documentation for each technology
+- Extract real pros, cons, pricing, and best-use cases
+- Create a substantive ADR before the interview phase
+
+```
+Example Flow:
+1. /api-research supabase
+   → Hook detects: database options (supabase, firebase, postgres)
+   → Creates: .claude/adr-requests/pending-database.json
+   → Injects: "Run /adr-deep-research database"
+
+2. /adr-deep-research database
+   → Spawns 3 parallel agents (one per option)
+   → Each agent fetches docs, extracts pros/cons
+   → Creates: .claude/adrs/ADR-0001-database-choice.md (with real content)
+
+3. Interview phase references ADR for informed decision
+```
+
+See `/adr-deep-research` skill and `docs/ARCHITECTURE_DECISION_RECORDS.md`.
   </claude-commands-template>

package/.skills/docs-sync/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: docs-sync
+description: Synchronize documentation after code changes. Updates existing docs, creates new ones for features, and ensures README links.
+license: MIT
+compatibility: Requires Claude Code with hooks
+metadata:
+  version: "1.0.0"
+  category: "documentation"
+  tags: ["docs", "readme", "sync", "maintenance"]
+  author: "Hustle Together"
+allowed-tools: Read Write Edit Glob Grep
+---
+
+# Docs Sync - Documentation Synchronization Skill
+
+Ensures documentation stays in sync with code changes. Run after implementing features, fixing gaps, or adding new capabilities.
+
+## Usage
+
+```bash
+/docs-sync                    # Analyze and sync all docs
+/docs-sync [feature-name]     # Sync docs for specific feature
+/docs-sync --check            # Check what needs updating (no writes)
+```
+
+## What This Skill Does
+
+### 1. Analyze Recent Changes
+
+First, examine what changed:
+- Read git diff or recent file modifications
+- Identify new hooks, skills, agents, or features
+- Detect removed or deprecated functionality
+
+### 2. Update Existing Documentation
+
+For each affected area, update the relevant doc:
+
+| Change Type | Doc to Update |
+|-------------|---------------|
+| New hook | `docs/HOOKS.md` |
+| New skill | `docs/SKILLS.md` |
+| New agent | `docs/AGENTS.md` |
+| Orchestrator change | `docs/ORCHESTRATOR.md` |
+| Re-grounding change | `docs/REGROUNDING.md` |
+| Gap fixed | `docs/GAP_ANALYSIS.md` |
+| Best practice added | `docs/CLAUDE_CODE_BEST_PRACTICES.md` |
+
+### 3. Create New Documentation
+
+If a feature warrants its own doc:
+
+1. Create `docs/[FEATURE_NAME].md`
+2. Use the standard header template (see below)
+3. Add link to README.md Core Reference table
+
+### 4. Ensure Problem/Solution Headers
+
+Every doc MUST have this header format:
+
+```markdown
+# [Document Title]
+
+**Version:** X.X.X
+**Last Updated:** YYYY-MM-DD
+
+> **The Problem**
+>
+> [Clear description of the pain point this addresses]
+
+> **The Solution**
+>
+> [How this document/feature solves the problem]
+
+---
+```
+
+### 5. Update README Links
+
+Add any new docs to the appropriate section in README.md:
+
+```markdown
+### Core Reference
+
+| Document | Purpose |
+| -------- | ------- |
+| **[docs/NEW_DOC.md](./docs/NEW_DOC.md)** | Brief description |
+```
+
+---
+
+## Document Header Template
+
+Use this exact format for all documentation:
+
+```markdown
+# [Title]
+
+**Version:** [version]
+**Last Updated:** [date]
+
+> **The Problem**
+>
+> [Describe the specific pain point, frustration, or gap this addresses.
+> Be concrete - what goes wrong without this? What do users struggle with?]
+
+> **The Solution**
+>
+> [Explain how this document/feature solves the problem.
+> What improvements does it provide? What's the benefit?]
+
+---
+
+## Table of Contents
+...
+```
+
+---
+
+## Execution Steps
+
+### Step 1: Identify Changes
+
+```bash
+# Check what files changed recently
+git diff --name-only HEAD~5
+# Or check specific areas
+ls -la hooks/
+ls -la .skills/
+ls -la docs/
+```
+
+Look for:
+- New `.py` files in `hooks/`
+- New folders in `.skills/`
+- New `.md` files in `.claude/agents/`
+- Modified core files
+
+### Step 2: Categorize Updates Needed
+
+Create a checklist:
+
+```markdown
+## Documentation Updates Needed
+
+### Existing Docs to Update
+- [ ] docs/HOOKS.md - Add [hook name]
+- [ ] docs/SKILLS.md - Add [skill name]
+- [ ] docs/GAP_ANALYSIS.md - Mark [gap] as fixed
+
+### New Docs to Create
+- [ ] docs/[FEATURE].md - New feature documentation
+
+### README Updates
+- [ ] Add link to [new doc]
+```
+
+### Step 3: Update Each Document
+
+For each doc that needs updating:
+
+1. **Read current content**
+2. **Add/update the Problem/Solution header if missing**
+3. **Add new sections for new features**
+4. **Update version and date**
+5. **Ensure See Also section includes related docs**
+
+### Step 4: Create New Documents
+
+For genuinely new features that need their own doc:
+
+1. Create file with header template
+2. Write comprehensive content
+3. Add to README Core Reference table
+4. Cross-link from related docs
+
+### Step 5: Verify Links
+
+Check all links work:
+- Internal doc links (`[text](./OTHER_DOC.md)`)
+- README links to docs
+- See Also sections
+
+---
+
+## Problem/Solution Examples
+
+### Good Example (REGROUNDING.md)
+
+```markdown
+> **The Problem**
+>
+> LLMs suffer from "context dilution" - as conversations grow longer,
+> the original instructions (CLAUDE.md, system prompts) get pushed to
+> the "middle" of the context where attention is weakest. Claude starts
+> forgetting the endpoint name, re-asking answered questions, and
+> recreating existing components.
+
+> **The Solution**
+>
+> The Re-Grounding System injects a comprehensive state reminder every
+> 7 turns, pushing critical context to the END where attention is
+> strongest. This includes current phase, key decisions, existing
+> registry elements, and deferred features - preventing the "lost in
+> the middle" problem.
+```
+
+### Good Example (ORCHESTRATOR.md)
+
+```markdown
+> **The Problem**
+>
+> Building complex features requires multiple workflows (APIs, components,
+> pages) that depend on each other. Running them manually means answering
+> the same questions repeatedly, managing dependency order yourself, and
+> manually wiring completed elements together.
+
+> **The Solution**
+>
+> The Orchestrator decomposes natural language requests into workflows,
+> orders them by dependency, shares decisions across all sub-workflows
+> (ask once, apply everywhere), and automatically wires completed
+> elements with proper imports and types.
+```
+
+---
+
+## Checklist Before Completing
+
+- [ ] All affected docs have Problem/Solution headers
+- [ ] New features are documented
+- [ ] README links are updated
+- [ ] Version numbers are bumped
+- [ ] Dates are updated
+- [ ] See Also sections cross-reference related docs
+- [ ] GAP_ANALYSIS.md reflects current state
+
+---
+
+## Output
+
+After running this skill, report:
+
+```markdown
+## Documentation Sync Complete
+
+### Updated
+- docs/HOOKS.md - Added auto-format hook
+- docs/GAP_ANALYSIS.md - Marked 3 gaps as fixed
+
+### Created
+- docs/NEW_FEATURE.md - New feature documentation
+
+### README
+- Added link to NEW_FEATURE.md
+
+### Headers Added
+- docs/SKILLS.md - Added Problem/Solution header
+- docs/AGENTS.md - Added Problem/Solution header
+```

package/.skills/docs-update/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: docs-update
+description: Ensure README, CHANGELOG, and docs stay current with features
+tools: Read, Write, Edit, Glob, Grep, Task, TodoWrite
+model: sonnet
+---
+
+# Documentation Update Skill
+
+Automatically maintains documentation consistency when features are added or changed. This skill is invoked by the `docs-update-check.py` hook after significant changes.
+
+## Philosophy
+
+> **README is the single source of truth** - It should provide a comprehensive overview
+> without becoming too long. Detailed docs live in `/docs/*.md`.
+
+### Update Rules
+
+1. **README.md** - Update only when:
+   - New major feature added (new skill, new workflow)
+   - Links section needs new doc reference
+   - Counts change (skills, hooks, agents)
+   - Version number changes
+   - Never let it exceed ~500 lines
+
+2. **CHANGELOG.md** - Always update when:
+   - New features added
+   - Breaking changes
+   - Bug fixes
+   - Version bump
+
+3. **docs/*.md** - Create/update when:
+   - New feature needs detailed explanation
+   - Existing doc is out of date
+   - Command signature changes
+
+## When This Skill Runs
+
+Triggered by `docs-update-check.py` hook when:
+- New skill created in `.skills/`
+- New hook added to `hooks/`
+- New agent defined in `.claude/agents/`
+- New doc created in `docs/`
+- registry.json sections added/changed
+
+## Execution Flow
+
+### Step 1: Detect What Changed
+
+```bash
+# Get recently modified files
+git diff --name-only HEAD~1 HEAD
+
+# Or for uncommitted changes
+git status --porcelain
+```
+
+### Step 2: Categorize Changes
+
+| File Pattern | Category | Action |
+|--------------|----------|--------|
+| `.skills/*/SKILL.md` | New Skill | Update README skills count, add to docs/SKILLS.md |
+| `hooks/*.py` | New Hook | Update README hooks count, add to docs/HOOKS.md |
+| `.claude/agents/*.md` | New Agent | Update README agents count, add to docs/AGENTS.md |
+| `docs/*.md` | New Doc | Add to README Documentation section |
+| `templates/*.tsx` | New Template | Consider dashboard integration |
+
+### Step 3: Update README Links
+
+Check if new docs need to be linked:
+
+```markdown
+## Documentation
+
+### Core Reference
+
+| Document | Purpose |
+| -------- | ------- |
+| **[docs/NEW_DOC.md](./docs/NEW_DOC.md)** | Description here |
+```
+
+### Step 4: Update CHANGELOG
+
+Add entry under current version or create new version:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- **`/new-skill`** - Description of what it does
+```
+
+### Step 5: Update Feature Doc
+
+If change affects an existing command, update its doc:
+
+```bash
+# Map skill to doc
+/api-create → docs/API-CREATE.md
+/hustle-ui-create → docs/HUSTLE-UI-CREATE.md
+/test-review → docs/SKILLS.md (test skills section)
+```
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════════
+                    DOCUMENTATION UPDATE
+═══════════════════════════════════════════════════════════════
+
+Changes Detected:
+  • New skill: /docs-update
+  • New doc: docs/PARALLEL_AUTONOMOUS_WORKFLOW.md
+  • Modified: .skills/hustle-build/SKILL.md
+
+Updates Made:
+  ✅ README.md - Added parallel workflow to docs section
+  ✅ CHANGELOG.md - Added v4.3.0 entry
+  ✅ docs/SKILLS.md - Added docs-update skill reference
+  ⏭️  docs/HOOKS.md - No changes needed
+
+Verification:
+  • README length: 516 lines (target: <600)
+  • All new docs linked: Yes
+  • CHANGELOG has entry: Yes
+
+═══════════════════════════════════════════════════════════════
+```
+
+## Decision Tree
+
+```
+New Feature Added?
+    │
+    ├─► Is it a major workflow change?
+    │       │
+    │       ├─► YES: Create new doc in docs/
+    │       │        Update README links
+    │       │        Update CHANGELOG
+    │       │
+    │       └─► NO: Is it an enhancement to existing command?
+    │               │
+    │               ├─► YES: Update that command's doc
+    │               │        Update CHANGELOG
+    │               │
+    │               └─► NO: Is it a minor fix?
+    │                       │
+    │                       └─► YES: Update CHANGELOG only
+    │
+    └─► Removing a feature?
+            │
+            ├─► WARNING: Removal requires justification
+            │   Only remove if:
+            │   - Feature never worked
+            │   - Replaced by better feature
+            │   - Security issue
+            │
+            └─► Update CHANGELOG with [BREAKING] if public API
+```
+
+## README Structure Limits
+
+| Section | Max Lines | Current |
+|---------|-----------|---------|
+| Header/Banner | 30 | - |
+| Quick Start | 20 | - |
+| Workflows | 50 | - |
+| Phases Diagram | 30 | - |
+| What Gets Installed | 20 | - |
+| Subagents | 20 | - |
+| Commands | 40 | - |
+| Documentation Links | 60 | - |
+| FAQ | 150 | - |
+| **Total** | **~500** | - |
+
+If README exceeds 600 lines, move content to dedicated docs.
+
+## Commands
+
+```bash
+# Run documentation update check
+/docs-update
+
+# Check what would be updated (dry run)
+/docs-update --dry-run
+
+# Force update all docs
+/docs-update --force
+
+# Update specific doc only
+/docs-update --target README
+```
+
+## Integration
+
+This skill integrates with:
+- `docs-update-check.py` hook (PostToolUse on Write/Edit)
+- Phase 13 (Documentation) of all workflows
+- `/commit` skill (suggests doc updates before commit)
+
+## See Also
+
+- [docs/SKILLS.md](../../docs/SKILLS.md) - All skills reference
+- [docs/HOOKS.md](../../docs/HOOKS.md) - All hooks reference
+- [CHANGELOG.md](../../CHANGELOG.md) - Version history