context-engineer 1.1.0

package/templates/core/scripts/sync-context.sh

@@ -0,0 +1,510 @@
+#!/usr/bin/env bash
+#
+# sync-context.sh — Regenerate auto-generated context files from source code
+#
+# Usage: bash scripts/sync-context.sh [--all | --data-model | --api-surface | --dependencies]
+#
+# This script analyzes source code and regenerates the auto-generated context files.
+# It supports multiple tech stacks and auto-detects the project type.
+
+set -euo pipefail
+
+CONTEXT_DIR=".context"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# ============================================================
+# Tech Stack Detection
+# ============================================================
+
+detect_tech_stack() {
+  local stacks=()
+
+  [ -f "package.json" ] && stacks+=("nodejs")
+  [ -f "tsconfig.json" ] && stacks+=("typescript")
+  ls ./*.csproj >/dev/null 2>&1 && stacks+=("dotnet")
+  ls ./*.sln >/dev/null 2>&1 && stacks+=("dotnet")
+  [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ] && stacks+=("python")
+  [ -f "go.mod" ] && stacks+=("go")
+  [ -f "Cargo.toml" ] && stacks+=("rust")
+  [ -f "pom.xml" ] || [ -f "build.gradle" ] && stacks+=("java")
+
+  if [ ${#stacks[@]} -eq 0 ]; then
+    echo "unknown"
+  else
+    echo "${stacks[*]}"
+  fi
+}
+
+# ============================================================
+# Dependencies Sync
+# ============================================================
+
+sync_dependencies() {
+  echo "Syncing dependencies..."
+  local output="$CONTEXT_DIR/architecture/dependencies.md"
+  local sources=()
+
+  {
+    echo "<!-- AUTO-GENERATED: Do not edit manually. Run scripts/sync-context.sh to regenerate. -->"
+    echo "<!-- generated-from: package manifests -->"
+    echo "<!-- generated-at: $TIMESTAMP -->"
+    echo ""
+    echo "# Dependencies"
+    echo ""
+    echo "## Summary"
+    echo ""
+
+    # Node.js / TypeScript
+    if [ -f "package.json" ]; then
+      sources+=("package.json")
+      echo "### Node.js Dependencies"
+      echo ""
+      echo "#### Runtime"
+      echo ""
+      echo '| Package | Version |'
+      echo '|---------|---------|'
+      # Extract dependencies from package.json
+      if command -v node >/dev/null 2>&1; then
+        node -e "
+          const pkg = require('./package.json');
+          const deps = pkg.dependencies || {};
+          Object.entries(deps).forEach(([k,v]) => console.log('| ' + k + ' | ' + v + ' |'));
+        " 2>/dev/null || echo "| (unable to parse) | — |"
+      else
+        echo "| (node not available to parse) | — |"
+      fi
+      echo ""
+      echo "#### Development"
+      echo ""
+      echo '| Package | Version |'
+      echo '|---------|---------|'
+      if command -v node >/dev/null 2>&1; then
+        node -e "
+          const pkg = require('./package.json');
+          const deps = pkg.devDependencies || {};
+          Object.entries(deps).forEach(([k,v]) => console.log('| ' + k + ' | ' + v + ' |'));
+        " 2>/dev/null || echo "| (unable to parse) | — |"
+      else
+        echo "| (node not available to parse) | — |"
+      fi
+      echo ""
+    fi
+
+    # Python
+    if [ -f "requirements.txt" ]; then
+      sources+=("requirements.txt")
+      echo "### Python Dependencies"
+      echo ""
+      echo '| Package | Version |'
+      echo '|---------|---------|'
+      while IFS= read -r line; do
+        # Skip comments and empty lines
+        [[ "$line" =~ ^#.*$ ]] && continue
+        [[ -z "$line" ]] && continue
+        # Parse package==version or package>=version
+        local pkg ver
+        pkg=$(echo "$line" | sed 's/[>=<~!].*//')
+        ver=$(echo "$line" | grep -oP '(?<=[>=<~!]=).*' || echo "any")
+        echo "| $pkg | $ver |"
+      done < "requirements.txt"
+      echo ""
+    fi
+
+    # .NET
+    for csproj in ./*.csproj; do
+      [ -f "$csproj" ] || continue
+      sources+=("$csproj")
+      echo "### .NET Dependencies ($csproj)"
+      echo ""
+      echo '| Package | Version |'
+      echo '|---------|---------|'
+      grep -oP 'Include="([^"]+)".*Version="([^"]+)"' "$csproj" | \
+        sed 's/Include="\([^"]*\)".*Version="\([^"]*\)"/| \1 | \2 |/' 2>/dev/null || echo "| (unable to parse) | — |"
+      echo ""
+    done
+
+    # Go
+    if [ -f "go.mod" ]; then
+      sources+=("go.mod")
+      echo "### Go Dependencies"
+      echo ""
+      echo '| Module | Version |'
+      echo '|--------|---------|'
+      grep -E '^\t' "go.mod" 2>/dev/null | \
+        awk '{print "| " $1 " | " $2 " |"}' || echo "| (unable to parse) | — |"
+      echo ""
+    fi
+
+    echo "## External Services"
+    echo ""
+    echo "| Service | Purpose | Environment Variable |"
+    echo "|---------|---------|---------------------|"
+    echo "| [Add external services manually] | — | — |"
+
+  } > "$output"
+
+  echo "  → $output (sources: ${sources[*]:-none})"
+}
+
+# ============================================================
+# Data Model Sync
+# ============================================================
+
+sync_data_model() {
+  echo "Syncing data model..."
+  local output="$CONTEXT_DIR/architecture/data-model.md"
+  local found_models=false
+
+  {
+    echo "<!-- AUTO-GENERATED: Do not edit manually. Run scripts/sync-context.sh to regenerate. -->"
+    echo "<!-- generated-from: ORM models and schema files -->"
+    echo "<!-- generated-at: $TIMESTAMP -->"
+    echo ""
+    echo "# Data Model"
+    echo ""
+
+    # C# / EF Core entities
+    local entity_files
+    entity_files=$(find . \( -path "*/Entities/*" -o -path "*/entities/*" -o -path "*/Models/*" -o -path "*/models/*" \) -name "*.cs" -not -path "./.git/*" -not -path "*/bin/*" -not -path "*/obj/*" 2>/dev/null || true)
+    if [ -n "$entity_files" ]; then
+      found_models=true
+      echo "## Entities"
+      echo ""
+      echo "| Entity | File |"
+      echo "|--------|------|"
+      echo "$entity_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP '(?:class|record)\s+([A-Z][a-zA-Z0-9_]+)' "$file" 2>/dev/null | sed 's/\(class\|record\)\s*//' | while read -r name; do
+          echo "| $name | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # Python models (Django / SQLAlchemy)
+    local py_model_files
+    py_model_files=$(find . -name "models.py" -not -path "./.git/*" -not -path "*/node_modules/*" -not -path "*/.venv/*" 2>/dev/null || true)
+    if [ -n "$py_model_files" ]; then
+      found_models=true
+      echo "## Python Models"
+      echo ""
+      echo "| Model | File |"
+      echo "|-------|------|"
+      echo "$py_model_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP 'class\s+([A-Z][a-zA-Z0-9_]+)' "$file" 2>/dev/null | sed 's/class\s*//' | while read -r name; do
+          echo "| $name | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # Prisma schema
+    if [ -f "prisma/schema.prisma" ]; then
+      found_models=true
+      echo "## Prisma Models"
+      echo ""
+      echo "| Model | Source |"
+      echo "|-------|--------|"
+      grep -oP 'model\s+([A-Z][a-zA-Z0-9_]+)' prisma/schema.prisma 2>/dev/null | sed 's/model\s*//' | while read -r name; do
+        echo "| $name | prisma/schema.prisma |"
+      done
+      echo ""
+    fi
+
+    # TypeScript entities (TypeORM / Sequelize / MikroORM)
+    local ts_entity_files
+    ts_entity_files=$(find . \( -name "*.entity.ts" -o -name "*.model.ts" \) -not -path "*/node_modules/*" -not -path "./.git/*" 2>/dev/null || true)
+    if [ -n "$ts_entity_files" ]; then
+      found_models=true
+      echo "## TypeScript Entities"
+      echo ""
+      echo "| Entity | File |"
+      echo "|--------|------|"
+      echo "$ts_entity_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP '(?:class|interface)\s+([A-Z][a-zA-Z0-9_]+)' "$file" 2>/dev/null | sed 's/\(class\|interface\)\s*//' | head -1 | while read -r name; do
+          [ -n "$name" ] && echo "| $name | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # Go structs in model directories
+    local go_model_files
+    go_model_files=$(find . \( -path "*/model/*" -o -path "*/models/*" -o -path "*/entity/*" \) -name "*.go" -not -name "*_test.go" -not -path "./.git/*" 2>/dev/null || true)
+    if [ -n "$go_model_files" ]; then
+      found_models=true
+      echo "## Go Models"
+      echo ""
+      echo "| Struct | File |"
+      echo "|--------|------|"
+      echo "$go_model_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP 'type\s+([A-Z][a-zA-Z0-9_]+)\s+struct' "$file" 2>/dev/null | sed 's/type\s*//;s/\s*struct//' | while read -r name; do
+          echo "| $name | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # Java entities
+    local java_entity_files
+    java_entity_files=$(find . -name "*.java" -not -path "./.git/*" -not -path "*/build/*" -not -path "*/target/*" 2>/dev/null | xargs grep -l '@Entity\|@Table\|@Document' 2>/dev/null || true)
+    if [ -n "$java_entity_files" ]; then
+      found_models=true
+      echo "## Java Entities"
+      echo ""
+      echo "| Entity | File |"
+      echo "|--------|------|"
+      echo "$java_entity_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP 'class\s+([A-Z][a-zA-Z0-9_]+)' "$file" 2>/dev/null | sed 's/class\s*//' | head -1 | while read -r name; do
+          [ -n "$name" ] && echo "| $name | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    if [ "$found_models" = false ]; then
+      echo "No ORM models, migration files, or schema definitions detected."
+      echo ""
+      echo "If this project uses a database, populate this file manually or run"
+      echo "\`/bootstrap-context\` for AI-assisted analysis."
+    fi
+
+  } > "$output"
+
+  echo "  → $output"
+}
+
+# ============================================================
+# API Surface Sync
+# ============================================================
+
+sync_api_surface() {
+  echo "Syncing API surface..."
+  local output="$CONTEXT_DIR/architecture/api-surface.md"
+  local found_routes=false
+
+  {
+    echo "<!-- AUTO-GENERATED: Do not edit manually. Run scripts/sync-context.sh to regenerate. -->"
+    echo "<!-- generated-from: route and controller definitions -->"
+    echo "<!-- generated-at: $TIMESTAMP -->"
+    echo ""
+    echo "# API Surface"
+    echo ""
+
+    # Express.js / NestJS / Node.js routes
+    local node_route_files
+    node_route_files=$(find . \( -name "*.routes.ts" -o -name "*.router.ts" -o -name "*.controller.ts" -o -name "*.routes.js" -o -name "*.router.js" \) -not -path "*/node_modules/*" -not -path "./.git/*" 2>/dev/null || true)
+    if [ -n "$node_route_files" ]; then
+      found_routes=true
+      echo "## Node.js Endpoints"
+      echo ""
+      echo "| Method | Path | File |"
+      echo "|--------|------|------|"
+      echo "$node_route_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP "(?:get|post|put|delete|patch|Get|Post|Put|Delete|Patch)\s*\(\s*['\"]([^'\"]+)" "$file" 2>/dev/null | \
+          sed "s/\s*(\s*['\"]/ /; s/['\"]//g" | while read -r method path; do
+          [ -n "$method" ] && [ -n "$path" ] && echo "| ${method^^} | $path | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # ASP.NET Core controllers
+    local cs_controllers
+    cs_controllers=$(find . -name "*Controller.cs" -not -path "./.git/*" -not -path "*/bin/*" -not -path "*/obj/*" 2>/dev/null || true)
+    if [ -n "$cs_controllers" ]; then
+      found_routes=true
+      echo "## ASP.NET Endpoints"
+      echo ""
+      echo "| Controller | Route Prefix | File |"
+      echo "|------------|-------------|------|"
+      echo "$cs_controllers" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        local controller
+        controller=$(grep -oP 'class\s+([A-Z][a-zA-Z0-9_]+Controller)' "$file" 2>/dev/null | sed 's/class\s*//' | head -1)
+        local route
+        route=$(grep -oP '\[Route\("([^"]+)"\)\]' "$file" 2>/dev/null | head -1 | grep -oP '"[^"]+"' | tr -d '"')
+        [ -n "$controller" ] && echo "| $controller | ${route:-/} | $file |"
+      done
+      echo ""
+    fi
+
+    # Python Flask / FastAPI / Django routes
+    local py_route_files
+    py_route_files=$(find . \( -name "views.py" -o -name "urls.py" -o -name "routes.py" \) -not -path "./.git/*" -not -path "*/node_modules/*" -not -path "*/.venv/*" 2>/dev/null || true)
+    if [ -n "$py_route_files" ]; then
+      found_routes=true
+      echo "## Python Endpoints"
+      echo ""
+      echo "| Path | File |"
+      echo "|------|------|"
+      echo "$py_route_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP "(?:path|url|route)\s*\(\s*['\"]([^'\"]+)" "$file" 2>/dev/null | \
+          grep -oP "['\"][^'\"]+['\"]" | tr -d "'\""  | while read -r path; do
+          [ -n "$path" ] && echo "| $path | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # Go routes (gin / echo / chi / net/http)
+    local go_route_files
+    go_route_files=$(find . -name "*.go" -not -name "*_test.go" -not -path "./.git/*" -not -path "*/vendor/*" 2>/dev/null | xargs grep -l '\.GET\|\.POST\|\.PUT\|\.DELETE\|\.HandleFunc\|\.Handle(' 2>/dev/null || true)
+    if [ -n "$go_route_files" ]; then
+      found_routes=true
+      echo "## Go Endpoints"
+      echo ""
+      echo "| Path | File |"
+      echo "|------|------|"
+      echo "$go_route_files" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        grep -oP '(?:GET|POST|PUT|DELETE|Handle|HandleFunc)\s*\(\s*"([^"]+)"' "$file" 2>/dev/null | \
+          grep -oP '"[^"]+"' | tr -d '"' | while read -r path; do
+          [ -n "$path" ] && echo "| $path | $file |"
+        done
+      done
+      echo ""
+    fi
+
+    # Java Spring Boot controllers
+    local java_controllers
+    java_controllers=$(find . -name "*.java" -not -path "./.git/*" -not -path "*/build/*" -not -path "*/target/*" 2>/dev/null | xargs grep -l '@RestController\|@Controller' 2>/dev/null || true)
+    if [ -n "$java_controllers" ]; then
+      found_routes=true
+      echo "## Java Endpoints"
+      echo ""
+      echo "| Controller | Mapping | File |"
+      echo "|------------|---------|------|"
+      echo "$java_controllers" | while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        local controller
+        controller=$(grep -oP 'class\s+([A-Z][a-zA-Z0-9_]+)' "$file" 2>/dev/null | sed 's/class\s*//' | head -1)
+        local mapping
+        mapping=$(grep -oP '@RequestMapping\s*\(\s*"([^"]+)"' "$file" 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"' | head -1)
+        [ -n "$controller" ] && echo "| $controller | ${mapping:-/} | $file |"
+      done
+      echo ""
+    fi
+
+    if [ "$found_routes" = false ]; then
+      echo "No route definitions, controllers, or API endpoints detected."
+      echo ""
+      echo "If this project exposes an API, populate this file manually or run"
+      echo "\`/bootstrap-context\` for AI-assisted analysis."
+    fi
+
+  } > "$output"
+
+  echo "  → $output"
+}
+
+# ============================================================
+# Module Graph Sync (delegates to extract-structure.sh)
+# ============================================================
+
+sync_module_graph() {
+  echo "Syncing module graph..."
+  local script_dir
+  script_dir=$(dirname "$0")
+
+  if [ -f "$script_dir/extract-structure.sh" ]; then
+    bash "$script_dir/extract-structure.sh" --module-graph
+  else
+    echo "  → extract-structure.sh not found. Skipping module graph sync."
+  fi
+}
+
+# ============================================================
+# Class Index Sync (delegates to extract-structure.sh)
+# ============================================================
+
+sync_class_index() {
+  echo "Syncing class index..."
+  local script_dir
+  script_dir=$(dirname "$0")
+
+  if [ -f "$script_dir/extract-structure.sh" ]; then
+    bash "$script_dir/extract-structure.sh" --class-index
+  else
+    echo "  → extract-structure.sh not found. Skipping class index sync."
+  fi
+}
+
+# ============================================================
+# Update Metadata
+# ============================================================
+
+update_metadata() {
+  echo "Updating metadata..."
+  local sync_file="$CONTEXT_DIR/_meta/last-sync.json"
+
+  if command -v node >/dev/null 2>&1; then
+    node -e "
+      const fs = require('fs');
+      const data = JSON.parse(fs.readFileSync('$sync_file', 'utf8'));
+      data.lastFullSync = '$TIMESTAMP';
+      fs.writeFileSync('$sync_file', JSON.stringify(data, null, 2) + '\n');
+    " 2>/dev/null || echo "  → Warning: Could not update last-sync.json (node error)"
+  else
+    echo "  → Warning: node not available, skipping metadata update"
+  fi
+}
+
+# ============================================================
+# Main
+# ============================================================
+
+echo "========================================="
+echo "  Context Sync"
+echo "========================================="
+echo ""
+
+TECH_STACK=$(detect_tech_stack)
+echo "Detected tech stack: $TECH_STACK"
+echo ""
+
+TARGET="${1:---all}"
+
+case "$TARGET" in
+  --all)
+    sync_dependencies
+    sync_data_model
+    sync_api_surface
+    sync_module_graph
+    sync_class_index
+    update_metadata
+    ;;
+  --dependencies)
+    sync_dependencies
+    update_metadata
+    ;;
+  --data-model)
+    sync_data_model
+    update_metadata
+    ;;
+  --api-surface)
+    sync_api_surface
+    update_metadata
+    ;;
+  --module-graph)
+    sync_module_graph
+    update_metadata
+    ;;
+  --class-index)
+    sync_class_index
+    update_metadata
+    ;;
+  *)
+    echo "Usage: bash scripts/sync-context.sh [--all | --data-model | --api-surface | --dependencies | --module-graph | --class-index]"
+    exit 1
+    ;;
+esac
+
+echo ""
+echo "Done. Run 'bash scripts/detect-drift.sh --report' to verify."

