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

package/templates/CLAUDE-SECTION.md

@@ -1,21 +1,37 @@
-## Hustle API Development Workflow (v3.7.0)
+## Hustle API Development Workflow (v4.0.0)
 
-This project uses **@hustle-together/api-dev-tools** for interview-driven, research-first API development.
+This project uses **@hustle-together/api-dev-tools** for interview-driven, research-first development.
+
+### Project Context
+
+<!-- INSTALLER: Replace these with actual project values -->
+**Tech Stack:** [Framework] + [Language] + [Database]
+**UI Library:** [UI framework or component library]
+**Testing:** [Test framework] + [E2E framework]
+
+### Existing Elements
+
+<!-- AUTO-POPULATED: Updated by registry hooks -->
+**APIs:** (check `.claude/registry.json`)
+**Components:** (check `.claude/registry.json`)
+**Pages:** (check `.claude/registry.json`)
 
 ### Available Commands
 
 | Command                            | Purpose                               |
 | ---------------------------------- | ------------------------------------- |
-| `/hustle-api-create [endpoint]`    | Complete 13-phase workflow            |
-| `/hustle-api-interview [endpoint]` | Questions FROM research findings      |
-| `/hustle-api-research [library]`   | Adaptive propose-approve research     |
-| `/hustle-api-verify [endpoint]`    | Re-research and verify implementation |
-| `/hustle-api-env [endpoint]`       | Check API keys                        |
-| `/hustle-api-status [endpoint]`    | Track progress                        |
-| `/hustle-api-continue [endpoint]`  | Resume interrupted workflow           |
-| `/hustle-api-sessions`             | Browse saved session logs             |
-
-### 13-Phase Flow
+| `/hustle-build [description]`      | Orchestrated multi-workflow build     |
+| `/api-create [endpoint]`           | Complete 14-phase API workflow        |
+| `/hustle-ui-create [component]`    | Component with Storybook              |
+| `/hustle-ui-create-page [page]`    | Page with Playwright E2E             |
+| `/hustle-combine [name]`           | Combine multiple APIs                 |
+| `/api-research [library]`          | Adaptive propose-approve research     |
+| `/api-interview [endpoint]`        | Questions FROM research findings      |
+| `/api-verify [endpoint]`           | Re-research and verify implementation |
+| `/api-env [endpoint]`              | Check API keys                        |
+| `/api-status [endpoint]`           | Track progress                        |
+
+### 14-Phase Flow
 
 ```
 Phase 1:  DISAMBIGUATION     - Clarify ambiguous terms before research
@@ -28,18 +44,20 @@ Phase 7:  ENVIRONMENT        - Verify API keys exist
 Phase 8:  TDD RED            - Write failing tests from schema
 Phase 9:  TDD GREEN          - Minimal implementation to pass tests
 Phase 10: VERIFY             - Re-research docs, compare to implementation
-Phase 11: TDD REFACTOR       - Clean up code while tests pass
-Phase 12: DOCUMENTATION      - Update manifests, cache research
-Phase 13: COMPLETION         - Final verification, commit
+Phase 11: CODE REVIEW        - 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
 ```
 
 ### Key Principles
 
-1. **Loop Until Green** - Every verification phase loops back if not successful
+1. **Research-First** - Never write code from memory, always verify docs
 2. **Questions FROM Research** - Never use generic template questions
-3. **Adaptive Research** - Propose searches based on context, not shotgun
+3. **Loop Until Green** - Every verification phase loops back if not successful
 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
+6. **Registry Awareness** - Don't recreate existing elements
 
 ### State Tracking
 
@@ -49,7 +67,17 @@ All progress is tracked in `.claude/api-dev-state.json`:
 - Interview decisions (injected during implementation)
 - Research sources with freshness tracking
 - Turn count for re-grounding
-- Multi-API support with active endpoint pointer
+- Deferred features list
+- Test run history
+
+### Registry
+
+`.claude/registry.json` tracks all created elements:
+
+- APIs with endpoints, schemas, and examples
+- Components with props and variants
+- Pages with routes and data requirements
+- Combined APIs with orchestration patterns
 
 ### Research Cache
 
@@ -59,61 +87,58 @@ Research is cached in `.claude/research/` with 7-day freshness:
 - `[api-name]/CURRENT.md` - Latest research
 - `[api-name]/sources.json` - Research sources
 - `[api-name]/interview.json` - Interview decisions
