aiknowsys 0.1.1 → 0.3.0

package/AGENTS.template.md

@@ -34,14 +34,16 @@
 - [ ] Read @CODEBASE_ESSENTIALS.md (patterns, conventions)
 - [ ] Read relevant skill if applicable
 - [ ] Make changes + write/update tests
-- [ ] **VALIDATE** (see validation matrix below)
+- [ ] **VALIDATE** (see validation matrix in ESSENTIALS)
 - [ ] Update docs if patterns changed
 
-**Validation Matrix (ALWAYS run after changes):**
+**Validation Matrix:**
 
-| Changed | Commands | Required |
-|---------|----------|----------|
-{{VALIDATION_MATRIX}}
+👉 **See [CODEBASE_ESSENTIALS.md - Validation Matrix](CODEBASE_ESSENTIALS.md#validation-matrix)**
+
+The validation matrix lives in CODEBASE_ESSENTIALS.md as the single source of truth. Always run all commands from that matrix after making changes.
+
+**🚨 RULE: Never claim work is complete without running validation!**
 
 ---
 
@@ -75,6 +77,19 @@
 
 Follow patterns from CODEBASE_ESSENTIALS.md and the skill you read.
 
+**💡 TDD Recommended:** For new features, practice Test-Driven Development:
+1. **RED**: Write a failing test first
+2. **GREEN**: Write minimal code to make it pass
+3. **REFACTOR**: Clean up code while tests stay green
+
+See `.github/skills/tdd-workflow/SKILL.md` for detailed TDD guidance.
+
+**Benefits of TDD:**
+- Better code design (forces decoupling)
+- Fewer bugs (issues caught before implementation)
+- Confidence in refactoring (tests catch regressions)
+- Living documentation (tests show intent)
+
 ### 4️⃣ VALIDATE: Run Tests & Checks (MANDATORY - DO NOT SKIP!)
 
 **⚠️ CRITICAL: Run validation EVERY TIME you make a change (even small fixes!)**
@@ -178,30 +193,100 @@ This project uses Developer + Architect agents for automated code review.
 
 ---
 
+## ✅ Pre-Commit Validation Checklist
+
+**Run this checklist BEFORE every commit. Copy-paste into terminal:**
+
+### Quick Check (1 minute)
+```bash
+# 1. Validation Matrix commands
+{{VALIDATION_CMD_1}}  # e.g., npm test
+{{VALIDATION_CMD_2}}  # e.g., npm run lint
+
+# 2. No debug code
+grep -r "console.log\|debugger\|TODO:" src/ || echo "✓ No debug code"
+
+# 3. No secrets
+grep -r "password\|api_key\|secret" . --exclude-dir={node_modules,.git} || echo "✓ No secrets"
+```
+
+### Full Check (5 minutes)
+```bash
+# Run all validation commands from matrix
+{{ALL_VALIDATION_COMMANDS}}
+
+# Additional checks
+git status                          # No untracked files
+git diff                            # Review changes
+grep "{{" {{TEMPLATE_FILES}}        # No unfilled placeholders
+```
+
+### Before Push
+```bash
+# Final validation
+{{VALIDATION_CMD_1}}
+
+# Check commits
+git log origin/main..HEAD           # Review commits
+
+# Push
+git push
+```
+
+---
+
+## 🔍 Troubleshooting Validation Failures
+
+### Tests Failing
+1. Read error message carefully
+2. Check CODEBASE_ESSENTIALS.md for test patterns
+3. Review "Common Gotchas" section
+4. Run single failing test: `{{SINGLE_TEST_CMD}}`
+5. Check if pattern violated (Critical Invariants)
+
+### Linting Errors
+1. Auto-fix if possible: `{{AUTO_FIX_CMD}}`
+2. Review Core Patterns for style rules
+3. Don't disable rules - fix the code
+4. If rule is wrong, update ESSENTIALS first
+
+### Build Errors
+1. Check dependency versions (Technology Stack section)
+2. Clear cache: `{{CLEAR_CACHE_CMD}}`
+3. Rebuild from scratch: `{{CLEAN_BUILD_CMD}}`
+4. Check environment variables
+
+---
+
 ## 📝 Customization Instructions
 
 **This is a template file. To customize:**
 
-1. **{{VALIDATION_MATRIX}}** - Replace with your actual validation commands
-   ```markdown
-   | Backend | pytest | ✅ MANDATORY |
-   | Frontend | npm run type-check | ✅ MANDATORY |
-   ```
-
-2. **{{SKILL_MAPPING}}** - Add your project's skill trigger words
+1. **{{SKILL_MAPPING}}** - Add your project's skill trigger words
    ```markdown
    | "refactor", "clean up" | code-refactoring | Test-driven refactoring |
    | "update deps" | dependency-updates | Safe dependency updates |
+   | "write tests", "TDD", "test first" | tdd-workflow | Test-driven development |
    ```
 
+2. **Validation Checklist Placeholders:**
+   - `{{VALIDATION_CMD_1}}` → Your primary test command (e.g., `npm test`)
+   - `{{VALIDATION_CMD_2}}` → Your lint command (e.g., `npm run lint`)
+   - `{{ALL_VALIDATION_COMMANDS}}` → All commands from validation matrix in ESSENTIALS
+   - `{{TEMPLATE_FILES}}` → Files to check for placeholders
+   - `{{SINGLE_TEST_CMD}}` → How to run one test (e.g., `npm test -- file.test.js`)
+   - `{{AUTO_FIX_CMD}}` → Auto-fix linting (e.g., `npm run lint:fix`)
+   - `{{CLEAR_CACHE_CMD}}` → Clear build cache
+   - `{{CLEAN_BUILD_CMD}}` → Clean rebuild command
+
 3. **Add project-specific sections** as needed
 
 4. **Remove placeholder text** and instructions
 
-5. **Rename to `AGENTS.md`** when complete
+**Note:** Validation Matrix is in CODEBASE_ESSENTIALS.md - no need to duplicate it here.
 
 ---
 
 *This file helps AI agents follow a consistent workflow: Read → Plan → Implement → Validate → Document → Confirm*
 
-*Part of the Knowledge System Template. See [README](README.md) for full documentation.*
+*Part of aiknowsys. See [README](README.md) and [SETUP_GUIDE.md](SETUP_GUIDE.md) for full documentation.*

package/CODEBASE_ESSENTIALS.template.md

@@ -34,18 +34,79 @@
 
 ---
 
-## Document Purpose & Usage
+## 📚 Knowledge System: Document Roles
+
+**Your project has three core knowledge files that work together:**
+
+### 1️⃣ CODEBASE_ESSENTIALS.md (This File)
+**Role:** Single source of truth for architecture, patterns, and invariants  
+**Read:** At the start of EVERY session before making changes  
+**Contains:**
+- Technology stack and versions
+- Validation commands (test, lint, build)
+- Project structure and file organization
+- Code patterns and conventions
+- Critical rules that must never be violated
+- Common gotchas and workarounds
+
+**Use this when:**
+- Starting a coding session (read first!)
+- Implementing new features (check existing patterns)
+- Debugging issues (review gotchas)
+- Onboarding new developers (comprehensive reference)
+
+### 2️⃣ AGENTS.md
+**Role:** AI assistant workflow and session procedures  
+**Read:** When working with AI coding assistants  
+**Contains:**
+- Mandatory session start protocol
+- Validation matrix (copy from this file)
+- Skill trigger words and workflows
+- Project-specific invariants for AI
+- Changelog update procedures
+
+**Use this when:**
+- Using GitHub Copilot, Claude, ChatGPT, etc.
+- Need workflow reminders (read → plan → implement → validate → document)
+- Looking for relevant skills for a task
+
+### 3️⃣ CODEBASE_CHANGELOG.md
+**Role:** Session-by-session development history  
+**Read:** When you need project history or context  
+**Contains:**
+- Session entries (what changed, when, why)
+- Validation results for each session
+- Key learnings and discoveries
+- Links to changed files with line numbers
+
+**Use this when:**
+- Understanding why a decision was made
+- Tracking down when a bug was introduced
+- Reviewing project evolution
+- After each session (add new entry)
+
+### 🔄 How They Work Together
 
-**When to read this document:**
-- At the start of EVERY session before making changes
-- Before implementing new features (patterns + constraints)
-- When debugging issues (gotchas + known quirks)
-- Before updating dependencies (stack snapshot)
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. Session Start: Read CODEBASE_ESSENTIALS.md          │
+│    (Get current architecture, patterns, invariants)     │
+└──────────────────────┬──────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────┐
+│ 2. Work Session: Follow AGENTS.md workflow             │
+│    (AI-guided: read → plan → code → validate → doc)    │
+└──────────────────────┬──────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────┐
+│ 3. Session End: Update CODEBASE_CHANGELOG.md           │
+│    (Document what changed, validation, learnings)       │
+└─────────────────────────────────────────────────────────┘
+```
 
-**Related documentation:**
-- Session history: [CODEBASE_CHANGELOG.md](CODEBASE_CHANGELOG.md)
-- AI workflow: [AGENTS.md](AGENTS.md)
-- Skills: [.github/skills/](.github/skills/)
+**Golden Rule:** ESSENTIALS = "what is", AGENTS = "how to work", CHANGELOG = "what happened"
 
 ---
 
@@ -342,6 +403,89 @@ openspec archive X --yes   # Archive after deployment
 
 ---
 
+## 🚀 First Implementation Guide
+
+**Once this template is filled, here's your recommended build order:**
+
+### Step 1: Foundation (Week 1)
+**Goal:** Get basic project running with validation
+
+**Build:**
+1. Set up project structure (directories from "Project Structure" section)
+2. Initialize package manager and install dependencies
+3. Configure build tools and linters
+4. Write "Hello World" or minimal working version
+5. Set up validation commands from Validation Matrix
+
+**Validate:**
+- [ ] All validation commands work (`npm test`, etc.)
+- [ ] Can build and run the project
+- [ ] Linting passes
+
+**Document:** Update CODEBASE_CHANGELOG.md with first session
+
+---
+
+### Step 2: Core Patterns (Week 2-3)
+**Goal:** Implement fundamental patterns from this document
+
+**Build:**
+1. Create pattern examples (from "Core Patterns" section)
+2. Set up error handling structure
+3. Implement logging/monitoring basics
+4. Add configuration management
+5. Write tests for core patterns
+
+**Validate:**
+- [ ] Pattern examples work as documented
+- [ ] Tests cover core patterns
+- [ ] No critical invariants violated
+
+**Why this order:** Patterns guide all future code. Establish them early.
+
+---
+
+### Step 3: Feature Development (Ongoing)
+**Goal:** Build actual features following established patterns
+
+**Build:**
+1. Reference "Core Patterns" for each implementation
+2. Follow "Critical Invariants" religiously
+3. Watch out for "Common Gotchas"
+4. Run validation before each commit
+5. Update changelog after each session
+
+**Validate:**
+- [ ] New code follows documented patterns
+- [ ] All validation passes
+- [ ] No gotchas violated
+
+**When stuck:** Review this document, check AGENTS.md for relevant skills
+
+---
+
+### Step 4: Hardening (Before Production)
+**Goal:** Production-ready quality
+
+**Build:**
+1. Implement security measures (Security section)
+2. Add performance optimizations (Performance section)
+3. Ensure accessibility (Accessibility section)
+4. Set up monitoring and alerting
+5. Document deployment process
+
+**Validate:**
+- [ ] Security checklist complete
+- [ ] Performance targets met
+- [ ] Accessibility standards met
+- [ ] Deployment tested
+
+---
+
+**Golden Rule:** Always refer back to this document. Don't drift from documented patterns.
+
+---
+
 ## Version Control
 
 **Branch strategy:** {{BRANCH_STRATEGY}}
@@ -354,43 +498,21 @@ openspec archive X --yes   # Archive after deployment
 
 ## 📝 Customization Instructions
 
-**This is a template file. To use it:**
-
-1. **Replace all {{PLACEHOLDERS}}** with your actual values
-2. **Remove sections** that don't apply to your project
-3. **Add sections** for your specific patterns
-4. **Fill in examples** with real code from your project
-5. **Update regularly** as patterns evolve
-
-**⚠️ CRITICAL RULES FOR AI AGENTS:**
-
-When filling this template, you MUST:
-- ✅ Replace `{{PLACEHOLDERS}}` with **REAL values from the project**, not generic text
-- ✅ Keep section headings **EXACTLY as written** (e.g., "Testing Patterns" stays "Testing Patterns")
-- ✅ Use actual commands, file paths, and code snippets from the codebase
-- ✅ Make content specific to THIS project, not generic advice
-
-When filling this template, you MUST NOT:
-- ❌ Change section headings (e.g., "Testing Patterns" → "Testing Guidelines")
-- ❌ Replace placeholders with other placeholders (e.g., `{{TEST_ORGANIZATION}}` → "Manual testing only")
-- ❌ Add generic content that could apply to any project
-- ❌ Skip sections - fill them or remove them
-
-**Common placeholders:**
-- `{{PROJECT_NAME}}` - Your project name
-- `{{DATE}}` - Current date
-- `{{FRAMEWORK}}` - Framework name and version
-- `{{LANGUAGE}}` - Programming language
-- `{{*_CMD}}` - Actual commands to run
-- `{{*_DESCRIPTION}}` - Your explanations
-- `{{*_EXAMPLE}}` - Real code examples
-
-**After customization:**
-1. Rename to `CODEBASE_ESSENTIALS.md`
-2. Commit to repository
-3. Reference in AGENTS.md
-4. Update as patterns change
+**This is a template file. To customize it for your project:**
+
+👉 **See [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed instructions**
+
+**Quick start:**
+1. Replace all `{{PLACEHOLDERS}}` with real values from your project
+2. Use actual commands, file paths, and code examples (not generic descriptions)
+3. Keep section headings exactly as written
+4. Remove sections that don't apply to your project
+
+**⚠️ Critical:** Replace placeholders with REAL values, not other placeholders  
+Example: `{{TEST_CMD}}` → `npm test` (not "run your tests")
+
+**AI-Assisted:** Use the prompt from `npx aiknowsys init` to have AI fill this automatically
 
 ---
 
-*This template is part of the Knowledge System Template. See [README](README.md) for full documentation.*
+*This template is part of aiknowsys. See [README](README.md) and [SETUP_GUIDE.md](SETUP_GUIDE.md) for full documentation.*

package/README.md

@@ -54,6 +54,9 @@ From production use in gnwebsite:
 # For new projects - interactive setup
 npx aiknowsys init
 
+# For new projects with pre-built stack template
+npx aiknowsys init --stack nextjs
+
 # For existing projects - auto-detect and migrate
 npx aiknowsys migrate
 
@@ -62,6 +65,35 @@ npm install -g aiknowsys
 aiknowsys init
 ```
 
+**🚀 Pre-built Stack Templates:**
+
+Skip most customization work with production-ready stack templates:
+
+```bash
+# List available stacks
+npx aiknowsys init --list-stacks
+
+# Initialize with Next.js stack
+npx aiknowsys init --stack nextjs
+
+# Initialize with Vue + Express full-stack monorepo
+npx aiknowsys init --stack vue-express
+```
+
+**Available stacks:**
+- `nextjs` - Next.js 15 + App Router + TypeScript + Tailwind + Prisma
+- `vue-express` - Vue 3 + Express full-stack monorepo with shared types
+
+Each stack template includes:
+- ✅ Pre-filled Technology Snapshot
+- ✅ Stack-specific validation matrix with proper commands
+- ✅ Core patterns and conventions for the stack
+- ✅ Common gotchas and solutions
+- ✅ Testing patterns and examples
+- ✅ Architecture decisions (why this stack)
+
+**Setup time:** 2-3 minutes (vs 10-15 min interactive, vs 45 min manual)
+
 **Available commands:**
 
 | Command | Description | Auto-installs agents/skills? |
@@ -70,11 +102,73 @@ aiknowsys init
 | `npx aiknowsys migrate` | Full migration for existing projects | ✅ Yes |
 | `npx aiknowsys scan` | Scan codebase and generate draft ESSENTIALS | ❌ No (run install-agents after) |
 | `npx aiknowsys update` | Update agents, skills, and workflow to latest version | N/A (updates existing) |
+| `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 install-agents` | Install Developer + Architect agents | N/A (standalone) |
 | `npx aiknowsys install-skills` | Install universal skills | N/A (standalone) |
 
 **💡 AI-Assisted Completion:** When using `init` in AI-guided mode, `migrate`, or `scan`, you'll receive a ready-to-copy prompt that you can paste to your AI assistant (Claude, GPT-4, Copilot Chat, etc.) to automatically complete the TODO sections based on your actual codebase. Manual mode lets you fill sections yourself, but you can always use AI later.
 
+**📋 Template Options:**
+
+- **Minimal Template** (10 sections): For learning projects, prototypes, and simple tools
+  ```bash
+  npx aiknowsys init --template minimal
+  ```
+  Includes: Tech Stack, Validation Matrix, Structure, Patterns, Invariants, Gotchas, Testing, Architecture, Change Management, Workflow
+
+- **Full Template** (13+ sections): For production projects and complex systems (default)
+  ```bash
+  npx aiknowsys init --template full  # or just: npx aiknowsys init
+  ```
+  Includes all minimal sections + Security, Performance, Accessibility
+
+See [examples/filled-simple-api](examples/filled-simple-api) for a realistic filled example using the minimal template.
+
+**🚀 Enhanced Interactive Setup (Manual Mode):**
+
+Manual mode now asks intelligent questions about your project and automatically fills many placeholders:
+
+- ✅ **Technology Snapshot**: Framework, language, build tool, package manager
+- ✅ **Validation Matrix**: Auto-generates test, lint, type-check commands
+- ✅ **Tooling Details**: Database, linter, test framework selections
+- ✅ **Individual Commands**: {{TEST_CMD}}, {{LINT_CMD}}, {{TYPE_CHECK_CMD}} all filled
+
+**Before**: 50+ placeholders to fill manually
+**After**: Only structure and pattern placeholders remain (for AI or human completion)
+
+This significantly reduces setup time while maintaining flexibility for project-specific details.
+
+**🔍 Verification & Maintenance Commands:**
+
+New commands to validate and maintain your knowledge system:
+
+```bash
+# Validate your setup
+npx aiknowsys check
+# ✓ Checks required files exist
+# ✓ Verifies agents and skills installed
+# ✓ Detects unfilled placeholders
+# ✓ Validates validation matrix
+
+# Fix redundancy (sync validation matrix reference)
+npx aiknowsys sync
+# Updates AGENTS.md to reference ESSENTIALS.md (DRY principle)
+
+# Find issues and violations
+npx aiknowsys audit
+# ⚠️ Detects validation matrix duplication
+# ⚠️ Finds generic placeholder values
+# ⚠️ Checks file size bloat
+# ℹ️ Suggests improvements
+```
+
+**When to use:**
+- `check` - Before committing, after setup, or when troubleshooting
+- `sync` - After upgrading from old templates with duplicated validation matrix
+- `audit` - Periodic health checks, before releases, or when reviewing code quality
+
 ---
 
 ## AI Tool Compatibility
@@ -206,6 +300,7 @@ User → @Developer → Implements feature → Auto-handoff → @SeniorArchitect
 - `code-refactoring` - Test-driven refactoring patterns
 - `testing-best-practices` - Framework-agnostic testing guide
 - `skill-creator` - How to create new skills
+- `tdd-workflow` - Test-Driven Development (RED-GREEN-REFACTOR cycle)
 
 **Custom skills you can add:**
 - Feature implementation workflows

package/bin/cli.js

@@ -11,6 +11,9 @@ import { migrate } from '../lib/commands/migrate.js';
 import { installAgents } from '../lib/commands/install-agents.js';
 import { installSkills } from '../lib/commands/install-skills.js';
 import { update } from '../lib/commands/update.js';
+import { check } from '../lib/commands/check.js';
+import { sync } from '../lib/commands/sync.js';
+import { audit } from '../lib/commands/audit.js';
 
 // Get version from package.json
 const __filename = fileURLToPath(import.meta.url);
@@ -38,6 +41,9 @@ program
   .description('Initialize knowledge system with AI-assisted setup')
   .option('-d, --dir <directory>', 'Target directory', '.')
   .option('-y, --yes', 'Skip prompts and use defaults')
+  .option('-t, --template <type>', 'Template size: minimal (10 sections) or full (13+ sections)', 'full')
+  .option('-s, --stack <name>', 'Use pre-built stack template (nextjs, vue-express, etc.)')
+  .option('--list-stacks', 'List available stack templates')
   .action(init);
 
 program
@@ -75,6 +81,24 @@ program
   .option('-f, --force', 'Force update even if already up to date')
   .action(update);
 
+program
+  .command('check')
+  .description('Validate knowledge system setup and configuration')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .action(check);
+
+program
+  .command('sync')
+  .description('Sync AGENTS.md validation reference with CODEBASE_ESSENTIALS.md')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .action(sync);
+
+program
+  .command('audit')
+  .description('Find common issues and pattern violations in knowledge system')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .action(audit);
+
 // Default command - show help with styled banner
 program
   .action(() => {