package/templates/cursor/.cursor/rules/always.mdc

@@ -0,0 +1,18 @@
+---
+description: "Always-loaded context: constitution summary and loading protocol"
+alwaysApply: true
+---
+
+# Context System
+
+This project uses `.context/` for structured project knowledge.
+
+## Loading Protocol
+1. Read `.context/constitution.md` for the Context Loading Route Table
+2. Load ONLY files relevant to your current task
+3. See `.context/index.md` for full context directory
+
+## Context Maintenance
+- Update `.context/` files when you change architecture, data models, APIs, or conventions
+- Record non-trivial bug fixes in `.context/experience/debugging.md`
+- Auto-generated files (marked `<!-- AUTO-GENERATED -->`) must not be edited manually

package/templates/cursor/.cursor/rules/backend.mdc

@@ -0,0 +1,16 @@
+---
+description: "Backend development context loader"
+globs: ["src/api/**", "src/services/**", "src/controllers/**", "src/routes/**", "server/**", "backend/**"]
+---
+
+# Backend Context
+
+When working on backend code, load these context files:
+- `.context/architecture/api-surface.md` — API contracts and endpoints
+- `.context/architecture/data-model.md` — Database schema and relationships
+- `.context/conventions/patterns.md` — Design patterns used in this project
+- `.context/conventions/code-style.md` — Naming and formatting conventions
+- `.context/conventions/error-handling.md` — Error handling patterns
+
+If modifying API endpoints, update `.context/architecture/api-surface.md`.
+If modifying database models, update `.context/architecture/data-model.md`.

