From 19186dd31b864a19e5224fab26d1592da8eb630a Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sun, 25 Jan 2026 17:13:54 +0100 Subject: [PATCH 01/18] Release cli 0.7.0 --- CHANGELOG.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 57ffc253..9272bc18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,14 +5,14 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.7.0] - 2026-01-25 ### Added - **Skill Management** - Centralized registry for managing Agent Skills across projects - - 🎯 **One-Command Installation**: `ai-devkit skill add / ` - - πŸ’Ύ **Local Cache**: Skills stored in `~/.ai-devkit/skills/` to avoid duplication - - πŸ”— **Symlink-First Strategy**: Symlinks with automatic copy fallback for Windows - - 🎨 **Multi-Environment Support**: Works with Cursor, Claude Code, Codex, OpenCode, and Antigravity + - **One-Command Installation**: `ai-devkit skill add / ` + - **Local Cache**: Skills stored in `~/.ai-devkit/skills/` to avoid duplication + - **Symlink-First Strategy**: Symlinks with automatic copy fallback for Windows + - **Multi-Environment Support**: Works with Cursor, Claude Code, Codex, OpenCode, and Antigravity - **CLI Commands**: - `ai-devkit skill add / ` - Install a skill from registry - `ai-devkit skill list` - List all installed skills with sources @@ -23,7 +23,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Environment filtering (only shows/uses environments with skill support) - Git repository caching for efficient reuse across projects - Validation for registry IDs and skill names (follows Agent Skills spec) - - **Test Coverage**: 67 new unit tests (187 total tests passing) ## [0.6.0] - 2026-01-22 From 04abb2eb9c6925884320f32cf06f7a32117d1977 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sun, 25 Jan 2026 17:25:57 +0100 Subject: [PATCH 02/18] Fix lint --- packages/cli/src/lib/SkillManager.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/cli/src/lib/SkillManager.ts b/packages/cli/src/lib/SkillManager.ts index 419b30c0..8690a6f1 100644 --- a/packages/cli/src/lib/SkillManager.ts +++ b/packages/cli/src/lib/SkillManager.ts @@ -161,6 +161,7 @@ export class SkillManager { registry = `${parts[0]}/${parts[1]}`; } } catch { + // Ignore errors } skills.push({ From 1f8ecce350d9efb82d6d0be68dbdf8a757373373 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sun, 25 Jan 2026 17:26:55 +0100 Subject: [PATCH 03/18] Update README to remove project title Removed project title and link from README. --- packages/cli/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index c2010ded..a6423116 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,6 +1,3 @@ -# @ai-devkit/cli -> Part of [AI DevKit](https://github.com/Codeaholicguy/ai-devkit) - The official command-line interface for **AI DevKit**. This tool orchestrates the setup and management of AI-assisted development environments, ensuring your project is ready for agents like Cursor, Claude Code, and more. From d2a5e64860dbd62036c0d19210806c067dee5a92 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sun, 25 Jan 2026 17:36:40 +0100 Subject: [PATCH 04/18] Update skills registry with new entries Added new registries for various skills. --- skills/registry.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/skills/registry.json b/skills/registry.json index b1c10e72..0f14d2d2 100644 --- a/skills/registry.json +++ b/skills/registry.json @@ -1,6 +1,11 @@ { "registries": { "anthropics/skills": "https://github.com/anthropics/skills.git", - "vercel-labs/agent-skills": "https://github.com/vercel-labs/agent-skills.git" + "vercel-labs/agent-skills": "https://github.com/vercel-labs/agent-skills.git", + "remotion-dev/skills": "https://github.com/remotion-dev/skills.git", + "supabase/agent-skills": "https://github.com/supabase/agent-skills.git", + "obra/superpowers": "https://github.com/obra/superpowers.git", + "softaworks/agent-toolkit": "https://github.com/softaworks/agent-toolkit.git", + "codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git" } } From 95cd49542cbf1c88d39a8a52c266f4116d033f22 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sun, 25 Jan 2026 17:58:10 +0100 Subject: [PATCH 05/18] Add document for skill --- web/app/globals.css | 44 +++++++ web/content/docs/7-skills.md | 221 +++++++++++++++++++++++++++++++++++ 2 files changed, 265 insertions(+) create mode 100644 web/content/docs/7-skills.md diff --git a/web/app/globals.css b/web/app/globals.css index 6b7e670c..c3db968f 100644 --- a/web/app/globals.css +++ b/web/app/globals.css @@ -121,6 +121,50 @@ article a { text-underline-offset: 2px; } +/* Table Styles */ +article table { + width: 100%; + border-collapse: collapse; + margin: 1.5rem 0; + font-size: 0.95rem; + border-radius: 0.5rem; + overflow: hidden; + border: 1px solid #e5e5e5; +} + +article thead { + background: #f5f5f5; +} + +article th { + padding: 0.875rem 1rem; + text-align: left; + font-weight: 600; + color: #171717; + border-bottom: 2px solid #e5e5e5; +} + +article td { + padding: 0.75rem 1rem; + border-bottom: 1px solid #e5e5e5; + color: #404040; +} + +article tbody tr:last-child td { + border-bottom: none; +} + +article tbody tr:hover { + background: #fafafa; +} + +article td code { + background: #f0f0f0; + padding: 0.15em 0.4em; + border-radius: 4px; + font-size: 0.875em; +} + @keyframes agent-marquee { 0% { transform: translateX(0); diff --git a/web/content/docs/7-skills.md b/web/content/docs/7-skills.md new file mode 100644 index 00000000..8dc33a4f --- /dev/null +++ b/web/content/docs/7-skills.md @@ -0,0 +1,221 @@ +--- +title: Skills +description: Extend your AI agents with reusable, community-driven skills from skill registries. +slug: skills +order: 7 +--- + +**Skills** are packaged capabilities that extend what your AI agents can do. Think of them as "plugins" for your AI assistantβ€”each skill teaches your agent a new competency, like frontend design patterns, database optimization, or security best practices. + +## How Skills Work + +A skill is a folder containing a `SKILL.md` file and optional supporting resources (scripts, examples, templates). When you install a skill, it's symlinked (or copied) into your project's skill directory, making it immediately available to your AI agent. + +Skills are distributed via **Skill Registries**β€”GitHub repositories that follow a standard structure. The AI DevKit maintains a curated list of registries, so you can easily discover and install skills from the community. + +## Supported Environments + +Skills are currently supported by the following AI coding agents: + +| Environment | Skill Path | +|----------------|---------------------| +| **Cursor** | `.cursor/skills` | +| **Claude Code**| `.claude/skills` | +| **Codex** | `.codex/skills` | +| **OpenCode** | `.opencode/skills` | +| **Antigravity**| `.agent/skills` | + +When you install a skill, it's automatically added to all skill-capable environments configured in your project. + +## Installation + +Skills are managed through the `ai-devkit skill` command. Make sure you have AI DevKit installed: + +```bash +npm install -g ai-devkit +``` + +## Commands + +### `ai-devkit skill add` + +Install a skill from a registry. + +**Syntax:** +```bash +ai-devkit skill add +``` + +**Parameters:** +- ``: The registry identifier (e.g., `anthropics/skills`) +- ``: The name of the skill to install (e.g., `frontend-design`) + +**Example:** +```bash +ai-devkit skill add anthropics/skills frontend-design +``` + +This command will: +1. Fetch the skill registry from GitHub +2. Clone the registry repository to a local cache (`~/.ai-devkit/skills/`) +3. Verify the skill exists and contains a valid `SKILL.md` +4. Symlink the skill into your project's skill directories + +**Output:** +``` +Validating skill: frontend-design from anthropics/skills +Fetching registry from GitHub... +Checking local cache... + β†’ Cloning anthropics/skills (this may take a moment)... +Loading project configuration... +Installing skill to project... + β†’ .cursor/skills/frontend-design (symlinked) + β†’ .claude/skills/frontend-design (symlinked) + +Successfully installed: frontend-design + Source: anthropics/skills + Installed to: cursor, claude +``` + +### `ai-devkit skill list` + +List all skills installed in your project. + +**Syntax:** +```bash +ai-devkit skill list +``` + +**Example Output:** +``` +Installed Skills: + + Skill Name Registry Environments + ──────────────────────────────────────────────────── + frontend-design anthropics/skills cursor, claude + api-patterns vercel-labs/agent-skills cursor, claude + + Total: 2 skill(s) +``` + +The list shows: +- **Skill Name**: The installed skill's name +- **Registry**: The source registry where the skill came from +- **Environments**: Which AI environments have this skill installed + +### `ai-devkit skill remove` + +Remove a skill from your project. + +**Syntax:** +```bash +ai-devkit skill remove +``` + +**Example:** +```bash +ai-devkit skill remove frontend-design +``` + +**Output:** +``` +Removing skill: frontend-design + β†’ Removed from .cursor/skills + β†’ Removed from .claude/skills + +Successfully removed from 2 location(s). +Note: Cached copy in ~/.ai-devkit/skills/ preserved for other projects. +``` + +The cached copy remains in `~/.ai-devkit/skills/` so you can quickly reinstall it in other projects without re-downloading. + +## Skill Registry + +AI DevKit uses a centralized registry file to map registry identifiers to their GitHub repositories. The registry is hosted at: + +``` +https://raw.githubusercontent.com/Codeaholicguy/ai-devkit/main/skills/registry.json +``` + +### Registry Format + +The registry is a simple JSON file: + +```json +{ + "registries": { + "anthropics/skills": "https://github.com/anthropics/skills.git", + "vercel-labs/agent-skills": "https://github.com/vercel-labs/agent-skills.git" + } +} +``` + +Each registry repository should follow this structure: + +``` +skills/ +β”œβ”€β”€ skill-name-1/ +β”‚ β”œβ”€β”€ SKILL.md # Required: Main skill instructions +β”‚ β”œβ”€β”€ scripts/ # Optional: Helper scripts +β”‚ β”œβ”€β”€ examples/ # Optional: Usage examples +β”‚ └── resources/ # Optional: Additional assets +β”œβ”€β”€ skill-name-2/ +β”‚ └── SKILL.md +└── ... +``` + +## Creating Your Own Skills + +Want to create your own skills? Here's what you need: + +### SKILL.md Structure + +Every skill must have a `SKILL.md` file with YAML frontmatter: + +```markdown +--- +name: my-awesome-skill +description: A brief description of what this skill does +--- + +# My Awesome Skill + +Detailed instructions for the AI agent on how to use this skill... +``` + +### Publishing Skills + +1. Create a GitHub repository with the `skills/` directory structure +2. Add your skills with proper `SKILL.md` files +3. Open a PR to add your registry to the [ai-devkit registry](https://github.com/Codeaholicguy/ai-devkit/blob/main/skills/registry.json) + +## Caching & Performance + +To provide fast installation times, AI DevKit caches skill registries locally: + +- **Cache Location**: `~/.ai-devkit/skills//` +- **Behavior**: Repositories are cloned once and reused across projects +- **Updates**: Currently, cached repositories are used as-is. To refresh, manually delete the cache directory + +## Troubleshooting + +### "Registry not found" + +The registry identifier doesn't exist in the skill registry. Check available registries: + +```bash +# View the registry file +curl https://raw.githubusercontent.com/Codeaholicguy/ai-devkit/main/skills/registry.json +``` + +### "Skill not found" + +The skill doesn't exist in the specified registry. Explore the registry repository on GitHub to see available skills. + +### "No skill-capable environments configured" + +Your project doesn't have any skill-compatible environments. Run `ai-devkit init` and select an environment that supports skills (Cursor, Claude Code, Codex, OpenCode, or Antigravity). + +### "SKILL.md not found" + +The skill folder exists but doesn't contain a `SKILL.md` file, meaning it's not a valid skill. Contact the registry maintainer. From 852de8960ed5f41b7b8e814b4f076f07f02cee3e Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 08:01:13 +0100 Subject: [PATCH 06/18] Update guidance on storing knowledge and testing --- packages/cli/templates/env/base.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/cli/templates/env/base.md b/packages/cli/templates/env/base.md index a2fbc8a0..3ee47fa1 100644 --- a/packages/cli/templates/env/base.md +++ b/packages/cli/templates/env/base.md @@ -49,7 +49,7 @@ The AI assistant should proactively use knowledge memory throughout all interact - When you establish new conventions or standards for the project **How to store**: -- Use `memory.storeKnowledge` MCP tool or run `/remember` command +- Use `memory.storeKnowledge` MCP tool - If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command - Include clear title, detailed content, relevant tags, and appropriate scope - Make knowledge specific and actionable, not generic advice @@ -79,5 +79,5 @@ When working on this project, you can run commands to: - Review architectural decisions (`review-design`) - Plan and execute tasks (`execute-plan`) - Verify implementation against design (`check-implementation`) -- Suggest missing tests (`suggest-tests`) -- Perform structured code reviews (`code-review`) \ No newline at end of file +- Writing tests (`writing-test`) +- Perform structured code reviews (`code-review`) From ccb46578fe6cf7a31ccb185fa873a4b99d530d86 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 08:29:20 +0100 Subject: [PATCH 07/18] Update document for skill --- web/content/docs/7-skills.md | 53 ++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 8 deletions(-) diff --git a/web/content/docs/7-skills.md b/web/content/docs/7-skills.md index 8dc33a4f..798286e0 100644 --- a/web/content/docs/7-skills.md +++ b/web/content/docs/7-skills.md @@ -7,12 +7,32 @@ order: 7 **Skills** are packaged capabilities that extend what your AI agents can do. Think of them as "plugins" for your AI assistantβ€”each skill teaches your agent a new competency, like frontend design patterns, database optimization, or security best practices. +> **Note:** AI DevKit reads your project configuration from `.ai-devkit.json`. If this file doesn't exist when you run `skill add`, you'll be prompted to select which AI environments to configure. Skills require at least one skill-capable environment (Cursor, Claude Code, Codex, OpenCode, or Antigravity). + ## How Skills Work -A skill is a folder containing a `SKILL.md` file and optional supporting resources (scripts, examples, templates). When you install a skill, it's symlinked (or copied) into your project's skill directory, making it immediately available to your AI agent. +A skill is a folder containing a `SKILL.md` file and optional supporting resources (scripts, examples, templates). When you install a skill, it's **symlinked** into your project's skill directory, making it immediately available to your AI agent. + +> **What's a symlink?** A symlink (symbolic link) is like a shortcutβ€”instead of copying files, it creates a reference to the original location. This means updates to the cached skill are automatically reflected in your project. On systems where symlinks aren't supported, files are copied instead. Skills are distributed via **Skill Registries**β€”GitHub repositories that follow a standard structure. The AI DevKit maintains a curated list of registries, so you can easily discover and install skills from the community. +## Quick Start + +Get up and running in 30 seconds: + +```bash +# 1. Initialize ai-devkit in your project (if not already done) +ai-devkit init + +# 2. Install a skill from a registry +ai-devkit skill add anthropics/skills frontend-design + +# 3. Done! Your AI agent can now use the skill. +``` + +Once installed, simply ask your AI agent to use the skill's capabilitiesβ€”it will automatically apply the techniques and patterns defined in the skill. + ## Supported Environments Skills are currently supported by the following AI coding agents: @@ -27,13 +47,31 @@ Skills are currently supported by the following AI coding agents: When you install a skill, it's automatically added to all skill-capable environments configured in your project. -## Installation +## Using Installed Skills -Skills are managed through the `ai-devkit skill` command. Make sure you have AI DevKit installed: +Once a skill is installed, your AI agent automatically has access to it. You don't need to do anything specialβ€”just ask! -```bash -npm install -g ai-devkit -``` +### How It Works + +When your AI agent starts a session, it reads the `SKILL.md` files from your project's skill directories. These files contain instructions that teach the agent new capabilities, patterns, or best practices. + +### Example Usage + +Let's say you installed a `frontend-design` skill. You can now ask your agent: + +> "Use the frontend-design skill to create a responsive navigation component" + +Or simply reference the concepts the skill teaches: + +> "Build a card component following modern design patterns" + +The agent will apply the techniques, conventions, and examples defined in the skill's instructions. + +### Tips for Using Skills + +- **Be explicit**: Mention the skill by name if you want the agent to use specific techniques from it +- **Check skill contents**: Read the `SKILL.md` file to understand what capabilities it provides +- **Combine skills**: Multiple skills can work togetherβ€”install several to expand your agent's knowledge ## Commands @@ -195,7 +233,6 @@ To provide fast installation times, AI DevKit caches skill registries locally: - **Cache Location**: `~/.ai-devkit/skills//` - **Behavior**: Repositories are cloned once and reused across projects -- **Updates**: Currently, cached repositories are used as-is. To refresh, manually delete the cache directory ## Troubleshooting @@ -218,4 +255,4 @@ Your project doesn't have any skill-compatible environments. Run `ai-devkit init ### "SKILL.md not found" -The skill folder exists but doesn't contain a `SKILL.md` file, meaning it's not a valid skill. Contact the registry maintainer. +The skill folder exists but doesn't contain a `SKILL.md` file, meaning it's not a valid skill. Contact the registry maintainer. \ No newline at end of file From 1410cf8182a91978768efb7ffee36220d7a3a4b3 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 09:08:46 +0100 Subject: [PATCH 08/18] Update document for getting started --- web/content/docs/1-getting-started.md | 117 +++++++++++++++++++------- 1 file changed, 86 insertions(+), 31 deletions(-) diff --git a/web/content/docs/1-getting-started.md b/web/content/docs/1-getting-started.md index b416d60d..72325acf 100644 --- a/web/content/docs/1-getting-started.md +++ b/web/content/docs/1-getting-started.md @@ -4,6 +4,28 @@ description: Quick start guide for AI DevKit order: 1 --- +**AI DevKit** is a toolkit that helps you work more effectively with AI coding assistants like Cursor, Claude Code, Codex, Antigravity, OpenCode, GitHub Copilot, and more. It provides structured workflows, reusable commands, and memory features to make AI-assisted development more consistent and productive. + +## Why AI DevKit? + +When working with AI assistants, you often find yourself: +- Repeating the same instructions across sessions +- Losing context between conversations +- Struggling to maintain consistency across features + +AI DevKit solves these problems by giving your AI assistant: +- **Structured workflows** β€” Consistent processes from requirements to deployment +- **Custom commands** β€” Reusable prompts tailored to your project +- **Long-term memory** β€” Rules and patterns that persist across sessions +- **Skills** β€” Community-contributed capabilities your AI can learn + +## Prerequisites + +Before you begin, make sure have: +- **Node.js** (version 18 or higher) +- **npm** or **npx** (comes with Node.js) +- An AI coding assistant (Cursor, Claude Code, Codex, Antigravity, OpenCode, GitHub Copilot, etc.) + ## Installation Install AI DevKit globally using npm: @@ -12,7 +34,7 @@ Install AI DevKit globally using npm: npm install -g ai-devkit ``` -Or use it directly with npx: +Or use it directly with npx (no installation required): ```bash npx ai-devkit init @@ -20,53 +42,86 @@ npx ai-devkit init ## Initialize Your Project -In your project directory, run: +Navigate to your project directory and run: ```bash ai-devkit init ``` -This will: -- Create a `docs/ai/` directory structure for your development phases -- Set up phase templates for requirements, design, planning, implementation, testing, deployment, and monitoring -- Copy environment-specific rules for CursorAI or Claude Code +You'll be prompted to select which AI environments you use (Cursor, Claude Code, etc.). AI DevKit will then: + +1. **Create documentation structure** β€” A `docs/ai/` directory with templates for each development phase +2. **Set up AI environment files** β€” Configuration and commands for your selected AI assistants +3. **Save your preferences** β€” Stored in `.ai-devkit.json` for future updates ## Project Structure -After initialization, you'll have: +After initialization, you'll have a structured documentation folder: ``` docs/ai/ -β”œβ”€β”€ requirements/ # Problem understanding and requirements -β”œβ”€β”€ design/ # System architecture and design decisions -β”œβ”€β”€ planning/ # Task breakdown and project planning -β”œβ”€β”€ implementation/ # Implementation guides and notes -β”œβ”€β”€ testing/ # Testing strategy and test cases -β”œβ”€β”€ deployment/ # Deployment and infrastructure docs -└── monitoring/ # Monitoring and observability setup +β”œβ”€β”€ requirements/ # What you're building and why +β”œβ”€β”€ design/ # Architecture and technical decisions +β”œβ”€β”€ planning/ # Task breakdown and timeline +β”œβ”€β”€ implementation/ # Implementation notes and guides +β”œβ”€β”€ testing/ # Test strategy and cases +β”œβ”€β”€ deployment/ # Deployment procedures +└── monitoring/ # Monitoring and observability ``` -## Using Commands +This structure helps you maintain documentation throughout your development lifecycle, giving your AI assistant the context it needs to help effectively. + +## Using Slash Commands + +AI DevKit installs **slash commands** into your AI editor. These are special prompts you type directly into your AI assistant's chat (not in your terminal). -AI DevKit provides helpful commands to guide your development workflow: +> **Note:** Slash commands like `/new-requirement` are used inside your AI editor (Cursor, Claude Code, etc.), not in the terminal. Terminal commands start with `ai-devkit`. -- `/new-requirement` - Start a new feature with structured documentation -- `/review-requirements` - Review requirements documentation -- `/review-design` - Validate design docs against requirements -- `/execute-plan` - Work through implementation tasks -- `/check-implementation` - Compare implementation with design documents -- `/writing-test` - Generate comprehensive test cases -- `/code-review` - Perform structured code reviews -- `/capture-knowledge` - Capture structured understanding of code entry points -- `/debug` - Debug issues by clarifying expectations and agreeing on fix plans -- `/update-planning` - Reconcile implementation progress with planning documentation +### Core Commands + +| Command | Purpose | +|---------|---------| +| `/new-requirement` | Start a new feature with structured documentation | +| `/review-requirements` | Validate completeness of requirements | +| `/review-design` | Check architecture and generate diagrams | +| `/execute-plan` | Work through implementation tasks step-by-step | +| `/check-implementation` | Compare code with design documents | +| `/writing-test` | Generate comprehensive test cases | +| `/code-review` | Perform pre-commit code reviews | +| `/capture-knowledge` | Document and understand existing code | +| `/debug` | Systematic debugging with structured analysis | +| `/update-planning` | Sync planning docs with implementation progress | +| `/remember` | Remember your important guidelines, rules, and best practices | + +For detailed usage of each command, see [Development with AI DevKit](/docs/development-with-ai-devkit). + +## Quick Example + +Here's how a typical workflow might look: + +``` +1. In your terminal: + $ ai-devkit init + +2. In Cursor/Claude Code: + > /new-requirement + + AI: "What feature would you like to build?" + You: "Add user authentication with OAuth" + + AI guides you through requirements β†’ design β†’ planning β†’ implementation +``` ## Next Steps -1. Review the phase templates in `docs/ai/` -2. Start your first feature with `/new-requirement` -3. Follow the structured workflow through each phase -4. Keep documentation updated as you implement +1. **Explore your AI editor** β€” Try `/new-requirement` on a small feature +2. **Read the workflows guide** β€” [Development with AI DevKit](/docs/development-with-ai-devkit) +3. **Set up memory** β€” [Give your AI long-term memory](/docs/memory) +4. **Install skills** β€” [Extend your AI's capabilities](/docs/skills) + +## Need Help? -For more details, check out our [documentation](/docs) and [roadmap](/roadmap). +- Check the [Supported Agents](/docs/supported-agents) page for environment-specific setup +- Browse the [Roadmap](/roadmap) to see what's coming +- Open an issue on [GitHub](https://github.com/Codeaholicguy/ai-devkit) for bugs or questions From 021ef64cf6ebf4eb4e76255eb532c74cf688a0d8 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 09:20:54 +0100 Subject: [PATCH 09/18] Update document for supported agents --- web/content/docs/2-supported-agents.md | 133 +++++++++++++------------ 1 file changed, 71 insertions(+), 62 deletions(-) diff --git a/web/content/docs/2-supported-agents.md b/web/content/docs/2-supported-agents.md index b7ccd84c..7cfa446c 100644 --- a/web/content/docs/2-supported-agents.md +++ b/web/content/docs/2-supported-agents.md @@ -4,104 +4,111 @@ description: Environments supported by AI DevKit order: 2 --- -## Supported Environments +AI DevKit works with a variety of AI coding assistants. This page lists all supported environments and explains what AI DevKit provides for each one. -### [Cursor](https://cursor.com/) -**Status:** Ready +## Status Legend + +| Status | Meaning | +|--------|---------| +| **Ready** | Fully supported and tested. Safe for production use. | +| **Experimental** | Works but may have issues. We're actively testing and improving support. | + +## Ready Environments +These environments are fully supported with stable integrations. + +### [Cursor](https://cursor.com/) **What AI DevKit provides:** -- `AGENTS.md` - Agent instructions for [Cursor](https://cursor.com/docs/context/rules) -- `.cursor/commands/` - Custom [slash commands](https://cursor.com/docs/context/commands) for structured development workflows -- `.cursor/rules/` - [Editor rules](https://cursor.com/docs/context/rules) for consistent coding standards +- `AGENTS.md` β€” Agent instructions for [Cursor](https://cursor.com/docs/context/rules) +- `.cursor/commands/` β€” Custom [slash commands](https://cursor.com/docs/context/commands) for structured development workflows +- `.cursor/rules/` β€” [Editor rules](https://cursor.com/docs/context/rules) for consistent coding standards ### [Claude Code](https://www.claude.com/product/claude-code) -**Status:** Ready - **What AI DevKit provides:** -- `AGENTS.md` - [Claude workspace configuration](https://www.anthropic.com/engineering/claude-code-best-practices) and context -- `.claude/commands/` - Custom [slash commands](https://code.claude.com/docs/en/slash-commands) +- `AGENTS.md` β€” [Claude workspace configuration](https://www.anthropic.com/engineering/claude-code-best-practices) and context +- `.claude/commands/` β€” Custom [slash commands](https://code.claude.com/docs/en/slash-commands) ### [GitHub Copilot](https://github.com/features/copilot) -**Status:** Ready - **What AI DevKit provides:** -- `.github/prompts/` - GitHub Copilot [custom prompts with VSCode](https://code.visualstudio.com/docs/copilot/customization/prompt-files) - -### [Google Gemini](https://geminicli.com/) -**Status:** Ready +- `.github/prompts/` β€” GitHub Copilot [custom prompts with VSCode](https://code.visualstudio.com/docs/copilot/customization/prompt-files) +### [Google Gemini CLI](https://geminicli.com/) **What AI DevKit provides:** -- `GEMINI.md` - [Context file](https://geminicli.com/docs/cli/gemini-md/) for providing instructional context to the Gemini model -- `.gemini/commands/` - Gemini [custom commands](https://geminicli.com/docs/cli/commands/) +- `GEMINI.md` β€” [Context file](https://geminicli.com/docs/cli/gemini-md/) for providing instructional context to the Gemini model +- `.gemini/commands/` β€” Gemini [custom commands](https://geminicli.com/docs/cli/commands/) ### [OpenAI Codex](https://chatgpt.com/en-SE/features/codex) -In order to use Codex, you need to run `ai-devkit setup --global`. +> **Note:** Codex requires global setup because it reads commands from a system-wide location rather than your project directory. +> +> ```bash +> ai-devkit setup --global +> ``` -**Status:** Ready +**What AI DevKit provides:** +- `AGENTS.md` β€” Codex-specific configuration and context +- `.codex/commands/` β€” Commands tailored for Codex's code-focused capabilities +### [OpenCode](https://opencode.ai/) **What AI DevKit provides:** -- `AGENTS.md` - Codex-specific configuration and context -- `.codex/commands/` - Commands tailored for Codex's code-focused capabilities +- `AGENTS.md` β€” OpenCode [custom instructions](https://opencode.ai/docs/rules/) +- `.opencode/commands/` β€” OpenCode [custom commands](https://opencode.ai/docs/commands/) -### [Windsurf](https://windsurf.com/) -**Status:** Testing +### [Antigravity](https://antigravity.google/) +> **Note:** Antigravity requires global setup. +> +> ```bash +> ai-devkit setup --global +> ``` **What AI DevKit provides:** -- `AGENTS.md` - Windsurf environment configuration -- `.windsurf/commands/` - Commands optimized for Windsurf's interface +- `.agent/workflows/` β€” Workflow for [Antigravity](https://codelabs.developers.google.com/getting-started-google-antigravity#8)'s advanced features -### [KiloCode](https://kilocode.ai/) -**Status:** Testing +## Experimental Environments -**What AI DevKit provides:** -- `AGENTS.md` - KiloCode configuration for large project handling -- `.kilocode/commands/` - Commands designed for large-scale development +These environments are under active development. They work, but you may encounter issues. -### [AMP](https://ampcode.com/) -**Status:** Testing +### [Windsurf](https://windsurf.com/) **What AI DevKit provides:** -- `AGENTS.md` - AMP configuration for accelerated workflows -- `.agents/commands/` - Commands optimized for rapid development cycles +- `AGENTS.md` β€” Windsurf environment configuration +- `.windsurf/commands/` β€” Commands optimized for Windsurf's interface -### [OpenCode](https://opencode.ai/) -**Status:** Ready +### [KiloCode](https://kilocode.ai/) **What AI DevKit provides:** -- `AGENTS.md` - OpenCode [custom instructions](https://opencode.ai/docs/rules/) -- `.opencode/commands/` - OpenCode [custom commands](https://opencode.ai/docs/commands/) +- `AGENTS.md` β€” KiloCode configuration for large project handling +- `.kilocode/commands/` β€” Commands designed for large-scale development -### [Roo Code](https://roocode.com/) -**Status:** Testing +### [AMP](https://ampcode.com/) **What AI DevKit provides:** -- `AGENTS.md` - Roo Code configuration and context -- `.roo/commands/` - Commands optimized for Roo's advanced features +- `AGENTS.md` β€” AMP configuration for accelerated workflows +- `.agents/commands/` β€” Commands optimized for rapid development cycles -### [Antigravity](https://antigravity.google/) -**Status:** Ready +### [Roo Code](https://roocode.com/) **What AI DevKit provides:** -- `.agent/workflows/` - Workflow for [Antigravity](https://codelabs.developers.google.com/getting-started-google-antigravity#8)'s advanced features +- `AGENTS.md` β€” Roo Code configuration and context +- `.roo/commands/` β€” Commands optimized for Roo's advanced features ## Environment Setup ### Interactive Multi-Selection -When you run `ai-devkit init`, you can select multiple environments simultaneously: +When you run `ai-devkit init`, you can select multiple environments at once: ```bash ai-devkit init ``` This presents an interactive checklist where you can: -- Use spacebar to select/deselect environments -- Press Enter to confirm your selections -- Choose any combination of the 10 supported environments +- **Spacebar** β€” Select or deselect an environment +- **Enter** β€” Confirm your selections +- Select any combination of the supported environments ### Configuration Storage -Your selections are stored in `.ai-devkit.json`: +Your selections are saved in `.ai-devkit.json`: ```json { @@ -113,22 +120,22 @@ Your selections are stored in `.ai-devkit.json`: } ``` -### Re-running Setup +### Adding More Environments Later -If you want to add more environments later: +Want to add another environment after initial setup? Just run: ```bash ai-devkit init ``` AI DevKit will: -1. Detect existing environments -2. Show confirmation prompts for overwriting +1. Detect your existing environments +2. Ask before overwriting any existing configurations 3. Add new environments alongside existing ones ### Override Protection -When re-running `ai-devkit init`, you'll be prompted before overwriting existing environment configurations: +When re-running `ai-devkit init`, you'll see a warning before any existing files are overwritten: ``` Warning: The following environments are already set up: cursor, claude @@ -136,11 +143,13 @@ Warning: The following environments are already set up: cursor, claude Do you want to continue? ``` -## Contributing New Environments +## For Contributors + +Want to add support for a new AI environment? We welcome contributions! -AI DevKit welcomes contributions for new AI development environments. To add support for a new environment: +1. **Create Environment Definition** β€” Add to `src/util/env.ts` +2. **Add Templates** β€” Create `templates/env/{code}/` directory +3. **Update Documentation** β€” Add to this guide +4. **Test Integration** β€” Ensure proper initialization and configuration -1. **Create Environment Definition**: Add to `src/util/env.ts` -2. **Add Templates**: Create `templates/env/{code}/` directory -3. **Update Documentation**: Add to this guide -4. **Test Integration**: Ensure proper initialization and configuration \ No newline at end of file +See our [Contributing Guide](https://github.com/Codeaholicguy/ai-devkit/blob/main/CONTRIBUTING.md) for details. \ No newline at end of file From be3ebd9ea41dd4e7ce61b42f851cc90d04f1b5a4 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 10:23:38 +0100 Subject: [PATCH 10/18] Update document for development with ai-devkit --- .../docs/3-development-with-ai-devkit.md | 157 +++++++++++++----- 1 file changed, 118 insertions(+), 39 deletions(-) diff --git a/web/content/docs/3-development-with-ai-devkit.md b/web/content/docs/3-development-with-ai-devkit.md index f02245fd..35778573 100644 --- a/web/content/docs/3-development-with-ai-devkit.md +++ b/web/content/docs/3-development-with-ai-devkit.md @@ -5,66 +5,145 @@ slug: development-with-ai-devkit order: 3 --- -## Start with `/new-requirement` +AI DevKit provides a structured workflow that takes you from idea to deployed feature. Instead of jumping straight into code, you'll create documentation at each phaseβ€”this gives your AI assistant the context it needs to help you effectively. -The `/new-requirement` command is your entry point for any new feature development. It guides you through a complete development lifecycle: +## Why Structured Development? -```bash -# In Cursor or Claude Code +When you work with AI assistants without structure, you often: +- Lose context between sessions +- Repeat yourself explaining requirements +- End up with inconsistent code and documentation + +AI DevKit solves this by creating documentation as you go. Each document becomes context for the next phase, so your AI assistant always knows what you're building and why. + +## The Development Lifecycle + +### 1. Start with `/new-requirement` + +The `/new-requirement` command is your entry point for any new feature. It guides you through the complete lifecycle: + +``` /new-requirement ``` **What happens:** -1. **Requirements Capture** - Define what you're building and why -2. **Design Phase** - Create architecture and technical specifications -3. **Planning** - Break down work into actionable tasks -4. **Implementation** - Step-by-step coding with guidance -5. **Testing** - Generate comprehensive test coverage -6. **Git Workflow** - Structured commits and PR creation - -**Generated Documentation:** -- `docs/ai/requirements/feature-{name}.md` - Requirements and user stories -- `docs/ai/design/feature-{name}.md` - Architecture and technical design -- `docs/ai/planning/feature-{name}.md` - Task breakdown and timeline -- `docs/ai/implementation/feature-{name}.md` - Implementation notes -- `docs/ai/testing/feature-{name}.md` - Test strategy and cases - -### Refine Your Work - -**Review Requirements:** -```bash + +| Phase | What You Do | +|-------|-------------| +| **Requirements** | Define what you're building and why | +| **Design** | Create architecture and technical specs | +| **Planning** | Break work into actionable tasks | +| **Implementation** | Code with step-by-step guidance | +| **Testing** | Generate comprehensive test coverage | + +**Documentation created:** + +``` +docs/ai/ +β”œβ”€β”€ requirements/feature-{name}.md # What and why +β”œβ”€β”€ design/feature-{name}.md # Architecture +β”œβ”€β”€ planning/feature-{name}.md # Task breakdown +β”œβ”€β”€ implementation/feature-{name}.md # Implementation notes +└── testing/feature-{name}.md # Test strategy +``` + +> **Tip:** You don't have to complete all phases in one session. AI DevKit saves your documentation, so you can pick up where you left off. + +## Refinement Commands + +After the initial pass, use these commands to refine your work: + +### `/review-requirements` + +``` /review-requirements ``` -Validates completeness and identifies gaps in your requirements. -**Review Design:** -```bash +**When to use:** Before starting design, to catch gaps in your requirements. + +**What it does:** +- Validates completeness of requirements +- Identifies missing acceptance criteria +- Suggests clarifying questions + +### `/review-design` + +``` /review-design ``` -Ensures architecture clarity and generates Mermaid diagrams. -**Execute Your Plan:** -```bash +**When to use:** After design, before implementation, to ensure your architecture is solid. + +**What it does:** +- Ensures architecture clarity +- Generates Mermaid diagrams for visualization +- Checks alignment with requirements + +### `/execute-plan` + +``` /execute-plan ``` -Interactive task execution that: + +**When to use:** During implementation, to work through tasks systematically. + +**What it does:** - Reads your planning document - Presents tasks in logical order -- Captures progress and notes -- Prompts documentation updates +- Tracks progress and captures notes +- Prompts documentation updates as you go + +### `/update-planning` + +``` +/update-planning +``` + +**When to use:** When implementation drifts from the original plan. + +**What it does:** +- Syncs planning documentation with actual progress +- Updates task status and notes +- Keeps documentation current + +## Quality Commands + +### `/code-review` -**Code Review:** -```bash +``` /code-review ``` -Pre-commit review that checks: + +**When to use:** Before committing, to catch issues early. + +**What it checks:** - Alignment with design documents - Logic, security, and performance issues -- Code redundancy and missing tests -- Documentation completeness +- Code redundancy and duplication +- Missing tests and documentation -**Generate Tests:** -```bash +### `/writing-test` + +``` /writing-test ``` -Creates unit and integration tests targeting high coverage. \ No newline at end of file + +**When to use:** After implementation, to ensure coverage. + +**What it does:** +- Generates unit and integration tests +- Targets high coverage of your new code +- Follows your project's testing conventions + +## Tips for Success + +1. **Don't skip phases** β€” Each phase builds context for the next +2. **Keep docs updated** β€” Use `/update-planning` when things change +3. **Review before committing** β€” `/code-review` catches issues early +4. **Be specific** β€” The more detail you give, the better your AI assistant can help + +## Next Steps + +- **Debug effectively** β€” See [Debugging with AI DevKit](/docs/debugging-with-ai-devkit) +- **Understand existing code** β€” See [Understanding Existing Code](/docs/understand-existing-code-with-ai-devkit) +- **Give your AI memory** β€” See [Memory](/docs/memory) \ No newline at end of file From d0a11a4d2e213f7f4b92bc6e4a93dfc4883da378 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 10:33:24 +0100 Subject: [PATCH 11/18] Update document for debug --- .../docs/4-debugging-with-ai-devkit.md | 95 ++++++++++++------- 1 file changed, 62 insertions(+), 33 deletions(-) diff --git a/web/content/docs/4-debugging-with-ai-devkit.md b/web/content/docs/4-debugging-with-ai-devkit.md index 25de3b96..6a7c0447 100644 --- a/web/content/docs/4-debugging-with-ai-devkit.md +++ b/web/content/docs/4-debugging-with-ai-devkit.md @@ -1,19 +1,64 @@ --- title: Debugging with AI DevKit description: Learn how to systematically debug issues using AI DevKit's structured debugging workflows -order: 5 +order: 4 --- -## Use `/debug` for Systematic Problem Solving +Debugging with AI assistants often becomes a guessing gameβ€”trying random fixes until something works. The `/debug` command changes this by providing a structured methodology that ensures you understand the problem before attempting a solution. -When issues arise, the `/debug` command provides a structured 7-step methodology to identify, analyze, and resolve problems systematically. +## When to Use `/debug` + +Use this command when: +- Something isn't working as expected +- You're facing a bug you can't immediately explain +- You need to troubleshoot performance or integration issues +- You want a systematic approach instead of trial-and-error + +## Quick Example + +Here's what a `/debug` session looks like: -```bash -# In Cursor or Claude Code -/debug ``` +You: /debug + +AI: What issue are you experiencing? + +You: Users are getting a 500 error when trying to upload images larger than 5MB. -### The 7-Step Debugging Process +AI: Let me help you debug this systematically. + +**Step 1: Gather Context** +- What's the expected behavior? (Users should upload images up to 10MB) +- When did this start? (After last deployment) +- Error logs? (Request entity too large) + +**Step 2: Clarify Expectations** +Based on your requirements doc, the upload limit should be 10MB. +Current config shows: maxFileSize: '5mb' + +**Step 3: Reproduce & Isolate** +I can reproduce with any file > 5MB. The issue is in the upload middleware. + +**Step 4-7: Analysis β†’ Solution** +Root cause: Config mismatch between frontend (10MB) and backend (5MB). +Recommended fix: Update backend config to match requirements. +``` + +## The 7-Step Debugging Process + +The `/debug` command follows a proven methodology: + +| Step | Purpose | +|------|---------| +| **1. Gather Context** | Understand what's happening vs. what should happen | +| **2. Clarify Expectations** | Confirm requirements and success criteria | +| **3. Reproduce & Isolate** | Create reliable reproduction steps | +| **4. Analyze Causes** | Identify potential root causes with evidence | +| **5. Surface Options** | Present multiple resolution approaches | +| **6. Confirm Path** | Select the best approach and plan validation | +| **7. Track Actions** | Document tasks, owners, and follow-ups | + +### Step Details **1. Gather Context** - Understand what's happening vs. what should happen @@ -50,32 +95,16 @@ When issues arise, the `/debug` command provides a structured 7-step methodology - Set timelines and follow-up actions - Plan monitoring and communication -### What You Get - -**Structured Methodology** -- Prevents random debugging attempts -- Ensures comprehensive problem analysis -- Maintains focus on root causes - -**Evidence-Based Analysis** -- Backed by logs, tests, and reproduction steps -- Clear documentation of findings -- Traceable decision-making process - -**Balanced Solutions** -- Multiple resolution options with trade-offs -- Risk assessment for each approach -- Clear implementation guidance +## Use Cases -**Actionable Plans** -- Specific tasks with owners and timelines -- Validation criteria and success metrics -- Follow-up monitoring and communication +- **Bug Fixes** β€” Resolve unexpected behavior or errors +- **Integration Issues** β€” Troubleshoot system interactions +- **Performance Problems** β€” Analyze and fix slowdowns +- **Security Concerns** β€” Investigate and resolve vulnerabilities +- **Validation** β€” Verify fixes before deployment -### Use Cases +## Next Steps -- **Bug Fixes** - Resolve unexpected behavior or errors -- **Integration Issues** - Troubleshoot system interactions -- **Performance Problems** - Analyze and fix slowdowns -- **Security Concerns** - Investigate and resolve vulnerabilities -- **Validation** - Verify fixes before deployment \ No newline at end of file +- **Understand code first** β€” See [Understanding Existing Code](/docs/understand-existing-code-with-ai-devkit) +- **Prevent bugs** β€” Use [/code-review](/docs/development-with-ai-devkit#code-review) before committing +- **Remember solutions** β€” Save fixes to [Memory](/docs/memory) so you don't repeat mistakes \ No newline at end of file From bfcdf53eb3d92e2608baa5372b6c3c330b9900c1 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 11:41:19 +0100 Subject: [PATCH 12/18] Update document for understanding existed code --- ...understand-existing-code-with-ai-devkit.md | 138 ++++++++++++++---- 1 file changed, 111 insertions(+), 27 deletions(-) diff --git a/web/content/docs/5-understand-existing-code-with-ai-devkit.md b/web/content/docs/5-understand-existing-code-with-ai-devkit.md index 18ae68a8..096800de 100644 --- a/web/content/docs/5-understand-existing-code-with-ai-devkit.md +++ b/web/content/docs/5-understand-existing-code-with-ai-devkit.md @@ -4,74 +4,158 @@ description: Learn how to analyze and document existing codebases using AI DevKi order: 4 --- -## Use `/capture-knowledge` for Code Analysis +## What is Knowledge Capture? -When working with existing codebases, the `/capture-knowledge` command helps you understand complex systems by analyzing code from any entry point and generating comprehensive documentation with visual diagrams. +When joining a new project or working with unfamiliar code, understanding how everything fits together can be overwhelming. The `/capture-knowledge` command analyzes your codebase from any entry point and generates comprehensive documentation with visual diagramsβ€”helping you understand complex systems in minutes instead of hours. -```bash -# In Cursor -/capture-knowledge [options] +**Common scenarios:** +- You just joined a team and need to understand the authentication system +- You're debugging an issue and need to trace the complete execution flow +- You're planning a refactor and need to see all dependencies -# In Claude Code +## Prerequisites + +Before using `/capture-knowledge`, ensure you have: +- Initialized AI DevKit in your project (`ai-devkit init`) +- An AI editor with slash command support (Cursor, Claude Code, etc.) + +## Using the Command + +> **Note:** The `/capture-knowledge` command is a **slash command** β€” type it directly in your AI editor's chat window, not in the terminal. + +### In Cursor or Similar Editors + +``` +/capture-knowledge +``` + +### In Claude Code + +``` Use the capture-knowledge command to analyze ``` -### Entry Point Types +## Entry Point Types + +You can analyze code starting from different types of entry points: -**Files:** -```bash +### Files + +``` /capture-knowledge src/api/users.ts ``` + Analyzes a specific file and its dependencies. -**Folders:** -```bash +### Folders + +``` /capture-knowledge src/services/ ``` + Analyzes an entire module or directory structure. -**Functions:** -```bash +### Functions + +``` /capture-knowledge calculateTotalPrice ``` + Analyzes a specific function and its call chain. -**API Endpoints:** -```bash +### API Endpoints + +``` /capture-knowledge POST:/api/users ``` + Analyzes complete API request/response flow. -### What You Get +## What You Get -**Detailed Explanations** +### Detailed Explanations - Natural language descriptions of how code works - Implementation details and design patterns - Logic flow and component relationships -**Recursive Analysis** +### Recursive Analysis - Automatically traces all dependencies - Maps complete execution paths - Identifies external integrations -**Visual Diagrams** +### Visual Diagrams - Flowcharts showing execution paths - Sequence diagrams for API flows - Architecture diagrams for modules - Component relationship maps -**Actionable Insights** +### Actionable Insights - Performance considerations - Security implications - Potential improvements - Refactoring opportunities -### Use Cases +## Example Output + +When you run `/capture-knowledge src/services/auth/`, the AI generates documentation like this: + +**docs/ai/knowledge/auth-service.md:** + +```markdown +# Auth Service Analysis + +## Overview +The auth service handles user authentication using JWT tokens... + +## Architecture Diagram + +flowchart TD + A[Login Request] --> B[Validate Credentials] + B --> C{Valid?} + C -->|Yes| D[Generate JWT] + C -->|No| E[Return 401] + +## Key Components +- `AuthController` β€” Handles HTTP endpoints +- `TokenService` β€” Manages JWT creation and validation +- `UserRepository` β€” Database access for user data +``` + +## Where Results Are Saved + +Generated documentation is saved to `docs/ai/knowledge/` in your project: + +``` +docs/ai/knowledge/ +β”œβ”€β”€ auth-service.md # Analysis of auth module +β”œβ”€β”€ user-api.md # Analysis of user endpoints +└── diagrams/ # Generated visual diagrams +``` + +These files can be committed to version control, making your knowledge base searchable and shareable with your team. + +## Use Cases + +| Use Case | Description | +|----------|-------------| +| **Onboarding** | Help new developers understand complex systems quickly | +| **Documentation** | Generate comprehensive system documentation automatically | +| **Debugging** | Understand complete execution flows before diving into code | +| **Refactoring** | Get full context and dependency maps before making changes | +| **Knowledge Base** | Create searchable, versioned documentation for your team | + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| Command not recognized | Run `ai-devkit init` first to install commands | +| Analysis seems incomplete | Try analyzing a smaller entry point first | +| Diagrams not rendering | Ensure your editor supports Mermaid syntax | +| Entry point not found | Check the path is relative to your project root | -- **Onboarding** - Help new developers understand complex systems -- **Documentation** - Generate comprehensive system documentation -- **Debugging** - Understand complete execution flows -- **Refactoring** - Get full context before making changes -- **Knowledge Base** - Create searchable documentation +## Next Steps -**Output Location:** Analysis is saved to `docs/ai/knowledge/` and can be versioned with your code. \ No newline at end of file +- **Debug an issue** β€” Use [`/debug`](/docs/debugging-with-ai-devkit) with your captured knowledge for context +- **Plan a refactor** β€” Use your analysis to inform design decisions with `/review-design` +- **Build your knowledge base** β€” Enable [Memory](/docs/memory) to make your captured knowledge searchable +- **Extend capabilities** β€” Install [Skills](/docs/skills) to add more AI capabilities \ No newline at end of file From e46dd36c96e07c7ccb05ce075a8ff074d03a6a10 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 11:46:29 +0100 Subject: [PATCH 13/18] Update document for memory --- web/content/docs/6-memory.md | 60 +++++++++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/web/content/docs/6-memory.md b/web/content/docs/6-memory.md index 1c3038ce..fa625505 100644 --- a/web/content/docs/6-memory.md +++ b/web/content/docs/6-memory.md @@ -9,6 +9,14 @@ Imagine if your AI assistant never made the same mistake twice. The **Memory** service allows you to store actionable insights, coding patterns, and project guidelines. Once stored, this knowledge is available to your AI agents (via MCP) and to you directly via the CLI, ensuring consistency across your development workflow. +## Prerequisites + +Before using Memory, ensure you have: + +- **Node.js 18+** installed +- **AI DevKit CLI** installed: `npm install -g ai-devkit` or use `npx ai-devkit` +- For MCP usage: A compatible AI assistant (Cursor, Claude Code, etc.) + ## How It Works You can interact with Memory in two ways: @@ -42,7 +50,12 @@ Once connected, you can talk to your AI naturally: **Storing Knowledge:** > "We just decided that all API responses must handle BigInt serialization. Please save this rule to memory with the tag #backend." -You can force your AI agent to store knowledge by using slash commands: `/remember`. This command is available if you init your project with `ai-devkit init`. +You can also force your AI agent to store knowledge by using the `/remember` slash command. This command is available if you initialized your project with `ai-devkit init`. + +**Example:** +> /remember Always use `BigInt.toString()` before sending API responses containing large numbers. + +The AI will prompt you for a title and tags, then save the knowledge to memory. **Retrieving Knowledge:** > "I'm building a new endpoint. Check memory for any API standards I need to follow." @@ -61,9 +74,19 @@ Found a solution to a tricky bug? Save it immediately: ai-devkit memory store \ --title "Fix: Docker connection refused on M1 Mac" \ --content "Enable 'Use Rosetta for x86/amd64 emulation' in Docker Desktop settings." \ - --tags "docker,mac,infra" + --tags "docker,mac,infra" \ + --scope "global" ``` +| Parameter | Required | Description | +|-----------|----------|-------------| +| `--title` | Yes | A short, descriptive title | +| `--content` | Yes | The detailed knowledge to store | +| `--tags` | No | Comma-separated tags for categorization | +| `--scope` | No | `global` (default), `project:`, or `repo:` | + +> πŸ’‘ **Tip:** Run `ai-devkit memory store --help` to see all available options. + ### Searching Knowledge Need to recall a specific command or pattern? Search for it: @@ -77,12 +100,16 @@ ai-devkit memory search --query "docker m1" [ { "title": "Fix: Docker connection refused on M1 Mac", - "content": "Enable 'Use Rosetta for x86/amd64 emulation'...", + "content": "Enable 'Use Rosetta for x86/amd64 emulation' in Docker Desktop settings.", + "tags": ["docker", "mac", "infra"], + "scope": "global", "score": 5.2 } ] ``` +> **Note:** If no results are found, an empty array `[]` is returned. + ## Organizing Your Knowledge To keep your memory effective, use **Tags** and **Scopes**. @@ -93,12 +120,24 @@ Categorize your entries so they trigger in the right context. - `["deployment", "ci"]` -> For DevOps procedures. ### Scopes -Control where your knowledge applies. -- **Global** (Default): Applies to all your projects. -- **Project**: `project:my-app` β€” Specific to a project. -- **Repo**: `repo:org/repo` β€” Specific to a git repository. -*Note: AI agents will prioritize knowledge that matches the scope of the project you are currently working on.* +Control where your knowledge applies: + +| Scope | CLI Flag | Description | +|-------|----------|-------------| +| Global | `--scope global` | Applies to all your projects (default) | +| Project | `--scope project:my-app` | Specific to a project | +| Repo | `--scope repo:org/repo` | Specific to a git repository | + +**Example:** +```bash +ai-devkit memory store \ + --title "Use pnpm for this monorepo" \ + --content "This project uses pnpm workspaces. Always use 'pnpm' instead of 'npm'." \ + --scope "repo:myorg/my-monorepo" +``` + +> **Note:** AI agents automatically prioritize knowledge matching the scope of your current working directory. ## Privacy & Storage @@ -107,3 +146,8 @@ Your memory is **100% local**. All data is stored in a high-performance SQLite database located at `~/.ai-devkit/memory.db`. No data is sent to the cloud, ensuring your proprietary coding patterns remain private. This is portable so you can just copy the database file to another machine to use it across different machines. + +## Next Steps + +- **[Skills](/docs/skills)**: Learn how to create reusable skill templates +- **[Getting Started](/docs/getting-started)**: New to AI DevKit? [Start here](/docs/getting-started) From e925c906ffee73ca0c209eb271098269d832e20e Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 11:46:50 +0100 Subject: [PATCH 14/18] Add technical-writer-review command --- .agent/workflows/technical-writer-review.md | 81 +++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 .agent/workflows/technical-writer-review.md diff --git a/.agent/workflows/technical-writer-review.md b/.agent/workflows/technical-writer-review.md new file mode 100644 index 00000000..aefe2e66 --- /dev/null +++ b/.agent/workflows/technical-writer-review.md @@ -0,0 +1,81 @@ +--- +description: Review and improve documentation for novice users with technical writing best practices +--- + +# Technical Writer Review Workflow + +Review documentation files from a professional technical writer's perspective, focusing on novice user experience. + +## Review Criteria + +For each document, evaluate: + +### 1. Clarity (Is it easy to understand?) +- Does it explain concepts before using them? +- Does it avoid jargon, or explain it when necessary? +- Are examples concrete and realistic? + +### 2. Completeness (Does it cover what users need?) +- Does it explain *what* something is before *how* to use it? +- Are prerequisites clearly stated? +- Are there quick start examples? +- Are edge cases and errors addressed? + +### 3. Actionability (Can users follow along?) +- Are commands copy-paste ready? +- Is expected output shown? +- Are "when to use" hints provided? +- Do links to related docs exist? + +### 4. Structure (Is it well organized?) +- Does the order make sense for newcomers? +- Are sections clearly separated? +- Is there a logical flow from simple to complex? + +## Review Output Format + +For each document, provide: + +```markdown +## [Document Name] + +| Aspect | Rating (1-5) | Notes | +|--------|--------------|-------| +| Clarity | ⭐⭐⭐ | ... | +| Completeness | ⭐⭐ | ... | +| Actionability | ⭐⭐⭐⭐ | ... | +| Structure | ⭐⭐⭐ | ... | + +**Issues:** +1. Issue description +2. Issue description + +**Suggested Fixes:** +- Fix description +``` + +## Common Patterns to Fix + +| Issue | Fix | +|-------|-----| +| Missing intro | Add opening paragraph explaining what and why | +| No prerequisites | Add prerequisites section with requirements | +| Jargon without explanation | Add callout boxes explaining terminology | +| No examples | Add Quick Start or example sections | +| Flat structure | Organize into logical sections | +| No cross-references | Add "Next Steps" or "See Also" links | +| Terminal vs editor confusion | Clarify which commands run where | + +## Workflow Steps + +1. **Read the document** from start to finish as a novice would +2. **Rate each aspect** using the criteria above +3. **Identify specific issues** with line references +4. **Suggest concrete fixes** with example text +5. **Prioritize fixes** as High/Medium/Low impact + +## Priority Levels + +- **High**: Blocks novice users from succeeding +- **Medium**: Causes confusion but users can figure it out +- **Low**: Nice to have improvements From 59e105e5825ddcd75c93ee351dd0a5417b6a997a Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 12:02:09 +0100 Subject: [PATCH 15/18] Add SEO tags --- web/app/docs/[slug]/page.tsx | 37 +++++++++++++++++++++++++++++-- web/app/docs/page.tsx | 43 +++++++++++++++++++++++++++++++++++- web/app/roadmap/page.tsx | 37 ++++++++++++++++++++++++++++--- web/app/vision/page.tsx | 34 ++++++++++++++++++++++++++-- 4 files changed, 143 insertions(+), 8 deletions(-) diff --git a/web/app/docs/[slug]/page.tsx b/web/app/docs/[slug]/page.tsx index 15087413..1e2e0992 100644 --- a/web/app/docs/[slug]/page.tsx +++ b/web/app/docs/[slug]/page.tsx @@ -4,6 +4,8 @@ import { getDocPage, getAllDocPages } from "@/lib/content/loader"; import MarkdownContent from "@/components/MarkdownContent"; import type { Metadata } from "next"; +const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || "https://ai-devkit.com"; + interface DocPageProps { params: Promise<{ slug: string }>; } @@ -24,12 +26,43 @@ export async function generateMetadata({ if (!doc) { return { title: "Page Not Found", + description: "The requested documentation page could not be found.", }; } + const pageUrl = `${siteUrl}/docs/${slug}`; + const title = doc.metadata.title; + const description = + doc.metadata.description || + `Learn about ${doc.metadata.title} in the AI DevKit documentation.`; + return { - title: `${doc.metadata.title} | AI DevKit Documentation`, - description: doc.metadata.description, + title, + description, + keywords: [ + doc.metadata.title, + "AI DevKit", + "documentation", + "AI-assisted development", + "structured workflows", + "coding assistant", + ], + openGraph: { + title, + description, + url: pageUrl, + siteName: "AI DevKit", + locale: "en_US", + type: "article", + }, + twitter: { + card: "summary_large_image", + title, + description, + }, + alternates: { + canonical: pageUrl, + }, }; } diff --git a/web/app/docs/page.tsx b/web/app/docs/page.tsx index c095a4e3..4dfdde84 100644 --- a/web/app/docs/page.tsx +++ b/web/app/docs/page.tsx @@ -1,5 +1,46 @@ import Link from 'next/link'; import { getAllDocPages } from '@/lib/content/loader'; +import type { Metadata } from 'next'; + +const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://ai-devkit.com'; + +export const metadata: Metadata = { + title: 'Documentation', + description: + 'Complete documentation for AI DevKit - Learn how to set up structured AI-assisted development workflows, use slash commands, configure memory, and extend capabilities with skills.', + keywords: [ + 'AI DevKit documentation', + 'AI coding assistant setup', + 'structured development workflows', + 'slash commands', + 'skills', + 'AI development tools', + 'Claude Code', + 'Cursor IDE', + 'Codex', + 'Antigravity', + 'Open Code', + 'AI pair programming', + ], + openGraph: { + title: 'AI DevKit Documentation', + description: + 'Complete documentation for AI DevKit - structured AI-assisted development workflows, commands, and skills.', + url: `${siteUrl}/docs`, + siteName: 'AI DevKit', + locale: 'en_US', + type: 'website', + }, + twitter: { + card: 'summary_large_image', + title: 'AI DevKit Documentation', + description: + 'Complete documentation for AI DevKit - structured AI-assisted development workflows, commands, and skills.', + }, + alternates: { + canonical: `${siteUrl}/docs`, + }, +}; export default function DocsPage() { const docs = getAllDocPages(); @@ -8,7 +49,7 @@ export default function DocsPage() {

