@nolrm/contextkit 0.12.8 → 0.12.10

package/README.md

@@ -29,41 +29,23 @@ Each platform gets auto-loaded bridge files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.m
 
 ## Quick Start (60s)
 
-**Requirements:** Node.js 14.x+ (16.x+ recommended) and npm/yarn. Optional: Git for hooks, AI tools for usage.
-
+**1. Install the CLI**
 ```bash
-# Step 1: Install the CLI globally (one-time, any machine)
 npm i -g @nolrm/contextkit
-
-# Step 2: Initialize in your project (once per project)
-cd your-project
-contextkit install          # interactive — prompts "Which AI tool?"
-contextkit install claude   # or specify your platform directly
 ```
 
-> **Project-level only.** `ck install` creates `.contextkit/` in your current directory and commits it with your project. There is no global mode — your standards live in git, not on your machine. This keeps them portable, CI-compatible, and shared with your team.
-
-> **Tip:** Need to share standards across projects? Push your `.contextkit/` to a shared repo and pull it with `ck pull`.
-
-This creates `.contextkit/` with skeleton context files (blank templates to be filled by AI):
-
-```
-.contextkit/
-  standards/       # Skeleton files: code-style.md, testing.md, architecture.md, ai-guidelines.md, workflows.md
-                  # Real files: glossary.md (universal), README.md (overview)
-  commands/        # analyze.md (project analysis & customization)
-  templates/       # skeleton template files (component, test, story, hook, api)
+**2. Set up your project**
+```bash
+cd your-project
+contextkit install
 ```
+Creates `.contextkit/` with skeleton standards files in your project.
 
-**Generate content with AI** (recommended):
+**3. Generate your standards**
 
-```bash
-ck analyze
-# AI scans your codebase and generates content for the skeleton files
-# or in Cursor chat:  @.contextkit/commands/analyze.md
-```
+Run `/analyze` in your AI tool — it scans your codebase and fills the skeleton files with your project's conventions.
 
-⚠️ **Important:** After running `ck analyze`, manually review and edit the generated content to match your exact needs. The AI provides a starting point, but you must customize it.
+Done. Your AI tools now have project-specific context.
 
 ---
 
@@ -322,8 +304,8 @@ ck windsurf    # add Windsurf integration (.windsurfrules)
 ck vscode      # alias for copilot
 
 # Analysis & Updates
-ck analyze     # customize standards to your project
-ck update      # pull latest updates
+/analyze       # customize standards to your project (slash command in your AI tool)
+ck update      # pull latest commands/hooks — preserves your analyzed standards
 ck status      # check install & integrations
 
 # Validation & Compliance

package/lib/commands/install.js

@@ -85,6 +85,7 @@ class InstallCommand {
       const { shouldContinue } = await this.promptReinstall();
       if (!shouldContinue) {
         console.log(chalk.yellow('⏭️  Installation cancelled'));
+        console.log(chalk.dim('💡 To get the latest command and squad files, run: ') + chalk.cyan('ck update'));
         return;
       }
     }
@@ -303,11 +304,11 @@ class InstallCommand {
     const skeletonFiles = {
       'standards/code-style.md': `# Code Style
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your code style standards will be automatically generated based on your codebase patterns, conventions, and existing code.
 
-Run \`ck analyze\` to generate this content.
+Run \`/analyze\` to generate this content.
 
 ## Conditional Loading
 
@@ -331,11 +332,11 @@ Use conditional loading tags:
       
       'standards/testing.md': `# Testing Standards
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your testing standards will be automatically generated based on your existing test patterns and testing framework.
 
-Run \`ck analyze\` to generate this content.
+Run \`/analyze\` to generate this content.
 
 ## ⭐ REQUIRED: Numbered Test Cases
 
@@ -366,38 +367,78 @@ describe("ComponentName", () => {
       
       'standards/architecture.md': `# Architecture
 
