@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/knowledge-overview/04-getting-started.md

@@ -0,0 +1,394 @@
+# Agent Assistant — Getting Started
+
+> **Purpose**: Step-by-step installation, environment setup, first run commands, testing, and troubleshooting
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum Version | Check Command | Notes |
+|------------|----------------|---------------|-------|
+| Node.js | 18.0.0 | `node --version` | Required for CLI installer and test runner |
+| npm | 9.0.0+ (bundled) | `npm --version` | Comes with Node.js 18+ |
+| Git | Any recent | `git --version` | Required for source installation and contributing |
+| AI Coding Tool | Latest | See table below | At least one supported tool must be installed |
+
+### Supported AI Tools
+
+| Tool | How to Get It |
+|------|--------------|
+| Cursor | Download from https://cursor.sh |
+| VS Code + GitHub Copilot | Install VS Code, then the GitHub Copilot extension |
+| Claude Code | Install via `npm install -g @anthropic-ai/claude-code` |
+| Codex | Install via OpenAI's Codex CLI |
+| Antigravity/Gemini | Install from Google's Antigravity editor |
+
+---
+
+## Installation
+
+### Option A: Global npm Package (Recommended)
+
+This is the simplest method. Install once, use across all projects.
+
+```bash
+# Step 1: Install the package globally
+npm install -g @namch/agent-assistant@latest
+
+# Step 2: Verify installation
+agent-assistant list
+
+# Step 3: Install for your AI tool(s)
+agent-assistant install cursor        # Cursor only
+agent-assistant install claude        # Claude Code only
+agent-assistant install copilot       # GitHub Copilot only
+agent-assistant install antigravity   # Antigravity/Gemini only
+agent-assistant install codex         # Codex only
+agent-assistant install --all         # All tools at once
+```
+
+### Option B: From Source
+
+Use this if you want to contribute, inspect the source, or run from a local checkout.
+
+```bash
+# Step 1: Clone the repository
+git clone https://github.com/hainamchung/agent-assistant.git
+
+# Step 2: Navigate into the project
+cd agent-assistant
+
+# Step 3: Install for your AI tool(s)
+node cli/install.js install cursor        # Cursor only
+node cli/install.js install claude        # Claude Code only
+node cli/install.js install copilot       # GitHub Copilot only
+node cli/install.js install antigravity   # Antigravity/Gemini only
+node cli/install.js install codex         # Codex only
+node cli/install.js install --all         # All tools at once
+```
+
+### What the Installer Does
+
+The CLI installer copies framework files into the AI tool's global configuration directory:
+
+| Tool | Target Directory |
+|------|-----------------|
+| Cursor | `~/.cursor/skills/agent-assistant/` |
+| GitHub Copilot | `~/.copilot/skills/agent-assistant/` |
+| Claude Code | `~/.claude/skills/agent-assistant/` |
+| Codex | `~/.codex/skills/agent-assistant/` |
+| Antigravity/Gemini | `~/.gemini/antigravity/skills/agent-assistant/` |
+
+Files installed include: 21 agent definitions, 14 command workflows with variants, 7 rule files, 19 matrix-skill registries, 1,430+ skill modules, and platform-specific entry point files.
+
+---
+
+## Verifying the Installation
+
+After installation, confirm files are in place:
+
+```bash
+# For Cursor:
+ls ~/.cursor/skills/agent-assistant/
+# Expected: agents/ commands/ rules/ matrix-skills/ skills/ documents/ ...
+
+# For Claude Code:
+ls ~/.claude/skills/agent-assistant/
+# Expected: same structure
+
+# For GitHub Copilot:
+ls ~/.copilot/skills/agent-assistant/
+# Expected: same structure
+
+# List all installed tools:
+agent-assistant list
+# Output shows which tools have Agent Assistant installed
+```
+
+---
+
+## First Run — Using Commands
+
+Open any project in your AI coding tool and try these commands in the AI chat:
+
+### Simple Feature (`:fast` variant)
+
+```
+/cook:fast "add a health check endpoint that returns { status: 'ok' }"
+```
+
+This spawns 2–3 agents (typically backend-engineer + tester) for a quick implementation.
+
+### Bug Fix
+
+```
+/fix "login form doesn't validate email format"
+```
+
+The Orchestrator delegates to the debugger and backend/frontend engineer to diagnose and fix.
+
+### Implementation Plan
+
+```
+/plan "build a notification system with email and push support"
+```
+
+The planner agent produces a structured implementation plan with phases, dependencies, and effort estimates.
+
+### Code Review
+
+```
+/review "audit the authentication module for security issues"
+```
+
+The reviewer and security-engineer agents analyze the code and produce findings.
+
+### Generate Project Documentation
+
+```
+/docs:core
+```
+
+Creates `./documents/` with technical knowledge files that agents reference for project-specific context. Run this first in any new project for best results.
+
+### Complex Feature (`:hard` variant)
+
+```
+/cook:hard "implement OAuth 2.0 with Google and GitHub providers"
+```
+
+This spawns 5–8 agents with full quality gates: implementation, testing, review, and security checks.
+
+---
+
+## Running Tests
+
+The project uses Node.js native test runner:
+
+```bash
+# Run all tests (from project root)
+npm test
+# Equivalent to: node --test cli/*.test.js
+
+# Lint JavaScript for syntax errors
+npm run lint
+# Equivalent to: node --check cli/install.js
+
+# Lint Markdown (requires npx)
+npm run lint:md
+# Prints the command to run manually: npx markdownlint "**/*.md" --ignore node_modules
+```
+
+Note: The test file `cli/install.test.js.example` is provided as an example template. Rename it to `cli/install.test.js` to activate it:
+
+```bash
+cp cli/install.test.js.example cli/install.test.js
+npm test
+```
+
+---
+
+## Uninstalling
+
+### Remove from AI Tools
+
+```bash
+# Remove from a specific tool:
+agent-assistant uninstall cursor
+agent-assistant uninstall claude
+agent-assistant uninstall copilot
+agent-assistant uninstall antigravity
+agent-assistant uninstall codex
+
+# Remove from all tools at once:
+agent-assistant uninstall --all
+```
+
+### Remove from Source
+
+```bash
+cd agent-assistant
+node cli/install.js uninstall --all
+cd ..
+rm -rf agent-assistant
+```
+
+### Remove Global Package
+
+```bash
+npm uninstall -g @namch/agent-assistant
+```
+
+---
+
+## Environment Setup for Contributors
+
+If you want to contribute to Agent Assistant:
+
+```bash
+# Step 1: Fork the repo on GitHub, then clone your fork
+git clone https://github.com/YOUR_USERNAME/agent-assistant.git
+cd agent-assistant
+
+# Step 2: Install devDependencies (for commit hooks and release tooling)
+npm install
+
+# Step 3: Husky git hooks are set up automatically via the prepare script
+# Verify hooks are installed:
+ls .husky/
+
+# Step 4: Make changes on a feature branch
+git checkout -b feat/my-new-feature
+
+# Step 5: Commit using Conventional Commits format
+git commit -m "feat: add new skill for kubernetes debugging"
+# Or: git commit -m "fix: correct path resolution on Windows"
+# Or: git commit -m "docs: update getting started guide"
+
+# Step 6: Push and create a PR
+git push origin feat/my-new-feature
+```
+
+### Commit Message Format
+
+The project uses Conventional Commits enforced by Husky hooks:
+
+| Prefix | Purpose | Version Bump |
+|--------|---------|-------------|
+| `feat:` | New feature | Minor (1.x.0) |
+| `fix:` | Bug fix | Patch (1.0.x) |
+| `docs:` | Documentation | No release |
+| `chore:` | Maintenance | No release |
+| `refactor:` | Code restructuring | No release |
+| `perf:` | Performance | Patch |
+| `test:` | Tests | No release |
+
+---
+
+## npm Scripts Reference
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `install:cursor` | `node cli/install.js install cursor` | Install for Cursor |
+| `install:copilot` | `node cli/install.js install copilot` | Install for GitHub Copilot |
+| `install:antigravity` | `node cli/install.js install antigravity` | Install for Antigravity/Gemini |
+| `install:codex` | `node cli/install.js install codex` | Install for Codex |
+| `install:all` | `node cli/install.js install --all` | Install for all tools |
+| `uninstall:cursor` | `node cli/install.js uninstall cursor` | Uninstall from Cursor |
+| `uninstall:copilot` | `node cli/install.js uninstall copilot` | Uninstall from GitHub Copilot |
+| `uninstall:antigravity` | `node cli/install.js uninstall antigravity` | Uninstall from Antigravity/Gemini |
+| `uninstall:codex` | `node cli/install.js uninstall codex` | Uninstall from Codex |
+| `uninstall:all` | `node cli/install.js uninstall --all` | Uninstall from all tools |
+| `list` | `node cli/install.js list` | Show installed tools |
+| `test` | `node --test cli/*.test.js` | Run test suite |
+| `lint` | `node --check cli/install.js` | Syntax validation |
+| `lint:md` | Echo markdownlint command | Markdown linting (manual) |
+| `semantic-release` | `semantic-release` | Automated release (CI only) |
+| `prepare` | `husky install` | Set up git hooks |
+
+---
+
+## Common Issues and Troubleshooting
+
+### "command not found: agent-assistant"
+
+**Cause**: Global npm bin directory is not in your PATH.
+
+```bash
+# Find where npm installs global binaries:
+npm config get prefix
+
+# Add to PATH (add to ~/.zshrc or ~/.bashrc):
+export PATH="$(npm config get prefix)/bin:$PATH"
+
+# Reload shell:
+source ~/.zshrc
+```
+
+### "Error: Node.js version too old"
+
+**Cause**: Agent Assistant requires Node.js >=18.0.0.
+
+```bash
+# Check current version:
+node --version
+
+# Update via nvm:
+nvm install 18
+nvm use 18
+
+# Or via Homebrew (macOS):
+brew install node@18
+```
+
+### "Permission denied" during install
+
+**Cause**: npm global directory requires elevated permissions.
+
+```bash
+# Option A: Fix npm permissions (recommended)
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+source ~/.zshrc
+npm install -g @namch/agent-assistant@latest
+
+# Option B: Use npx (no global install)
+npx @namch/agent-assistant install --all
+```
+
+### "Files not appearing in AI tool"
+
+**Cause**: The AI tool may need to be restarted to pick up new global configuration files.
+
+```bash
+# Verify files exist:
+ls ~/.cursor/skills/agent-assistant/    # For Cursor
+ls ~/.claude/skills/agent-assistant/    # For Claude Code
+ls ~/.copilot/skills/agent-assistant/   # For Copilot
+
+# If files exist but tool doesn't see them:
+# 1. Close and reopen the AI tool completely
+# 2. For VS Code/Copilot: reload window (Cmd+Shift+P → "Reload Window")
+```
+
+### "Commands not recognized by AI tool"
+
+**Cause**: The platform entry file may not have loaded. Agent Assistant commands (like `/cook`, `/plan`) are interpreted by the AI model via the installed Markdown files, not by the tool's CLI.
+
+```bash
+# Verify the entry point file exists:
+ls ~/.cursor/rules/          # Should contain Agent Assistant rules for Cursor
+ls ~/.claude/CLAUDE.md       # Entry point for Claude Code
+ls ~/.copilot/               # Entry point for Copilot
+
+# If missing, re-run install:
+agent-assistant install cursor   # or your tool
+```
+
+### "Test file not found"
+
+**Cause**: The test file is shipped as an example, not an active test.
+
+```bash
+# Activate the example test:
+cp cli/install.test.js.example cli/install.test.js
+
+# Run tests:
+npm test
+```
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Package manifest (scripts, engines, bin) | [../../package.json](../../package.json) |
+| README (installation, uninstallation) | [../../README.md](../../README.md) |
+| CLI installer (platform configs, paths) | [../../cli/install.js](../../cli/install.js) |
+| Test example | [../../cli/install.test.js.example](../../cli/install.test.js.example) |
+| Core rules (command routing) | [../../rules/CORE.md](../../rules/CORE.md) |

