aiknowsys 0.5.0 → 0.7.0

package/README.md

@@ -1,4 +1,4 @@
-# aiknowsys - Knowledge System Template
+# AIKnowSys - Knowledge System Template
 
 **AI-Powered Development Workflow for Consistent, High-Quality Code**
 
@@ -13,7 +13,7 @@ A battle-tested knowledge management system that enables AI-assisted development
 A structured workflow system consisting of:
 
 1. **CODEBASE_ESSENTIALS.md** - Single source of truth for patterns, conventions, and invariants
-2. **Custom Agents** (Developer + Architect) - Automated code review enforcing KISS/DRY/SOLID/YAGNI
+2. **Custom Agents** (Planner → Developer → Architect) - Three-agent workflow with automated code review enforcing KISS/DRY/SOLID/YAGNI
 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
@@ -52,17 +52,17 @@ From production use in gnwebsite:
 
 ```bash
 # For new projects - interactive setup
-npx aiknowsys init
+npx  init
 
 # For new projects with pre-built stack template
-npx aiknowsys init --stack nextjs
+npx  init --stack nextjs
 
 # For existing projects - auto-detect and migrate
-npx aiknowsys migrate
+npx  migrate
 
 # Or install globally
-npm install -g aiknowsys
-aiknowsys init
+npm install -g 
+ init
 ```
 
 **🚀 Pre-built Stack Templates:**
@@ -71,13 +71,13 @@ Skip most customization work with production-ready stack templates:
 
 ```bash
 # List available stacks
-npx aiknowsys init --list-stacks
+npx  init --list-stacks
 
 # Initialize with Next.js stack
-npx aiknowsys init --stack nextjs
+npx  init --stack nextjs
 
 # Initialize with Vue + Express full-stack monorepo
-npx aiknowsys init --stack vue-express
+npx  init --stack vue-express
 ```
 
 **Available stacks:**
@@ -98,29 +98,101 @@ Each stack template includes:
 
 | Command | Description | Auto-installs agents/skills? |
 |---------|-------------|------------------------------|
-| `npx aiknowsys init` | Initialize for a new project | ✅ Yes |
-| `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  init` | Initialize for a new project | ✅ Yes |
+| `npx  migrate` | Full migration for existing projects | ✅ Yes |
+| `npx  scan` | Scan codebase and generate draft ESSENTIALS | ❌ No (run install-agents after) |
+| `npx  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-agents` | Install Planner + Developer + Architect agents | N/A (standalone) |
 | `npx aiknowsys install-skills` | Install universal skills | N/A (standalone) |
 
+**🤔 `init` vs `migrate` - Which Should I Use?**
+
+- **`init`** → Recommended for everyone (new OR existing projects)
+  - Detects your situation and offers appropriate options
+  - For existing projects: choose "🔍 Scan Codebase" → runs migrate workflow
+  - More user-friendly with guided choices
+
+- **`migrate`** → Direct path for existing projects only
+  - Skips the setup menu, goes straight to scanning
+  - Same result as `init` → "Scan Codebase"
+  - Use if you prefer fewer prompts
+
+**TL;DR:** Both do the same thing for existing code. `init` with "Scan Codebase" literally calls `migrate` internally. Just use `init` unless you want to skip the setup mode selection.
+
 **💡 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.
 