Documentation

- +

Everything you need to know about using AI DevKit for AI-assisted structured software development.

diff --git a/web/app/roadmap/page.tsx b/web/app/roadmap/page.tsx index 212ba4aa..364f6ee1 100644 --- a/web/app/roadmap/page.tsx +++ b/web/app/roadmap/page.tsx @@ -2,9 +2,40 @@ import { getRoadmap } from '@/lib/content/loader'; import MarkdownContent from '@/components/MarkdownContent'; import type { Metadata } from 'next'; +const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://ai-devkit.com'; + export const metadata: Metadata = { - title: 'Roadmap | AI DevKit', - description: 'The development roadmap for AI DevKit - see what we\'re building and where we\'re headed.', + title: 'Roadmap', + description: + "The development roadmap for AI DevKit - see what we're building, current progress, and upcoming features for AI-assisted development.", + keywords: [ + 'AI DevKit roadmap', + 'AI DevKit features', + 'development roadmap', + 'upcoming features', + 'AI coding tools', + 'product roadmap', + 'AI DevKit plans', + 'feature requests', + ], + openGraph: { + title: 'Roadmap - AI DevKit', + description: + "See what we're building and where we're headed with AI DevKit - our development roadmap and upcoming features.", + url: `${siteUrl}/roadmap`, + siteName: 'AI DevKit', + locale: 'en_US', + type: 'website', + }, + twitter: { + card: 'summary_large_image', + title: 'Roadmap - AI DevKit', + description: + "See what we're building and where we're headed with AI DevKit - our development roadmap and upcoming features.", + }, + alternates: { + canonical: `${siteUrl}/roadmap`, + }, }; const statusColors = { @@ -35,7 +66,7 @@ export default function RoadmapPage() {

