mindsystem-cc 3.0.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "mindsystem-cc",
+  "version": "3.0.0",
+  "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
+  "bin": {
+    "mindsystem-cc": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "mindsystem",
+    "agents",
+    "scripts"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "meta-prompting",
+    "context-engineering",
+    "spec-driven-development"
+  ],
+  "author": "Roland Tolnay",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rolandtolnay/mindsystem.git"
+  },
+  "engines": {
+    "node": ">=16.7.0"
+  }
+}

package/scripts/generate-phase-patch.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+#
+# generate-phase-patch.sh
+# Generates a patch file with implementation changes from a phase,
+# excluding documentation and generated files.
+#
+# Usage: ./scripts/generate-phase-patch.sh <phase_number> [--suffix=<suffix>]
+# Example: ./scripts/generate-phase-patch.sh 04
+#          ./scripts/generate-phase-patch.sh 4
+#          ./scripts/generate-phase-patch.sh 04 --suffix=uat-fixes
+#
+# Options:
+#   --suffix=<suffix>  Filter commits by message pattern and use custom output filename
+#                      When --suffix=uat-fixes: looks for commits with "({phase}-uat):" pattern
+#                      Output: {phase}-{suffix}.patch instead of {phase}-changes.patch
+
+set -e
+
+# --- Configuration ---
+EXCLUSIONS=(
+  # Documentation
+  '.planning'
+
+  # Flutter/Dart generated
+  '*.g.dart'
+  '*.freezed.dart'
+  '*.gr.dart'
+  'generated'
+  '.dart_tool'
+
+  # Next.js/TypeScript generated
+  'node_modules'
+  '.next'
+  'dist'
+  'build'
+  '*.d.ts'
+  '.turbo'
+
+  # Common build artifacts
+  '*.lock'
+)
+
+# --- Parse arguments ---
+PHASE_INPUT=""
+SUFFIX=""
+
+for arg in "$@"; do
+  case $arg in
+    --suffix=*)
+      SUFFIX="${arg#*=}"
+      ;;
+    *)
+      if [ -z "$PHASE_INPUT" ]; then
+        PHASE_INPUT="$arg"
+      fi
+      ;;
+  esac
+done
+
+# --- Validation ---
+if [ -z "$PHASE_INPUT" ]; then
+  echo "Error: Phase number required"
+  echo "Usage: $0 <phase_number> [--suffix=<suffix>]"
+  exit 1
+fi
+
+# --- Find git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+cd "$GIT_ROOT"
+
+# --- Normalize phase number (zero-pad if needed) ---
+if [[ "$PHASE_INPUT" =~ ^[0-9]$ ]]; then
+  PHASE_NUMBER=$(printf "%02d" "$PHASE_INPUT")
+else
+  PHASE_NUMBER="$PHASE_INPUT"
+fi
+
+# --- Determine commit pattern based on suffix ---
+if [ -n "$SUFFIX" ]; then
+  # With suffix: filter by specific pattern
+  # For uat-fixes: look for "fix({phase}-uat):" pattern
+  if [ "$SUFFIX" = "uat-fixes" ]; then
+    COMMIT_PATTERN="\($PHASE_NUMBER-uat\):"
+    echo "Generating UAT fixes patch for phase $PHASE_NUMBER..."
+  else
+    # Generic suffix: look for pattern with suffix in scope
+    COMMIT_PATTERN="\($PHASE_NUMBER-$SUFFIX\):"
+    echo "Generating $SUFFIX patch for phase $PHASE_NUMBER..."
+  fi
+else
+  # No suffix: standard phase commits
+  COMMIT_PATTERN="\($PHASE_NUMBER-"
+  echo "Generating patch for phase $PHASE_NUMBER..."
+fi
+
+# --- Find matching commits ---
+PHASE_COMMITS=$(git log --oneline | grep -E "$COMMIT_PATTERN" | cut -d' ' -f1 || true)
+
+if [ -z "$PHASE_COMMITS" ]; then
+  echo "No commits found matching pattern: $COMMIT_PATTERN"
+  echo "Patch skipped"
+  exit 0
+fi
+
+COMMIT_COUNT=$(echo "$PHASE_COMMITS" | wc -l | tr -d ' ')
+echo "Found $COMMIT_COUNT commit(s)"
+
+# --- Determine base commit ---
+EARLIEST_COMMIT=$(echo "$PHASE_COMMITS" | tail -1)
+BASE_COMMIT=$(git rev-parse "${EARLIEST_COMMIT}^" 2>/dev/null || git rev-list --max-parents=0 HEAD)
+echo "Base commit: $(git log --oneline -1 "$BASE_COMMIT")"
+
+# --- Find output directory ---
+PHASES_DIR=".planning/phases"
+PHASE_DIR=$(find "$PHASES_DIR" -maxdepth 1 -type d -name "${PHASE_NUMBER}-*" 2>/dev/null | head -1)
+
+if [ -z "$PHASE_DIR" ]; then
+  PHASE_DIR="$PHASES_DIR"
+  echo "No phase directory found, saving to $PHASES_DIR/"
+else
+  echo "Output directory: $PHASE_DIR/"
+fi
+
+# Ensure directory exists
+mkdir -p "$PHASE_DIR"
+
+# --- Build exclusion arguments ---
+EXCLUDE_ARGS=""
+for pattern in "${EXCLUSIONS[@]}"; do
+  EXCLUDE_ARGS="$EXCLUDE_ARGS ':!$pattern'"
+done
+
+# --- Determine output filename ---
+if [ -n "$SUFFIX" ]; then
+  PATCH_FILE="$PHASE_DIR/${PHASE_NUMBER}-${SUFFIX}.patch"
+else
+  PATCH_FILE="$PHASE_DIR/${PHASE_NUMBER}-changes.patch"
+fi
+
+# --- Generate diff ---
+# For suffix mode: generate diff only for the specific commits
+# For standard mode: generate diff from base to HEAD
+if [ -n "$SUFFIX" ]; then
+  # Create combined diff from all matching commits
+  LATEST_COMMIT=$(echo "$PHASE_COMMITS" | head -1)
+  eval "git diff \"$BASE_COMMIT\" \"$LATEST_COMMIT\" -- . $EXCLUDE_ARGS" > "$PATCH_FILE"
+else
+  eval "git diff \"$BASE_COMMIT\" HEAD -- . $EXCLUDE_ARGS" > "$PATCH_FILE"
+fi
+
+# --- Check result ---
+if [ ! -s "$PATCH_FILE" ]; then
+  rm "$PATCH_FILE"
+  echo "No implementation changes outside excluded patterns"
+  echo "Patch skipped"
+  exit 0
+fi
+
+PATCH_LINES=$(wc -l < "$PATCH_FILE" | tr -d ' ')
+echo ""
+echo "Generated: $PATCH_FILE ($PATCH_LINES lines)"
+echo ""
+echo "Review:  cat $PATCH_FILE"
+echo "Apply:   git apply $PATCH_FILE"
+echo "Discard: rm $PATCH_FILE"