+---
+
+### 🎯 Advanced: Custom Essentials Filename
+
+All commands support the `--essentials` (or `-e`) flag to use a custom filename instead of `CODEBASE_ESSENTIALS.md`:
+
+```bash
+# Initialize with custom filename
+npx aiknowsys init --essentials ARCHITECTURE.md
+
+# All other commands work with the same flag
+npx aiknowsys check --essentials ARCHITECTURE.md
+npx aiknowsys sync --essentials ARCHITECTURE.md
+npx aiknowsys audit --essentials ARCHITECTURE.md
+npx aiknowsys update --essentials ARCHITECTURE.md
+npx aiknowsys migrate --essentials ARCHITECTURE.md
+npx aiknowsys install-agents --essentials ARCHITECTURE.md
+```
+
+**Common Use Cases:**
+
+1. **Corporate Naming Standards**
+   ```bash
+   # Your company requires "ENGINEERING_GUIDE.md"
+   npx aiknowsys init --essentials ENGINEERING_GUIDE.md
+   ```
+
+2. **Monorepo Organization**
+   ```bash
+   # Different essentials per package
+   cd packages/backend
+   npx aiknowsys init --essentials BACKEND_ESSENTIALS.md
+   
+   cd packages/frontend
+   npx aiknowsys init --essentials FRONTEND_ESSENTIALS.md
+   ```
+
+3. **Localization**
+   ```bash
+   # Non-English teams
+   npx aiknowsys init --essentials CODEBASE_ESSENTIALS_FR.md
+   npx aiknowsys init --essentials コードベース要点.md
+   ```
+
+4. **Legacy Project Migration**
+   ```bash
+   # You already have "CONTRIBUTING.md" or "ARCHITECTURE.md"
+   npx aiknowsys init --essentials ARCHITECTURE.md
+   ```
+
+**Important Notes:**
+- Custom agents will automatically reference your custom filename
+- All validation and maintenance commands work seamlessly
+- The system defaults to `CODEBASE_ESSENTIALS.md` if flag not provided
+- Backwards compatible - existing projects continue working without changes
+
+---
+
 **📋 Template Options:**
 
 - **Minimal Template** (10 sections): For learning projects, prototypes, and simple tools
   ```bash
-  npx aiknowsys init --template minimal
+  npx  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
+  npx  init --template full  # or just: npx  init
   ```
   Includes all minimal sections + Security, Performance, Accessibility
 
@@ -146,18 +218,18 @@ New commands to validate and maintain your knowledge system:
 
 ```bash
 # Validate your setup
-npx aiknowsys check
+npx  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
+npx  sync
 # Updates AGENTS.md to reference ESSENTIALS.md (DRY principle)
 
 # Find issues and violations
-npx aiknowsys audit
+npx  audit
 # ⚠️ Detects validation matrix duplication
 # ⚠️ Finds generic placeholder values
 # ⚠️ Checks file size bloat
@@ -216,7 +288,7 @@ Example: How do you create API instances? Base URL configuration?
 
 **Workflow:**
 1. Read example to understand format and level of detail
-2. Run `npx aiknowsys scan` to generate draft for your project
+2. Run `npx  scan` to generate draft for your project
 3. Use example as reference while filling TODOs
 4. Copy structure, not content (write your own patterns!)
 
@@ -394,8 +466,8 @@ Stay tuned for updates!
 
 ```bash
 # Clone the template
-git clone https://github.com/YOUR_ORG/aiknowsys.git
-cd aiknowsys
+git clone https://github.com/YOUR_ORG/.git
+cd 
 
 # Run interactive setup
 ./scripts/setup.sh