Roadmap

- +

Our development roadmap shows what we're working on and what's coming next for AI DevKit.

diff --git a/web/app/vision/page.tsx b/web/app/vision/page.tsx index b4675f7d..2a63a931 100644 --- a/web/app/vision/page.tsx +++ b/web/app/vision/page.tsx @@ -3,10 +3,40 @@ import MarkdownContent from "@/components/MarkdownContent"; import { notFound } from "next/navigation"; import type { Metadata } from "next"; +const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || "https://ai-devkit.com"; + export const metadata: Metadata = { - title: "Vision | AI DevKit", + title: "Vision", description: - "The vision and purpose behind AI DevKit - bridging AI-assisted development with structured software engineering practices.", + "The vision and purpose behind AI DevKit - bridging AI-assisted development with structured software engineering practices for better code quality and team collaboration.", + keywords: [ + "AI DevKit vision", + "AI-assisted development", + "structured software engineering", + "development best practices", + "AI coding philosophy", + "software development methodology", + "code quality", + "team collaboration", + ], + openGraph: { + title: "Vision - AI DevKit", + description: + "Discover the vision behind AI DevKit - bridging AI-assisted development with structured software engineering practices.", + url: `${siteUrl}/vision`, + siteName: "AI DevKit", + locale: "en_US", + type: "article", + }, + twitter: { + card: "summary_large_image", + title: "Vision - AI DevKit", + description: + "Discover the vision behind AI DevKit - bridging AI-assisted development with structured software engineering practices.", + }, + alternates: { + canonical: `${siteUrl}/vision`, + }, }; export default function VisionPage() { From c514fa4e97b5ce855087e005432e41e12016d2ea Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Mon, 26 Jan 2026 12:20:29 +0100 Subject: [PATCH 16/18] Add memory skill --- packages/cli/templates/env/base.md | 24 +++- skills/memory/SKILL.md | 200 +++++++++++++++++++++++++++++ web/content/docs/6-memory.md | 36 +++++- 3 files changed, 255 insertions(+), 5 deletions(-) create mode 100644 skills/memory/SKILL.md diff --git a/packages/cli/templates/env/base.md b/packages/cli/templates/env/base.md index 3ee47fa1..bf60e87a 100644 --- a/packages/cli/templates/env/base.md +++ b/packages/cli/templates/env/base.md @@ -28,8 +28,26 @@ This project uses ai-devkit for structured AI-assisted development. Phase docume - For new features, start with requirements clarification - Update phase docs when significant changes or decisions are made +## Skills (Extend Your Capabilities) +Skills are packaged capabilities that teach you new competencies, patterns, and best practices. Check for installed skills in the project's skill directory and use them to enhance your work. + +### Using Installed Skills +1. **Check for skills**: Look for `SKILL.md` files in the project's skill directory +2. **Read skill instructions**: Each skill contains detailed guidance on when and how to use it +3. **Apply skill knowledge**: Follow the patterns, commands, and best practices defined in the skill + +### Key Installed Skills +- **memory**: Use AI DevKit's memory service via CLI commands when MCP is unavailable. Read the skill for detailed `memory store` and `memory search` command usage. + +### When to Reference Skills +- Before implementing features that match a skill's domain +- When MCP tools are unavailable but skill provides CLI alternatives +- To follow established patterns and conventions defined in skills + ## Knowledge Memory (Always Use When Helpful) -The AI assistant should proactively use knowledge memory throughout all interactions: +The AI assistant should proactively use knowledge memory throughout all interactions. + +> **Tip**: If MCP is unavailable, use the **memory skill** for detailed CLI command reference. ### When to Search Memory - Before starting any task, search for relevant project conventions, patterns, or decisions @@ -39,7 +57,7 @@ The AI assistant should proactively use knowledge memory throughout all interact **How to search**: - Use `memory.searchKnowledge` MCP tool with relevant keywords, tags, and scope -- If MCP tools are unavailable, use `npx ai-devkit memory search` CLI command +- If MCP tools are unavailable, use `npx ai-devkit memory search` CLI command (see memory skill for details) - Example: Search for "authentication patterns" when implementing auth features ### When to Store Memory @@ -50,7 +68,7 @@ The AI assistant should proactively use knowledge memory throughout all interact **How to store**: - Use `memory.storeKnowledge` MCP tool -- If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command +- If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command (see memory skill for details) - Include clear title, detailed content, relevant tags, and appropriate scope - Make knowledge specific and actionable, not generic advice diff --git a/skills/memory/SKILL.md b/skills/memory/SKILL.md new file mode 100644 index 00000000..8af194c4 --- /dev/null +++ b/skills/memory/SKILL.md @@ -0,0 +1,200 @@ +--- +name: memory +description: Use AI DevKit's memory service to store and retrieve knowledge via CLI commands instead of MCP. +--- + +# AI DevKit Memory Skill + +This skill teaches you how to use AI DevKit's **Memory** service through CLI commands. Memory allows you to store actionable insights, coding patterns, and project guidelines that persist across sessions. + +## When to Use This Skill + +Use the memory CLI commands when: +- MCP (Model Context Protocol) is not available or not configured +- You need to store knowledge directly from the terminal +- You want to search for previously stored patterns or guidelines +- You're scripting memory operations + +## Prerequisites + +Ensure AI DevKit CLI is available: +```bash +npx ai-devkit --version +``` + +## Commands Reference + +### Storing Knowledge + +Store new knowledge items using the `memory store` command: + +```bash +npx ai-devkit memory store \ + --title "" \ + --content "" \ + --tags "" \ + --scope "" +``` + +**Parameters:** + +| Parameter | Required | Description | +|-------------|----------|-------------| +| `--title` | Yes | Short, descriptive title (5-12 words, 10-100 chars) | +| `--content` | Yes | Detailed explanation in markdown format (50-5000 chars) | +| `--tags` | No | Comma-separated domain keywords (e.g., `typescript,react`) | +| `--scope` | No | `global` (default), `project:`, or `repo:` | + +**Examples:** + +```bash +# Store a global coding pattern +npx ai-devkit memory store \ + --title "Always handle BigInt serialization in API responses" \ + --content "When returning BigInt values from API endpoints, convert them to strings using \`BigInt.toString()\` before serialization. JSON.stringify() cannot serialize BigInt natively." \ + --tags "api,backend,serialization" \ + --scope "global" + +# Store project-specific knowledge +npx ai-devkit memory store \ + --title "Use pnpm for package management" \ + --content "This monorepo uses pnpm workspaces. Always use 'pnpm' instead of 'npm' or 'yarn'. Install dependencies with 'pnpm install' and run scripts with 'pnpm run