package/scripts/ms-lookup/README.md

@@ -0,0 +1,112 @@
+# ms-lookup
+
+CLI tool for Mindsystem research providing access to Context7 library documentation and Perplexity deep research.
+
+## Installation
+
+The tool is installed automatically with Mindsystem. To use it standalone:
+
+```bash
+cd scripts/ms-lookup
+uv sync
+uv run python -m ms_lookup --help
+```
+
+Or with pip:
+
+```bash
+pip install -e .
+ms-lookup --help
+```
+
+## Environment Variables
+
+```bash
+# Required for docs command
+export CONTEXT7_API_KEY="your-context7-api-key"
+
+# Required for deep command
+export PERPLEXITY_API_KEY="your-perplexity-api-key"
+```
+
+Get API keys:
+- Context7: https://context7.com/dashboard
+- Perplexity: https://docs.perplexity.ai/
+
+## Commands
+
+### docs - Library Documentation
+
+Query library documentation via Context7. Provides authoritative, version-aware API documentation.
+
+```bash
+ms-lookup docs <library> "<query>"
+
+# Examples
+ms-lookup docs nextjs "app router setup"
+ms-lookup docs react "hooks useEffect cleanup"
+ms-lookup docs "react-three-fiber" "physics integration"
+```
+
+### deep - Deep Research
+
+Perform comprehensive multi-source research via Perplexity.
+
+**Note:** This costs ~$0.005 per query + tokens. Use sparingly for high-value research questions.
+
+```bash
+ms-lookup deep "<query>"
+
+# Examples
+ms-lookup deep "authentication patterns for SaaS applications"
+ms-lookup deep "WebGPU browser support and performance 2026"
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--max-tokens, -t` | Maximum tokens in response (default: 2000) |
+| `--no-cache` | Skip cache lookup |
+| `--json-pretty, -p` | Pretty-print JSON output |
+| `--version, -v` | Show version |
+
+## Output Format
+
+All commands return JSON:
+
+```json
+{
+  "success": true,
+  "command": "docs",
+  "query": "app router setup",
+  "library": "nextjs",
+  "results": [
+    {
+      "title": "App Router Getting Started",
+      "content": "The App Router uses...",
+      "source_url": "https://nextjs.org/docs/...",
+      "tokens": 450,
+      "type": "info"
+    }
+  ],
+  "metadata": {
+    "library_id": "/vercel/next.js",
+    "total_available": 15,
+    "returned": 3,
+    "tokens_used": 830,
+    "max_tokens": 2000,
+    "cache_hit": false,
+    "confidence": "HIGH",
+    "backend": "context7"
+  }
+}
+```
+
+## Caching
+
+Results are cached in `~/.cache/ms-lookup/`:
+- docs: 24 hours TTL
+- deep: 6 hours TTL
+
+Use `--no-cache` to bypass cache.