package/documents/knowledge-source-base/00-index.md

@@ -0,0 +1,107 @@
+# Knowledge Source Base
+
+> **Purpose**: Comprehensive technical knowledge base for the @namch/agent-assistant project — a multi-agent orchestration framework for AI coding assistants
+> **Sub-files**: 4
+> **Last Updated**: 2026-03-26
+
+---
+
+## Quick Summary
+
+Agent Assistant is a plugin-based orchestration framework (v1.3.0) that installs Markdown and YAML configuration files into AI coding tool directories (Cursor, GitHub Copilot, Antigravity/Gemini, Claude Code, and Codex). The framework implements a Hybrid Skill Orchestration Layer (HSOL) that dynamically resolves and injects skills from a matrix of 1,430 skill definitions across 19 domains. It operates as a pure CLI tool built on Node.js >=18.0.0 using only built-in modules (fs, path, os, readline) with zero production dependencies.
+
+The core architecture centers on an Orchestrator pattern: an AI coding assistant reads the platform entry point file (CURSOR.md, COPILOT.md, CLAUDE.md, CODEX.md, or GEMINI.md), which bootstraps it into the Orchestrator role. The Orchestrator then delegates work to 21 specialist agents (plus 51 team agents across 17 teams) using 14 command workflows with 47 variant strategies. Skills are resolved through the matrix-skills YAML registry and optionally enhanced by dynamic discovery via the find-skills mechanism.
+
+The project also includes a separate React 19 + Vite + Tailwind marketing website under the `web/` directory, deployed to Vercel, and uses semantic-release with conventional commits for automated versioning and npm publishing.
+
+---
+
+## Table of Contents
+
+1. [Quick Summary](#quick-summary)
+2. [Sub-Files](#sub-files)
+3. [Quick Facts](#quick-facts)
+4. [Cross-References](#cross-references)
+5. [Known Gaps and Open Questions](#known-gaps-and-open-questions)
+
+---
+
+## Sub-Files
+
+| File | Description |
+|------|-------------|
+| [01-directory-structure.md](./01-directory-structure.md) | Complete annotated directory tree (depth 3-4) with purpose of every top-level directory |
+| [02-entry-points.md](./02-entry-points.md) | Application entry files, CLI boot sequence, build entry points, and config entry points |
+| [03-key-modules.md](./03-key-modules.md) | Per-module breakdown: purpose, exports, dependencies, and internal structure for all major modules |
+| [04-configuration.md](./04-configuration.md) | Configuration files inventory, environment variables, secrets management, and platform-specific configs |
+
+---
+
+## Quick Facts
+
+| Key | Value |
+|-----|-------|
+| Package Name | `@namch/agent-assistant` |
+| Version | 1.3.0 |
+| License | MIT |
+| Author | NamCH |
+| Runtime | Node.js >=18.0.0 |
+| Module System | CommonJS (CLI), ESM (web) |
+| Production Dependencies | 0 (zero) |
+| Dev Dependencies | 10 (semantic-release ecosystem + husky) |
+| CLI Entry Point | `cli/install.js` |
+| Supported Platforms | Cursor, GitHub Copilot, Antigravity (Gemini), Claude Code, Codex |
+| Solo Agents | 21 Markdown files |
+| Team Directories | 17 teams × 3 roles (executor, reviewer, techlead) = 51 team agents |
+| Total Agent Files | 72 |
+| Commands | 14 router files + 47 variant files = 61 total |
+| Matrix Skill Domains | 19 YAML registries + _index.yaml + _dynamic.yaml |
+| Total Skills | 1,430 skill folders (each containing SKILL.md) |
+| Rule Files | 7 (CORE, PHASES, AGENTS, SKILLS, TEAMS, ERRORS, REFERENCE) |
+| Code Assistant Templates | 5 (cursor, copilot, antigravity, claude, codex) |
+| Web Framework | React 19 + Vite + Tailwind CSS 4 |
+| Web Deployment | Vercel |
+| Release Automation | semantic-release with conventional commits |
+| Branch Strategy | `main` (single release branch) |
+
+---
+
+## Read Order for New Members
+
+1. **Start here** — Read this index to understand scope and structure
+2. **[01-directory-structure.md](./01-directory-structure.md)** — Get oriented with where everything lives
+3. **[02-entry-points.md](./02-entry-points.md)** — Understand how the system boots and what runs
+4. **[03-key-modules.md](./03-key-modules.md)** — Deep dive into each module's internals
+5. **[04-configuration.md](./04-configuration.md)** — Learn the configuration landscape
+6. **`rules/CORE.md`** — Read the Orchestrator protocol (the "operating system" for agents)
+7. **`AGENT-TEMPLATE.md`** — Understand how agents are structured with Matrix Skill Discovery
+8. **`matrix-skills/_index.yaml`** — See how HSOL skill resolution works
+
+---
+
+## Cross-References
+
+- **HSOL Architecture**: `documents/SMART-SKILL-ORCHESTRATION-BLUEPRINT.md` — Full design document for the Hybrid Skill Orchestration Layer
+- **HSOL Assessment**: `documents/HSOL-ASSESSMENT.md` — Evaluation and analysis of the HSOL system
+- **CLI Documentation**: `cli/README.md` — CLI-specific usage guide and examples
+- **Orchestrator Rules**: `rules/CORE.md` — The core protocol that governs how the Orchestrator operates
+- **Phase Execution**: `rules/PHASES.md` — How command phases are structured and executed
+- **Agent Definitions**: `rules/AGENTS.md` — Tiered execution model (sub-agent vs. embodiment)
+- **Skill Resolution**: `rules/SKILLS.md` — How skills are discovered and injected
+- **Team Protocol**: `rules/TEAMS.md` — How multi-agent teams coordinate
+- **Error Recovery**: `rules/ERRORS.md` — Error handling and recovery procedures
+- **Agent Template**: `AGENT-TEMPLATE.md` — Standard structure for all agent files with Matrix Skill Discovery frontmatter
+- **Changelog**: `CHANGELOG.md` — Version history and release notes
+- **Web Site README**: `web/README.md` — Marketing site documentation
+
+---
+
+## Known Gaps and Open Questions
+
+1. **No automated test suite**: `cli/install.test.js.example` exists as an example but no actual test file is committed; the `npm test` script (`node --test cli/*.test.js`) would find no tests to run unless the example is renamed
+2. **Web app environment variables**: The Vercel-hosted marketing site may use environment variables, but none are documented in the repository (`.env` is gitignored)
+3. **Skill SKILL.md format specification**: While `AGENT-TEMPLATE.md` documents the agent file format, there is no equivalent template for skill SKILL.md files
+4. **Dynamic skill manifest**: `matrix-skills/_dynamic.yaml` exists for community-installed skills but its exact schema and lifecycle are defined only in the `_index.yaml` header comments
+5. **Platform-specific differences**: Each code-assistant template (cursor, copilot, etc.) handles installation slightly differently with unique assets and path structures, but there is no unified comparison document
+6. **Husky hooks**: The `.husky/` directory contains only a `_/` subfolder; the actual git hook scripts are not visible in the directory listing, suggesting they may be generated or missing
+7. **Web app deployment pipeline**: `web/vercel.json` exists with rewrite rules, but the CI/CD pipeline for the web app (separate from the CLI semantic-release) is not documented in the repository