diff --git a/README.md b/README.md index 9e418dd..ca1a624 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ ai-devkit init --phases requirements,design,planning ``` This will: + 1. Create a `.ai-devkit.json` configuration file 2. Set up your AI development environment (Cursor/Claude Code) 3. Generate phase templates in `docs/ai/` @@ -62,11 +63,13 @@ Detailed user guide can be found [here](https://ai-devkit.com/docs/). Initialize AI DevKit in your project. **Options:** + - `-e, --environment `: Specify environment (cursor|claude|both) - `-a, --all`: Initialize all phases at once - `-p, --phases `: Comma-separated list of specific phases **Examples:** + ```bash # Interactive mode ai-devkit init @@ -83,6 +86,7 @@ ai-devkit init --phases requirements,design,implementation Add or update a specific phase template. **Examples:** + ```bash # Interactive selection ai-devkit phase @@ -119,18 +123,18 @@ your-project/ ``` Supported Tools & Agents: -| Agent | Support | Notes | +| Agent | Support | Notes | |-----------------------------------------------------------|---------|---------------------------------------------------| -| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | -| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | VSCode only | -| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | -| [Cursor](https://cursor.sh/) | ✅ | | -| [opencode](https://opencode.ai/) | 🚧 | Testing | -| [Windsurf](https://windsurf.com/) | 🚧 | Testing | -| [Kilo Code](https://github.com/Kilo-Org/kilocode) | 🚧 | Testing | -| [Roo Code](https://roocode.com/) | 🚧 | Testing | -| [Codex CLI](https://github.com/openai/codex) | 🚧 | Testing | -| [Amp](https://ampcode.com/) | 🚧 | Testing | +| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | +| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | VSCode only | +| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | +| [Cursor](https://cursor.sh/) | ✅ | | +| [opencode](https://opencode.ai/) | 🚧 | Testing | +| [Windsurf](https://windsurf.com/) | 🚧 | Testing | +| [Kilo Code](https://github.com/Kilo-Org/kilocode) | 🚧 | Testing | +| [Roo Code](https://roocode.com/) | ✅ | | +| [Codex CLI](https://github.com/openai/codex) | 🚧 | Testing | +| [Amp](https://ampcode.com/) | 🚧 | Testing | Templates are designed to provide structure while remaining concise and AI-friendly. @@ -139,10 +143,12 @@ Templates are designed to provide structure while remaining concise and AI-frien ### Cursor Generated files: + - `.cursor/rules/`: Project-specific rules as Markdown files (per [Cursor documentation](https://cursor.com/docs/context/rules)) - `.cursor/commands/`: Custom slash commands as Markdown files (per [Cursor documentation](https://cursor.com/docs/agent/chat/commands)) Available slash commands: + - `/new-requirement`: Complete workflow for adding a new feature from requirements to PR - `/code-review`: Structured local code review against design docs before pushing changes - `/execute-plan`: Walk a feature plan task-by-task with interactive prompts @@ -157,10 +163,12 @@ Each command is stored as a plain Markdown file in `.cursor/commands/` and will ### Claude Code Generated files: + - `.claude/CLAUDE.md`: Workspace configuration and guidelines - `.claude/commands/`: Custom commands as Markdown files Available commands: + - `new-requirement` - Complete workflow for adding a new feature from requirements to PR - `code-review` - Structured local code review against design docs before pushing changes - `execute-plan` - Walk a feature plan task-by-task with interactive prompts @@ -178,32 +186,39 @@ Commands can be referenced in Claude Code chats to guide AI assistance through y ### Initial Project Setup 1. **Initialize your project:** + ```bash ai-devkit init ``` 2. **Start with requirements:** + - Fill out `docs/ai/requirements/README.md` - Use your AI assistant to help clarify and document requirements 3. **Design your system:** + - Complete `docs/ai/design/README.md` and feature-specific files - Include mermaid diagrams for architecture, component interactions, and data flow - Reference requirements when making design decisions 4. **Plan your work:** + - Break down tasks in `docs/ai/planning/README.md` - Estimate and prioritize 5. **Implement with guidance:** + - Follow patterns in `docs/ai/implementation/README.md` - Keep implementation notes updated 6. **Test thoroughly:** + - Use `docs/ai/testing/README.md` as your testing guide - Document test cases and results 7. **Deploy confidently:** + - Follow deployment procedures in `docs/ai/deployment/README.md` 8. **Monitor and iterate:** @@ -278,20 +293,19 @@ MIT ## Quick Reference -| Task | Command | -|------|---------| -| Initialize everything | `npx ai-devkit init --all` | -| Initialize for Cursor | `npx ai-devkit init --environment cursor` | -| Add specific phases | `npx ai-devkit init --phases requirements,design` | -| Add one phase later | `npx ai-devkit phase testing` | -| Guided feature workflow | `/new-requirement` (Cursor & Claude) | -| Execute feature plan | `/execute-plan` (Cursor & Claude) | -| Generate tests | `/writing-test` (Cursor & Claude) | -| Local code review | `/code-review` (Cursor & Claude) | -| Help | `npx ai-devkit --help` | - -| Quick links | Description | -|-------------|-------------| +| Task | Command | +| ----------------------- | ------------------------------------------------- | +| Initialize everything | `npx ai-devkit init --all` | +| Initialize for Cursor | `npx ai-devkit init --environment cursor` | +| Add specific phases | `npx ai-devkit init --phases requirements,design` | +| Add one phase later | `npx ai-devkit phase testing` | +| Guided feature workflow | `/new-requirement` (Cursor & Claude) | +| Execute feature plan | `/execute-plan` (Cursor & Claude) | +| Generate tests | `/writing-test` (Cursor & Claude) | +| Local code review | `/code-review` (Cursor & Claude) | +| Help | `npx ai-devkit --help` | + +| Quick links | Description | +| ---------------------------- | -------------------------------- | | [CHANGELOG.md](CHANGELOG.md) | Recent changes and release notes | -| [templates/](templates/) | Phase and environment templates | - +| [templates/](templates/) | Phase and environment templates | diff --git a/src/lib/TemplateManager.ts b/src/lib/TemplateManager.ts index 076b006..d144ae8 100644 --- a/src/lib/TemplateManager.ts +++ b/src/lib/TemplateManager.ts @@ -29,13 +29,13 @@ export class TemplateManager { "docs", "ai", phase, - "README.md" + "README.md", ); return fs.pathExists(targetFile); } async setupMultipleEnvironments( - environmentIds: EnvironmentCode[] + environmentIds: EnvironmentCode[], ): Promise { const copiedFiles: string[] = []; @@ -75,7 +75,7 @@ export class TemplateManager { } private async setupSingleEnvironment( - env: EnvironmentDefinition + env: EnvironmentDefinition, ): Promise { const copiedFiles: string[] = []; @@ -90,7 +90,8 @@ export class TemplateManager { console.warn(`Warning: Context file not found: ${contextSource}`); } - if (!env.isCustomCommandPath) { + // Roo Code commands are handled in copyRooSpecificFiles + if (!env.isCustomCommandPath && env.code !== "roo") { await this.copyCommands(env, copiedFiles); } @@ -101,6 +102,9 @@ export class TemplateManager { case "gemini": await this.copyGeminiSpecificFiles(copiedFiles); break; + case "roo": + await this.copyRooSpecificFiles(copiedFiles); + break; default: break; } @@ -114,7 +118,7 @@ export class TemplateManager { private async copyCommands( env: EnvironmentDefinition, - copiedFiles: string[] + copiedFiles: string[], ): Promise { const commandsSourceDir = path.join(this.templatesDir, "commands"); const commandExtension = env.customCommandExtension || ".md"; @@ -128,17 +132,17 @@ export class TemplateManager { commandFiles .filter((file: string) => file.endsWith(".md")) .map(async (file: string) => { - const targetFile = file.replace('.md', commandExtension); + const targetFile = file.replace(".md", commandExtension); await fs.copy( path.join(commandsSourceDir, file), - path.join(commandsTargetDir, targetFile) + path.join(commandsTargetDir, targetFile), ); copiedFiles.push(path.join(commandsTargetDir, targetFile)); - }) + }), ); } else { console.warn( - `Warning: Commands directory not found: ${commandsSourceDir}` + `Warning: Commands directory not found: ${commandsSourceDir}`, ); } } @@ -148,7 +152,7 @@ export class TemplateManager { this.templatesDir, "env", "cursor", - "rules" + "rules", ); const rulesTargetDir = path.join(this.targetDir, ".cursor", "rules"); @@ -165,7 +169,7 @@ export class TemplateManager { private async copyGeminiSpecificFiles(copiedFiles: string[]): Promise { const commandFiles = await fs.readdir( - path.join(this.templatesDir, "commands") + path.join(this.templatesDir, "commands"), ); const commandTargetDir = path.join(this.targetDir, ".gemini", "commands"); @@ -176,10 +180,33 @@ export class TemplateManager { .map(async (file: string) => { await fs.copy( path.join(this.templatesDir, "commands", file), - path.join(commandTargetDir, file) + path.join(commandTargetDir, file), ); copiedFiles.push(path.join(commandTargetDir, file)); - }) + }), ); } + + private async copyRooSpecificFiles(copiedFiles: string[]): Promise { + // Copy commands to .roo/commands/ + const commandsSourceDir = path.join(this.templatesDir, "commands"); + const commandsTargetDir = path.join(this.targetDir, ".roo", "commands"); + + if (await fs.pathExists(commandsSourceDir)) { + await fs.ensureDir(commandsTargetDir); + + const commandFiles = await fs.readdir(commandsSourceDir); + await Promise.all( + commandFiles + .filter((file: string) => file.endsWith(".md")) + .map(async (file: string) => { + await fs.copy( + path.join(commandsSourceDir, file), + path.join(commandsTargetDir, file), + ); + copiedFiles.push(path.join(commandsTargetDir, file)); + }), + ); + } + } } diff --git a/src/util/env.ts b/src/util/env.ts index f545aa0..d3e199a 100644 --- a/src/util/env.ts +++ b/src/util/env.ts @@ -1,77 +1,84 @@ -import { EnvironmentDefinition, EnvironmentCode } from '../types.js'; +import { EnvironmentDefinition, EnvironmentCode } from "../types.js"; -export const ENVIRONMENT_DEFINITIONS: Record = { +export const ENVIRONMENT_DEFINITIONS: Record< + EnvironmentCode, + EnvironmentDefinition +> = { cursor: { - code: 'cursor', - name: 'Cursor', - contextFileName: 'AGENTS.md', - commandPath: '.cursor/commands', + code: "cursor", + name: "Cursor", + contextFileName: "AGENTS.md", + commandPath: ".cursor/commands", }, claude: { - code: 'claude', - name: 'Claude Code', - contextFileName: 'CLAUDE.md', - commandPath: '.claude/commands', + code: "claude", + name: "Claude Code", + contextFileName: "CLAUDE.md", + commandPath: ".claude/commands", }, github: { - code: 'github', - name: 'GitHub Copilot', - contextFileName: 'AGENTS.md', - commandPath: '.github/prompts', - customCommandExtension: '.prompt.md', + code: "github", + name: "GitHub Copilot", + contextFileName: "AGENTS.md", + commandPath: ".github/prompts", + customCommandExtension: ".prompt.md", }, gemini: { - code: 'gemini', - name: 'Google Gemini', - contextFileName: 'AGENTS.md', - commandPath: '.gemini/commands', + code: "gemini", + name: "Google Gemini", + contextFileName: "AGENTS.md", + commandPath: ".gemini/commands", isCustomCommandPath: true, }, codex: { - code: 'codex', - name: 'OpenAI Codex', - contextFileName: 'AGENTS.md', - commandPath: '.codex/commands', + code: "codex", + name: "OpenAI Codex", + contextFileName: "AGENTS.md", + commandPath: ".codex/commands", }, windsurf: { - code: 'windsurf', - name: 'Windsurf', - contextFileName: 'AGENTS.md', - commandPath: '.windsurf/commands', + code: "windsurf", + name: "Windsurf", + contextFileName: "AGENTS.md", + commandPath: ".windsurf/commands", }, kilocode: { - code: 'kilocode', - name: 'KiloCode', - contextFileName: 'AGENTS.md', - commandPath: '.kilocode/commands', + code: "kilocode", + name: "KiloCode", + contextFileName: "AGENTS.md", + commandPath: ".kilocode/commands", }, amp: { - code: 'amp', - name: 'AMP', - contextFileName: 'AGENTS.md', - commandPath: '.agents/commands', + code: "amp", + name: "AMP", + contextFileName: "AGENTS.md", + commandPath: ".agents/commands", }, opencode: { - code: 'opencode', - name: 'OpenCode', - contextFileName: 'AGENTS.md', - commandPath: '.opencode/commands', + code: "opencode", + name: "OpenCode", + contextFileName: "AGENTS.md", + commandPath: ".opencode/commands", }, roo: { - code: 'roo', - name: 'Roo Code', - contextFileName: 'AGENTS.md', - commandPath: '.roo/commands', - } + code: "roo", + name: "Roo Code", + contextFileName: "AGENTS.md", + commandPath: ".roo/commands", + }, }; -export const ALL_ENVIRONMENT_CODES: EnvironmentCode[] = Object.keys(ENVIRONMENT_DEFINITIONS) as EnvironmentCode[]; +export const ALL_ENVIRONMENT_CODES: EnvironmentCode[] = Object.keys( + ENVIRONMENT_DEFINITIONS, +) as EnvironmentCode[]; export function getAllEnvironments(): EnvironmentDefinition[] { return Object.values(ENVIRONMENT_DEFINITIONS); } -export function getEnvironment(envCode: EnvironmentCode): EnvironmentDefinition | undefined { +export function getEnvironment( + envCode: EnvironmentCode, +): EnvironmentDefinition | undefined { return ENVIRONMENT_DEFINITIONS[envCode]; } @@ -79,11 +86,17 @@ export function getAllEnvironmentCodes(): EnvironmentCode[] { return [...ALL_ENVIRONMENT_CODES]; } -export function getEnvironmentsByCodes(codes: EnvironmentCode[]): EnvironmentDefinition[] { - return codes.map(code => getEnvironment(code)).filter((env): env is EnvironmentDefinition => env !== undefined); +export function getEnvironmentsByCodes( + codes: EnvironmentCode[], +): EnvironmentDefinition[] { + return codes + .map((code) => getEnvironment(code)) + .filter((env): env is EnvironmentDefinition => env !== undefined); } -export function isValidEnvironmentCode(value: string): value is EnvironmentCode { +export function isValidEnvironmentCode( + value: string, +): value is EnvironmentCode { return ALL_ENVIRONMENT_CODES.includes(value as EnvironmentCode); } @@ -92,7 +105,9 @@ export function getEnvironmentDisplayName(envCode: EnvironmentCode): string { return env ? env.name : envCode; } -export function validateEnvironmentCodes(envCodes: string[]): EnvironmentCode[] { +export function validateEnvironmentCodes( + envCodes: string[], +): EnvironmentCode[] { const validCodes: EnvironmentCode[] = []; const invalidCodes: string[] = []; @@ -105,7 +120,7 @@ export function validateEnvironmentCodes(envCodes: string[]): EnvironmentCode[] } if (invalidCodes.length > 0) { - throw new Error(`Invalid environment codes: ${invalidCodes.join(', ')}`); + throw new Error(`Invalid environment codes: ${invalidCodes.join(", ")}`); } return validCodes; diff --git a/templates/commands/capture-knowledge.md b/templates/commands/capture-knowledge.md index 8347230..4064935 100644 --- a/templates/commands/capture-knowledge.md +++ b/templates/commands/capture-knowledge.md @@ -1,43 +1,55 @@ +--- +description: Capture structured knowledge about a code entry point and save it to the knowledge docs +argument-hint: +--- + # Knowledge Capture Assistant Guide me through creating a structured understanding of a code entry point and saving it to the knowledge docs. ## Step 1: Gather Context + - Entry point (file, folder, function, API) - Why this entry point matters (feature, bug, investigation) - Relevant requirements/design docs (if any) - Desired depth or focus areas (logic, dependencies, data flow) ## Step 2: Validate Entry Point + - Determine entry point type and confirm it exists - Surface ambiguity (multiple matches) and ask for clarification - If not found, suggest likely alternatives or spelling fixes ## Step 3: Collect Source Context + - Read the primary file/module and summarize purpose, exports, key patterns - For folders: list structure, highlight key modules - For functions/APIs: capture signature, parameters, return values, error handling - Extract essential snippets (avoid large dumps) ## Step 4: Analyze Dependencies + - Build a dependency view up to depth 3 - Track visited nodes to avoid loops - Categorize dependencies (imports, function calls, services, external packages) - Note important external systems or generated code that should be excluded ## Step 5: Synthesize Explanation + - Draft an overview (purpose, language, high-level behavior) - Detail core logic, key components, execution flow, patterns - Highlight error handling, performance, security considerations - Identify potential improvements or risks discovered during analysis ## Step 6: Create Documentation + - Normalize entry point name to kebab-case (`calculateTotalPrice` → `calculate-total-price`) - Create `docs/ai/implementation/knowledge-{name}.md` using the headings implied in Step 5 (Overview, Implementation Details, Dependencies, Visual Diagrams, Additional Insights, Metadata, Next Steps) - Populate sections with findings, diagrams, and metadata (analysis date, depth, files touched) - Include mermaid diagrams when they clarify flows or relationships ## Step 7: Review & Next Actions + - Summarize key insights and open questions for follow-up - Suggest related areas for deeper dives or refactors - Confirm the knowledge file path and remind to commit it diff --git a/templates/commands/check-implementation.md b/templates/commands/check-implementation.md index c39eab8..955b43b 100644 --- a/templates/commands/check-implementation.md +++ b/templates/commands/check-implementation.md @@ -1,16 +1,24 @@ +--- +description: Compare implementation with design and requirements documentation +argument-hint: +--- + Compare the current implementation with the design in docs/ai/design/ and requirements in docs/ai/requirements/. Please follow this structured review: 1. Ask me for: + - Feature/branch description - List of modified files - Relevant design doc(s) (feature-specific and/or project-level) - Any known constraints or assumptions 2. For each design doc: + - Summarize key architectural decisions and constraints - Highlight components, interfaces, and data flows that must be respected 3. File-by-file comparison: + - Confirm implementation matches design intent - Note deviations or missing pieces - Flag logic gaps, edge cases, or security issues @@ -18,4 +26,3 @@ Compare the current implementation with the design in docs/ai/design/ and requir - Identify missing tests or documentation updates 4. Summarize findings with recommended next steps. - diff --git a/templates/commands/code-review.md b/templates/commands/code-review.md index f0df076..def06fb 100644 --- a/templates/commands/code-review.md +++ b/templates/commands/code-review.md @@ -1,9 +1,16 @@ +--- +description: Perform a local code review before pushing changes +argument-hint: +--- + # Local Code Review Assistant You are helping me perform a local code review **before** I push changes. Please follow this structured workflow. ## Step 1: Gather Context + Ask me for: + - Brief feature/branch description - List of modified files (with optional summaries) - Relevant design doc(s) (e.g., `docs/ai/design/feature-{name}.md` or project-level design) @@ -12,18 +19,23 @@ Ask me for: - Which tests have already been run If possible, request the latest diff: + ```bash git status -sb git diff --stat ``` ## Step 2: Understand Design Alignment + For each provided design doc: + - Summarize the architectural intent - Note critical requirements, patterns, or constraints the design mandates ## Step 3: File-by-File Review + For every modified file: + 1. Highlight deviations from the referenced design or requirements 2. Spot potential logic or flow issues and edge cases 3. Identify redundant or duplicate code @@ -35,13 +47,16 @@ For every modified file: 9. Flag missing or outdated tests related to this file ## Step 4: Cross-Cutting Concerns + - Verify naming consistency and adherence to project conventions - Confirm documentation/comments are updated where the behavior changed - Identify missing tests (unit, integration, E2E) needed to cover the changes - Ensure configuration/migration updates are captured if applicable ## Step 5: Summarize Findings + Provide results in this structure: + ``` ### Summary - Blocking issues: [count] @@ -69,7 +84,9 @@ Provide results in this structure: ``` ## Step 6: Final Checklist + Confirm whether each item is complete (yes/no/needs follow-up): + - Implementation matches design & requirements - No obvious logic or edge-case gaps remain - Redundant code removed or justified @@ -78,4 +95,5 @@ Confirm whether each item is complete (yes/no/needs follow-up): - Documentation/design notes updated --- + Let me know when you're ready to begin the review. diff --git a/templates/commands/debug.md b/templates/commands/debug.md index a2a1b37..cdb6d66 100644 --- a/templates/commands/debug.md +++ b/templates/commands/debug.md @@ -1,9 +1,16 @@ +--- +description: Debug issues by clarifying expectations and agreeing on fix plans +argument-hint: +--- + # Local Debugging Assistant Help me debug an issue by clarifying expectations, identifying gaps, and agreeing on a fix plan before changing code. ## Step 1: Gather Context + Ask me for: + - Brief issue description (what is happening?) - Expected behavior or acceptance criteria (what should happen?) - Current behavior and any error messages/logs @@ -11,35 +18,40 @@ Ask me for: - Scope of impact (users, services, environments) ## Step 2: Clarify Reality vs Expectation + - Restate the observed behavior vs the expected outcome - Confirm relevant requirements, tickets, or docs that define the expectation - Identify acceptance criteria for the fix (how we know it is resolved) ## Step 3: Reproduce & Isolate + - Determine reproducibility (always, intermittent, environment-specific) - Capture reproduction steps or commands - Note any available tests that expose the failure - List suspected components, services, or modules ## Step 4: Analyze Potential Causes + - Brainstorm plausible root causes (data, config, code regressions, external dependencies) - Gather supporting evidence (logs, metrics, traces, screenshots) - Highlight gaps or unknowns that need investigation ## Step 5: Surface Options + - Present possible resolution paths (quick fix, deeper refactor, rollback, feature flag, etc.) - For each option, list pros/cons, risks, and verification steps - Consider required approvals or coordination ## Step 6: Confirm Path Forward + - Ask which option we should pursue - Summarize chosen approach, required pre-work, and success criteria - Plan validation steps (tests, monitoring, user sign-off) ## Step 7: Next Actions & Tracking + - Document tasks, owners, and timelines for the selected option - Note follow-up actions after deployment (monitoring, comms, postmortem if needed) - Encourage updating relevant docs/tests once resolved Let me know when you're ready to walk through the debugging flow. - diff --git a/templates/commands/execute-plan.md b/templates/commands/execute-plan.md index 73ff6ca..e8798ef 100644 --- a/templates/commands/execute-plan.md +++ b/templates/commands/execute-plan.md @@ -1,9 +1,16 @@ +--- +description: Execute a feature plan interactively, task by task +argument-hint: +--- + # Feature Plan Execution Assistant Help me work through a feature plan one task at a time. ## Step 1: Gather Context + Ask me for: + - Feature name (kebab-case, e.g., `user-authentication`) - Brief feature/branch description - Relevant planning doc path (default `docs/ai/planning/feature-{name}.md`) @@ -11,6 +18,7 @@ Ask me for: - Current branch and latest diff summary (`git status -sb`, `git diff --stat`) ## Step 2: Load the Plan + - Request the planning doc contents or offer commands like: ```bash cat docs/ai/planning/feature-.md @@ -19,16 +27,21 @@ Ask me for: - Build an ordered queue of tasks grouped by section (e.g., Foundation, Core Features, Testing). ## Step 3: Present Task Queue + Show an overview: + ``` ### Task Queue: 1. [status] Section • Task title 2. ... ``` + Status legend: `todo`, `in-progress`, `done`, `blocked` (based on checkbox/notes if present). ## Step 4: Interactive Task Execution + For each task in order: + 1. Display the section/context, full bullet text, and any existing notes. 2. Suggest relevant docs to reference (requirements/design/implementation). 3. Ask: "Plan for this task?" Offer to outline sub-steps using the design doc. @@ -37,17 +50,23 @@ For each task in order: 6. If blocked, record blocker info and move task to the end or into a "Blocked" list. ## Step 5: Update Planning Doc + After each status change, generate a Markdown snippet the user can paste back into the planning doc, e.g.: + ``` - [x] Task: Implement auth service (Notes: finished POST /auth/login, tests added) ``` + Remind the user to keep the source doc updated. ## Step 6: Check for Newly Discovered Work + After each section, ask if new tasks were discovered. If yes, capture them in a "New Work" list with status `todo` and include in the summary. ## Step 7: Session Summary + Produce a summary table: + ``` ### Execution Summary - Completed: (list) @@ -58,7 +77,9 @@ Produce a summary table: ``` ## Step 8: Next Actions + Remind the user to: + - Update `docs/ai/planning/feature-{name}.md` with the new statuses - Sync related docs (requirements/design/implementation/testing) if decisions changed - Run `/check-implementation` to validate changes against design docs @@ -68,4 +89,5 @@ Remind the user to: - Run test suites relevant to completed tasks --- + Let me know when you're ready to start executing the plan. Provide the feature name and planning doc first. diff --git a/templates/commands/new-requirement.md b/templates/commands/new-requirement.md index 1550738..96adf80 100644 --- a/templates/commands/new-requirement.md +++ b/templates/commands/new-requirement.md @@ -1,14 +1,23 @@ +--- +description: Add new feature/requirement and guide through complete development workflow +argument-hint: +--- + I want to add a new feature/requirement. Please guide me through the complete development workflow: ## Step 1: Capture Requirement + First, ask me: + - What is the feature name? (e.g., "user-authentication", "payment-integration") - What problem does it solve? - Who will use it? - What are the key user stories? ## Step 2: Create Feature Documentation Structure + Once I provide the requirement, create the following files (copy the existing template content so sections/frontmatter match exactly): + - Start from `docs/ai/requirements/README.md` → save as `docs/ai/requirements/feature-{name}.md` - Start from `docs/ai/design/README.md` → save as `docs/ai/design/feature-{name}.md` - Start from `docs/ai/planning/README.md` → save as `docs/ai/planning/feature-{name}.md` @@ -18,7 +27,9 @@ Once I provide the requirement, create the following files (copy the existing te Ensure the YAML frontmatter and section headings remain identical to the templates before filling in feature-specific content. ## Step 3: Requirements Phase + Help me fill out `docs/ai/requirements/feature-{name}.md`: + - Clarify the problem statement - Define goals and non-goals - Write detailed user stories @@ -27,7 +38,9 @@ Help me fill out `docs/ai/requirements/feature-{name}.md`: - List open questions ## Step 4: Design Phase + Guide me through `docs/ai/design/feature-{name}.md`: + - Propose system architecture changes needed - Define data models/schema changes - Design API endpoints or interfaces @@ -36,7 +49,9 @@ Guide me through `docs/ai/design/feature-{name}.md`: - Note security and performance considerations ## Step 5: Planning Phase + Help me break down work in `docs/ai/planning/feature-{name}.md`: + - Create task breakdown with subtasks - Identify dependencies (on other features, APIs, etc.) - Estimate effort for each task @@ -44,15 +59,19 @@ Help me break down work in `docs/ai/planning/feature-{name}.md`: - Identify risks and mitigation strategies ## Step 6: Documentation Review (Chained Commands) + Once the docs above are drafted, run the following commands to tighten them up: + - `/review-requirements` to validate the requirements doc for completeness and clarity - `/review-design` to ensure the design doc aligns with requirements and highlights key decisions (If you are using Claude Code, reference the `review-requirements` and `review-design` commands instead.) ## Step 7: Implementation Phase (Deferred) + This command focuses on documentation only. Actual implementation happens later via `/execute-plan`. For each task in the plan: + 1. Review the task requirements and design 2. Ask me to confirm I'm starting this task 3. Guide implementation with reference to design docs @@ -61,7 +80,9 @@ For each task in the plan: 6. Update `docs/ai/implementation/feature-{name}.md` with notes ## Step 8: Testing Phase + Guide testing in `docs/ai/testing/feature-{name}.md`: + - Draft unit test cases with `/writing-test` - Draft integration test scenarios with `/writing-test` - Recommend manual testing steps @@ -69,7 +90,9 @@ Guide testing in `docs/ai/testing/feature-{name}.md`: - Verify all success criteria are testable ## Step 9: Local Testing & Verification + Guide me through: + 1. Running all tests locally 2. Manual testing checklist 3. Reviewing against requirements @@ -77,39 +100,49 @@ Guide me through: 5. Preparing for code review (diff summary, list of files, design references) ## Step 10: Local Code Review (Optional but recommended) + Before pushing, ask me to run `/code-review` with the modified file list and relevant docs. ## Step 11: Implementation Execution Reminder + When ready to implement, run `/execute-plan` to work through the planning doc tasks interactively. That command will orchestrate implementation, testing, and follow-up documentation. ## Step 12: Create Merge/Pull Request + Provide the MR/PR description: + ```markdown ## Feature: [Feature Name] ### Summary + [Brief description of what this feature does] ### Requirements + - Documented in: `docs/ai/requirements/feature-{name}.md` - Related to: [issue/ticket number if applicable] ### Changes + - [List key changes] - [List new files/components] - [List modified files] ### Design + - Architecture: [Link to design doc section] - Key decisions: [Brief summary] ### Testing + - Unit tests: [coverage/status] - Integration tests: [status] - Manual testing: Completed - Test documentation: `docs/ai/testing/feature-{name}.md` ### Checklist + - [ ] Code follows project standards - [ ] All tests pass - [ ] Documentation updated @@ -118,10 +151,10 @@ Provide the MR/PR description: ``` Then provide the appropriate command: + - **GitHub**: `gh pr create --title "feat: [feature-name]" --body-file pr-description.md` - **GitLab**: `glab mr create --title "feat: [feature-name]" --description "$(cat mr-description.md)"` --- **Let's start! Tell me about the feature you want to build.** - diff --git a/templates/commands/review-design.md b/templates/commands/review-design.md index 6fedcb2..da60d4b 100644 --- a/templates/commands/review-design.md +++ b/templates/commands/review-design.md @@ -1,4 +1,10 @@ +--- +description: Review design documentation for completeness and accuracy +argument-hint: +--- + Review the design documentation in docs/ai/design/feature-{name}.md (and the project-level README if relevant). Summarize: + - Architecture overview (ensure mermaid diagram is present and accurate) - Key components and their responsibilities - Technology choices and rationale @@ -8,4 +14,3 @@ Review the design documentation in docs/ai/design/feature-{name}.md (and the pro - Non-functional requirements that must be preserved Highlight any inconsistencies, missing sections, or diagrams that need updates. - diff --git a/templates/commands/review-requirements.md b/templates/commands/review-requirements.md index d2e6b81..a129b94 100644 --- a/templates/commands/review-requirements.md +++ b/templates/commands/review-requirements.md @@ -1,4 +1,10 @@ +--- +description: Review requirements documentation for completeness and alignment +argument-hint: +--- + Please review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize: + - Core problem statement and affected users - Goals, non-goals, and success criteria - Primary user stories & critical flows @@ -6,4 +12,3 @@ Please review `docs/ai/requirements/feature-{name}.md` and the project-level tem - Any missing sections or deviations from the template Identify gaps or contradictions and suggest clarifications. - diff --git a/templates/commands/update-planning.md b/templates/commands/update-planning.md index 911f2ca..941036d 100644 --- a/templates/commands/update-planning.md +++ b/templates/commands/update-planning.md @@ -1,9 +1,16 @@ +--- +description: Update planning documentation to reflect implementation progress +argument-hint: +--- + # Planning Update Assistant Please help me reconcile the current implementation progress with our planning documentation. ## Step 1: Gather Context + Ask me for: + - Feature/branch name and brief status - Tasks completed since last update - Any new tasks discovered @@ -11,20 +18,26 @@ Ask me for: - Relevant planning docs (e.g., `docs/ai/planning/feature-{name}.md`) ## Step 2: Review Planning Doc + If a planning doc exists: + - Summarize existing milestones and task breakdowns - Note expected sequencing and dependencies - Identify outstanding tasks in the plan ## Step 3: Reconcile Progress + For each planned task: + - Mark status (done / in progress / blocked / not started) - Note actual work completed vs. planned scope - Record blockers or changes in approach - Identify tasks that were skipped or added ## Step 4: Update Task List + Help me produce an updated checklist such as: + ``` ### Current Status: [Feature Name] @@ -44,18 +57,21 @@ Help me produce an updated checklist such as: ``` ## Step 5: Next Steps & Priorities + - Suggest the next 2-3 actionable tasks - Highlight risky areas needing attention - Recommend coordination (design changes, stakeholder sync, etc.) - List documentation updates needed ## Step 6: Summary for Planning Doc + Prepare a summary paragraph to copy into the planning doc, covering: + - Current state and progress - Major risks/blockers - Upcoming focus items - Any changes to scope or timeline --- -Let me know when you're ready to begin the planning update. +Let me know when you're ready to begin the planning update. diff --git a/templates/commands/writing-test.md b/templates/commands/writing-test.md index 01c399a..41b853c 100644 --- a/templates/commands/writing-test.md +++ b/templates/commands/writing-test.md @@ -1,7 +1,14 @@ +--- +description: Generate comprehensive test suites targeting 100% coverage +argument-hint: +--- + Review `docs/ai/testing/feature-{name}.md` and ensure it mirrors the base template before writing tests. ## Step 1: Gather Context + Ask me for: + - Feature name and branch - Summary of what changed (link to design & requirements docs) - Target environment (backend, frontend, full-stack) @@ -9,12 +16,15 @@ Ask me for: - Any flaky or slow tests to avoid ## Step 2: Analyze Testing Template + - Identify required sections from `docs/ai/testing/feature-{name}.md` (unit, integration, manual verification, coverage targets) - Confirm success criteria and edge cases from requirements & design docs - Note any mocks/stubs or fixtures already available ## Step 3: Unit Tests (Aim for 100% coverage) + For each module/function: + 1. List behavior scenarios (happy path, edge cases, error handling) 2. Generate concrete test cases with assertions and inputs 3. Reference existing utilities/mocks to accelerate implementation @@ -22,21 +32,25 @@ For each module/function: 5. Highlight potential missing branches preventing full coverage ## Step 4: Integration Tests + 1. Identify critical flows that span multiple components/services 2. Define setup/teardown steps (databases, APIs, queues) 3. Outline test cases validating interaction boundaries, data contracts, and failure modes 4. Suggest instrumentation/logging to debug failures ## Step 5: Coverage Strategy + - Recommend tooling commands (e.g., `npm run test -- --coverage`) - Call out files/functions that still need coverage and why - Suggest additional tests if coverage <100% ## Step 6: Manual & Exploratory Testing + - Propose manual test checklist covering UX, accessibility, and error handling - Identify exploratory scenarios or chaos/failure injection tests if relevant ## Step 7: Update Documentation & TODOs + - Summarize which tests were added or still missing - Update `docs/ai/testing/feature-{name}.md` sections with links to test files and results - Flag follow-up tasks for deferred tests (with owners/dates) diff --git a/web/content/docs/2-supported-agents.md b/web/content/docs/2-supported-agents.md index e7a2322..fe823c3 100644 --- a/web/content/docs/2-supported-agents.md +++ b/web/content/docs/2-supported-agents.md @@ -7,55 +7,82 @@ order: 2 ## Supported Environments ### [Cursor](https://cursor.com/) + **What AI DevKit provides:** + - `AGENTS.md` - Context file with AI agent configurations - `.cursor/commands/` - Custom slash commands for structured development workflows - `.cursor/rules/` - Editor rules for consistent coding standards ### [Claude Code](https://www.claude.com/product/claude-code) + **What AI DevKit provides:** + - `AGENTS.md` - Claude workspace configuration and context - `.claude/commands/` - Command-line tools and scripts optimized for Claude Code ### [GitHub Copilot](https://github.com/features/copilot) + **What AI DevKit provides:** + - `AGENTS.md` - GitHub Copilot configuration and context settings - `.github/commands/` - GitHub-integrated workflow commands ### [Google Gemini](https://geminicli.com/) + **What AI DevKit provides:** + - `AGENTS.md` - Gemini configuration with multimodal context - `.gemini/commands/` - Commands optimized for Gemini's capabilities ### [OpenAI Codex](https://chatgpt.com/en-SE/features/codex) + **What AI DevKit provides:** + - `AGENTS.md` - Codex-specific configuration and context - `.codex/commands/` - Commands tailored for Codex's code-focused capabilities ### [Windsurf](https://windsurf.com/) + **What AI DevKit provides:** + - `AGENTS.md` - Windsurf environment configuration - `.windsurf/commands/` - Commands optimized for Windsurf's interface ### [KiloCode](https://kilocode.ai/) + **What AI DevKit provides:** + - `AGENTS.md` - KiloCode configuration for large project handling - `.kilocode/commands/` - Commands designed for large-scale development ### [AMP](https://ampcode.com/) + **What AI DevKit provides:** + - `AGENTS.md` - AMP configuration for accelerated workflows - `.agents/commands/` - Commands optimized for rapid development cycles ### [OpenCode](https://opencode.ai/) + **What AI DevKit provides:** + - `AGENTS.md` - OpenCode configuration with community features - `.opencode/commands/` - Commands leveraging open-source AI improvements ### [Roo Code](https://roocode.com/) + **What AI DevKit provides:** -- `AGENTS.md` - Roo Code configuration and context -- `.roo/commands/` - Commands optimized for Roo's advanced features + +- `AGENTS.md` - Roo Code configuration and context at project root +- `.roo/commands/` - Slash commands with frontmatter support (description, argument-hint) + +**Roo Code Features:** + +- Slash commands with fuzzy search and auto-complete +- Frontmatter metadata for descriptions and argument hints +- Project-specific commands in `.roo/commands/` +- Context file at project root for easy access ## Environment Setup @@ -68,6 +95,7 @@ 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 @@ -95,6 +123,7 @@ ai-devkit init ``` AI DevKit will: + 1. Detect existing environments 2. Show confirmation prompts for overwriting 3. Add new environments alongside existing ones @@ -116,4 +145,4 @@ AI DevKit welcomes contributions for new AI development environments. To add sup 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 +4. **Test Integration**: Ensure proper initialization and configuration