shipkit-project-context

shipkit-project-context - Smart Project Context Scanner

Purpose: Generate and maintain lightweight project context files (stack, env, schema) by scanning package files, configs, and migrations. Uses file modification time checks to avoid unnecessary rescans.

What it does: Scans project files to detect tech stack, environment requirements, and database schema. Generates .shipkit/stack.json as a structured JSON artifact, plus optional markdown files for env and schema.

Output format: JSON — readable by Claude, machine-readable by other tools, and the single source of truth for project tech stack.

---

When to Invoke

User triggers:

• "Scan the project"
• "Update context"
• "Rescan stack"
• "Generate project context"
• "What's my tech stack?"

Auto-triggered by:

• session start / any skill needing stack.json (when it is missing or stale)

First run:

• No .shipkit/ directory exists
• User starts new Shipkit project

---

Prerequisites

Required:

• Project has package.json (or equivalent dependency file)

Optional but helpful:

• .env.example (for env requirements)
• Database migration files (for schema)
• Config files (next.config.js, tailwind.config.js, etc.)

---

Process

Completion Tracking

This skill produces 3 files, not 1. Create tasks:

• TaskCreate: "Write stack.json"
• TaskCreate: "Write env-requirements.md"
• TaskCreate: "Write schema.json"
• TaskCreate: "Detect working patterns (Step 3.5)"

TaskUpdate each task to in_progress when starting it, completed when done.

stack.json alone is NOT done — env-requirements.md and schema.json must also be written. Do NOT present the completion summary until all 3 files exist.

Step 1: Check Freshness (Smart Caching)

Before doing any work, check if rescan is needed.

Commands: See references/bash-commands.md for platform-specific freshness checks

Freshness logic:

1. If .shipkit/stack.json doesn't exist → First run, proceed directly to Step 3 (scan).
2. If stack.json exists:
   • Compare modification times.
   • If stack.json newer than package.json → SKIP SCAN, read cached file and exit early with a "using cached stack" report.
   • If package.json newer than stack.json → Rescan automatically (no prompt). Archive the stale stack.json if overwrite risk matters, then proceed to Step 3.