@@ -408,7 +480,7 @@ cd aiknowsys
 
 ```bash
 # Clone into your project
-git clone https://github.com/YOUR_ORG/aiknowsys.git temp-template
+git clone https://github.com/YOUR_ORG/.git temp-template
 cp -r temp-template/scripts ./
 cp -r temp-template/templates ./
 
@@ -432,7 +504,87 @@ cp -r temp-template/templates ./
 
 ## Core Components
 
-### 1. CODEBASE_ESSENTIALS.md
+### 1. AI Knowledge System (.aiknowsys/)
+
+**Purpose:** Structured memory and continuous learning for AI assistants.
+
+When you run `init`, AIKnowSys creates a `.aiknowsys/` directory that enables AI assistants to maintain context across sessions and accumulate project-specific knowledge over time.
+
+**Directory Structure:**
+```
+.aiknowsys/
+├── 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
+```
+
+#### Session Files (Temporary)
+
+**What they are:**
+- Working memory for a single AI conversation
+- Created/updated during complex multi-step work
+- Automatically loaded by AI agents at session start
+
+**Why gitignored:**
+- Session-specific context (like IDE workspace files)
+- Not useful to other developers or other AI sessions
+- Prevents git history clutter
+
+**Benefits:**
+- ✅ Context continuity across messages in same session
+- ✅ AI remembers what you worked on last time
+- ✅ Complex multi-step work doesn't lose progress
+
+#### Learned Patterns (Permanent)
+
+**What they are:**
+- Discovered patterns applicable to whole project
+- Reusable across all AI assistants and team members
+- Examples: Custom validation rules, debugging techniques, library-specific gotchas
+
+**Why committed:**
+- Valuable team knowledge
+- Helps onboard new developers
+- AI assistants get smarter with each session
+- Project knowledge accumulates over time
+
+**Benefits:**
+- ✅ Reduced repeated explanations
+- ✅ Team-wide pattern sharing
+- ✅ AI learns from mistakes and successes
+
+#### Review Files (Ephemeral)
+
+**What they are:**
+- Detailed code reviews created by Architect agent
+- Deleted after Developer addresses issues
+- Temporary handoff mechanism between agents
+
+**Example workflow:**
+1. Developer implements feature
+2. Architect writes review to `PENDING_REVIEW.md`
+3. Developer reads review and fixes issues
+4. Developer deletes `PENDING_REVIEW.md`
+
+#### Gitignore Configuration
+
+The init command automatically adds:
+
+```gitignore
+# Session-specific AI memory (temporary, not committed)
+.aiknowsys/sessions/*.md
+!.aiknowsys/sessions/README.md
+.aiknowsys/PENDING_REVIEW.md
+# Note: .aiknowsys/learned/ IS committed (project-specific patterns)
+```
+
+**Validation:** Run `npx aiknowsys audit` to check if gitignore is configured correctly.
+
+### 2. CODEBASE_ESSENTIALS.md
 
 **Purpose:** Single-source reference for architecture, patterns, and critical invariants.
 
@@ -450,17 +602,32 @@ cp -r temp-template/templates ./
 
 **Why it matters:** AI reads this at session start, ensuring all suggestions align with your architecture.
 
-### 2. Custom Agents (Developer + Architect)
+### 2. Custom Agents (Planner → Developer → Architect)
 
-**Purpose:** Automated quality gate enforcing documented patterns.
+**Purpose:** Three-agent workflow with automated quality gates enforcing documented patterns.
 
 **Platform:** GitHub Copilot in VS Code (other AI tools: see [AI Tool Compatibility](#ai-tool-compatibility))
 
 **Workflow:**
 ```
-User → @Developer → Implements feature → Auto-handoff → @SeniorArchitect → Reviews against ESSENTIALS → ✅ Approve or 🔄 Refactor
+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
 ```
 
+**What Planner does:**
+- Breaks down complex features into actionable steps
+- Identifies architectural concerns and dependencies
+- Documents implementation plan in `.aiknowsys/CURRENT_PLAN.md`
+- Ensures proper sequencing and risk mitigation
+
+**What Developer does:**
+- Reads implementation plan from `.aiknowsys/CURRENT_PLAN.md`
+- Implements features following project patterns
+- Writes tests (TDD if enabled, coverage testing otherwise)
+- Validates all changes before handoff
+- Auto-calls Architect for code review
+
 **What Architect checks:**
 - KISS (Keep It Simple) - No unnecessary complexity
 - DRY (Don't Repeat Yourself) - Proper abstraction

package/bin/cli.js

@@ -24,7 +24,7 @@ try {
   packageJson = JSON.parse(
     readFileSync(join(__dirname, '../package.json'), 'utf-8')
   );
-} catch (error) {
+} catch (_error) {
   console.error(chalk.red('Error: Could not read package.json'));
   process.exit(1);
 }
@@ -77,6 +77,7 @@ program
   .command('update')
   .description('Update agents, skills, and workflow to latest version')
   .option('-d, --dir <directory>', 'Project directory', '.')
+  .option('-e, --essentials <file>', 'ESSENTIALS file name', 'CODEBASE_ESSENTIALS.md')
   .option('-y, --yes', 'Update all components without prompting')
   .option('-f, --force', 'Force update even if already up to date')
   .action(update);
@@ -85,18 +86,21 @@ program
   .command('check')
   .description('Validate knowledge system setup and configuration')
   .option('-d, --dir <directory>', 'Target directory', '.')
+  .option('-e, --essentials <file>', 'ESSENTIALS file name', 'CODEBASE_ESSENTIALS.md')
   .action(check);
 
 program
   .command('sync')
   .description('Sync AGENTS.md validation reference with CODEBASE_ESSENTIALS.md')
   .option('-d, --dir <directory>', 'Target directory', '.')
+  .option('-e, --essentials <file>', 'ESSENTIALS file name', 'CODEBASE_ESSENTIALS.md')
   .action(sync);
 
 program
   .command('audit')
   .description('Find common issues and pattern violations in knowledge system')
   .option('-d, --dir <directory>', 'Target directory', '.')
+  .option('-e, --essentials <file>', 'ESSENTIALS file name', 'CODEBASE_ESSENTIALS.md')
   .action(audit);
 
 // Default command - show help with styled banner