-<!-- Content will be generated by running: ck analyze -->
+## Documentation Levels
+
+All documentation follows a 3-level hierarchy. Each level answers a different question.
+
+| Level | Scope | Question it answers |
+|-------|-------|---------------------|
+| **Architecture** | System / platform | How things are connected and communicate |
+| **Page / Feature** | App / route / feature | Containers and complex features |
+| **Component** | Single component | One component and its own docs |
+
+### Architecture Level
+
+High-level system documentation: how the system is structured and how parts interact.
+
+- **Location:** \`docs/architecture.md\` in the project root (or any root-level docs folder)
+- **Scope:** Whole product, platform, or cross-cutting feature
+- **Content:** System/domain boundaries, main flows, how services/apps/packages connect and communicate
+- **Artifacts:** Diagrams (Mermaid or similar) for routing, sequence flows, context/containers; architecture decision notes; shared patterns and conventions
+- **Audience:** Engineers onboarding, tech leads, or anyone needing the big picture before touching code
+
+### Page / Feature Level
+
+Documentation for a full screen, route, or feature area — the containers that hold many components.
+
+- **Scope:** One app, one major feature, or one route/page
+- **Content:** Purpose of the page/feature, main sections and layout, which components and hooks are used, data/state and API usage, key user flows
+- **Artifacts:** Feature or page READMEs; lists of subcomponents and responsibilities; optional simple flow or layout sketches
+- **Audience:** Developers working on that page/feature or integrating with it
+
+### Component Level
+
+Documentation for a single component or a small, cohesive set of components.
+
+- **Scope:** One component (or a tight group)
+- **Content:** What the component does, props/API, usage examples, behavior and edge cases, where it's used
+- **Artifacts:** README colocated next to the component; props table; code snippets
+- **Audience:** Developers implementing or reusing the component
+
+## Project Architecture
+
+<!-- Content will be generated by running: /analyze -->
 
 Your architecture patterns will be documented based on your project structure and organization.
 
-Run \`ck analyze\` to generate this content.`,
+Run \`/analyze\` to generate this content.`,
       
       'standards/ai-guidelines.md': `# AI Guidelines
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Guidelines for AI assistance will be defined based on your project's needs and patterns.
 
-Run \`ck analyze\` to generate this content.`,
+Run \`/analyze\` to generate this content.`,
       
       'standards/workflows.md': `# Workflows
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Development workflows and processes will be documented based on your project's practices.
 
-Run \`ck analyze\` to generate this content.`
+Run \`/analyze\` to generate this content.`
     };
 
     // Create granular code-style skeleton files
     const granularCodeStyleFiles = {
       'standards/code-style/css-style.md': `# CSS Style Guide
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 CSS-specific coding standards will be generated based on your project's styling patterns.
 
-Run \`ck analyze\` to generate this content.
+Run \`/analyze\` to generate this content.
 
 ## Conditional Loading
 
@@ -410,11 +451,11 @@ This file is loaded when CSS-related tasks are detected:
 
       'standards/code-style/typescript-style.md': `# TypeScript Style Guide
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 TypeScript-specific coding standards will be generated based on your project's TypeScript patterns.
 
-Run \`ck analyze\` to generate this content.
+Run \`/analyze\` to generate this content.
 
 ## Conditional Loading
 
@@ -427,11 +468,11 @@ This file is loaded when TypeScript-related tasks are detected:
 
       'standards/code-style/javascript-style.md': `# JavaScript Style Guide
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 JavaScript-specific coding standards will be generated based on your project's JavaScript patterns.
 
-Run \`ck analyze\` to generate this content.
+Run \`/analyze\` to generate this content.
 
 ## Conditional Loading
 
@@ -444,11 +485,11 @@ This file is loaded when JavaScript-related tasks are detected:
 
       'standards/code-style/html-style.md': `# HTML Style Guide
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 HTML-specific coding standards will be generated based on your project's HTML patterns.
 
-Run \`ck analyze\` to generate this content.
+Run \`/analyze\` to generate this content.
 
 ## Conditional Loading
 
@@ -473,43 +514,116 @@ This file is loaded when HTML-related tasks are detected:
     const skeletonFiles = {
       'templates/component.md': `# Component Template
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your canonical component/module pattern will be generated based on your project's framework, language, and conventions.
 
-Run \`ck analyze\` to generate this content, or manually add your component pattern below.
+Run \`/analyze\` to generate this content, or manually add your component pattern below.
 `,
       'templates/test.md': `# Test Template
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your canonical test file pattern will be generated based on your project's testing framework and conventions.
 
-Run \`ck analyze\` to generate this content, or manually add your test pattern below.
+Run \`/analyze\` to generate this content, or manually add your test pattern below.
 `,
       'templates/story.md': `# Story/Demo Template
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your canonical story/demo pattern will be generated based on your project's documentation and showcase conventions.
 
-Run \`ck analyze\` to generate this content, or manually add your story/demo pattern below.
+Run \`/analyze\` to generate this content, or manually add your story/demo pattern below.
 `,
       'templates/hook.md': `# Hook/Composable/Helper Template
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your canonical hook, composable, or helper pattern will be generated based on your project's framework and conventions.
 
-Run \`ck analyze\` to generate this content, or manually add your pattern below.
+Run \`/analyze\` to generate this content, or manually add your pattern below.
 `,
       'templates/api.md': `# API Service/Client Template
 
-<!-- Content will be generated by running: ck analyze -->
+<!-- Content will be generated by running: /analyze -->
 
 Your canonical API service or client pattern will be generated based on your project's architecture and conventions.
 
-Run \`ck analyze\` to generate this content, or manually add your API pattern below.
+Run \`/analyze\` to generate this content, or manually add your API pattern below.
+`,
+
+      'templates/feature-spec.md': `# [FeatureName]
+
+> **Spec-first document.** Write this before writing any code.
+> When complete, this file lives next to the feature: \`FeatureName/FeatureName.md\`
+> This is a **Page / Feature Level** doc (Level 2 of the documentation hierarchy).
+
+---
+
+## Purpose
+
+What this feature does and why it exists. One or two sentences max.
+
+## Scope
+
+What this feature **owns**:
+- [Responsibility 1]
+- [Responsibility 2]
+
+What this feature **does NOT cover** (out of scope):
+- [Excluded concern 1]
+- [Excluded concern 2]
+
+## Main Sections / Layout
+
+Key areas of the feature and what each contains:
+
+| Section | Description |
+|---------|-------------|
+| [Section name] | [What it shows or does] |
+| [Section name] | [What it shows or does] |
+
+## Components & Hooks
+
+| Name | Type | Role |
+|------|------|------|
+| \`[ComponentName]\` | Component | [What it handles] |
+| \`[useHookName]\` | Hook | [What state/logic it manages] |
+
+## Data & State
+
+**API endpoints used:**
+- \`[METHOD] /[endpoint]\` — [What it returns]
+
+**Key state:**
+- \`[stateName]\` — [What it tracks and when it changes]
+
+## Key User Flows
+
+Main paths through this feature:
+
+1. **[Flow name]:** [User does X → system does Y → result Z]
+2. **[Flow name]:** [User does X → system does Y → result Z]
+
+**Edge cases:**
+- [What happens when...]
+- [What happens when...]
+
+## Dependencies
+
+**Depends on:**
+- [Feature, service, or shared component this relies on]
+
+**Entry points:**
+- [Route or screen that leads here]
+
+**Exit points:**
+- [Where the user goes after completing the main flow]
+
+## Notes
+
+Any design decisions, trade-offs, or open questions to resolve before coding.
 `
     };
 
