aiknowsys 0.7.2 → 0.9.0

package/README.md

@@ -17,6 +17,11 @@ A structured workflow system consisting of:
 3. **Skills System** - Domain-specific how-to guides for common tasks
 4. **Changelog** - Session-by-session validation and learning history
 5. **Validation Matrix** - Mandatory test running before completion
+6. **Multi-Developer Collaboration** - Per-developer plan tracking and reviews prevent merge conflicts (Phase 2)
+7. **Multi-Plan Support** - Work on multiple initiatives simultaneously without losing context
+8. **OpenSpec + Plan Integration** - Combine proposal-driven design with task tracking ([see advanced workflows](docs/advanced-workflows.md))
+9. **ESSENTIALS Compression** - Automated detection and extraction of bloat to keep ESSENTIALS lean (600-800 lines)
+10. **VSCode Hooks** - 17 intelligent hooks for GitHub Copilot: session tracking, TDD enforcement, skill detection, health monitoring, collaboration alerts, performance tracking, migration assistance, and git collaboration reminders (optional)
 
 **Result:** AI assistants that understand your codebase, follow your patterns, and catch issues before production.
 
@@ -44,6 +49,66 @@ From production use in gnwebsite:
 | Patterns exist in tribal knowledge | Patterns documented and enforced |
 | Each session restarts context | Historical context preserved |
 