package/templates/cursor/.cursor/rules/database.mdc

@@ -0,0 +1,16 @@
+---
+description: "Database and data model context loader"
+globs: ["**/migrations/**", "**/models/**", "**/entities/**", "**/schema*", "prisma/**", "**/DbContext*"]
+---
+
+# Database Context
+
+When working on database-related code, load these context files:
+- `.context/architecture/data-model.md` — Current schema and relationships
+- `.context/conventions/patterns.md` — Data access patterns
+- `.context/business/domain-model.md` — Business entity definitions
+
+After making schema changes:
+1. Update `.context/architecture/data-model.md`
+2. Check if `.context/business/domain-model.md` needs updating
+3. Run `scripts/sync-context.sh` to regenerate auto-generated files

package/templates/cursor/.cursor/rules/frontend.mdc

@@ -0,0 +1,13 @@
+---
+description: "Frontend development context loader"
+globs: ["src/components/**", "src/pages/**", "src/views/**", "src/hooks/**", "src/stores/**", "frontend/**", "client/**"]
+---
+
+# Frontend Context
+
+When working on frontend code, load these context files:
+- `.context/architecture/overview.md` — System architecture
+- `.context/conventions/code-style.md` — Naming and formatting conventions
+- `.context/conventions/patterns.md` — UI component patterns
+
+If adding new pages or routes, check `.context/architecture/api-surface.md` for available API endpoints.