-- `[api-name]/schema.json` - Schema snapshot
 - Stale research (>7 days) triggers re-research prompt
 
-### Hooks (25 Total - Automatic Enforcement)
-
-| Hook                               | Event            | Action                               |
-| ---------------------------------- | ---------------- | ------------------------------------ |
-| `session-startup.py`               | SessionStart     | Inject state context                 |
-| `detect-interruption.py`           | SessionStart     | Detect interrupted workflows         |
-| `enforce-external-research.py`     | UserPromptSubmit | Require research first               |
-| `enforce-disambiguation.py`        | PreToolUse       | Phase 1 enforcement                  |
-| `enforce-scope.py`                 | PreToolUse       | Phase 2 enforcement                  |
-| `enforce-research.py`              | PreToolUse       | Phase 3 enforcement                  |
-| `enforce-interview.py`             | PreToolUse       | Phase 4 - inject decisions           |
-| `enforce-deep-research.py`         | PreToolUse       | Phase 5 enforcement                  |
-| `enforce-schema.py`                | PreToolUse       | Phase 6 enforcement                  |
-| `enforce-environment.py`           | PreToolUse       | Phase 7 enforcement                  |
-| `enforce-tdd-red.py`               | PreToolUse       | Phase 8 enforcement                  |
-| `verify-implementation.py`         | PreToolUse       | Phase 9 helper                       |
-| `enforce-verify.py`                | PreToolUse       | Phase 10 enforcement                 |
-| `enforce-refactor.py`              | PreToolUse       | Phase 11 enforcement                 |
-| `enforce-documentation.py`         | PreToolUse       | Phase 12 enforcement                 |
-| `enforce-questions-sourced.py`     | PreToolUse       | Validate questions from research     |
-| `enforce-schema-from-interview.py` | PreToolUse       | Validate schema from interview       |
-| `track-tool-use.py`                | PostToolUse      | Log research, count turns            |
-| `periodic-reground.py`             | PostToolUse      | Re-inject context every 7 turns      |
-| `track-scope-coverage.py`          | PostToolUse      | Track implemented vs deferred        |
-| `verify-after-green.py`            | PostToolUse      | Trigger Phase 10 after tests pass    |
-| `cache-research.py`                | PostToolUse      | Create research cache files          |
-| `generate-manifest-entry.py`       | PostToolUse      | Auto-generate API documentation      |
-| `api-workflow-check.py`            | Stop             | Block if incomplete, generate output |
-| `session-logger.py`                | Stop             | Save session to api-sessions         |
-
-### Auto-Generated Documentation
-
-When Phase 12 completes, `generate-manifest-entry.py` automatically creates:
-
-- **Comprehensive curl examples** (minimal, full, auth, enum variations, boundary values)
-- **Complete test cases** (success, validation, required fields, types, boundaries, arrays)
-- **Parameter documentation** with all possible values
-- **Ready-to-use entries** for `api-tests-manifest.json`
+### Re-grounding System
+
+Every 7 turns, the system injects a reminder with:
+
+- Current endpoint and phase progress
+- Key interview decisions
+- Existing registry elements (don't recreate)
+- Deferred features (don't re-suggest)
+- Last test status (GREEN/RED)
+- Brand guide status
+- Research freshness warnings
+- Orchestrator progress (if in /hustle-build)
+
+See: [docs/REGROUNDING.md](./docs/REGROUNDING.md)
+
+### Brand Guide
+
+If `.claude/BRAND_GUIDE.md` exists:
+
+- All UI components use brand colors/fonts
+- Enforce hook checks before component creation
+- Re-grounding reminds about brand guide
+
+### Hooks (45+ Automatic Enforcement)
+
+| Category | Hooks | Purpose |
+| -------- | ----- | ------- |
+| SessionStart | 4 | Inject state, detect interruptions, check updates |
+| UserPromptSubmit | 1 | Require research before API questions |
+| PreToolUse | 22 | Phase enforcement, schema validation |
+| PostToolUse | 12 | Tracking, re-grounding, registry updates |
+| Stop | 2 | Workflow completion, session logging |
 
 ### Usage
 
 ```bash
-# Full automated workflow
-/hustle-api-create my-endpoint
+# Orchestrated build (recommended for features)
+/hustle-build dashboard with user stats and activity charts
 
-# Manual step-by-step
-/hustle-api-research [library]
-/hustle-api-interview [endpoint]
-/hustle-api-env [endpoint]
+# Individual workflows
+/api-create stripe-checkout
+/hustle-ui-create StatCard
+/hustle-ui-create-page Dashboard
+
+# TDD cycle
 /red
 /green
-/hustle-api-verify [endpoint]
 /refactor
+
+# Git
 /commit
+/pr
 ```

package/templates/adr-viewer/_components/ADRViewer.tsx

@@ -0,0 +1,326 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+
+interface ADR {
+  number: number;
+  title: string;
+  status: 'proposed' | 'accepted' | 'deprecated' | 'superseded';
+  date: string;
+  phase: 'initial_research' | 'interview' | 'deep_research';
+  endpoint: string;
+  file: string;
+  supersededBy?: number;
+}
+
+interface ADRIndex {
+  adrs: ADR[];
+}
+
+const statusColors: Record<ADR['status'], string> = {
+  proposed: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-200',
+  accepted: 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200',
+  deprecated: 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200',
+  superseded: 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-200',
+};
+
+const phaseLabels: Record<ADR['phase'], string> = {
+  initial_research: 'Initial Research',
+  interview: 'Interview',
+  deep_research: 'Deep Research',
+};
+
+function StatusBadge({ status }: { status: ADR['status'] }) {
+  return (
+    <span className={`inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium ${statusColors[status]}`}>
+      {status.charAt(0).toUpperCase() + status.slice(1)}
+    </span>
+  );
+}
+
+function PhaseBadge({ phase }: { phase: ADR['phase'] }) {
+  const phaseColors: Record<ADR['phase'], string> = {
+    initial_research: 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200',
+    interview: 'bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200',
+    deep_research: 'bg-indigo-100 text-indigo-800 dark:bg-indigo-900 dark:text-indigo-200',
+  };
+
+  return (
+    <span className={`inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium ${phaseColors[phase]}`}>
+      {phaseLabels[phase]}
+    </span>
+  );
+}
+
+function ADRCard({ adr, onClick }: { adr: ADR; onClick: () => void }) {
+  return (
+    <div
+      onClick={onClick}
+      className="p-4 border rounded-lg cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors"
+    >
+      <div className="flex items-start justify-between">
+        <div>
+          <div className="flex items-center gap-2 mb-1">
+            <span className="text-sm font-mono text-gray-500">
+              ADR-{adr.number.toString().padStart(4, '0')}
+            </span>
+            <StatusBadge status={adr.status} />
+          </div>
+          <h3 className="text-lg font-semibold">{adr.title}</h3>
+        </div>
+        <span className="text-sm text-gray-500">{adr.date}</span>
+      </div>
+
+      <div className="mt-2 flex items-center gap-2">
+        <PhaseBadge phase={adr.phase} />
+        <span className="text-sm text-gray-500">→</span>
+        <span className="text-sm font-medium text-blue-600 dark:text-blue-400">
+          {adr.endpoint}
+        </span>
+      </div>
+
+      {adr.supersededBy && (
+        <div className="mt-2 text-sm text-gray-500">
+          Superseded by ADR-{adr.supersededBy.toString().padStart(4, '0')}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function ADRDetail({ adr, content, onBack }: { adr: ADR; content: string; onBack: () => void }) {
+  return (
+    <div>
+      <button
+        onClick={onBack}
+        className="mb-4 flex items-center gap-1 text-sm text-gray-500 hover:text-gray-700 dark:hover:text-gray-300"
+      >
+        <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+        </svg>
+        Back to list
+      </button>
+
+      <div className="flex items-center gap-4 mb-4">
+        <span className="text-lg font-mono text-gray-500">
+          ADR-{adr.number.toString().padStart(4, '0')}
+        </span>
+        <StatusBadge status={adr.status} />
+        <PhaseBadge phase={adr.phase} />
+      </div>
+
+      <h1 className="text-2xl font-bold mb-2">{adr.title}</h1>
+
+      <div className="text-sm text-gray-500 mb-6">
+        {adr.date} • {adr.endpoint}
+      </div>
+
+      <div
+        className="prose dark:prose-invert max-w-none"
+        dangerouslySetInnerHTML={{ __html: content }}
+      />
+    </div>
+  );
+}
+
+function EmptyState() {
+  return (
+    <div className="text-center py-12">
+      <svg className="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+      </svg>
+      <h3 className="mt-2 text-sm font-medium text-gray-900 dark:text-gray-100">No ADRs yet</h3>
+      <p className="mt-1 text-sm text-gray-500">
+        ADRs are created during Interview and Deep Research phases.
+      </p>
+      <p className="mt-2 text-xs text-gray-400">
+        Run <code className="bg-gray-100 dark:bg-gray-800 px-1 rounded">/api-create</code> to generate your first ADR.
+      </p>
+    </div>
+  );
+}
+
+function FilterBar({
+  statusFilter,
+  setStatusFilter,
+  phaseFilter,
+  setPhaseFilter,
+  searchQuery,
+  setSearchQuery,
+}: {
+  statusFilter: ADR['status'] | 'all';
+  setStatusFilter: (v: ADR['status'] | 'all') => void;
+  phaseFilter: ADR['phase'] | 'all';
+  setPhaseFilter: (v: ADR['phase'] | 'all') => void;
+  searchQuery: string;
+  setSearchQuery: (v: string) => void;
+}) {
+  return (
+    <div className="flex flex-wrap gap-4 mb-6">
+      <input
+        type="text"
+        placeholder="Search ADRs..."
+        value={searchQuery}
+        onChange={(e) => setSearchQuery(e.target.value)}
+        className="flex-1 min-w-[200px] px-3 py-2 border rounded-lg bg-white dark:bg-gray-800 focus:ring-2 focus:ring-blue-500 outline-none"
+      />
+
+      <select
+        value={statusFilter}
+        onChange={(e) => setStatusFilter(e.target.value as ADR['status'] | 'all')}
+        className="px-3 py-2 border rounded-lg bg-white dark:bg-gray-800"
+      >
+        <option value="all">All Statuses</option>
+        <option value="proposed">Proposed</option>
+        <option value="accepted">Accepted</option>
+        <option value="deprecated">Deprecated</option>
+        <option value="superseded">Superseded</option>
+      </select>
+
+      <select
+        value={phaseFilter}
+        onChange={(e) => setPhaseFilter(e.target.value as ADR['phase'] | 'all')}
+        className="px-3 py-2 border rounded-lg bg-white dark:bg-gray-800"
+      >
+        <option value="all">All Phases</option>
+        <option value="initial_research">Initial Research</option>
+        <option value="interview">Interview</option>
+        <option value="deep_research">Deep Research</option>
+      </select>
+    </div>
+  );
+}
+
+export default function ADRViewer() {
+  const [adrs, setAdrs] = useState<ADR[]>([]);
+  const [selectedAdr, setSelectedAdr] = useState<ADR | null>(null);
+  const [adrContent, setAdrContent] = useState<string>('');
+  const [loading, setLoading] = useState(true);
+  const [statusFilter, setStatusFilter] = useState<ADR['status'] | 'all'>('all');
+  const [phaseFilter, setPhaseFilter] = useState<ADR['phase'] | 'all'>('all');
+  const [searchQuery, setSearchQuery] = useState('');
+
+  useEffect(() => {
+    // In production, fetch from .claude/adrs/index.json
+    // For now, use mock data or empty state
+    const fetchADRs = async () => {
+      try {
+        const res = await fetch('/.claude/adrs/index.json');
+        if (res.ok) {
+          const data: ADRIndex = await res.json();
+          setAdrs(data.adrs);
+        }
+      } catch {
+        // No ADRs yet - show empty state
+        setAdrs([]);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchADRs();
+  }, []);
+
+  const handleSelectAdr = async (adr: ADR) => {
+    setSelectedAdr(adr);
+    try {
+      const res = await fetch(`/.claude/adrs/${adr.file}`);
+      if (res.ok) {
+        const text = await res.text();
+        // Basic markdown to HTML (in production, use a proper markdown parser)
+        const html = text
+          .replace(/^### (.+)$/gm, '<h3>$1</h3>')
+          .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+          .replace(/^# (.+)$/gm, '<h1>$1</h1>')
+          .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+          .replace(/\n\n/g, '</p><p>')
+          .replace(/^- (.+)$/gm, '<li>$1</li>');
+        setAdrContent(`<p>${html}</p>`);
+      }
+    } catch {
+      setAdrContent('<p>Failed to load ADR content.</p>');
+    }
+  };
+
+  const filteredAdrs = adrs.filter((adr) => {
+    if (statusFilter !== 'all' && adr.status !== statusFilter) return false;
+    if (phaseFilter !== 'all' && adr.phase !== phaseFilter) return false;
+    if (searchQuery) {
+      const query = searchQuery.toLowerCase();
+      return (
+        adr.title.toLowerCase().includes(query) ||
+        adr.endpoint.toLowerCase().includes(query) ||
+        `adr-${adr.number}`.includes(query)
+      );
+    }
+    return true;
+  });
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600" />
+      </div>
+    );
+  }
+
+  if (selectedAdr) {
+    return (
+      <ADRDetail
+        adr={selectedAdr}
+        content={adrContent}
+        onBack={() => setSelectedAdr(null)}
+      />
+    );
+  }
+
+  return (
+    <div>
+      <div className="mb-6">
+        <h1 className="text-2xl font-bold">Architecture Decision Records</h1>
+        <p className="text-gray-500 mt-1">
+          Significant decisions made during research and interview phases
+        </p>
+      </div>
+
+      {adrs.length > 0 && (
+        <FilterBar
+          statusFilter={statusFilter}
+          setStatusFilter={setStatusFilter}
+          phaseFilter={phaseFilter}
+          setPhaseFilter={setPhaseFilter}
+          searchQuery={searchQuery}
+          setSearchQuery={setSearchQuery}
+        />
+      )}
+
+      {filteredAdrs.length === 0 ? (
+        adrs.length === 0 ? (
+          <EmptyState />
+        ) : (
+          <div className="text-center py-8 text-gray-500">
+            No ADRs match your filters
+          </div>
+        )
+      ) : (
+        <div className="space-y-4">
+          {filteredAdrs.map((adr) => (
+            <ADRCard key={adr.number} adr={adr} onClick={() => handleSelectAdr(adr)} />
+          ))}
+        </div>
+      )}
+
+      <div className="mt-8 p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+        <h3 className="font-medium mb-2">About ADRs</h3>
+        <p className="text-sm text-gray-600 dark:text-gray-400">
+          Architecture Decision Records capture significant decisions made during the development workflow.
+          They are created automatically during Interview (Phase 4) and Deep Research (Phase 5)
+          when you make choices about authentication, error handling, caching, and other architectural concerns.
+        </p>
+        <p className="text-sm text-gray-500 mt-2">
+          See <code className="bg-gray-200 dark:bg-gray-700 px-1 rounded">docs/ARCHITECTURE_DECISION_RECORDS.md</code> for details.
+        </p>
+      </div>
+    </div>
+  );
+}

package/templates/api-dev-state.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.10.0",
+  "version": "3.11.0",
   "created_at": null,
   "workflow": null,
   "_workflow_options": [
@@ -12,6 +12,38 @@
   "active_element": null,
   "endpoints": {},
   "elements": {},
+
+  "session_archives": {
+    "_description": "Completed workflow sessions archived for reference and learning",
+    "_archive_policy": "Sessions archived on workflow completion or manual archival",
+    "completed": [],
+    "interrupted": [],
+    "_archive_template": {
+      "id": "uuid",
+      "workflow": "api-create",
+      "element_name": "stripe-subscriptions",
+      "status": "completed",
+      "started_at": "2025-12-29T10:00:00Z",
+      "completed_at": "2025-12-29T14:30:00Z",
+      "duration_minutes": 270,
+      "phases_completed": 14,
+      "total_turns": 45,
+      "research_sources_count": 8,
+      "interview_decisions_count": 5,
+      "files_created": ["src/app/api/stripe/route.ts", "src/lib/stripe.ts"],
+      "files_modified": ["registry.json"],
+      "test_coverage": 92,
+      "learnings": ["stripe webhooks require idempotency keys", "always validate signature first"],
+      "archived_at": "2025-12-29T14:31:00Z",
+      "archive_reason": "workflow_completed"
+    },
+    "_learnings_aggregated": {
+      "_description": "Patterns learned across all archived sessions - used for re-grounding",
+      "common_pitfalls": [],
+      "successful_patterns": [],
+      "service_specific": {}
+    }
+  },
   "combine_config": {
     "_comment": "Configuration for combine-api workflow",
     "mode": null,