package/scripts/ms-lookup/ms_lookup/__init__.py

@@ -0,0 +1,3 @@
+"""Mindsystem Lookup CLI - Context7 docs and Perplexity deep research."""
+
+__version__ = "1.0.0"

package/scripts/ms-lookup/ms_lookup/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m ms_lookup."""
+
+from ms_lookup.cli import app
+
+if __name__ == "__main__":
+    app()

package/scripts/ms-lookup/ms_lookup/backends/__init__.py

@@ -0,0 +1,6 @@
+"""API backends for ms-lookup."""
+
+from ms_lookup.backends.context7 import Context7Client
+from ms_lookup.backends.perplexity import PerplexityClient
+
+__all__ = ["Context7Client", "PerplexityClient"]

package/scripts/ms-lookup/ms_lookup/backends/context7.py

@@ -0,0 +1,219 @@
+"""Context7 API client for library documentation."""
+
+import httpx
+
+from ms_lookup.config import CONTEXT7_API_KEY, CONTEXT7_BASE_URL
+from ms_lookup.errors import ErrorCode, MsLookupError
+
+
+class Context7Client:
+    """Client for Context7 documentation API."""
+
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or CONTEXT7_API_KEY
+        self.base_url = CONTEXT7_BASE_URL
+
+    def _check_api_key(self) -> None:
+        """Verify API key is configured."""
+        if not self.api_key:
+            raise MsLookupError(
+                ErrorCode.MISSING_API_KEY,
+                "CONTEXT7_API_KEY environment variable not set",
+                suggestions=[
+                    "Set CONTEXT7_API_KEY in your environment",
+                    "Get an API key at https://context7.com/dashboard",
+                ],
+            )
+
+    def resolve_library(self, library_name: str, query: str) -> dict:
+        """Resolve library name to Context7 library ID.
+
+        Args:
+            library_name: Library name to search for
+            query: User's original query (used for relevance ranking)
+
+        Returns:
+            Dict with library_id and library info
+
+        Raises:
+            MsLookupError: If library not found or API error
+        """
+        self._check_api_key()
+
+        url = f"{self.base_url}/libs/search"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        params = {"query": library_name, "limit": 5}
+
+        try:
+            with httpx.Client(timeout=30.0) as client:
+                response = client.get(url, headers=headers, params=params)
+                response.raise_for_status()
+                data = response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise MsLookupError(
+                    ErrorCode.MISSING_API_KEY,
+                    "Invalid CONTEXT7_API_KEY",
+                    suggestions=["Check your API key at https://context7.com/dashboard"],
+                )
+            elif e.response.status_code == 429:
+                raise MsLookupError(
+                    ErrorCode.RATE_LIMITED,
+                    "Context7 API rate limit exceeded",
+                    suggestions=["Wait a moment and try again", "Use --no-cache sparingly"],
+                )
+            raise MsLookupError(
+                ErrorCode.API_ERROR,
+                f"Context7 API error: {e.response.status_code}",
+            )
+        except httpx.RequestError as e:
+            raise MsLookupError(
+                ErrorCode.NETWORK_ERROR,
+                f"Network error connecting to Context7: {str(e)}",
+            )
+
+        # Find best matching library
+        libraries = data.get("results", [])
+        if not libraries:
+            raise MsLookupError(
+                ErrorCode.LIBRARY_NOT_FOUND,
+                f"Could not find library '{library_name}' in Context7",
+                suggestions=self._get_library_suggestions(library_name),
+            )
+
+        # Return first (best) match
+        best_match = libraries[0]
+        return {
+            "library_id": best_match.get("id", ""),
+            "name": best_match.get("name", library_name),
+            "description": best_match.get("description", ""),
+            "url": best_match.get("url", ""),
+        }
+
+    def query_docs(self, library_id: str, query: str) -> dict:
+        """Query documentation for a library.
+
+        Args:
+            library_id: Context7 library ID (e.g., "/vercel/next.js")
+            query: Documentation query
+
+        Returns:
+            Dict with documentation results
+
+        Raises:
+            MsLookupError: If API error
+        """
+        self._check_api_key()
+
+        url = f"{self.base_url}/context"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        params = {"libraryId": library_id, "query": query}
+
+        try:
+            with httpx.Client(timeout=60.0) as client:
+                response = client.get(url, headers=headers, params=params)
+                response.raise_for_status()
+
+                # Context7 can return JSON or plain text depending on the endpoint
+                content_type = response.headers.get("content-type", "")
+                if "application/json" in content_type:
+                    data = response.json()
+                else:
+                    # Plain text/markdown response - wrap in a structure
+                    data = {"content": response.text, "format": "markdown"}
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise MsLookupError(
+                    ErrorCode.LIBRARY_NOT_FOUND,
+                    f"Library '{library_id}' not found in Context7",
+                )
+            elif e.response.status_code == 429:
+                raise MsLookupError(
+                    ErrorCode.RATE_LIMITED,
+                    "Context7 API rate limit exceeded",
+                )
+            raise MsLookupError(
+                ErrorCode.API_ERROR,
+                f"Context7 API error: {e.response.status_code}",
+            )
+        except httpx.RequestError as e:
+            raise MsLookupError(
+                ErrorCode.NETWORK_ERROR,
+                f"Network error connecting to Context7: {str(e)}",
+            )
+
+        return data
+
+    def format_results(self, raw_response: dict) -> list[dict]:
+        """Transform Context7 response to unified format.
+
+        Args:
+            raw_response: Raw API response
+
+        Returns:
+            List of formatted result dicts
+        """
+        results = []
+
+        # Process code snippets
+        for snippet in raw_response.get("codeSnippets", []):
+            results.append({
+                "title": snippet.get("title", "Code Example"),
+                "content": snippet.get("code", ""),
+                "source_url": snippet.get("url", ""),
+                "type": "code",
+            })
+
+        # Process info snippets
+        for snippet in raw_response.get("infoSnippets", []):
+            results.append({
+                "title": snippet.get("title", "Documentation"),
+                "content": snippet.get("content", ""),
+                "source_url": snippet.get("url", ""),
+                "type": "info",
+            })
+
+        # If no structured snippets, try to extract from content field
+        if not results and "content" in raw_response:
+            results.append({
+                "title": "Documentation",
+                "content": raw_response["content"],
+                "source_url": raw_response.get("url", ""),
+                "type": "info",
+            })
+
+        return results
+
+    def _get_library_suggestions(self, query: str) -> list[str]:
+        """Get suggestions for similar library names."""
+        # Common library name variations
+        suggestions = []
+        query_lower = query.lower()
+
+        # Common mappings
+        mappings = {
+            "react": ["react", "react-dom", "react-router"],
+            "next": ["nextjs", "next.js", "vercel/next.js"],
+            "nextjs": ["nextjs", "next.js", "vercel/next.js"],
+            "vue": ["vue", "vuejs", "vue-router"],
+            "angular": ["angular", "@angular/core"],
+            "express": ["express", "expressjs"],
+            "fastapi": ["fastapi", "tiangolo/fastapi"],
+            "django": ["django", "djangoproject"],
+            "flask": ["flask", "pallets/flask"],
+            "three": ["three.js", "threejs", "mrdoob/three.js"],
+            "r3f": ["react-three-fiber", "@react-three/fiber"],
+        }
+
+        for key, values in mappings.items():
+            if key in query_lower:
+                suggestions.extend(values)
+                break
+
+        if not suggestions:
+            suggestions = [
+                "Try the exact package name from npm/pypi",
+                "Check for common aliases (e.g., 'nextjs' for Next.js)",
+            ]
+
+        return suggestions[:3]

package/scripts/ms-lookup/ms_lookup/backends/perplexity.py

@@ -0,0 +1,145 @@
+"""Perplexity API client for deep research."""
+
+import re
+
+import httpx
+
+from ms_lookup.config import PERPLEXITY_API_KEY, PERPLEXITY_BASE_URL, PERPLEXITY_DEEP_MODEL
+from ms_lookup.errors import ErrorCode, MsLookupError
+
+
+class PerplexityClient:
+    """Client for Perplexity deep research API."""
+
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or PERPLEXITY_API_KEY
+        self.base_url = PERPLEXITY_BASE_URL
+
+    def _check_api_key(self) -> None:
+        """Verify API key is configured."""
+        if not self.api_key:
+            raise MsLookupError(
+                ErrorCode.MISSING_API_KEY,
+                "PERPLEXITY_API_KEY environment variable not set",
+                suggestions=[
+                    "Set PERPLEXITY_API_KEY in your environment",
+                    "Get an API key at https://docs.perplexity.ai/",
+                ],
+            )
+
+    def query(self, query: str) -> dict:
+        """Perform deep research query.
+
+        Args:
+            query: Research query
+
+        Returns:
+            Dict with research response
+
+        Raises:
+            MsLookupError: If API error
+        """
+        self._check_api_key()
+
+        url = f"{self.base_url}/chat/completions"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "model": PERPLEXITY_DEEP_MODEL,
+            "messages": [
+                {
+                    "role": "system",
+                    "content": (
+                        "You are a technical research assistant. Think step-by-step to analyze the query, "
+                        "search for authoritative sources, and synthesize actionable findings.\n\n"
+                        "RESEARCH APPROACH:\n"
+                        "1. Identify the core technical question\n"
+                        "2. Search for current best practices from official docs and trusted sources\n"
+                        "3. Verify claims across multiple sources when possible\n"
+                        "4. Synthesize into practical guidance\n\n"
+                        "OUTPUT FORMAT:\n"
+                        "- Lead with the recommended approach or answer\n"
+                        "- Support with 8-12 key findings as bullet points\n"
+                        "- Each finding cites its source inline [Source]\n"
+                        "- Include code examples when relevant\n"
+                        "- Flag any caveats or edge cases\n"
+                        "- End with clear next steps if applicable\n"
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": query,
+                },
+            ],
+        }
+
+        try:
+            with httpx.Client(timeout=90.0) as client:  # Reasoning model is faster
+                response = client.post(url, headers=headers, json=payload)
+                response.raise_for_status()
+                data = response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise MsLookupError(
+                    ErrorCode.MISSING_API_KEY,
+                    "Invalid PERPLEXITY_API_KEY",
+                    suggestions=["Check your API key at https://docs.perplexity.ai/"],
+                )
+            elif e.response.status_code == 429:
+                raise MsLookupError(
+                    ErrorCode.RATE_LIMITED,
+                    "Perplexity API rate limit exceeded",
+                    suggestions=["Wait a moment and try again"],
+                )
+            raise MsLookupError(
+                ErrorCode.API_ERROR,
+                f"Perplexity API error: {e.response.status_code}",
+            )
+        except httpx.RequestError as e:
+            raise MsLookupError(
+                ErrorCode.NETWORK_ERROR,
+                f"Network error connecting to Perplexity: {str(e)}",
+            )
+
+        return data
+
+    def _strip_think_tags(self, content: str) -> str:
+        """Remove <think>...</think> blocks from response."""
+        # Remove think tags and their content (including multiline)
+        return re.sub(r"<think>.*?</think>", "", content, flags=re.DOTALL).strip()
+
+    def format_results(self, raw_response: dict) -> tuple[list[dict], list[str]]:
+        """Transform Perplexity response to unified format.
+
+        Args:
+            raw_response: Raw API response
+
+        Returns:
+            Tuple of (results list, citations list)
+        """
+        results = []
+        citations = []
+
+        # Extract content from response
+        choices = raw_response.get("choices", [])
+        if choices:
+            message = choices[0].get("message", {})
+            content = message.get("content", "")
+
+            # Strip think tags
+            content = self._strip_think_tags(content)
+
+            if content:
+                results.append({
+                    "title": "Research Findings",
+                    "content": content,
+                    "source_url": "",
+                    "type": "research",
+                })
+
+        # Extract citations if available
+        citations = raw_response.get("citations", [])
+
+        return results, citations