{"id":42763648,"url":"https://github.com/arpa73/aiknowsys","last_synced_at":"2026-01-29T21:01:03.530Z","repository":{"id":334363103,"uuid":"1140536674","full_name":"arpa73/aiknowsys","owner":"arpa73","description":"aiknowsys - AI-Powered Development Workflow for Consistent, High-Quality Code","archived":false,"fork":false,"pushed_at":"2026-01-24T19:02:20.000Z","size":266,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T19:23:51.654Z","etag":null,"topics":["agents","ai","claude","code-review","copilot","developer-workflow","documentation","knowledge-management"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arpa73.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-23T12:15:22.000Z","updated_at":"2026-01-24T19:02:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arpa73/aiknowsys","commit_stats":null,"previous_names":["arpa73/aiknowsys"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/arpa73/aiknowsys","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arpa73%2Faiknowsys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arpa73%2Faiknowsys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arpa73%2Faiknowsys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arpa73%2Faiknowsys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arpa73","download_url":"https://codeload.github.com/arpa73/aiknowsys/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arpa73%2Faiknowsys/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28884689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T19:55:09.949Z","status":"ssl_error","status_checked_at":"2026-01-29T19:55:08.490Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","claude","code-review","copilot","developer-workflow","documentation","knowledge-management"],"created_at":"2026-01-29T21:01:02.635Z","updated_at":"2026-01-29T21:01:03.508Z","avatar_url":"https://github.com/arpa73.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AIKnowSys - Knowledge System Template\n\n**AI-Powered Development Workflow for Consistent, High-Quality Code**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA battle-tested knowledge management system that enables AI-assisted development while maintaining architectural consistency and preventing regressions. Originally developed for production use in the [gnwebsite project](https://github.com/arpa73/gnwebsite), now extracted as a reusable template for any tech stack.\n\n---\n\n## What Is This?\n\nA structured workflow system consisting of:\n\n1. **CODEBASE_ESSENTIALS.md** - Single source of truth for patterns, conventions, and invariants\n2. **Custom Agents** (Planner → Developer → Architect) - Three-agent workflow with automated code review enforcing KISS/DRY/SOLID/YAGNI\n3. **Skills System** - Domain-specific how-to guides for common tasks\n4. **Changelog** - Session-by-session validation and learning history\n5. **Validation Matrix** - Mandatory test running before completion\n\n**Result:** AI assistants that understand your codebase, follow your patterns, and catch issues before production.\n\n---\n\n## Why Use This?\n\n### Real-World Impact\n\nFrom production use in gnwebsite:\n\n✅ **Prevented pattern drift** - Caught MediaAsset using two different URL generation methods  \n✅ **Comprehensive testing** - Logger utility got 16 tests because ESSENTIALS mandates testing  \n✅ **Caught regressions** - Mailerlite integration tests caught 8 production bugs  \n✅ **Consistent refactoring** - Test-driven refactoring prevented behavior changes  \n✅ **Fast onboarding** - New AI sessions start productive immediately  \n\n### Before vs After\n\n| Without Knowledge System | With Knowledge System |\n|-------------------------|----------------------|\n| AI suggests inconsistent patterns | AI follows documented standards |\n| \"Quick fixes\" create technical debt | Process ensures quality every time |\n| Validation is manual/forgotten | Validation is automatic/mandatory |\n| Patterns exist in tribal knowledge | Patterns documented and enforced |\n| Each session restarts context | Historical context preserved |\n\n---\n\n## Quick Start\n\n### Install via npm (Recommended)\n\n```bash\n# For new projects - interactive setup\nnpx  init\n\n# For new projects with pre-built stack template\nnpx  init --stack nextjs\n\n# For existing projects - auto-detect and migrate\nnpx  migrate\n\n# Or install globally\nnpm install -g \n init\n```\n\n**🚀 Pre-built Stack Templates:**\n\nSkip most customization work with production-ready stack templates:\n\n```bash\n# List available stacks\nnpx  init --list-stacks\n\n# Initialize with Next.js stack\nnpx  init --stack nextjs\n\n# Initialize with Vue + Express full-stack monorepo\nnpx  init --stack vue-express\n```\n\n**Available stacks:**\n- `nextjs` - Next.js 15 + App Router + TypeScript + Tailwind + Prisma\n- `vue-express` - Vue 3 + Express full-stack monorepo with shared types\n\nEach stack template includes:\n- ✅ Pre-filled Technology Snapshot\n- ✅ Stack-specific validation matrix with proper commands\n- ✅ Core patterns and conventions for the stack\n- ✅ Common gotchas and solutions\n- ✅ Testing patterns and examples\n- ✅ Architecture decisions (why this stack)\n\n**Setup time:** 2-3 minutes (vs 10-15 min interactive, vs 45 min manual)\n\n**Available commands:**\n\n| Command | Description | Auto-installs agents/skills? |\n|---------|-------------|------------------------------|\n| `npx  init` | Initialize for a new project | ✅ Yes |\n| `npx  migrate` | Full migration for existing projects | ✅ Yes |\n| `npx  scan` | Scan codebase and generate draft ESSENTIALS | ❌ No (run install-agents after) |\n| `npx  update` | Update agents, skills, and workflow to latest version | N/A (updates existing) |\n| `npx aiknowsys check` | Validate knowledge system setup and configuration | N/A (validation) |\n| `npx aiknowsys sync` | Sync AGENTS.md validation reference with ESSENTIALS.md | N/A (maintenance) |\n| `npx aiknowsys audit` | Find common issues and pattern violations | N/A (analysis) |\n| `npx aiknowsys install-agents` | Install Planner + Developer + Architect agents | N/A (standalone) |\n| `npx aiknowsys install-skills` | Install universal skills | N/A (standalone) |\n\n**🤔 `init` vs `migrate` - Which Should I Use?**\n\n- **`init`** → Recommended for everyone (new OR existing projects)\n  - Detects your situation and offers appropriate options\n  - For existing projects: choose \"🔍 Scan Codebase\" → runs migrate workflow\n  - More user-friendly with guided choices\n\n- **`migrate`** → Direct path for existing projects only\n  - Skips the setup menu, goes straight to scanning\n  - Same result as `init` → \"Scan Codebase\"\n  - Use if you prefer fewer prompts\n\n**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.\n\n**💡 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.\n\n---\n\n### 🎯 Advanced: Custom Essentials Filename\n\nAll commands support the `--essentials` (or `-e`) flag to use a custom filename instead of `CODEBASE_ESSENTIALS.md`:\n\n```bash\n# Initialize with custom filename\nnpx aiknowsys init --essentials ARCHITECTURE.md\n\n# All other commands work with the same flag\nnpx aiknowsys check --essentials ARCHITECTURE.md\nnpx aiknowsys sync --essentials ARCHITECTURE.md\nnpx aiknowsys audit --essentials ARCHITECTURE.md\nnpx aiknowsys update --essentials ARCHITECTURE.md\nnpx aiknowsys migrate --essentials ARCHITECTURE.md\nnpx aiknowsys install-agents --essentials ARCHITECTURE.md\n```\n\n**Common Use Cases:**\n\n1. **Corporate Naming Standards**\n   ```bash\n   # Your company requires \"ENGINEERING_GUIDE.md\"\n   npx aiknowsys init --essentials ENGINEERING_GUIDE.md\n   ```\n\n2. **Monorepo Organization**\n   ```bash\n   # Different essentials per package\n   cd packages/backend\n   npx aiknowsys init --essentials BACKEND_ESSENTIALS.md\n   \n   cd packages/frontend\n   npx aiknowsys init --essentials FRONTEND_ESSENTIALS.md\n   ```\n\n3. **Localization**\n   ```bash\n   # Non-English teams\n   npx aiknowsys init --essentials CODEBASE_ESSENTIALS_FR.md\n   npx aiknowsys init --essentials コードベース要点.md\n   ```\n\n4. **Legacy Project Migration**\n   ```bash\n   # You already have \"CONTRIBUTING.md\" or \"ARCHITECTURE.md\"\n   npx aiknowsys init --essentials ARCHITECTURE.md\n   ```\n\n**Important Notes:**\n- Custom agents will automatically reference your custom filename\n- All validation and maintenance commands work seamlessly\n- The system defaults to `CODEBASE_ESSENTIALS.md` if flag not provided\n- Backwards compatible - existing projects continue working without changes\n\n---\n\n**📋 Template Options:**\n\n- **Minimal Template** (10 sections): For learning projects, prototypes, and simple tools\n  ```bash\n  npx  init --template minimal\n  ```\n  Includes: Tech Stack, Validation Matrix, Structure, Patterns, Invariants, Gotchas, Testing, Architecture, Change Management, Workflow\n\n- **Full Template** (13+ sections): For production projects and complex systems (default)\n  ```bash\n  npx  init --template full  # or just: npx  init\n  ```\n  Includes all minimal sections + Security, Performance, Accessibility\n\nSee [examples/filled-simple-api](examples/filled-simple-api) for a realistic filled example using the minimal template.\n\n**🚀 Enhanced Interactive Setup (Manual Mode):**\n\nManual mode now asks intelligent questions about your project and automatically fills many placeholders:\n\n- ✅ **Technology Snapshot**: Framework, language, build tool, package manager\n- ✅ **Validation Matrix**: Auto-generates test, lint, type-check commands\n- ✅ **Tooling Details**: Database, linter, test framework selections\n- ✅ **Individual Commands**: {{TEST_CMD}}, {{LINT_CMD}}, {{TYPE_CHECK_CMD}} all filled\n\n**Before**: 50+ placeholders to fill manually\n**After**: Only structure and pattern placeholders remain (for AI or human completion)\n\nThis significantly reduces setup time while maintaining flexibility for project-specific details.\n\n**🔍 Verification \u0026 Maintenance Commands:**\n\nNew commands to validate and maintain your knowledge system:\n\n```bash\n# Validate your setup\nnpx  check\n# ✓ Checks required files exist\n# ✓ Verifies agents and skills installed\n# ✓ Detects unfilled placeholders\n# ✓ Validates validation matrix\n\n# Fix redundancy (sync validation matrix reference)\nnpx  sync\n# Updates AGENTS.md to reference ESSENTIALS.md (DRY principle)\n\n# Find issues and violations\nnpx  audit\n# ⚠️ Detects validation matrix duplication\n# ⚠️ Finds generic placeholder values\n# ⚠️ Checks file size bloat\n# ℹ️ Suggests improvements\n```\n\n**When to use:**\n- `check` - Before committing, after setup, or when troubleshooting\n- `sync` - After upgrading from old templates with duplicated validation matrix\n- `audit` - Periodic health checks, before releases, or when reviewing code quality\n\n---\n\n## 🔍 Enhanced Auto-Detection\n\nThe `scan` command has been significantly enhanced to auto-detect and pre-fill more information:\n\n**Now detects 15+ technology categories:**\n- ✅ **Database**: PostgreSQL, MySQL, MongoDB, SQLite\n- ✅ **ORM**: Prisma, Drizzle, TypeORM, Sequelize, Mongoose\n- ✅ **State Management**: Pinia, Redux, Zustand, MobX, Jotai\n- ✅ **API Client**: Axios, TanStack Query\n- ✅ **Authentication**: NextAuth, Passport, Auth0, Supabase, Firebase\n- ✅ **Styling**: Tailwind CSS, Material UI, Styled Components, Emotion, Sass\n- ✅ **Code Patterns**: API routes, auth middleware, error handling, validation\n\n**Before:**\n```markdown\n## 3. Core Patterns\n\n### API Calls\nTODO: How do you make API calls?\n```\n\n**After:**\n```markdown\n## 3. Core Patterns\n\n### API Calls\nDetected: Axios\nTODO: Document standard usage pattern\nExample: How do you create API instances? Base URL configuration?\n```\n\n**Impact:** Reduces manual setup work by 40-50%, provides context-aware hints for completion.\n\n---\n\n## 📚 Example Templates\n\n**New in v0.3.0:** Completed example templates to guide your setup!\n\n**See:** [`docs/examples/`](docs/examples/)\n- **[CODEBASE_ESSENTIALS.example.md](docs/examples/CODEBASE_ESSENTIALS.example.md)** - Fully-filled example (TaskAPI - Express/TypeScript/Prisma)\n- **[README.md](docs/examples/README.md)** - How to use examples effectively\n\n**Workflow:**\n1. Read example to understand format and level of detail\n2. Run `npx  scan` to generate draft for your project\n3. Use example as reference while filling TODOs\n4. Copy structure, not content (write your own patterns!)\n\n**What makes a good example:**\n\n❌ **Too Generic:**\n```markdown\n### API Calls\nWe use axios for API calls.\n```\n\n✅ **Specific \u0026 Useful:**\n```markdown\n### API Calls\n```typescript\n// src/lib/api.ts - All API calls use this instance\nimport axios from 'axios';\n\nexport const api = axios.create({\n  baseURL: '/api',\n  timeout: 5000\n});\n\n// Usage in components\nconst tasks = await api.get('/tasks');\n```\n**Why:** Centralized config, consistent timeout, easy to mock in tests\n```\n\n**Based on user feedback:** \"Templates can feel overwhelming without seeing a completed example\" - this addresses the #1 priority from usability testing.\n\n---\n\n## 🧪 TDD Enforcement System\n\n**New in v0.3.1:** Multi-layered enforcement of Test-Driven Development to prevent \"implement first, test later\" violations.\n\n### The Problem\n\nEven with TDD documented in `CODEBASE_ESSENTIALS.md` as Critical Invariant #7, it's easy to forget and write implementation before tests (we did this ourselves and caught it!).\n\n### The Solution: 4 Layers of Enforcement\n\n#### Layer 1: Pre-Work Checklist (AGENTS.md)\n\nEvery AI session now starts with explicit TDD reminder:\n\n```markdown\n**Step 3: Check TDD Requirement**\n  - [ ] 🔴 RED: Write failing test FIRST\n  - [ ] 🟢 GREEN: Implement minimal code to pass\n  - [ ] 🔵 REFACTOR: Clean up while keeping tests green\n```\n\n#### Layer 2: TDD Self-Audit (AGENTS.md Step 3½)\n\nBefore validation, AI must self-audit:\n\n```markdown\nDid you follow RED-GREEN-REFACTOR?\n- [ ] Wrote test BEFORE implementation (RED)\n- [ ] Saw test fail first\n- [ ] Implemented minimal code (GREEN)\n- [ ] Refactored while keeping tests green\n\nIf NO to any: Document violation in CODEBASE_CHANGELOG.md\n```\n\n#### Layer 3: Git Hook (Local Enforcement)\n\nPre-commit hook checks for test changes:\n\n```bash\n# Install git hooks\n./scripts/install-git-hooks.sh\n\n# Now when you commit lib/ without test/ changes:\n⚠️  WARNING: Staging lib/ changes without test/ changes\n\nDid you follow TDD?\n  🔴 RED: Write failing test first\n  🟢 GREEN: Implement minimal code to pass\n  🔵 REFACTOR: Clean up while keeping tests green\n\nContinue with commit anyway? (y/N)\n```\n\n**See:** `.git-hooks/README.md` for hook documentation\n\n#### Layer 4: GitHub Actions (CI Enforcement)\n\nPR checks enforce TDD compliance:\n\n```yaml\n# .github/workflows/tdd-compliance.yml\n# Fails CI if lib/ changed without test/ changes\n```\n\n**See workflow:** [`.github/workflows/tdd-compliance.yml`](.github/workflows/tdd-compliance.yml)\n\n### Skills Integration\n\n**New skill:** `.github/skills/tdd-workflow/SKILL.md`\n\nComplete TDD guide with:\n- RED-GREEN-REFACTOR cycle explained\n- Step-by-step examples\n- Common pitfalls and solutions\n- Integration with project workflow\n\n**Trigger words:** \"implement\", \"add feature\", \"TDD\", \"test first\", \"red-green-refactor\"\n\n**Enhanced:** `.github/skills/feature-implementation/SKILL.md` now includes Phase 0: TDD Setup (mandatory before implementation)\n\n### Why This Matters\n\n**From our own experience:**\n\nWe violated our own TDD requirement during the automation enhancement session (v0.3.0). We implemented scan auto-detection features, THEN wrote tests. This backwards approach:\n\n❌ Lost design benefits of test-first thinking  \n❌ Tests became \"verification\" not \"design\"  \n✅ Still achieved test coverage (28/28 passing)  \n✅ Documented violation as lesson learned  \n\n**The lesson:** Even rule creators forget rules when moving fast. Having multiple enforcement layers prevents this.\n\n**Learn more:**\n- See [CODEBASE_CHANGELOG.md](CODEBASE_CHANGELOG.md) \"Automation Enhancements\" session\n- Read [.github/skills/tdd-workflow/SKILL.md](.github/skills/tdd-workflow/SKILL.md)\n- Review [.git-hooks/README.md](.git-hooks/README.md)\n\n\n\n## AI Tool Compatibility\n\n### ✅ Works with ANY AI Tool\n\nThese components work with **all AI assistants** (Claude Desktop, ChatGPT, Cursor, Gemini CLI, etc.):\n\n- **`CODEBASE_ESSENTIALS.md`** - Reference this file manually: `@CODEBASE_ESSENTIALS.md`\n- **`AGENTS.md`** - Copy/paste workflow instructions to any AI\n- **`CODEBASE_CHANGELOG.md`** - Historical context for any AI\n- **`.github/skills/`** - Read skills with: `@.github/skills/feature-implementation/SKILL.md`\n\nYou can use the core knowledge system with any AI tool by manually referencing these files.\n\n### 🎯 GitHub Copilot-Specific Features\n\nThese features **only work in VS Code with GitHub Copilot Chat**:\n\n- **Custom Agents** (`@Developer`, `@SeniorArchitect`) - Automatic agent triggering\n- **Auto-handoff workflow** - Developer → Architect review pipeline\n- **`.github/agents/`** directory - Auto-loaded by Copilot's Agent Skills feature\n\n**Without Copilot:** You can still follow the Developer → Architect workflow by manually copying prompts to your AI tool. The automation just won't be automatic.\n\n### 🔮 Roadmap: Multi-Tool Support\n\n**Planned for near future:**\n- **Claude Desktop MCP Server** - Native agent support for Claude Desktop\n- **Cursor integration** - Custom agent support\n- **Universal agent format** - Tool-agnostic agent definitions\n\nStay tuned for updates!\n\n---\n\n### Alternative: Manual Setup\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand manual setup instructions\u003c/summary\u003e\n\n#### For New Projects\n\n```bash\n# Clone the template\ngit clone https://github.com/YOUR_ORG/.git\ncd \n\n# Run interactive setup\n./scripts/setup.sh\n\n# Follow prompts to customize for your tech stack\n# Files will be generated with your configuration\n```\n\n#### For Existing Projects\n\n```bash\n# Clone into your project\ngit clone https://github.com/YOUR_ORG/.git temp-template\ncp -r temp-template/scripts ./\ncp -r temp-template/templates ./\n\n# Run migration workflow\n./scripts/migrate-existing.sh\n\n# Scanner will:\n# 1. Detect your tech stack automatically\n# 2. Generate draft CODEBASE_ESSENTIALS.md (70% complete)\n# 3. Install custom agents\n# 4. Set up universal skills\n# 5. Initialize changelog\n\n# Complete TODO sections in CODEBASE_ESSENTIALS.md\n# Start using: @Developer \u003cyour request\u003e\n```\n\n\u003c/details\u003e\n\n---\n\n## Core Components\n\n### 1. AI Knowledge System (.aiknowsys/)\n\n**Purpose:** Structured memory and continuous learning for AI assistants.\n\nWhen you run `init`, AIKnowSys creates a `.aiknowsys/` directory that enables AI assistants to maintain context across sessions and accumulate project-specific knowledge over time.\n\n**Directory Structure:**\n```\n.aiknowsys/\n├── sessions/        # 🚫 Gitignored - Temporary session working memory\n│   ├── README.md    # ✅ Committed - Explains purpose\n│   └── YYYY-MM-DD-session.md  # 🚫 Daily session notes (not committed)\n├── learned/         # ✅ Committed - Permanent project-specific patterns\n│   ├── README.md    # ✅ Committed - Explains pattern format\n│   └── *.md         # ✅ Committed - Discovered patterns\n└── PENDING_REVIEW.md # 🚫 Gitignored - Temporary architect reviews\n```\n\n#### Session Files (Temporary)\n\n**What they are:**\n- Working memory for a single AI conversation\n- Created/updated during complex multi-step work\n- Automatically loaded by AI agents at session start\n\n**Why gitignored:**\n- Session-specific context (like IDE workspace files)\n- Not useful to other developers or other AI sessions\n- Prevents git history clutter\n\n**Benefits:**\n- ✅ Context continuity across messages in same session\n- ✅ AI remembers what you worked on last time\n- ✅ Complex multi-step work doesn't lose progress\n\n#### Learned Patterns (Permanent)\n\n**What they are:**\n- Discovered patterns applicable to whole project\n- Reusable across all AI assistants and team members\n- Examples: Custom validation rules, debugging techniques, library-specific gotchas\n\n**Why committed:**\n- Valuable team knowledge\n- Helps onboard new developers\n- AI assistants get smarter with each session\n- Project knowledge accumulates over time\n\n**Benefits:**\n- ✅ Reduced repeated explanations\n- ✅ Team-wide pattern sharing\n- ✅ AI learns from mistakes and successes\n\n#### Review Files (Ephemeral)\n\n**What they are:**\n- Detailed code reviews created by Architect agent\n- Deleted after Developer addresses issues\n- Temporary handoff mechanism between agents\n\n**Example workflow:**\n1. Developer implements feature\n2. Architect writes review to `PENDING_REVIEW.md`\n3. Developer reads review and fixes issues\n4. Developer deletes `PENDING_REVIEW.md`\n\n#### Gitignore Configuration\n\nThe init command automatically adds:\n\n```gitignore\n# Session-specific AI memory (temporary, not committed)\n.aiknowsys/sessions/*.md\n!.aiknowsys/sessions/README.md\n.aiknowsys/PENDING_REVIEW.md\n# Note: .aiknowsys/learned/ IS committed (project-specific patterns)\n```\n\n**Validation:** Run `npx aiknowsys audit` to check if gitignore is configured correctly.\n\n### 2. CODEBASE_ESSENTIALS.md\n\n**Purpose:** Single-source reference for architecture, patterns, and critical invariants.\n\n**Contains:**\n- Technology stack snapshot\n- Validation commands (tests, type checking, linting)\n- Core patterns (how you do auth, API calls, state management)\n- Critical invariants (rules that must NEVER be violated)\n- Common gotchas (things that trip up new contributors)\n\n**See examples:**\n- [Python/Django API](examples/python-django/CODEBASE_ESSENTIALS.md) - Django REST Framework patterns\n- [TypeScript/Vue SPA](examples/typescript-vue/CODEBASE_ESSENTIALS.md) - Vue 3 Composition API patterns\n- [Rust/Actix Web API](examples/rust-actix/CODEBASE_ESSENTIALS.md) - Type-safe Rust patterns\n\n**Why it matters:** AI reads this at session start, ensuring all suggestions align with your architecture.\n\n### 2. Custom Agents (Planner → Developer → Architect)\n\n**Purpose:** Three-agent workflow with automated quality gates enforcing documented patterns.\n\n**Platform:** GitHub Copilot in VS Code (other AI tools: see [AI Tool Compatibility](#ai-tool-compatibility))\n\n**Workflow:**\n```\nUser → @Planner → Creates implementation plan → Writes to .aiknowsys/CURRENT_PLAN.md →\n  @Developer → Reads plan → Implements feature → Auto-handoff →\n    @SeniorArchitect → Reviews against ESSENTIALS → Writes to .aiknowsys/PENDING_REVIEW.md → ✅ Approve or 🔄 Refactor\n```\n\n**What Planner does:**\n- Breaks down complex features into actionable steps\n- Identifies architectural concerns and dependencies\n- Documents implementation plan in `.aiknowsys/CURRENT_PLAN.md`\n- Ensures proper sequencing and risk mitigation\n\n**What Developer does:**\n- Reads implementation plan from `.aiknowsys/CURRENT_PLAN.md`\n- Implements features following project patterns\n- Writes tests (TDD if enabled, coverage testing otherwise)\n- Validates all changes before handoff\n- Auto-calls Architect for code review\n\n**What Architect checks:**\n- KISS (Keep It Simple) - No unnecessary complexity\n- DRY (Don't Repeat Yourself) - Proper abstraction\n- SOLID - Single responsibility, dependency inversion\n- YAGNI (You Ain't Gonna Need It) - No speculative features\n- CODEBASE_ESSENTIALS.md compliance\n\n**Result:** Instant feedback loop (seconds vs hours), consistent enforcement.\n\n### 3. Skills System\n\n**Purpose:** Step-by-step workflows for common tasks.\n\n**Included universal skills:**\n- `dependency-updates` - Safe upgrade procedures\n- `documentation-management` - Changelog archiving, AI-friendly writing\n- `code-refactoring` - Test-driven refactoring patterns\n- `testing-best-practices` - Framework-agnostic testing guide\n- `skill-creator` - How to create new skills\n- `tdd-workflow` - Test-Driven Development (RED-GREEN-REFACTOR cycle)\n\n**Custom skills you can add:**\n- Feature implementation workflows\n- Deployment procedures\n- Database migration patterns\n- Security review checklists\n\n### 4. Validation Matrix\n\n**Purpose:** Ensure all changes pass tests before claiming completion.\n\n**Example:**\n```markdown\n| Changed | Commands | Required |\n|---------|----------|----------|\n| Backend | pytest | ✅ MANDATORY |\n| Frontend | npm run type-check | ✅ MANDATORY |\n| Frontend Logic | npm run test:run | ✅ MANDATORY |\n```\n\n**Rule:** Never say \"done\" until validation passes.\n\n### 5. Session Changelog\n\n**Purpose:** Historical context prevents repeating mistakes.\n\n**Entry format:**\n```markdown\n## Session: Logger Utility Implementation (Jan 18, 2026)\n\n**Goal**: Add structured logging with type safety\n\n**Changes**:\n- [src/utils/logger.ts](src/utils/logger.ts#L1-L50): Created logger\n- [tests/logger.test.ts](tests/logger.test.ts): Added 16 tests\n\n**Validation**:\n- ✅ All 456 tests passed\n- ✅ TypeScript: No errors\n\n**Key Learning**: Logger needs environment detection for test mocking\n```\n\n---\n\n## Production-Ready Examples\n\nThe template includes **7 comprehensive examples** showing real patterns across different ecosystems:\n\n### Backend Examples\n\n#### Python/Django REST API\n\n**Stack:** Django 4.2 + DRF + PostgreSQL + pytest + Docker\n\n**Key patterns:**\n- ViewSet + Serializer + Router (DRF)\n- factory-boy for test data generation\n- TimestampedModel abstract base class\n- SQLAlchemy migrations\n- Environment configuration with django-environ\n\n**What you'll learn:**\n- How to structure Django REST API patterns\n- Comprehensive pytest testing with factories\n- N+1 query prevention with `select_related`\n- Production deployment checklist\n\n[→ View Django Example](examples/python-django/CODEBASE_ESSENTIALS.md)\n\n#### Python/FastAPI\n\n**Stack:** FastAPI 0.108 + SQLAlchemy 2.0 + Pydantic + Alembic + PostgreSQL\n\n**Key patterns:**\n- Router + Pydantic schemas + dependency injection\n- Async SQLAlchemy with asyncpg\n- JWT authentication with python-jose\n- Alembic migrations\n- pytest-asyncio testing\n\n**What you'll learn:**\n- FastAPI async/await patterns\n- Type-safe async database access\n- Pydantic validation + OpenAPI docs\n- Common gotchas (mixing sync/async, N+1 queries)\n\n[→ View FastAPI Example](examples/python-fastapi/CODEBASE_ESSENTIALS.md)\n\n#### Node.js/Express + TypeScript\n\n**Stack:** Express 4.18 + TypeScript + Prisma + PostgreSQL + Jest\n\n**Key patterns:**\n- Router + Controller + Service layer\n- Zod validation + custom error handling\n- JWT authentication with passport\n- Prisma ORM with migrations\n- Supertest for API testing\n\n**What you'll learn:**\n- Express TypeScript setup\n- Service layer separation\n- Type-safe middleware\n- Common gotchas (async errors, integer parsing)\n\n[→ View Express Example](examples/nodejs-express/CODEBASE_ESSENTIALS.md)\n\n#### Rust/Actix Web API\n\n**Stack:** Actix Web 4.4 + SQLx + PostgreSQL + Tokio + Serde\n\n**Key patterns:**\n- Handler + Extractor + Responder\n- Custom error types with ResponseError trait\n- SQLx compile-time query verification\n- Integration tests with test database\n- Async error handling with Result types\n\n**What you'll learn:**\n- Type-safe Rust web API development\n- Database migrations with SQLx CLI\n- Production optimization (LTO, code-gen-units)\n- Common gotchas (lifetime errors, async runtime conflicts)\n\n[→ View Rust Example](examples/rust-actix/CODEBASE_ESSENTIALS.md)\n\n### Frontend Examples\n\n#### TypeScript/React + Vite\n\n**Stack:** React 18.2 + TypeScript + Vite + Zustand + TanStack Query + Tailwind\n\n**Key patterns:**\n- Functional components + hooks + custom hooks\n- Zustand for client state, TanStack Query for server state\n- React Hook Form + Zod validation\n- Testing Library + user-event\n- Type-safe routing with React Router\n\n**What you'll learn:**\n- Modern React patterns (hooks, composition)\n- State management (Zustand vs Redux)\n- Form handling best practices\n- Common gotchas (infinite re-renders, missing dependencies)\n\n[→ View React Example](examples/typescript-react/CODEBASE_ESSENTIALS.md)\n\n#### TypeScript/Vue SPA\n\n**Stack:** Vue 3 Composition API + TypeScript + Pinia + Vite + Vitest + Tailwind\n\n**Key patterns:**\n- Script setup + typed props + composables\n- Pinia stores for state management\n- Typed API client integration\n- Router guards for authentication\n- Component testing with @vue/test-utils\n\n**What you'll learn:**\n- Modern Vue 3 Composition API patterns\n- Full TypeScript type safety\n- Common gotchas (reactive destructuring, Vitest hanging)\n- Why Pinia over Vuex, Vite over Webpack\n\n[→ View Vue Example](examples/typescript-vue/CODEBASE_ESSENTIALS.md)\n\n### Fullstack Examples\n\n#### TypeScript/Next.js 14\n\n**Stack:** Next.js 14 App Router + TypeScript + Prisma + NextAuth.js + PostgreSQL\n\n**Key patterns:**\n- Server Components (default) + Client Components (opt-in)\n- Server Actions for mutations (no API routes)\n- Prisma ORM with type-safe queries\n- NextAuth.js OAuth + sessions\n- E2E testing with Playwright\n\n**What you'll learn:**\n- Next.js App Router paradigm (Server vs Client)\n- Server Actions for type-safe mutations\n- Prisma schema + migrations\n- Common gotchas (hydration mismatch, missing revalidation)\n\n[→ View Next.js Example](examples/typescript-nextjs/CODEBASE_ESSENTIALS.md)\n\n[→ View Rust Example](examples/rust-actix/CODEBASE_ESSENTIALS.md)\n\n---\n\n## How It Works\n\n### The Workflow (Read → Plan → Implement → Validate → Document)\n\n#### 1. START: Read Context\n```\nAt session start, AI reads:\n- CODEBASE_ESSENTIALS.md (patterns)\n- Relevant skill for the task\n- Recent changelog (history)\n```\n\n#### 2. PLAN: Check Skills\n```\nTrigger words map to skills:\n\"refactor\" → code-refactoring skill\n\"update dependencies\" → dependency-updates skill\n\"add feature\" → feature-implementation skill\n```\n\n#### 3. IMPLEMENT: Code + Tests\n```\nFollow documented patterns\nWrite tests alongside code\nUse project conventions\n```\n\n#### 4. VALIDATE: Run Tests\n```\nRun validation matrix commands\nAll tests must pass\nNo errors allowed\n```\n\n#### 5. DOCUMENT: Update Changelog\n```\nAdd session entry\nUpdate ESSENTIALS if patterns changed\nLink to specific lines\n```\n\n#### 6. CONFIRM: Only End After Validation\n```\nReport what was built/fixed\nReport test results\nConfirm docs updated\n```\n\n---\n\n## Installation Options\n\n### Option 1: Interactive Setup (New Projects)\n\n```bash\n./scripts/setup.sh\n```\n\n**Prompts for:**\n- Primary language (TypeScript/Python/Rust/Go)\n- Framework (Vue/React/Django/FastAPI/etc)\n- Testing tools (Vitest/Jest/pytest/cargo test)\n- Package manager (npm/pip/cargo/go mod)\n\n**Generates:**\n- CODEBASE_ESSENTIALS.md with validation commands\n- AGENTS.md with workflow instructions\n- Custom agents configured for your stack\n- Universal skills installed\n\n### Option 2: Codebase Scanner (Existing Projects)\n\n```bash\n./scripts/migrate-existing.sh\n```\n\n**Automatically detects:**\n- Tech stack from package files\n- Test commands from package.json/Makefile/CI\n- Project structure\n- Key dependencies\n\n**Generates:**\n- Draft CODEBASE_ESSENTIALS.md (70% complete)\n- TODO sections for manual patterns\n- Validation matrix\n- Changelog initialized\n\n**Time saved:** ~3-4 hours of manual documentation\n\n### Option 3: Manual Setup\n\n```bash\n# Copy templates\ncp templates/CODEBASE_ESSENTIALS.template.md CODEBASE_ESSENTIALS.md\ncp templates/AGENTS.template.md AGENTS.md\ncp -r templates/agents/ .github/agents/\n\n# Customize for your project\n# Fill in {{PLACEHOLDERS}}\n# Add your patterns and conventions\n```\n\n---\n\n## Examples\n\n### Example Projects\n\nIncluded in `examples/` directory:\n\n- **python-django/** - Backend API with PostgreSQL\n- **typescript-react/** - Frontend SPA with Vite\n- **rust-actix/** - Systems programming example\n\nEach example shows:\n- Completed CODEBASE_ESSENTIALS.md\n- Custom skills for that stack\n- Validation commands\n- Real patterns from production code\n\n---\n\n## Customization Guide\n\n### Adapting for Your Stack\n\n**1. Update Validation Commands**\n\nEdit CODEBASE_ESSENTIALS.md:\n```markdown\n**Validation Commands:**\n```bash\n# Your test framework\ncargo test                    # Rust\ngo test ./...                 # Go\nmvn test                      # Java/Maven\nbundle exec rspec             # Ruby/RSpec\n```\n```\n\n**2. Customize Agent Review Criteria**\n\nEdit `.github/agents/architect.agent.md`:\n```markdown\n### Project-Specific Rules:\n- All database queries must use ORM\n- API responses must match OpenAPI schema\n- Components must be accessible (WCAG AA)\n- Errors must use structured logging\n```\n\n**3. Create Custom Skills**\n\nUse skill-creator skill:\n```bash\n@Developer create a skill for our deployment workflow\n```\n\nOr manually:\n```bash\ncp .github/skills/_skill-template .github/skills/my-workflow\n# Edit SKILL.md with your steps\n```\n\n**4. Add Your Patterns**\n\nUpdate CODEBASE_ESSENTIALS.md:\n```markdown\n## Authentication Pattern\n\n**Always use:** JWT tokens in HttpOnly cookies\n\n**Example:**\n```typescript\n// ✅ Correct\nconst token = req.cookies.access_token\n\n// ❌ Wrong\nconst token = req.headers.authorization\n```\n```\n\n---\n\n## OpenSpec Integration (Recommended)\n\n**For teams and major features, we recommend using OpenSpec for spec-driven development.**\n\n### What is OpenSpec?\n\nOpenSpec is a specification-driven development tool that helps manage:\n- Breaking changes and API contracts\n- Architecture decisions with proposals\n- Feature planning with structured tasks\n- Change tracking and archiving\n\n### How it integrates with Knowledge System\n\n1. **During `init`:** You'll be asked if you want to use OpenSpec - if yes, it's **automatically installed**\n2. **During `scan`:** OpenSpec directories are automatically detected\n3. **In templates:** CODEBASE_ESSENTIALS.md includes an OpenSpec section\n4. **In skills:** The feature-implementation skill covers OpenSpec workflows\n\n### When to use OpenSpec proposals\n\n| Change Type | Create Proposal? |\n|-------------|------------------|\n| New features or capabilities | ✅ Yes |\n| Breaking changes (API, schema) | ✅ Yes |\n| Architecture changes | ✅ Yes |\n| Bug fixes, typos, formatting | ❌ No |\n| Non-breaking dependency updates | ❌ No |\n\n### Quick Start with OpenSpec\n\n```bash\n# Install OpenSpec CLI\nnpm install -g openspec\n\n# Initialize in your project\nopenspec init\n\n# Create a proposal for a new feature\nopenspec create add-user-profiles\n\n# Validate before implementing\nopenspec validate add-user-profiles --strict\n\n# After deployment, archive the change\nopenspec archive add-user-profiles --yes\n```\n\n**Learn more:** [OpenSpec Documentation](https://github.com/your-org/openspec)\n\n---\n\n## Philosophy\n\n### Why This Approach Works\n\n**1. Single Source of Truth**\n- CODEBASE_ESSENTIALS.md prevents pattern drift\n- One place to update when patterns change\n- AI and humans read the same reference\n\n**2. Automated Enforcement**\n- Custom agents enforce patterns automatically\n- Instant feedback loop\n- Consistent standards across all changes\n\n**3. Knowledge Preservation**\n- Changelog captures what changed and why\n- Patterns documented as they're discovered\n- Historical context prevents repeating mistakes\n\n**4. Gradual Adoption**\n- Start with scanner-generated draft\n- Add patterns as you discover them\n- System grows with your project\n\n**5. Framework-Agnostic**\n- Core workflow works for any stack\n- Template variables adapt to your tools\n- Universal skills apply everywhere\n\n---\n\n## FAQ\n\n**Q: Does this replace human code review?**  \nA: No, it complements it. Agents handle mechanical checks (style, patterns, DRY), freeing humans to focus on architecture and business logic.\n\n**Q: Will this slow down development?**  \nA: Initially adds ~10 minutes per feature for documentation. Saves hours debugging pattern inconsistencies later. Net positive after first week.\n\n**Q: What if my project uses multiple languages?**  \nA: Create separate validation commands per language. Example: `pytest` for Python backend, `npm test` for TypeScript frontend.\n\n**Q: Can I use this without AI assistants?**  \nA: Yes! The documentation and workflow benefit human developers too. Think of it as \"docs that AI can also read.\"\n\n**Q: Does this only work with GitHub Copilot?**  \nA: No! Core knowledge files (CODEBASE_ESSENTIALS.md, skills) work with any AI tool. The custom agents (`@Developer`, `@SeniorArchitect`) require GitHub Copilot in VS Code, but you can manually follow the same workflow with Claude Desktop, ChatGPT, Cursor, or any AI assistant. See [AI Tool Compatibility](#ai-tool-compatibility) for details.\n\n**Q: How do I update the system as my project evolves?**  \nA: Update CODEBASE_ESSENTIALS.md when patterns change. Agents automatically enforce the updated patterns. Add changelog entry documenting the evolution.\n\n**Q: What if validation fails?**  \nA: Don't merge! Fix the issues, re-run validation, update changelog with what broke and how you fixed it. This prevents regressions.\n\n---\n\n## Contributing\n\nWe welcome contributions!\n\n**Areas for improvement:**\n- Additional language support (Java, C#, PHP, etc.)\n- Framework-specific examples\n- CI/CD integration guides\n- VS Code extension for scaffolding\n- Skill marketplace/discovery\n\n**To contribute:**\n1. Fork the repository\n2. Create feature branch\n3. Follow the knowledge system workflow (dogfooding!)\n4. Submit PR with changelog entry\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n**TL;DR:** Free to use, modify, distribute. Attribution appreciated but not required.\n\n---\n\n## Credits\n\nOriginally developed for [gnwebsite](https://github.com/arpa73/gnwebsite), a fullstack Django/Vue project.\n\n**Lessons learned from:**\n- 20+ AI-assisted development sessions\n- 450+ tests written using the system\n- Multiple refactorings without regressions\n- Production deployment validation\n\n**Built with:**\n- Markdown for maximum portability\n- Bash scripts for zero dependencies\n- Templates for easy customization\n- Real production patterns\n\n---\n\n## Support\n\n**Documentation:**\n- [Customization Guide](docs/customization-guide.md) - Adapt for your tech stack\n- [Migration Guide](docs/migration-guide.md) - Add to existing projects\n- [Philosophy](docs/philosophy.md) - Why this approach works\n\n**Examples:**\n- [Python/Django](examples/python-django/) - REST API patterns\n- [TypeScript/Vue](examples/typescript-vue/) - SPA patterns\n- [Rust/Actix](examples/rust-actix/) - Type-safe web API patterns\n\n**Questions?**\n- Open an issue\n- Check examples/ directory for your stack\n- Read docs/philosophy.md for design rationale\n\n---\n\n**Start building better code with AI assistants that actually understand your codebase.** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farpa73%2Faiknowsys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farpa73%2Faiknowsys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farpa73%2Faiknowsys/lists"}