@@ -525,7 +639,7 @@ Run \`ck analyze\` to generate this content, or manually add your API pattern be
       await this.createSkeletonStandards();
       
       console.log(chalk.green('✅ Skeleton files created'));
-      console.log(chalk.yellow('💡 Run: ck analyze to generate content based on your codebase'));
+      console.log(chalk.yellow('💡 Run: /analyze to generate content based on your codebase'));
       console.log('');
       
       // Download base files
@@ -733,6 +847,7 @@ claude "read .contextkit/context.md to see available standards, then create a bu
 - \`.contextkit/instructions/core/auto-corrections-log.md\` - Auto-logging instructions
 
 ### Templates
+- \`.contextkit/templates/feature-spec.md\`
 - \`.contextkit/templates/component.md\`
 - \`.contextkit/templates/test.md\`
 - \`.contextkit/templates/story.md\`
@@ -1465,7 +1580,7 @@ Check this project's ContextKit setup and report status.
 
 2. Read \`.contextkit/config.yml\` and check the \`last_analyzed\` field.
 
-3. Check each standards file for skeleton markers. Read these files and check if they contain \`<!-- Content will be generated by running: ck analyze -->\`:
+3. Check each standards file for skeleton markers. Read these files and check if they contain \`<!-- Content will be generated by running: /analyze -->\`:
    - \`.contextkit/standards/code-style.md\`
    - \`.contextkit/standards/testing.md\`
    - \`.contextkit/standards/architecture.md\`
@@ -1545,9 +1660,9 @@ If standards are still skeletons, warn that @imports in CLAUDE.md are loading em
       console.log(`   @.contextkit/commands/analyze.md`);
       console.log('');
       console.log('Or via CLI:');
-      console.log(chalk.yellow('👉'), `ck analyze`);
+      console.log(chalk.yellow('👉'), `/analyze`);
     } else {
-      console.log(chalk.yellow('👉'), `ck analyze`);
+      console.log(chalk.yellow('👉'), `/analyze`);
     }
 
     console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "description": "ContextKit - Context Engineering for AI Development. Provide rich context to AI through structured MD files with standards, code guides, and documentation. Works with Cursor, Claude, Aider, VS Code Copilot, and more.",
   "main": "lib/index.js",
   "bin": {