package/templates/cursor/.cursorrules

@@ -0,0 +1,23 @@
+# Cursor Rules
+
+This project uses a structured context system at `.context/`.
+
+## Context Loading Protocol
+
+1. Read `.context/constitution.md` for non-negotiable principles and the Context Loading Route Table
+2. Use the Route Table to load ONLY the context files relevant to your current task
+3. Read `.context/index.md` for a full directory of available context
+
+## Context Maintenance
+
+When you modify code that affects architecture, data models, API surfaces, or conventions, update the corresponding `.context/` file in the same commit.
+
+When you fix a non-trivial bug, record it in `.context/experience/debugging.md`.
+
+## Key Commands
+
+```bash
+# Build: [BUILD_COMMAND]
+# Test: [TEST_COMMAND]
+# Drift check: bash scripts/detect-drift.sh
+```

package/templates/github/.github/copilot-instructions.md

@@ -0,0 +1,15 @@
+# GitHub Copilot Instructions
+
+This project uses a structured context system at `.context/`.
+
+## Context Loading
+
+1. Read `.context/constitution.md` for non-negotiable principles and the Context Loading Route Table
+2. Use the Route Table to determine which context files are relevant to your current task
+3. See `.context/index.md` for a full directory of all available context
+
+## Key Rules
+
+- When modifying architecture, data models, or APIs, update corresponding `.context/` files
+- When fixing bugs, record the issue and resolution in `.context/experience/debugging.md`
+- Files marked `<!-- AUTO-GENERATED -->` should not be edited manually