+### Intelligent Automation with VSCode Hooks
+
+**17 lifecycle hooks** that run automatically during GitHub Copilot sessions:
+
+✅ **Never forget tests** - TDD reminder before editing code  
+✅ **Never skip validation** - Validation reminder before claiming "done"  
+✅ **Auto-detect skills** - Suggests relevant guides based on your prompt  
+✅ **Health monitoring** - Alerts on disk space, lint errors, type issues  
+✅ **Avoid conflicts** - Detects concurrent work on same files  
+✅ **Track performance** - Warns on test regressions (>20% slower)  
+✅ **Stay updated** - Migration alerts for version mismatches  
+✅ **Fresh docs** - Staleness warnings for outdated documentation  
+✅ **Team collaboration** - Remind to share patterns, show teammates' active plans (git hooks)  
+
+**[Learn more about hooks →](docs/vscode-hooks-guide.md)**
+
+### vs GitHub Copilot Memory
+
+AIKnowSys complements (or replaces) GitHub's Copilot Memory with key advantages:
+
+🔒 **100% Local** - Never leaves your machine (privacy-first)  
+♾️ **Permanent** - Knowledge lasts forever (not 28-day expiration)  
+🌍 **Any AI Tool** - Works with Claude, ChatGPT, Cursor, etc. (not locked to Copilot)  
+📖 **Human-Readable** - Markdown files you can read and edit (not opaque AI format)  
+✍️ **You Control** - Decide what's documented (not AI-decided patterns)  
+🤝 **Team Shareable** - Commit to git, everyone benefits (not subscription-locked)  
+
+**[Read full comparison →](docs/copilot-memory-comparison.md)**
+
+### Plugin Ecosystem
+
+Extend aiknowsys with optional plugins for additional capabilities:
+
+**🔌 Available Plugins:**
+
+- **[aiknowsys-plugin-context7](https://www.npmjs.com/package/aiknowsys-plugin-context7)** - Context7 MCP integration
+  - Validate skills/stacks against current library documentation
+  - Query up-to-date framework docs (Next.js, Vue, React, etc.)
+  - Detect framework updates and breaking changes
+  - Generate validation reports for monthly reviews
+  - CI/CD integration for automated quality checks
+
+**Installation:**
+```bash
+npm install aiknowsys-plugin-context7
+
+# Plugin discovered automatically
+npx aiknowsys --help
+# Shows: validate-deliverables, query-docs commands
+```
+
+**Plugin Architecture:**
+- 🔌 Zero impact on core (optional dependencies)
+- 🎯 Auto-discovered via package.json
+- 📦 Separate npm packages
+- 🧪 Independent testing
+- 📖 Full documentation
+
+**[See plugin development guide →](docs/plugin-architecture.md)**
+
 ---
 
 ## Quick Start
@@ -105,8 +170,14 @@ Each stack template includes:
 | `npx aiknowsys check` | Validate knowledge system setup and configuration | N/A (validation) |
 | `npx aiknowsys sync` | Sync AGENTS.md validation reference with ESSENTIALS.md | N/A (maintenance) |
 | `npx aiknowsys audit` | Find common issues and pattern violations | N/A (analysis) |
+| `npx aiknowsys compress-essentials --analyze` | Preview ESSENTIALS compression opportunities | N/A (analysis) |
+| `npx aiknowsys compress-essentials --auto` | Auto-extract verbose sections to docs/ | N/A (maintenance) |
+| `npx aiknowsys compress-essentials --interactive` | Interactive compression workflow | N/A (maintenance) |
 | `npx aiknowsys install-agents` | Install Planner + Developer + Architect agents | N/A (standalone) |
 | `npx aiknowsys install-skills` | Install universal skills | N/A (standalone) |
+| `npx aiknowsys enable <feature>` | Enable and install a specific feature | N/A (feature management) |
+| `npx aiknowsys disable <feature>` | Disable a feature (optionally remove files) | N/A (feature management) |
+| `npx aiknowsys uninstall` | Remove AIKnowSys completely from project | N/A (cleanup) |
 
 **🤔 `init` vs `migrate` - Which Should I Use?**
 
@@ -241,6 +312,77 @@ npx  audit
 - `sync` - After upgrading from old templates with duplicated validation matrix
 - `audit` - Periodic health checks, before releases, or when reviewing code quality
 
+### 🗜️ Keeping ESSENTIALS Lean
+
+CODEBASE_ESSENTIALS.md should stay focused (600-800 lines recommended). Use compression commands to extract verbose content:
+
+```bash
+# Check if ESSENTIALS is bloated
+npx aiknowsys check
+# ⚠️ ESSENTIALS: 1400 lines (recommended: <800)
+
+# Preview what can be extracted
+npx aiknowsys compress-essentials --analyze
+# Shows verbose sections and where to extract them
+
+# Auto-extract verbose sections to docs/patterns/
+npx aiknowsys compress-essentials --auto
+# Moves code examples, updates references, preserves structure
+
+# Interactive mode for manual control
+npx aiknowsys compress-essentials --interactive
+# Step-by-step compression with previews
+```
+
+### 🔧 Feature Management
+
+Manage features after initial setup:
+
+```bash
+# Enable a feature that was skipped during init
+npx aiknowsys enable skills
+npx aiknowsys enable vscodeHooks
+npx aiknowsys enable tddEnforcement
+
+# Disable a feature (keeps files by default)
+npx aiknowsys disable openspec
+
+# Disable and remove files
+npx aiknowsys disable skills --remove-files
+
+# Remove AIKnowSys completely
+npx aiknowsys uninstall
+# ⚠️ Removes all AIKnowSys files with safety prompts
+# Option to keep user data (.aiknowsys/learned, sessions)
+```
+
+**Available features:**
+- `agents` - Developer + Architect + Planner custom agents
+- `skills` - Universal skills library (.github/skills/)
+- `vscodeHooks` - VS Code session hooks for auto-context loading
+- `sessionPersistence` - Session tracking (.aiknowsys/sessions/)
+- `tddEnforcement` - TDD git hooks and GitHub Actions
+- `openspec` - OpenSpec integration for change proposals
+- `context7` - Context7 MCP integration (reserved for future)
+
+**When to use:**
+- Skip optional features during init, add them later
+- Experiment with features without reinstalling
+- Clean up unused features to reduce repository size
+- Complete removal when migrating away from AIKnowSys
+
+**Prevention (built into templates):**
+- Template hints guide AI toward concise examples (<15 lines)
+- Post-init check warns if ESSENTIALS >800 lines after setup
+- Monthly `check` command catches growth early
+
+**Why this matters:**
+- Faster AI context loading (fewer tokens)
+- Easier navigation and maintenance
+- Better signal-to-noise ratio
+
+**See:** [docs/essentials-compression-guide.md](docs/essentials-compression-guide.md) for detailed guide
+
 ---
 
 ## 🔍 Enhanced Auto-Detection
@@ -362,8 +504,9 @@ If NO to any: Document violation in CODEBASE_CHANGELOG.md
 Pre-commit hook checks for test changes:
 
 ```bash
-# Install git hooks
-./scripts/install-git-hooks.sh
+# Install git hooks (cross-platform)
+node scripts/install-git-hooks.cjs
+# Or: npm run install-hooks
 
 # Now when you commit lib/ without test/ changes:
 ⚠️  WARNING: Staging lib/ changes without test/ changes
@@ -457,51 +600,6 @@ Stay tuned for updates!
 
 ---
 
-### Alternative: Manual Setup
-
-<details>
-<summary>Click to expand manual setup instructions</summary>
-
-#### For New Projects
-
-```bash
-# Clone the template
-git clone https://github.com/YOUR_ORG/.git
-cd 
-
-# Run interactive setup
-./scripts/setup.sh
-
-# Follow prompts to customize for your tech stack
-# Files will be generated with your configuration
-```
-
-#### For Existing Projects
-
-```bash
-# Clone into your project
-git clone https://github.com/YOUR_ORG/.git temp-template
-cp -r temp-template/scripts ./
-cp -r temp-template/templates ./
-
-# Run migration workflow
-./scripts/migrate-existing.sh
-
-# Scanner will:
-# 1. Detect your tech stack automatically
-# 2. Generate draft CODEBASE_ESSENTIALS.md (70% complete)
-# 3. Install custom agents
-# 4. Set up universal skills
-# 5. Initialize changelog
-
-# Complete TODO sections in CODEBASE_ESSENTIALS.md
-# Start using: @Developer <your request>
-```
-
-</details>
-
----
-
 ## Core Components
 
 ### 1. AI Knowledge System (.aiknowsys/)
@@ -513,13 +611,22 @@ When you run `init`, AIKnowSys creates a `.aiknowsys/` directory that enables AI
 **Directory Structure:**
 ```
 .aiknowsys/
+├── CURRENT_PLAN.md  # ✅ Committed - Team index (auto-generated)
+├── PLAN_*.md        # ✅ Committed - Implementation plans
+├── plans/           # ✅ Committed - Per-developer plan pointers
+│   ├── README.md    # ✅ Committed - Workflow explanation
+│   └── active-<username>.md  # ✅ Committed - Your active plan
+├── reviews/         # 🚫 Gitignored - Per-developer reviews
+│   ├── README.md    # ✅ Committed - Workflow explanation
+│   └── PENDING_<username>.md # 🚫 Temporary architect reviews
 ├── sessions/        # 🚫 Gitignored - Temporary session working memory
 │   ├── README.md    # ✅ Committed - Explains purpose
 │   └── YYYY-MM-DD-session.md  # 🚫 Daily session notes (not committed)
 ├── learned/         # ✅ Committed - Permanent project-specific patterns
 │   ├── README.md    # ✅ Committed - Explains pattern format
 │   └── *.md         # ✅ Committed - Discovered patterns
-└── PENDING_REVIEW.md # 🚫 Gitignored - Temporary architect reviews
+└── personal/        # 🚫 Gitignored - Personal patterns
+    └── <username>/  # 🚫 Your personal patterns
 ```
 
 #### Session Files (Temporary)
@@ -561,14 +668,15 @@ When you run `init`, AIKnowSys creates a `.aiknowsys/` directory that enables AI
 
 **What they are:**
 - Detailed code reviews created by Architect agent
+- Scoped per developer (no conflicts in team environments)
 - Deleted after Developer addresses issues
 - Temporary handoff mechanism between agents
 
 **Example workflow:**
 1. Developer implements feature
-2. Architect writes review to `PENDING_REVIEW.md`
+2. Architect writes review to `reviews/PENDING_<username>.md`
 3. Developer reads review and fixes issues
-4. Developer deletes `PENDING_REVIEW.md`
+4. Developer deletes `reviews/PENDING_<username>.md`
 
 #### Gitignore Configuration
 
@@ -578,8 +686,11 @@ The init command automatically adds:
 # Session-specific AI memory (temporary, not committed)
 .aiknowsys/sessions/*.md
 !.aiknowsys/sessions/README.md
-.aiknowsys/PENDING_REVIEW.md
+.aiknowsys/reviews/
+!.aiknowsys/reviews/README.md
+.aiknowsys/personal/
 # Note: .aiknowsys/learned/ IS committed (project-specific patterns)
+# Note: .aiknowsys/plans/ IS committed (team plan tracking)
 ```
 
 **Validation:** Run `npx aiknowsys audit` to check if gitignore is configured correctly.
@@ -610,19 +721,20 @@ The init command automatically adds:
 
 **Workflow:**
 ```
-User → @Planner → Creates implementation plan → Writes to .aiknowsys/CURRENT_PLAN.md →
-  @Developer → Reads plan → Implements feature → Auto-handoff →
-    @SeniorArchitect → Reviews against ESSENTIALS → Writes to .aiknowsys/PENDING_REVIEW.md → ✅ Approve or 🔄 Refactor
+User → @Planner → Creates implementation plan → Writes to PLAN_*.md →
+  @Developer → Updates plans/active-<username>.md → Implements feature → Auto-handoff →
+    @SeniorArchitect → Reviews against ESSENTIALS → Writes to reviews/PENDING_<username>.md → ✅ Approve or 🔄 Refactor
 ```
 
 **What Planner does:**
 - Breaks down complex features into actionable steps
 - Identifies architectural concerns and dependencies
-- Documents implementation plan in `.aiknowsys/CURRENT_PLAN.md`
+- Documents implementation plan in `PLAN_*.md`
+- Updates developer's plan pointer in `plans/active-<username>.md`
 - Ensures proper sequencing and risk mitigation
 
 **What Developer does:**
-- Reads implementation plan from `.aiknowsys/CURRENT_PLAN.md`
+- Reads implementation plan from `plans/active-<username>.md` pointer
 - Implements features following project patterns
 - Writes tests (TDD if enabled, coverage testing otherwise)
 - Validates all changes before handoff
@@ -890,58 +1002,23 @@ Confirm docs updated
 
 ---
 
-## Installation Options
-
-### Option 1: Interactive Setup (New Projects)
-
-```bash
-./scripts/setup.sh
-```
-
-**Prompts for:**
-- Primary language (TypeScript/Python/Rust/Go)
-- Framework (Vue/React/Django/FastAPI/etc)
-- Testing tools (Vitest/Jest/pytest/cargo test)
-- Package manager (npm/pip/cargo/go mod)
+## Deprecated Installation Methods
 
-**Generates:**
-- CODEBASE_ESSENTIALS.md with validation commands
-- AGENTS.md with workflow instructions
-- Custom agents configured for your stack
-- Universal skills installed
+<details>
+<summary>⚠️ Old bash scripts (removed in v0.9.0) - Click for migration path</summary>
 
-### Option 2: Codebase Scanner (Existing Projects)
+The original bash scripts (`setup.sh`, `migrate-existing.sh`, `scan-codebase.sh`) have been removed. They are fully replaced by CLI commands:
 
 ```bash
-./scripts/migrate-existing.sh
+# Old (removed)                   →  New (use this)
+./scripts/setup.sh               →  npx aiknowsys init
+./scripts/migrate-existing.sh    →  npx aiknowsys migrate  
+./scripts/scan-codebase.sh       →  npx aiknowsys scan
 ```
 
-**Automatically detects:**
-- Tech stack from package files
-- Test commands from package.json/Makefile/CI
-- Project structure
-- Key dependencies
-
-**Generates:**
-- Draft CODEBASE_ESSENTIALS.md (70% complete)
-- TODO sections for manual patterns
-- Validation matrix
-- Changelog initialized
-
-**Time saved:** ~3-4 hours of manual documentation
-
-### Option 3: Manual Setup
+See [scripts/README.md](scripts/README.md) for full details.
 
-```bash
-# Copy templates
-cp templates/CODEBASE_ESSENTIALS.template.md CODEBASE_ESSENTIALS.md
-cp templates/AGENTS.template.md AGENTS.md
-cp -r templates/agents/ .github/agents/
-
-# Customize for your project
-# Fill in {{PLACEHOLDERS}}
-# Add your patterns and conventions
-```
+</details>
 
 ---
 
@@ -992,6 +1069,11 @@ Edit `.github/agents/architect.agent.md`:
 - Errors must use structured logging
 ```
 
+**Advanced:** Customize agent `model` and `tools` frontmatter fields:
+- See `.github/agents/USAGE.txt` section "Customizing `model` and `tools`"
+- Or [docs/customization-guide.md](docs/customization-guide.md) for full field reference
+- Control which AI model each agent uses and what capabilities they have
+
 **3. Create Custom Skills**
 
 Use skill-creator skill: