From b835a4675ac9c7eda38f13685db0659a8adad5d3 Mon Sep 17 00:00:00 2001 From: 2witstudios <2witstudios@gmail.com> Date: Tue, 13 Jan 2026 00:34:28 -0600 Subject: [PATCH] refactor: migrate from commands/rules to Skills Protocol - Remove legacy ai/commands/ and ai/rules/ directories - Add ai/skills/aidd/ with Skills Protocol structure - Introduce SKILL.md as main orchestrator replacing agent-orchestrator.mdc - Convert .mdc files to .md format with proper Skills Protocol headers - Organize references under ai/skills/aidd/references/ - Update README.md with new directory structure and paths - Update CONTRIBUTING.md and AGENTS.md for skills format - Update tests to reflect new file structure - Add docs/commands_to_skills.md migration guide BREAKING CHANGE: ai/commands/ and ai/rules/ replaced by ai/skills/ --- .github/pull_request_template.md | 4 +- AGENTS.md | 26 +++- CONTRIBUTING.md | 9 +- README.md | 86 +++++++------ ai/commands/discover.md | 8 -- ai/commands/execute.md | 8 -- ai/commands/help.md | 8 -- ai/commands/index.md | 66 ---------- ai/commands/log.md | 4 - ai/commands/plan.md | 4 - ai/commands/review.md | 7 -- ai/commands/run-test.md | 11 -- ai/commands/task.md | 8 -- ai/commands/user-test.md | 7 -- ai/index.md | 8 +- ai/rules/agent-orchestrator.mdc | 45 ------- ai/rules/frameworks/redux/index.md | 18 --- ai/rules/index.md | 96 --------------- ai/rules/javascript/index.md | 24 ---- ai/rules/please.mdc | 56 --------- ai/rules/security/index.md | 24 ---- ai/skills/aidd/SKILL.md | 95 +++++++++++++++ ai/{commands => skills/aidd}/commit.md | 8 +- ai/skills/aidd/discover.md | 13 ++ ai/skills/aidd/execute.md | 13 ++ ai/skills/aidd/help.md | 13 ++ ai/skills/aidd/index.md | 78 ++++++++++++ ai/skills/aidd/log.md | 10 ++ ai/skills/aidd/plan.md | 10 ++ .../aidd/references/autodux-example.md} | 10 +- .../aidd/references/autodux.md} | 10 +- .../aidd/references/code-review-example.md} | 4 +- .../aidd/references/code-review.md} | 26 ++-- .../aidd/references/error-causes.md} | 10 +- ai/skills/aidd/references/index.md | 114 ++++++++++++++++++ .../aidd/references/javascript-io.md} | 16 ++- .../aidd/references/javascript.md} | 12 +- .../aidd/references/jwt-security.md} | 10 +- .../log.mdc => skills/aidd/references/log.md} | 8 +- .../aidd/references/product-manager.md} | 9 +- .../aidd/references/requirements.md} | 6 +- .../aidd/references/stack.md} | 12 +- .../aidd/references/task-creator.md} | 14 +-- .../tdd.mdc => skills/aidd/references/tdd.md} | 13 +- .../aidd/references/timing-safe-compare.md} | 9 +- .../references/timing-vulnerabilities.md} | 7 +- .../ui.mdc => skills/aidd/references/ui.md} | 9 +- .../aidd/references/user-testing.md} | 10 +- .../aidd/references}/user-testing.test.js | 91 +++++++------- ai/skills/aidd/review.md | 14 +++ ai/skills/aidd/run-test.md | 16 +++ ai/skills/aidd/task.md | 13 ++ ai/skills/aidd/user-test.md | 12 ++ ai/{rules/frameworks => skills}/index.md | 6 +- docs/commands_to_skills.md | 84 +++++++++++++ docs/new-project-setup-nextjs-shadcn.md | 8 +- docs/security.md | 4 +- lib/agents-index-e2e.test.js | 30 ++--- lib/index-generator.test.js | 14 +-- plan/story-map/review-command-journey.yaml | 2 +- 60 files changed, 718 insertions(+), 652 deletions(-) delete mode 100644 ai/commands/discover.md delete mode 100644 ai/commands/execute.md delete mode 100644 ai/commands/help.md delete mode 100644 ai/commands/index.md delete mode 100644 ai/commands/log.md delete mode 100644 ai/commands/plan.md delete mode 100644 ai/commands/review.md delete mode 100644 ai/commands/run-test.md delete mode 100644 ai/commands/task.md delete mode 100644 ai/commands/user-test.md delete mode 100644 ai/rules/agent-orchestrator.mdc delete mode 100644 ai/rules/frameworks/redux/index.md delete mode 100644 ai/rules/index.md delete mode 100644 ai/rules/javascript/index.md delete mode 100644 ai/rules/please.mdc delete mode 100644 ai/rules/security/index.md create mode 100644 ai/skills/aidd/SKILL.md rename ai/{commands => skills/aidd}/commit.md (71%) create mode 100644 ai/skills/aidd/discover.md create mode 100644 ai/skills/aidd/execute.md create mode 100644 ai/skills/aidd/help.md create mode 100644 ai/skills/aidd/index.md create mode 100644 ai/skills/aidd/log.md create mode 100644 ai/skills/aidd/plan.md rename ai/{rules/frameworks/redux/example.mdc => skills/aidd/references/autodux-example.md} (80%) rename ai/{rules/frameworks/redux/autodux.mdc => skills/aidd/references/autodux.md} (94%) rename ai/{rules/review-example.md => skills/aidd/references/code-review-example.md} (99%) rename ai/{rules/review.mdc => skills/aidd/references/code-review.md} (68%) rename ai/{rules/javascript/error-causes.mdc => skills/aidd/references/error-causes.md} (96%) create mode 100644 ai/skills/aidd/references/index.md rename ai/{rules/javascript/javascript-io-network-effects.mdc => skills/aidd/references/javascript-io.md} (92%) rename ai/{rules/javascript/javascript.mdc => skills/aidd/references/javascript.md} (94%) rename ai/{rules/security/jwt-security.mdc => skills/aidd/references/jwt-security.md} (96%) rename ai/{rules/log.mdc => skills/aidd/references/log.md} (91%) rename ai/{rules/productmanager.mdc => skills/aidd/references/product-manager.md} (94%) rename ai/{rules/requirements.mdc => skills/aidd/references/requirements.md} (73%) rename ai/{rules/stack.mdc => skills/aidd/references/stack.md} (80%) rename ai/{rules/task-creator.mdc => skills/aidd/references/task-creator.md} (93%) rename ai/{rules/tdd.mdc => skills/aidd/references/tdd.md} (85%) rename ai/{rules/security/timing-safe-compare.mdc => skills/aidd/references/timing-safe-compare.md} (86%) rename ai/{rules/security/timing-safe-compare-vulnerabilities.mdc => skills/aidd/references/timing-vulnerabilities.md} (93%) rename ai/{rules/ui.mdc => skills/aidd/references/ui.md} (83%) rename ai/{rules/user-testing.mdc => skills/aidd/references/user-testing.md} (95%) rename ai/{rules => skills/aidd/references}/user-testing.test.js (51%) create mode 100644 ai/skills/aidd/review.md create mode 100644 ai/skills/aidd/run-test.md create mode 100644 ai/skills/aidd/task.md create mode 100644 ai/skills/aidd/user-test.md rename ai/{rules/frameworks => skills}/index.md (51%) create mode 100644 docs/commands_to_skills.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a0d4993..945c258 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,7 +1,7 @@ diff --git a/AGENTS.md b/AGENTS.md index 2b2efde..6375fcf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,16 +1,30 @@ # AI Agent Guidelines -This project uses AI-assisted development with structured guidance in the `ai/` directory. +This project uses AI-assisted development with the AIDD Skills Protocol. -## Directory Structure +## Skills Location -Agents should examine the `ai/*` directory listings to understand the available commands, rules, and workflows. +All AI guidance is located in `ai/skills/aidd/`: -## Index Files +- `SKILL.md` - Main skill definition with commands and orchestration +- `references/` - Domain guidance files (TDD, code review, JS best practices, etc.) -Each folder in the `ai/` directory contains an `index.md` file that describes the purpose and contents of that folder. Agents can read these index files to learn the function of files in each folder without needing to read every file. +## Commands -**Important:** The `ai/**/index.md` files are auto-generated from frontmatter. Do not create or edit these files manuallyβ€”they will be overwritten by the pre-commit hook. +Commands are defined as skills in `ai/skills/aidd/` and invoked via slash commands: + +| Command | Description | +|---------|-------------| +| `/help` | List available commands | +| `/log` | Log completed epics to activity-log.md | +| `/commit` | Commit using conventional format | +| `/plan` | Review plan.md and suggest next steps | +| `/discover` | Product discovery for user journeys | +| `/task` | Create and plan a task epic | +| `/execute` | Execute a task epic | +| `/review` | Conduct code review | +| `/user-test` | Generate test scripts from user journeys | +| `/run-test` | Execute AI agent test script | ## Progressive Discovery diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a55f14..da02dd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ See the [Development Workflow](README.md#development-workflow) section in the RE ### JavaScript/TypeScript -- Follow the guidelines in `ai/rules/javascript/javascript.mdc` +- Follow the guidelines in `ai/skills/aidd/references/javascript.md` - Use functional programming patterns - Keep functions small, pure, and composable - Use `const`, avoid mutation @@ -34,7 +34,7 @@ See the [Development Workflow](README.md#development-workflow) section in the RE ### Commit Messages -Follow conventional commit format (see `ai/commands/commit.md`): +Follow conventional commit format (see `ai/skills/aidd/commit.md`): ``` type(scope): description @@ -52,7 +52,7 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `perf`, `ci`, `build` 1. Ensure all tests pass (`npm test`) 2. Update documentation if needed -3. Follow the code review guidelines in `ai/rules/review.mdc` +3. Follow the code review guidelines in `ai/skills/aidd/references/code-review.md` 4. Address review feedback promptly 5. Squash commits if requested 6. Wait for approval from maintainers @@ -60,10 +60,9 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `perf`, `ci`, `build` ## Questions or Issues? - Check existing [issues](https://github.com/paralleldrive/aidd/issues) -- Review the AI rules in `ai/rules/` for guidance +- Review the AI skills in `ai/skills/aidd/references/` for guidance - Ask questions in your PR or open a discussion ## License By contributing, you agree that your contributions will be licensed under the MIT License. - diff --git a/README.md b/README.md index 428fa8e..635ff03 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ Includes: - [Examples](#examples) - [πŸ“ AI System Structure](#-ai-system-structure) - [Key Components](#key-components) + - [Skills Protocol](#skills-protocol) - [🎯 AI Integration](#-ai-integration) - [πŸ“‹ Vision Document](#-vision-document) - [Why You Need a Vision Document](#why-you-need-a-vision-document) @@ -68,6 +69,8 @@ AIDD Framework is a collection of reusable metaprograms, agent orchestration sys /log - log the changes to the activity log /commit - commit the changes to the repository /user-test - generate user testing scripts for post-deploy validation +/run-test - execute AI agent test script in real browser +/help - list all available commands ``` ## πŸš€ Quick Start with AIDD CLI @@ -120,19 +123,19 @@ npx aidd my-project ```bash cd my-project - ls ai/ # See available components - cat ai/rules/please.mdc # Read the main orchestrator + ls ai/ # See available components + cat ai/skills/aidd/SKILL.md # Read the main skill definition ``` 5. **Start using AI workflows**: - - Reference `ai/rules/` in AI prompts for better context - - Use `ai/commands/` as workflow templates - - Customize rules for your specific project needs + - Reference `ai/skills/aidd/references/` in AI prompts for better context + - Use `ai/skills/aidd/` as workflow templates + - Customize skills for your specific project needs This gives you immediate access to: -- πŸ€– **Agent orchestration rules** (`ai/rules/`) -- βš™οΈ **AI workflow commands** (`ai/commands/`) +- πŸ€– **Skills Protocol** (`ai/skills/aidd/`) +- βš™οΈ **AI workflow commands** (`ai/skills/aidd/`) - πŸ“‹ **Development best practices** (JavaScript, TDD, UI/UX) - 🎯 **Product management tools** (user stories, journey mapping) @@ -418,20 +421,26 @@ After running the CLI, you'll have a complete `ai/` folder: ``` your-project/ β”œβ”€β”€ ai/ -β”‚ β”œβ”€β”€ commands/ # Workflow commands -β”‚ β”‚ β”œβ”€β”€ help.md # List available commands -β”‚ β”‚ β”œβ”€β”€ plan.md # Project planning -β”‚ β”‚ β”œβ”€β”€ review.md # Code reviews -β”‚ β”‚ β”œβ”€β”€ task.md # Task management -β”‚ β”‚ └── ... -β”‚ β”œβ”€β”€ rules/ # Agent orchestration rules -β”‚ β”‚ β”œβ”€β”€ agent-orchestrator.mdc -β”‚ β”‚ β”œβ”€β”€ javascript/ # JS/TS best practices -β”‚ β”‚ β”œβ”€β”€ frameworks/ # Redux, TDD patterns -β”‚ β”‚ β”œβ”€β”€ productmanager.mdc -β”‚ β”‚ β”œβ”€β”€ tdd.mdc -β”‚ β”‚ β”œβ”€β”€ ui.mdc +β”‚ β”œβ”€β”€ commands/ # Legacy command references (deprecated) β”‚ β”‚ └── ... +β”‚ β”œβ”€β”€ skills/ # Skills Protocol (primary) +β”‚ β”‚ └── aidd/ +β”‚ β”‚ β”œβ”€β”€ SKILL.md # Main skill orchestrator +β”‚ β”‚ β”œβ”€β”€ help.md # /help skill +β”‚ β”‚ β”œβ”€β”€ log.md # /log skill +β”‚ β”‚ β”œβ”€β”€ commit.md # /commit skill +β”‚ β”‚ β”œβ”€β”€ plan.md # /plan skill +β”‚ β”‚ β”œβ”€β”€ discover.md # /discover skill +β”‚ β”‚ β”œβ”€β”€ task.md # /task skill +β”‚ β”‚ β”œβ”€β”€ execute.md # /execute skill +β”‚ β”‚ β”œβ”€β”€ review.md # /review skill +β”‚ β”‚ β”œβ”€β”€ user-test.md # /user-test skill +β”‚ β”‚ β”œβ”€β”€ run-test.md # /run-test skill +β”‚ β”‚ └── references/ # Domain guidance files +β”‚ β”‚ β”œβ”€β”€ javascript.md +β”‚ β”‚ β”œβ”€β”€ tdd.md +β”‚ β”‚ β”œβ”€β”€ ui.md +β”‚ β”‚ └── ... β”‚ └── ... β”œβ”€β”€ plan/ # Product discovery artifacts β”‚ β”œβ”€β”€ story-map/ # User journeys & personas (YAML) @@ -442,13 +451,22 @@ your-project/ ### Key Components -- **Agent Orchestrator** (`ai/rules/agent-orchestrator.mdc`) - Coordinates multiple AI agents -- **Development Rules** (`ai/rules/javascript/`, `ai/rules/tdd.mdc`) - Best practices and patterns -- **Workflow Commands** (`ai/commands/`) - Structured AI interaction templates -- **Product Management** (`ai/rules/productmanager.mdc`) - User stories and journey mapping +- **AIDD Skill Orchestrator** (`ai/skills/aidd/SKILL.md`) - Main skill definition that orchestrates all commands +- **Individual Skill Commands** (`ai/skills/aidd/*.md`) - Skill files for each command (e.g., `commit.md`, `task.md`) +- **Development References** (`ai/skills/aidd/references/`) - Best practices (JavaScript, TDD, UI/UX) +- **Product Management** (`ai/skills/aidd/references/product-manager.md`) - User stories and journey mapping - **Product Discovery Artifacts** (`plan/story-map/`) - User journeys, personas, and story maps (YAML format) - **User Testing Scripts** (`plan/`) - Human and AI agent test scripts generated from journeys -- **UI/UX Guidelines** (`ai/rules/ui.mdc`) - Design and user experience standards +- **UI/UX Guidelines** (`ai/skills/aidd/references/ui.md`) - Design and user experience standards + +### Skills Protocol + +All AIDD commands use the Claude Code Skills Protocol. Each skill has: +- A `name` field matching the invocation pattern (e.g., `commit`, `task`) +- A `description` field with trigger keywords for automatic activation +- References to implementation files in `references/` + +See [docs/commands_to_skills.md](docs/commands_to_skills.md) for the complete parity table. ## 🎯 AI Integration @@ -571,21 +589,21 @@ npx aidd my-project **For Cursor users with existing rules:** -Reference the rules in your prompts or add to `.cursor/rules`: +Reference the skills in your prompts or add to `.cursor/rules`: ``` -See ai/rules/javascript/javascript.mdc for JavaScript best practices -See ai/rules/tdd.mdc for test-driven development -See ai/rules/productmanager.mdc for product management +See ai/skills/aidd/references/javascript.md for JavaScript best practices +See ai/skills/aidd/references/tdd.md for test-driven development +See ai/skills/aidd/references/product-manager.md for product management ``` **For other editors (VS Code, Vim, etc.):** -Reference rules directly in your AI assistant prompts: +Reference skills directly in your AI assistant prompts: ``` -Please follow the guidelines in ai/rules/javascript/javascript.mdc -Use the workflow from ai/commands/task.md +Please follow the guidelines in ai/skills/aidd/references/javascript.md +Use the workflow from ai/skills/aidd/task.md ``` ### Troubleshooting @@ -597,8 +615,8 @@ Use the workflow from ai/commands/task.md ls ai/ # Verify key files exist -ls ai/rules/please.mdc -ls ai/commands/ +ls ai/skills/aidd/SKILL.md +ls ai/skills/aidd/ ``` **Common Issues** diff --git a/ai/commands/discover.md b/ai/commands/discover.md deleted file mode 100644 index f41709e..0000000 --- a/ai/commands/discover.md +++ /dev/null @@ -1,8 +0,0 @@ -## πŸ” Discover - -Use productmanager.mdc to discover a user journey, user story, or feature. - -Constraints { -Begin by reading the file and asking the user relevant questions to spark the discovery process. -Before beginning, read and respect the constraints in please.mdc. -} diff --git a/ai/commands/execute.md b/ai/commands/execute.md deleted file mode 100644 index 70c62eb..0000000 --- a/ai/commands/execute.md +++ /dev/null @@ -1,8 +0,0 @@ -## βš™οΈ Execute Task/Epic - -Use the task creator to execute a task epic. - -Constraints { -Before beginning, read and respect the constraints in please.mdc. -Remember to use the TDD process if asked to implement code. -} diff --git a/ai/commands/help.md b/ai/commands/help.md deleted file mode 100644 index 529d4c6..0000000 --- a/ai/commands/help.md +++ /dev/null @@ -1,8 +0,0 @@ -## ❓ Help - -List commands from please.mdc and report them to the user. - -Constraints { -Before beginning, read and respect the constraints in please.mdc. -Keep the response extremely concise - essentially just the list of commands, their descriptions, and options, without offering trivial details or informing users of constraints. -} diff --git a/ai/commands/index.md b/ai/commands/index.md deleted file mode 100644 index f728833..0000000 --- a/ai/commands/index.md +++ /dev/null @@ -1,66 +0,0 @@ -# commands - -This index provides an overview of the contents in this directory. - -## Files - -### Commit - -**File:** `commit.md` - -*No description available* - -### discover - -**File:** `discover.md` - -*No description available* - -### execute - -**File:** `execute.md` - -*No description available* - -### help - -**File:** `help.md` - -*No description available* - -### log - -**File:** `log.md` - -*No description available* - -### plan - -**File:** `plan.md` - -*No description available* - -### πŸ”¬ Code Review - -**File:** `review.md` - -*No description available* - -### run-test - -**File:** `run-test.md` - -*No description available* - -### task - -**File:** `task.md` - -*No description available* - -### user-test - -**File:** `user-test.md` - -*No description available* - diff --git a/ai/commands/log.md b/ai/commands/log.md deleted file mode 100644 index 18ae367..0000000 --- a/ai/commands/log.md +++ /dev/null @@ -1,4 +0,0 @@ -## πŸ“ Log - -Use log.mdc to collect salient changes, and log them to the activity-log.md. -Before beginning, read and respect the constraints in please.mdc. diff --git a/ai/commands/plan.md b/ai/commands/plan.md deleted file mode 100644 index 9cef037..0000000 --- a/ai/commands/plan.md +++ /dev/null @@ -1,4 +0,0 @@ -## πŸ“‹ Plan - -Review plan.md to identify priorities and suggest next steps to the user -d 10. -Before beginning, read and respect the constraints in please.mdc. diff --git a/ai/commands/review.md b/ai/commands/review.md deleted file mode 100644 index 4d5c1e7..0000000 --- a/ai/commands/review.md +++ /dev/null @@ -1,7 +0,0 @@ -# πŸ”¬ Code Review - -use review.mdc to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards. - -Constraints { -Before beginning, read and respect the constraints in please.mdc. -} diff --git a/ai/commands/run-test.md b/ai/commands/run-test.md deleted file mode 100644 index 2ab4690..0000000 --- a/ai/commands/run-test.md +++ /dev/null @@ -1,11 +0,0 @@ -## πŸ€– Run Test - -Execute AI agent test script in real browser. - -Use @user-testing.mdc to run agent test, capturing screenshots and generating report. - -Constraints { - Before beginning, read and respect the constraints in please.mdc. - Drive real browser, narrate thoughts like human tester. - Generate structured markdown report with screenshots. -} diff --git a/ai/commands/task.md b/ai/commands/task.md deleted file mode 100644 index c17684d..0000000 --- a/ai/commands/task.md +++ /dev/null @@ -1,8 +0,0 @@ -## βœ… Task - -Use the task creator to plan and execute a task epic. - -Constraints { -Before beginning, read and respect the constraints in please.mdc. -Remember to use the TDD process if asked to implement code. -} diff --git a/ai/commands/user-test.md b/ai/commands/user-test.md deleted file mode 100644 index ac0fb65..0000000 --- a/ai/commands/user-test.md +++ /dev/null @@ -1,7 +0,0 @@ -## πŸ§ͺ User Test - -Use @user-testing.mdc to generate human and AI agent test scripts from user journeys. - -Constraints { -Before beginning, read and respect the constraints in please.mdc. -} diff --git a/ai/index.md b/ai/index.md index 0419529..cd4f729 100644 --- a/ai/index.md +++ b/ai/index.md @@ -4,11 +4,7 @@ This index provides an overview of the contents in this directory. ## Subdirectories -### πŸ“ commands/ +### πŸ“ skills/ -See [`commands/index.md`](./commands/index.md) for contents. - -### πŸ“ rules/ - -See [`rules/index.md`](./rules/index.md) for contents. +See [`skills/index.md`](./skills/index.md) for contents. diff --git a/ai/rules/agent-orchestrator.mdc b/ai/rules/agent-orchestrator.mdc deleted file mode 100644 index 16703ec..0000000 --- a/ai/rules/agent-orchestrator.mdc +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: Senior software engineer, product manager, project manager, and technical writer assistant with reflective thinking -globs: -alwaysApply: true ---- -# Aiden Agent Orchestrator - -Act as a top-tier software engineer, product manager, project manager, and technical writer assistant with reflective thinking. Your job is to assist with software development projects. - -userRequestIncludes => - please => please.mdc - -You are an agent orchestrator. You are responsible for coordinating the actions of the other agents, which are all available in `$projectRoot/ai/**/*.mdc` files: - -Agents { - please: when user says "please", use this guide for general assistance, logging, committing, and proofing tasks - stack: when implementing NextJS + React/Redux + Shadcn UI features, use this guide for tech stack guidance and best practices - productmanager: when planning features, user stories, user journeys, or conducting product discovery, use this guide for building specifications and user journey maps - tdd: when implementing code changes, use this guide for systematic test-driven development with proper test isolation - javascript: when writing JavaScript or TypeScript code, use this guide for JavaScript best practices and guidance - log: when documenting changes, use this guide for creating structured change logs with emoji categorization - commit: when committing code, use this guide for conventional commit format with proper message structure - autodux: when building Redux state management, use this guide for creating and transpiling Autodux dux objects - javascript-io-network-effects: when you need to make network requests or invoke side-effects, use this guide for saga pattern implementation - ui: when building user interfaces and user experiences, use this guide for beautiful and friendly UI/UX design - requirements: when writing functional requirements for a user story, use this guide for functional requirement specification -} - -const taskPrompt = "# Guides\n\nRead each of the following guides for important context, and follow their instructions carefully: ${list guide file refs in markdown format}\n\n# User Prompt\n\n${prompt}" - -withCLI() { - `cursor-agent --agent ${agent} --prompt $taskPrompt` -} - -directExecution() { - prompt yourself with the $taskPrompt: -} - -handleInitialRequest() { - use taskCreator to create and execute a task plan - match (contextRequirements = infer) { - > 1 guide => use withCLI - default => use directExecution - } -} diff --git a/ai/rules/frameworks/redux/index.md b/ai/rules/frameworks/redux/index.md deleted file mode 100644 index 133d240..0000000 --- a/ai/rules/frameworks/redux/index.md +++ /dev/null @@ -1,18 +0,0 @@ -# redux - -This index provides an overview of the contents in this directory. - -## Files - -### Autodux - -**File:** `autodux.mdc` - -When building Redux state management, use this guide for creating and transpiling Autodux dux objects - -### example - -**File:** `example.mdc` - -Autodux usage example showing Todo App implementation in SudoLang - diff --git a/ai/rules/index.md b/ai/rules/index.md deleted file mode 100644 index da91dcb..0000000 --- a/ai/rules/index.md +++ /dev/null @@ -1,96 +0,0 @@ -# rules - -This index provides an overview of the contents in this directory. - -## Subdirectories - -### πŸ“ frameworks/ - -See [`frameworks/index.md`](./frameworks/index.md) for contents. - -### πŸ“ javascript/ - -See [`javascript/index.md`](./javascript/index.md) for contents. - -### πŸ“ security/ - -See [`security/index.md`](./security/index.md) for contents. - -## Files - -### Aiden Agent Orchestrator - -**File:** `agent-orchestrator.mdc` - -Senior software engineer, product manager, project manager, and technical writer assistant with reflective thinking - -**Always active** - -### log - -**File:** `log.mdc` - -When documenting changes, use this guide for creating structured change logs with emoji categorization - -### Aiden - -**File:** `please.mdc` - -When user says "please", use this guide for general assistance, logging, committing, and proofing tasks - -**Always active** - -### ProductManager - -**File:** `productmanager.mdc` - -When planning features, user stories, user journeys, or conducting product discovery, use this guide for building specifications and user journey maps - -### Functional requirements - -**File:** `requirements.mdc` - -When writing functional requirements for a user story, use this guide for functional requirement specification - -### πŸ”¬ **COMPREHENSIVE CODE REVIEW: Release Latest Tag Epic** - -**File:** `review-example.md` - -*No description available* - -### πŸ”¬ Code Review - -**File:** `review.mdc` - -Use this guide to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards. - -### Tech Stack - -**File:** `stack.mdc` - -When implementing NextJS + React/Redux + Shadcn UI features, use this guide for tech stack guidance and best practices - -### Task Creator - -**File:** `task-creator.mdc` - -when the user asks you to complete a task, use this guide for systematic task/epic planning and execution - -### TDD Engineer - -**File:** `tdd.mdc` - -*No description available* - -### UI/UX Engineer - -**File:** `ui.mdc` - -When building user interfaces and user experiences, use this guide for beautiful and friendly UI/UX design - -### User Testing Generator - -**File:** `user-testing.mdc` - -Generate human and AI agent test scripts from user journey specifications - diff --git a/ai/rules/javascript/index.md b/ai/rules/javascript/index.md deleted file mode 100644 index e4cc0a4..0000000 --- a/ai/rules/javascript/index.md +++ /dev/null @@ -1,24 +0,0 @@ -# javascript - -This index provides an overview of the contents in this directory. - -## Files - -### Error Causes Rule - -**File:** `error-causes.mdc` - -*No description available* - -### JavaScript IO Guide - -**File:** `javascript-io-network-effects.mdc` - -When you need to make network requests or invoke side-effects, use this guide for saga pattern implementation - -### JavaScript/TypeScript guide - -**File:** `javascript.mdc` - -*No description available* - diff --git a/ai/rules/please.mdc b/ai/rules/please.mdc deleted file mode 100644 index 8b2b3db..0000000 --- a/ai/rules/please.mdc +++ /dev/null @@ -1,56 +0,0 @@ ---- -description: When user says "please", use this guide for general assistance, logging, committing, and proofing tasks -alwaysApply: true ---- -# Aiden - -Act as a top-tier senior software engineer, product manager, project manager, and technical writer. Your job is to assist with software development projects. - -## About You - -You are a SoTA AI agent system with access to advanced tools and computational resources. Gigs of memory, the best models and GPUs, and all the time you need to accomplish anything the user asks. You got this! 🦾 - - -Think() deeply when a complex task is presented. -Read the project README.md and stack.mdc before responding. - -UnrecognizedCommand => check the agent orchestrator for relevant instructions. - - -# Thinking: Reflective Thought Composition (RTC) - -fn think() { - show your work: - 🎯 restate |>πŸ’‘ ideate |> πŸͺž reflectCritically |> πŸ”­ expandOrthogonally |> βš–οΈ scoreRankEvaluate |> πŸ’¬ respond - - Constraints { - Keep the thinking process concise, compact, and information-dense, ranging from a few words per step (d=1) to a few bullet points per step (d = 10). - } -} - -Options { - --depth | -d [1..10] - Set response depth. 1 = ELIF, 10 = prep for PhD -} - -Commands { - ❓ /help - List commands from please.mdc and report the available commands to the user without modifying any files - πŸ“ /log - use log.mdc to collect salient changes, and log them to the activity-log.md. - πŸ’Ύ /commit - use commit.md to commit the changes to the repository. - πŸ“‹ /plan - review plan.md to identify priorities and suggest next steps to the user -d 10 - πŸ” /discover - use productmanager.mdc to discover a user journey, user story, or feature. - βœ… /task - use the task creator to plan and execute a task epic - βš™οΈ /execute - use the task creator to execute a task epic - πŸ”¬ /review - conduct a thorough code review focusing on code quality, best practices, and adherence to project standards - πŸ§ͺ /user-test - use user-testing.mdc to generate human and AI agent test scripts from user journeys - πŸ€– /run-test - execute AI agent test script in real browser with screenshots -} - -Constraints { - When executing commands, do not modify any files unless the command explicitly requires it or the user explicitly asks you to. Instead, focus your interactions on the chat. - - When executing commands, show the command name and emoji to the user chat. - - Do ONE THING at a time, get user approval before moving on. - - BEFORE attempting to use APIs for which you are not 99.9% confident, try looking at the documentation for it in the installed module README, or use web search if necessary. -} \ No newline at end of file diff --git a/ai/rules/security/index.md b/ai/rules/security/index.md deleted file mode 100644 index a1e216c..0000000 --- a/ai/rules/security/index.md +++ /dev/null @@ -1,24 +0,0 @@ -# security - -This index provides an overview of the contents in this directory. - -## Files - -### JWT Security Review - -**File:** `jwt-security.mdc` - -JWT security review - flag insecure patterns - -### Timing Safe Compare Vulnerabilities - -**File:** `timing-safe-compare-vulnerabilities.mdc` - -Vulnerability reports for timing-safe compare functions. Referenced by timing-safe-compare.mdc. - -### Constraint: Timing Safe Compare - -**File:** `timing-safe-compare.mdc` - -Security rule for timing-safe secret comparison. Use SHA3-256 hashing instead of timing-safe compare functions. - diff --git a/ai/skills/aidd/SKILL.md b/ai/skills/aidd/SKILL.md new file mode 100644 index 0000000..a6ccbe2 --- /dev/null +++ b/ai/skills/aidd/SKILL.md @@ -0,0 +1,95 @@ +--- +name: aidd +description: Use when user says "please", invokes AIDD commands (/help, /log, /commit, /plan, /discover, /task, /execute, /review, /user-test, /run-test), mentions task epics, RTC thinking, "Given/should" requirements, TDD development, product discovery, user journeys, code review, or NextJS/React/Redux/Shadcn development. AI-Driven Development framework for systematic software engineering. Always applies. +--- + +# Aiden + +Act as a top-tier senior software engineer, product manager, project manager, and technical writer. Your job is to assist with software development projects. + +## About You + +You are a SoTA AI agent system with access to advanced tools and computational resources. Gigs of memory, the best models and GPUs, and all the time you need to accomplish anything the user asks. You got this! + +Think() deeply when a complex task is presented. +Read the project README.md and stack.md before responding. + +UnrecognizedCommand => check the agent orchestrator for relevant instructions. + + +# Thinking: Reflective Thought Composition (RTC) + +fn think() { + show your work: + 🎯 restate |>πŸ’‘ ideate |> πŸͺž reflectCritically |> πŸ”­ expandOrthogonally |> βš–οΈ scoreRankEvaluate |> πŸ’¬ respond + + Constraints { + Keep the thinking process concise, compact, and information-dense, ranging from a few words per step (d=1) to a few bullet points per step (d = 10). + } +} + +Options { + --depth | -d [1..10] - Set response depth. 1 = ELIF, 10 = prep for PhD +} + +Commands { + ❓ /help - List commands and report the available commands to the user without modifying any files + πŸ“ /log - use log.md to collect salient changes, and log them to the activity-log.md. + πŸ’Ύ /commit - use commit.md to commit the changes to the repository. + πŸ“‹ /plan - review plan.md to identify priorities and suggest next steps to the user -d 10 + πŸ” /discover - use product-manager.md to discover a user journey, user story, or feature. + βœ… /task - use the task creator to plan and execute a task epic + βš™οΈ /execute - use the task creator to execute a task epic + πŸ”¬ /review - conduct a thorough code review focusing on code quality, best practices, and adherence to project standards + πŸ§ͺ /user-test - use user-testing.md to generate human and AI agent test scripts from user journeys + πŸ€– /run-test - execute AI agent test script in real browser with screenshots +} + +Constraints { + When executing commands, do not modify any files unless the command explicitly requires it or the user explicitly asks you to. Instead, focus your interactions on the chat. + + When executing commands, show the command name and emoji to the user chat. + + Do ONE THING at a time, get user approval before moving on. + + BEFORE attempting to use APIs for which you are not 99.9% confident, try looking at the documentation for it in the installed module README, or use web search if necessary. +} + + +# Aiden Agent Orchestrator + +You are an agent orchestrator. You are responsible for coordinating the actions of the other agents, which are all available in reference files: + +Agents { + please: when user says "please", use this guide for general assistance, logging, committing, and proofing tasks + stack: when implementing NextJS + React/Redux + Shadcn UI features, use stack.md for tech stack guidance and best practices + productmanager: when planning features, user stories, user journeys, or conducting product discovery, use product-manager.md for building specifications and user journey maps + tdd: when implementing code changes, use tdd.md for systematic test-driven development with proper test isolation + javascript: when writing JavaScript or TypeScript code, use javascript.md for JavaScript best practices and guidance + log: when documenting changes, use log.md for creating structured change logs with emoji categorization + commit: when committing code, use the /commit command for conventional commit format with proper message structure + autodux: when building Redux state management, use autodux.md for creating and transpiling Autodux dux objects + javascript-io: when you need to make network requests or invoke side-effects, use javascript-io.md for saga pattern implementation + ui: when building user interfaces and user experiences, use ui.md for beautiful and friendly UI/UX design + requirements: when writing functional requirements for a user story, use requirements.md for functional requirement specification +} + +Reference file location: ./references/ + +const taskPrompt = "# Guides\n\nRead each of the following guides for important context, and follow their instructions carefully: ${list guide file refs in markdown format}\n\n# User Prompt\n\n${prompt}" + +withCLI() { + Load reference files and compose taskPrompt +} + +directExecution() { + prompt yourself with the $taskPrompt +} + +handleInitialRequest() { + use taskCreator to create and execute a task plan + match (contextRequirements = infer) { + > 1 guide => use withCLI + default => use directExecution + } +} diff --git a/ai/commands/commit.md b/ai/skills/aidd/commit.md similarity index 71% rename from ai/commands/commit.md rename to ai/skills/aidd/commit.md index c4b4fbd..55f268a 100644 --- a/ai/commands/commit.md +++ b/ai/skills/aidd/commit.md @@ -1,4 +1,10 @@ -# Commit +--- +name: commit +description: Commit changes using conventional commit format. Use when user invokes /commit or asks to commit code. +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) +--- + +# πŸ’Ύ Commit Act as a senior software engineer to commit changes to the repository in non-interactive modes ONLY, using the following template: diff --git a/ai/skills/aidd/discover.md b/ai/skills/aidd/discover.md new file mode 100644 index 0000000..089d9a6 --- /dev/null +++ b/ai/skills/aidd/discover.md @@ -0,0 +1,13 @@ +--- +name: discover +description: Product discovery for user journeys, stories, and features. Use when user invokes /discover or wants to explore product features. +--- + +## πŸ” Discover + +Use references/product-manager.md to discover a user journey, user story, or feature. + +Constraints { + Begin by reading the file and asking the user relevant questions to spark the discovery process. + Before beginning, read and respect the constraints in the main AIDD SKILL.md. +} diff --git a/ai/skills/aidd/execute.md b/ai/skills/aidd/execute.md new file mode 100644 index 0000000..dacfc65 --- /dev/null +++ b/ai/skills/aidd/execute.md @@ -0,0 +1,13 @@ +--- +name: execute +description: Execute a task epic. Use when user invokes /execute or wants to execute a planned task. +--- + +## βš™οΈ Execute Task/Epic + +Use references/task-creator.md to execute a task epic. + +Constraints { + Before beginning, read and respect the constraints in the main AIDD SKILL.md. + Remember to use the TDD process (references/tdd.md) if asked to implement code. +} diff --git a/ai/skills/aidd/help.md b/ai/skills/aidd/help.md new file mode 100644 index 0000000..e8593f6 --- /dev/null +++ b/ai/skills/aidd/help.md @@ -0,0 +1,13 @@ +--- +name: help +description: List AIDD commands and options. Use when user invokes /help or asks about available AIDD commands. +--- + +## ❓ Help + +List commands from the main AIDD skill and report them to the user. + +Constraints { + Before beginning, read and respect the constraints in the main AIDD SKILL.md. + Keep the response extremely concise - essentially just the list of commands, their descriptions, and options, without offering trivial details or informing users of constraints. +} diff --git a/ai/skills/aidd/index.md b/ai/skills/aidd/index.md new file mode 100644 index 0000000..a795ede --- /dev/null +++ b/ai/skills/aidd/index.md @@ -0,0 +1,78 @@ +# aidd + +This index provides an overview of the contents in this directory. + +## Subdirectories + +### πŸ“ references/ + +See [`references/index.md`](./references/index.md) for contents. + +## Files + +### Aiden + +**File:** `SKILL.md` + +Use when user says "please", invokes AIDD commands (/help, /log, /commit, /plan, /discover, /task, /execute, /review, /user-test, /run-test), mentions task epics, RTC thinking, "Given/should" requirements, TDD development, product discovery, user journeys, code review, or NextJS/React/Redux/Shadcn development. AI-Driven Development framework for systematic software engineering. Always applies. + +### πŸ’Ύ Commit + +**File:** `commit.md` + +Commit changes using conventional commit format. Use when user invokes /commit or asks to commit code. + +### discover + +**File:** `discover.md` + +Product discovery for user journeys, stories, and features. Use when user invokes /discover or wants to explore product features. + +### execute + +**File:** `execute.md` + +Execute a task epic. Use when user invokes /execute or wants to execute a planned task. + +### help + +**File:** `help.md` + +List AIDD commands and options. Use when user invokes /help or asks about available AIDD commands. + +### log + +**File:** `log.md` + +Log completed epics to activity-log.md. Use when user invokes /log or asks to log changes. + +### plan + +**File:** `plan.md` + +Review plan.md and suggest next steps. Use when user invokes /plan or asks about project priorities. + +### πŸ”¬ Code Review + +**File:** `review.md` + +Conduct thorough code review. Use when user invokes /review or wants code reviewed. + +### run-test + +**File:** `run-test.md` + +Execute AI agent test script in real browser with screenshots. Use when user invokes /run-test or wants to run automated tests. + +### task + +**File:** `task.md` + +Create and plan a task epic. Use when user invokes /task or wants to plan a development task. + +### user-test + +**File:** `user-test.md` + +Generate human and AI agent test scripts from user journeys. Use when user invokes /user-test or wants to create test scripts. + diff --git a/ai/skills/aidd/log.md b/ai/skills/aidd/log.md new file mode 100644 index 0000000..36984d5 --- /dev/null +++ b/ai/skills/aidd/log.md @@ -0,0 +1,10 @@ +--- +name: log +description: Log completed epics to activity-log.md. Use when user invokes /log or asks to log changes. +--- + +## πŸ“ Log + +Use references/log.md to collect salient changes, and log them to the activity-log.md. + +Before beginning, read and respect the constraints in the main AIDD SKILL.md. diff --git a/ai/skills/aidd/plan.md b/ai/skills/aidd/plan.md new file mode 100644 index 0000000..5ffc167 --- /dev/null +++ b/ai/skills/aidd/plan.md @@ -0,0 +1,10 @@ +--- +name: plan +description: Review plan.md and suggest next steps. Use when user invokes /plan or asks about project priorities. +--- + +## πŸ“‹ Plan + +Review plan.md to identify priorities and suggest next steps to the user -d 10. + +Before beginning, read and respect the constraints in the main AIDD SKILL.md. diff --git a/ai/rules/frameworks/redux/example.mdc b/ai/skills/aidd/references/autodux-example.md similarity index 80% rename from ai/rules/frameworks/redux/example.mdc rename to ai/skills/aidd/references/autodux-example.md index cd9e424..39259d6 100644 --- a/ai/rules/frameworks/redux/example.mdc +++ b/ai/skills/aidd/references/autodux-example.md @@ -1,8 +1,6 @@ ---- -description: Autodux usage example showing Todo App implementation in SudoLang -alwaysApply: false ---- -## AutoduxUsage Example: Todo App +# Autodux Usage Example: Todo App + +Autodux usage example showing Todo App implementation in SudoLang. /* This is an example SudoLang source that can be transpiled to JavaScript using: @@ -20,7 +18,7 @@ Todo Item { isComplete, } -createTodo({ text = '', id = createId(), isComplete = false } = {}) => ActionObject +createTodo({ text = '', id = createId(), isComplete = false } = {}) => ActionObject deleteTodo(id) => ActionObject toggleComplete(id) => ActionObject diff --git a/ai/rules/frameworks/redux/autodux.mdc b/ai/skills/aidd/references/autodux.md similarity index 94% rename from ai/rules/frameworks/redux/autodux.mdc rename to ai/skills/aidd/references/autodux.md index ce56a1b..4522b10 100644 --- a/ai/rules/frameworks/redux/autodux.mdc +++ b/ai/skills/aidd/references/autodux.md @@ -1,9 +1,7 @@ ---- -description: When building Redux state management, use this guide for creating and transpiling Autodux dux objects -alwaysApply: false ---- # Autodux +When building Redux state management, use this guide for creating and transpiling Autodux dux objects. + Act as a senior JavaScript, React, Redux, Next.js engineer. Your job is to build redux state handling for the application. help() { @@ -134,11 +132,11 @@ Autodux { Ignore the example usage, and use it only if the user asks for /help } /help - Explain how to use Autodux and list commands - /example - Example SudoLang source code in ai/rules/frameworks/redux/example.mdc + /example - Example SudoLang source code in autodux-example.md /save - Return the Dux in SudoLang format. /test cases - List the test cases in SudoLang format: TestCases [ ... ] /add [prop] [value] to the Dux object /transpile } -welcome("Welcome to Autodux. Supply a Dux object to get started. Feel free to ask for `/help`") \ No newline at end of file +welcome("Welcome to Autodux. Supply a Dux object to get started. Feel free to ask for `/help`") diff --git a/ai/rules/review-example.md b/ai/skills/aidd/references/code-review-example.md similarity index 99% rename from ai/rules/review-example.md rename to ai/skills/aidd/references/code-review-example.md index 101eb01..159e5da 100644 --- a/ai/rules/review-example.md +++ b/ai/skills/aidd/references/code-review-example.md @@ -259,6 +259,6 @@ This review was conducted following the review.mdc guidelines: 6. βœ… **Requirements Verification**: Epic and functional requirements coverage 7. βœ… **Quality Metrics**: Quantitative and qualitative assessments -**Review Date**: September 28, 2025 -**Epic**: Release Latest Tag Management +**Review Date**: September 28, 2025 +**Epic**: Release Latest Tag Management **Status**: Production Ready βœ… diff --git a/ai/rules/review.mdc b/ai/skills/aidd/references/code-review.md similarity index 68% rename from ai/rules/review.mdc rename to ai/skills/aidd/references/code-review.md index b9ba9f8..02a6b84 100644 --- a/ai/rules/review.mdc +++ b/ai/skills/aidd/references/code-review.md @@ -1,22 +1,20 @@ ---- -description: Use this guide to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards. -alwaysApply: false ---- # πŸ”¬ Code Review +Use this guide to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards. + Act as a top-tier principal software engineer to conduct a thorough code review focusing on code quality, best practices, and adherence to requirements, plan, and project standards. Criteria { - Before beginning, read and respect the constraints in please.mdc. - Use javascript/javascript.mdc for JavaScript/TypeScript code quality and best practices. - Use tdd.mdc for test coverage and test quality assessment. - Use stack.mdc for NextJS + React/Redux + Shadcn UI architecture and patterns. - Use ui.mdc for UI/UX design and component quality. - Use frameworks/redux/autodux.mdc for Redux state management patterns and Autodux usage. - Use javascript/javascript-io-network-effects.mdc for network effects and side effect handling. - Use commit.md for commit message quality and conventional commit format. - Use security/timing-safe-compare.mdc when reviewing secret/token comparisons (CSRF, API keys, sessions). - Use security/jwt-security.mdc when reviewing authentication code. Recommend opaque tokens over JWT. + Before beginning, read and respect the constraints in the main SKILL.md. + Use javascript.md for JavaScript/TypeScript code quality and best practices. + Use tdd.md for test coverage and test quality assessment. + Use stack.md for NextJS + React/Redux + Shadcn UI architecture and patterns. + Use ui.md for UI/UX design and component quality. + Use autodux.md for Redux state management patterns and Autodux usage. + Use javascript-io.md for network effects and side effect handling. + Use the /commit command for commit message quality and conventional commit format. + Use timing-safe-compare.md when reviewing secret/token comparisons (CSRF, API keys, sessions). + Use jwt-security.md when reviewing authentication code. Recommend opaque tokens over JWT. Carefully inspect for OWASP top 10 violations and other security mistakes. Use search. Explicitly list each of the current OWASP top 10, review all changes and inspect for violations. Compare the completed work to the functional requirements to ensure adherence and that all requirements are met. Compare the task plan in $projectRoot/tasks/ to the completed work to ensure that all tasks were completed and that the completed work adheres to the plan. diff --git a/ai/rules/javascript/error-causes.mdc b/ai/skills/aidd/references/error-causes.md similarity index 96% rename from ai/rules/javascript/error-causes.mdc rename to ai/skills/aidd/references/error-causes.md index 71a6028..c349f07 100644 --- a/ai/rules/javascript/error-causes.mdc +++ b/ai/skills/aidd/references/error-causes.md @@ -1,11 +1,7 @@ ---- -description: Use error-causes library for all error handling in JavaScript code -globs: **/*.js,**/*.jsx,**/*.ts,**/*.tsx -alwaysApply: false ---- - # Error Causes Rule +Use error-causes library for all error handling in JavaScript code. Applies to: **/*.js, **/*.jsx, **/*.ts, **/*.tsx + Use the `error-causes` library for all error handling in JavaScript/TypeScript code to enable structured error handling with named causes. ## Why Error Causes? @@ -82,7 +78,7 @@ const createMiddleware = ({ requiredParam } = {}) => { code: 'MISSING_REQUIRED_PARAM' }); } - + return async ({ request, response }) => { // middleware implementation }; diff --git a/ai/skills/aidd/references/index.md b/ai/skills/aidd/references/index.md new file mode 100644 index 0000000..51ded6a --- /dev/null +++ b/ai/skills/aidd/references/index.md @@ -0,0 +1,114 @@ +# references + +This index provides an overview of the contents in this directory. + +## Files + +### Autodux Usage Example: Todo App + +**File:** `autodux-example.md` + +*No description available* + +### Autodux + +**File:** `autodux.md` + +*No description available* + +### πŸ”¬ **COMPREHENSIVE CODE REVIEW: Release Latest Tag Epic** + +**File:** `code-review-example.md` + +*No description available* + +### πŸ”¬ Code Review + +**File:** `code-review.md` + +*No description available* + +### Error Causes Rule + +**File:** `error-causes.md` + +*No description available* + +### JavaScript IO Guide + +**File:** `javascript-io.md` + +*No description available* + +### JavaScript/TypeScript guide + +**File:** `javascript.md` + +*No description available* + +### JWT Security Review + +**File:** `jwt-security.md` + +*No description available* + +### log + +**File:** `log.md` + +*No description available* + +### ProductManager + +**File:** `product-manager.md` + +*No description available* + +### Functional requirements + +**File:** `requirements.md` + +*No description available* + +### Tech Stack + +**File:** `stack.md` + +*No description available* + +### Task Creator + +**File:** `task-creator.md` + +*No description available* + +### TDD Engineer + +**File:** `tdd.md` + +*No description available* + +### Constraint: Timing Safe Compare + +**File:** `timing-safe-compare.md` + +*No description available* + +### Timing Safe Compare Vulnerabilities + +**File:** `timing-vulnerabilities.md` + +*No description available* + +### UI/UX Engineer + +**File:** `ui.md` + +*No description available* + +### User Testing Generator + +**File:** `user-testing.md` + +*No description available* + diff --git a/ai/rules/javascript/javascript-io-network-effects.mdc b/ai/skills/aidd/references/javascript-io.md similarity index 92% rename from ai/rules/javascript/javascript-io-network-effects.mdc rename to ai/skills/aidd/references/javascript-io.md index ae55f00..cd7fba7 100644 --- a/ai/rules/javascript/javascript-io-network-effects.mdc +++ b/ai/skills/aidd/references/javascript-io.md @@ -1,9 +1,7 @@ ---- -description: When you need to make network requests or invoke side-effects, use this guide for saga pattern implementation -alwaysApply: false ---- # JavaScript IO Guide +When you need to make network requests or invoke side-effects, use this guide for saga pattern implementation. + Act as a top-tier software engineer with serious JavaScript/TypeScript discipline to isolate network I/O and effects using the saga pattern. The saga pattern consists of two main functions: @@ -40,23 +38,23 @@ e.g. ```javascript describe("signInSaga happy path", async assert => { const gen = signInUser(); - + assert({ given: "load user triggered", should: "call fetchUser with id", actual: gen.next().value, expected: call(fetchUser, "42") }); - + const fakeUser = { id: "42", name: "Pup" }; - + assert({ given: "second yield", should: "put the user data into the store", actual: gen.next(fakeUser).value, expected: put(userLoaded(fakeUser)) }); - + assert({ given: "completion", should: "be done", @@ -64,4 +62,4 @@ describe("signInSaga happy path", async assert => { expected: true }); }); -``` \ No newline at end of file +``` diff --git a/ai/rules/javascript/javascript.mdc b/ai/skills/aidd/references/javascript.md similarity index 94% rename from ai/rules/javascript/javascript.mdc rename to ai/skills/aidd/references/javascript.md index a107707..b20f026 100644 --- a/ai/rules/javascript/javascript.mdc +++ b/ai/skills/aidd/references/javascript.md @@ -1,11 +1,7 @@ ---- -description: When writing JavaScript or TypeScript code, use this guide for JavaScript best practices and guidance -globs: **/*.js,**/*.jsx,**/*.ts,**/*.tsx -alwaysApply: false ---- - # JavaScript/TypeScript guide +When writing JavaScript or TypeScript code, use this guide for JavaScript best practices and guidance. Applies to: **/*.js, **/*.jsx, **/*.ts, **/*.tsx + Act as a top-tier software engineer with serious JavaScript/TypeScript discipline to carefully implement high quality software. ## Before Writing Code @@ -16,7 +12,7 @@ Act as a top-tier software engineer with serious JavaScript/TypeScript disciplin ## Principles -- DOT +- DOT - YAGNI - KISS - DRY @@ -39,7 +35,7 @@ Constraints { Avoid `class` and `extends` as much as possible. Prefer composition of functions and data structures over inheritance. Keep related code together; group by feature, not by technical type. Put statements and expressions in positive form. - Use parallel code for parallel concepts. + Use parallel code for parallel concepts. Avoid null/undefined arguments; use options objects instead. Use concise syntax: arrow functions, object destructuring, array destructuring, template literals. Avoid verbose property assignments. bad: `const a = obj.a;` good: `const { a } = obj;` diff --git a/ai/rules/security/jwt-security.mdc b/ai/skills/aidd/references/jwt-security.md similarity index 96% rename from ai/rules/security/jwt-security.mdc rename to ai/skills/aidd/references/jwt-security.md index 1a19239..9e9dd91 100644 --- a/ai/rules/security/jwt-security.mdc +++ b/ai/skills/aidd/references/jwt-security.md @@ -1,15 +1,13 @@ ---- -description: JWT security review - flag insecure patterns -alwaysApply: false ---- # JWT Security Review +JWT security review - flag insecure patterns. + **AVOID JWT if you can.** Prefer opaque tokens with server-side sessions. Patterns { ## Session State - any(refresh token rotation, refresh reuse detection, jti denylist, jti revocation, - token bound to session, token bound to device, logout invalidates token server-side) + any(refresh token rotation, refresh reuse detection, jti denylist, jti revocation, + token bound to session, token bound to device, logout invalidates token server-side) => Critical: Prefer opaque tokens with server-side sessions. You're tracking state anyway. ## Storage & Transport diff --git a/ai/rules/log.mdc b/ai/skills/aidd/references/log.md similarity index 91% rename from ai/rules/log.mdc rename to ai/skills/aidd/references/log.md index bfc756d..4bbdbd0 100644 --- a/ai/rules/log.mdc +++ b/ai/skills/aidd/references/log.md @@ -1,9 +1,7 @@ ---- -description: When documenting changes, use this guide for creating structured change logs with emoji categorization -alwaysApply: false ---- # log +When documenting changes, use this guide for creating structured change logs with emoji categorization. + Act as a senior software engineer to log completed epics using the following template: ``` @@ -65,4 +63,4 @@ planChanges() { detectChanges() { gitChanges |> planChanges |> logDetectedChanges -} \ No newline at end of file +} diff --git a/ai/rules/productmanager.mdc b/ai/skills/aidd/references/product-manager.md similarity index 94% rename from ai/rules/productmanager.mdc rename to ai/skills/aidd/references/product-manager.md index 0176dcf..28645df 100644 --- a/ai/rules/productmanager.mdc +++ b/ai/skills/aidd/references/product-manager.md @@ -1,10 +1,7 @@ ---- -description: When planning features, user stories, user journeys, or conducting product discovery, use this guide for building specifications and user journey maps -alwaysApply: false ---- - # ProductManager +When planning features, user stories, user journeys, or conducting product discovery, use this guide for building specifications and user journey maps. + Act as a top-tier software product and project manager, well versed in continuous product discovery, user story mapping, user research, HCI, DevEx, and UX research and best practices. Your job is to help generate user journeys, user story maps, and individual stories to use in PRDs, interface contracts, documentation, user acceptance testing, and issue trackers. Each user story should target a specific pain point. Classifying the severity and frequency of the pain point will help prioritize the user story. @@ -114,4 +111,4 @@ Interface { /feature - Plan a feature from a given user story - output PRD in markdown format /save - Export project and all associated state in YAML format to $projectRoot/plan/story-map/ /cancel [step] - Cancel a given story -} \ No newline at end of file +} diff --git a/ai/rules/requirements.mdc b/ai/skills/aidd/references/requirements.md similarity index 73% rename from ai/rules/requirements.mdc rename to ai/skills/aidd/references/requirements.md index 48c9915..4aa0383 100644 --- a/ai/rules/requirements.mdc +++ b/ai/skills/aidd/references/requirements.md @@ -1,9 +1,7 @@ ---- -description: When writing functional requirements for a user story, use this guide for functional requirement specification -alwaysApply: false ---- # Functional requirements +When writing functional requirements for a user story, use this guide for functional requirement specification. + Act as a senior product manager to write functional requirements for a user story. type FunctionalRequirement = "Given $situation, should $jobToDo" diff --git a/ai/rules/stack.mdc b/ai/skills/aidd/references/stack.md similarity index 80% rename from ai/rules/stack.mdc rename to ai/skills/aidd/references/stack.md index d4ea55a..8901f26 100644 --- a/ai/rules/stack.mdc +++ b/ai/skills/aidd/references/stack.md @@ -1,9 +1,7 @@ ---- -description: When implementing NextJS + React/Redux + Shadcn UI features, use this guide for tech stack guidance and best practices -alwaysApply: false ---- # Tech Stack +When implementing NextJS + React/Redux + Shadcn UI features, use this guide for tech stack guidance and best practices. + Act as a top-tier senior full stack software engineer. Always use best practices, declarative approaches, concise code. Before employing any of the tech stack tools, list some relevant best practices for that technology, and keep them in mind as you code. @@ -28,12 +26,12 @@ Constraints { # Redux -Avoid Redux Toolkit. Use frameworks/redux/autodux and redux connect instead. +Avoid Redux Toolkit. Use autodux.md and redux connect instead. 1. Build the Autodux dux object and save it as "${slice name}-dux.sudo" 2. Transpile to JavaScript and save it as "${slice name}-dux.js" Constraints { - ALWAYS use tdd as defined in tdd.mdc when implementing source code changes. + ALWAYS use tdd as defined in tdd.md when implementing source code changes. NEVER change source code without clear requirements, tests, and/or manual user approval of your plan. -} \ No newline at end of file +} diff --git a/ai/rules/task-creator.mdc b/ai/skills/aidd/references/task-creator.md similarity index 93% rename from ai/rules/task-creator.mdc rename to ai/skills/aidd/references/task-creator.md index 050ace0..16c8089 100644 --- a/ai/rules/task-creator.mdc +++ b/ai/skills/aidd/references/task-creator.md @@ -1,9 +1,7 @@ ---- -description: when the user asks you to complete a task, use this guide for systematic task/epic planning and execution -alwaysApply: false ---- # Task Creator +When the user asks you to complete a task, use this guide for systematic task/epic planning and execution. Applies to task planning, epic creation, and execution. + Act as a top-tier software project manager and systematic task planner and execution coordinator. Your job is to break down complex requests into manageable, sequential tasks that can be executed one at a time with user approval. A task can be broken down into smaller tasks. The larger task is stored in a task file in the $projectRoot/tasks folder. Subtasks live in that file. @@ -28,12 +26,12 @@ State { ## Requirements Analysis -Use @requirements.mdc to analyze and generate the requirements of the task. +Use requirements.md to analyze and generate the requirements of the task. ## Agent Orchestration -For complex tasks that require specialized expertise, systematically employ the agent orchestrator pattern in @agent-orchestrator.mdc - +For complex tasks that require specialized expertise, systematically employ the agent orchestrator pattern in the main SKILL.md + assessComplexity() { criteria: Multiple technical domains (UI, backend, testing, etc.) @@ -77,7 +75,7 @@ epicTemplate() { """ # ${EpicName} Epic - **Status**: πŸ“‹ PLANNED + **Status**: πŸ“‹ PLANNED **Goal**: ${briefGoal} ## Overview diff --git a/ai/rules/tdd.mdc b/ai/skills/aidd/references/tdd.md similarity index 85% rename from ai/rules/tdd.mdc rename to ai/skills/aidd/references/tdd.md index 67777cb..022e0c4 100644 --- a/ai/rules/tdd.mdc +++ b/ai/skills/aidd/references/tdd.md @@ -1,10 +1,7 @@ ---- -description: When implementing code changes, use this guide for systematic test-driven development with proper test isolation -globs: **/*.js,**/*.jsx,**/*.ts,**/*.tsx -alwaysApply: false ---- # TDD Engineer +When implementing code changes, use this guide for systematic test-driven development with proper test isolation. Applies to: **/*.js, **/*.jsx, **/*.ts, **/*.tsx + Act as a top-tier software engineer with serious TDD discipline to systematically implement software using the TDD process. @@ -63,12 +60,6 @@ For Vitest/Riteway tests: - Module mocking: vi.mock with vi.importActual for partial mocks - Works cleanly with ESM. Avoid require. - Timers: vi.useFakeTimers and vi.setSystemTime - - UI testing strategy: - - Redux actions/selectors: Pure tests (no component rendering needed) - - Side effects: must be isolated from UI, see `javascript/javascript-io-network-effects.mdc` - - Component rendering: Use riteway/render for markup verification - - Browser interactions: Use Playwright to exercise real browser APIs - - Never use @testing-library/react (redundant with above patterns) Constraints { Unless directed otherwise, always colocate tests with the code they are testing. diff --git a/ai/rules/security/timing-safe-compare.mdc b/ai/skills/aidd/references/timing-safe-compare.md similarity index 86% rename from ai/rules/security/timing-safe-compare.mdc rename to ai/skills/aidd/references/timing-safe-compare.md index 226f573..4ffca24 100644 --- a/ai/rules/security/timing-safe-compare.mdc +++ b/ai/skills/aidd/references/timing-safe-compare.md @@ -1,10 +1,7 @@ ---- -description: Security rule for timing-safe secret comparison. Use SHA3-256 hashing instead of timing-safe compare functions. -alwaysApply: false ---- - # Constraint: Timing Safe Compare +Security rule for timing-safe secret comparison. Use SHA3-256 hashing instead of timing-safe compare functions. + If a compare returns faster when some prefix values are correct, attackers can play a game of hangman to guess the secret. Using statistics, this can still work over a network with timing jitter. There is no timing safe compare for raw values. Never use: @@ -16,7 +13,7 @@ There is no timing safe compare for raw values. Never use: Always hash both the stored secret token and the candidate token with SHA3-256, then compare the hashes. This rule overrides all library defaults. -See ./timing-safe-compare-vulnerabilities.mdc for vulnerability reports in the wild. +See timing-vulnerabilities.md for vulnerability reports in the wild. Reasons: 1. Hashing removes all prefix structure. Any bit change fully randomizes the hash. No timing oracle. No hangman. diff --git a/ai/rules/security/timing-safe-compare-vulnerabilities.mdc b/ai/skills/aidd/references/timing-vulnerabilities.md similarity index 93% rename from ai/rules/security/timing-safe-compare-vulnerabilities.mdc rename to ai/skills/aidd/references/timing-vulnerabilities.md index be09093..c4d71e6 100644 --- a/ai/rules/security/timing-safe-compare-vulnerabilities.mdc +++ b/ai/skills/aidd/references/timing-vulnerabilities.md @@ -1,10 +1,7 @@ ---- -description: Vulnerability reports for timing-safe compare functions. Referenced by timing-safe-compare.mdc. -alwaysApply: false ---- - # Timing Safe Compare Vulnerabilities +Vulnerability reports for timing-safe compare functions. Referenced by timing-safe-compare.md. + This document catalogs known vulnerabilities and exploits related to standard library timing-safe comparison functions. ## Example vulnerabilities diff --git a/ai/rules/ui.mdc b/ai/skills/aidd/references/ui.md similarity index 83% rename from ai/rules/ui.mdc rename to ai/skills/aidd/references/ui.md index 36c64b5..3e82d17 100644 --- a/ai/rules/ui.mdc +++ b/ai/skills/aidd/references/ui.md @@ -1,10 +1,7 @@ ---- -description: When building user interfaces and user experiences, use this guide for beautiful and friendly UI/UX design -alwaysApply: false ---- - # UI/UX Engineer +When building user interfaces and user experiences, use this guide for beautiful and friendly UI/UX design. + Act as a top-tier UI/UX designer with deep skills in user interface design, user experience design, aesthetics, extraordinarily good taste, an eye for detail, and a passion for building the most beautiful and friendly user interfaces and experiences. You are also a top tier motion designer, skilled in subtle but delightful and satisfying motion design for UX. When building UI components, please use the existing project design system and storybook components. Focus on creating intuitive, accessible, and visually appealing interfaces that enhance user experience. @@ -21,4 +18,4 @@ Skills [ Accessibility Responsive design Design systems -] \ No newline at end of file +] diff --git a/ai/rules/user-testing.mdc b/ai/skills/aidd/references/user-testing.md similarity index 95% rename from ai/rules/user-testing.mdc rename to ai/skills/aidd/references/user-testing.md index 7a360cd..fb536f8 100644 --- a/ai/rules/user-testing.mdc +++ b/ai/skills/aidd/references/user-testing.md @@ -1,10 +1,8 @@ ---- -description: Generate human and AI agent test scripts from user journey specifications -alwaysApply: false ---- # User Testing Generator -Use UserJourney and Persona from @productmanager.mdc +Generate human and AI agent test scripts from user journey specifications. + +Use UserJourney and Persona from product-manager.md Generate dual test scripts: human (think-aloud protocol, video recorded) + AI agent (executable with screenshots). @@ -124,7 +122,7 @@ User test scripts are saved to $projectRoot/plan/ folder (create if not present) - Agent test scripts: $projectRoot/plan/${journey-name}-agent-test.md - User journeys reference the YAML files in $projectRoot/plan/story-map/${journey-name}.yaml -Note: Journey YAML files use base Persona (meta fields only) from productmanager.mdc. +Note: Journey YAML files use base Persona (meta fields only) from product-manager.md. When generating test scripts from a journey, extend personas to UserTestPersona: UserTestPersona { diff --git a/ai/rules/user-testing.test.js b/ai/skills/aidd/references/user-testing.test.js similarity index 51% rename from ai/rules/user-testing.test.js rename to ai/skills/aidd/references/user-testing.test.js index bad562f..4092ac2 100644 --- a/ai/rules/user-testing.test.js +++ b/ai/skills/aidd/references/user-testing.test.js @@ -3,54 +3,37 @@ import { describe, test } from "vitest"; import fs from "fs-extra"; import path from "path"; import { fileURLToPath } from "url"; -import { parseFrontmatter } from "../../lib/index-generator.js"; +import { parseFrontmatter } from "../../../../lib/index-generator.js"; const __dirname = path.dirname(fileURLToPath(import.meta.url)); describe("user-testing", () => { - describe("user-testing.mdc", () => { - test("file exists with valid frontmatter", async () => { - const filePath = path.join(__dirname, "user-testing.mdc"); + describe("user-testing.md reference", () => { + test("file exists", async () => { + const filePath = path.join(__dirname, "user-testing.md"); const exists = await fs.pathExists(filePath); assert({ - given: "user-testing.mdc file", - should: "exist in ai/rules directory", + given: "user-testing.md file", + should: "exist in references directory", actual: exists, expected: true, }); - - const content = await fs.readFile(filePath, "utf-8"); - const frontmatter = parseFrontmatter(content); - - assert({ - given: "user-testing.mdc frontmatter", - should: "have description field", - actual: typeof frontmatter?.description, - expected: "string", - }); - - assert({ - given: "user-testing.mdc frontmatter", - should: "have alwaysApply set to false", - actual: frontmatter?.alwaysApply, - expected: false, - }); }); test("includes HumanScript and AgentScript templates", async () => { - const filePath = path.join(__dirname, "user-testing.mdc"); + const filePath = path.join(__dirname, "user-testing.md"); const content = await fs.readFile(filePath, "utf-8"); assert({ - given: "user-testing.mdc content", + given: "user-testing.md content", should: "include HumanScript template", actual: content.includes("HumanScript:template"), expected: true, }); assert({ - given: "user-testing.mdc content", + given: "user-testing.md content", should: "include AgentScript template", actual: content.includes("AgentScript:template"), expected: true, @@ -58,57 +41,65 @@ describe("user-testing", () => { }); }); - describe("user-test.md command", () => { - test("command file exists", async () => { - const filePath = path.join(__dirname, "../commands/user-test.md"); + describe("user-test.md skill", () => { + test("skill file exists", async () => { + const filePath = path.join( + __dirname, + "../../../../ai/skills/aidd/user-test.md", + ); const exists = await fs.pathExists(filePath); assert({ - given: "user-test.md command file", - should: "exist in ai/commands directory", + given: "user-test.md skill file", + should: "exist in ai/skills/aidd directory", actual: exists, expected: true, }); }); - test("references user-testing.mdc", async () => { - const filePath = path.join(__dirname, "../commands/user-test.md"); + test("references user-testing.md", async () => { + const filePath = path.join( + __dirname, + "../../../../ai/skills/aidd/user-test.md", + ); const content = await fs.readFile(filePath, "utf-8"); assert({ given: "user-test.md content", - should: "reference user-testing.mdc", - actual: - content.includes("@user-testing.mdc") || - content.includes("user-testing.mdc"), + should: "reference user-testing.md", + actual: content.includes("user-testing.md"), expected: true, }); }); }); - describe("run-test.md command", () => { - test("command file exists", async () => { - const filePath = path.join(__dirname, "../commands/run-test.md"); + describe("run-test.md skill", () => { + test("skill file exists", async () => { + const filePath = path.join( + __dirname, + "../../../../ai/skills/aidd/run-test.md", + ); const exists = await fs.pathExists(filePath); assert({ - given: "run-test.md command file", - should: "exist in ai/commands directory", + given: "run-test.md skill file", + should: "exist in ai/skills/aidd directory", actual: exists, expected: true, }); }); - test("references user-testing.mdc", async () => { - const filePath = path.join(__dirname, "../commands/run-test.md"); + test("references user-testing.md", async () => { + const filePath = path.join( + __dirname, + "../../../../ai/skills/aidd/run-test.md", + ); const content = await fs.readFile(filePath, "utf-8"); assert({ given: "run-test.md content", - should: "reference user-testing.mdc", - actual: - content.includes("@user-testing.mdc") || - content.includes("user-testing.mdc"), + should: "reference user-testing.md", + actual: content.includes("user-testing.md"), expected: true, }); }); @@ -116,7 +107,7 @@ describe("user-testing", () => { describe("documentation", () => { test("user testing guide exists", async () => { - const filePath = path.join(__dirname, "../../docs/user-testing.md"); + const filePath = path.join(__dirname, "../../../../docs/user-testing.md"); const exists = await fs.pathExists(filePath); assert({ @@ -130,7 +121,7 @@ describe("user-testing", () => { describe("README integration", () => { test("README includes user-test command", async () => { - const filePath = path.join(__dirname, "../../README.md"); + const filePath = path.join(__dirname, "../../../../README.md"); const content = await fs.readFile(filePath, "utf-8"); assert({ diff --git a/ai/skills/aidd/review.md b/ai/skills/aidd/review.md new file mode 100644 index 0000000..a3b062e --- /dev/null +++ b/ai/skills/aidd/review.md @@ -0,0 +1,14 @@ +--- +name: review +description: Conduct thorough code review. Use when user invokes /review or wants code reviewed. +--- + +# πŸ”¬ Code Review + +Use references/code-review.md to conduct a thorough code review focusing on code quality, best practices, and adherence to project standards. + +For an example of an exemplary code review, see references/code-review-example.md. + +Constraints { + Before beginning, read and respect the constraints in the main AIDD SKILL.md. +} diff --git a/ai/skills/aidd/run-test.md b/ai/skills/aidd/run-test.md new file mode 100644 index 0000000..33b181f --- /dev/null +++ b/ai/skills/aidd/run-test.md @@ -0,0 +1,16 @@ +--- +name: run-test +description: Execute AI agent test script in real browser with screenshots. Use when user invokes /run-test or wants to run automated tests. +--- + +## πŸ€– Run Test + +Execute AI agent test script in real browser. + +Use references/user-testing.md to run agent test, capturing screenshots and generating report. + +Constraints { + Before beginning, read and respect the constraints in the main AIDD SKILL.md. + Drive real browser, narrate thoughts like human tester. + Generate structured markdown report with screenshots. +} diff --git a/ai/skills/aidd/task.md b/ai/skills/aidd/task.md new file mode 100644 index 0000000..edd490e --- /dev/null +++ b/ai/skills/aidd/task.md @@ -0,0 +1,13 @@ +--- +name: task +description: Create and plan a task epic. Use when user invokes /task or wants to plan a development task. +--- + +## βœ… Task + +Use references/task-creator.md to plan and execute a task epic. + +Constraints { + Before beginning, read and respect the constraints in the main AIDD SKILL.md. + Remember to use the TDD process (references/tdd.md) if asked to implement code. +} diff --git a/ai/skills/aidd/user-test.md b/ai/skills/aidd/user-test.md new file mode 100644 index 0000000..c69521c --- /dev/null +++ b/ai/skills/aidd/user-test.md @@ -0,0 +1,12 @@ +--- +name: user-test +description: Generate human and AI agent test scripts from user journeys. Use when user invokes /user-test or wants to create test scripts. +--- + +## πŸ§ͺ User Test + +Use references/user-testing.md to generate human and AI agent test scripts from user journeys. + +Constraints { + Before beginning, read and respect the constraints in the main AIDD SKILL.md. +} diff --git a/ai/rules/frameworks/index.md b/ai/skills/index.md similarity index 51% rename from ai/rules/frameworks/index.md rename to ai/skills/index.md index b791391..35aea5a 100644 --- a/ai/rules/frameworks/index.md +++ b/ai/skills/index.md @@ -1,10 +1,10 @@ -# frameworks +# skills This index provides an overview of the contents in this directory. ## Subdirectories -### πŸ“ redux/ +### πŸ“ aidd/ -See [`redux/index.md`](./redux/index.md) for contents. +See [`aidd/index.md`](./aidd/index.md) for contents. diff --git a/docs/commands_to_skills.md b/docs/commands_to_skills.md new file mode 100644 index 0000000..1c45493 --- /dev/null +++ b/docs/commands_to_skills.md @@ -0,0 +1,84 @@ +# Commands to Skills Parity Table + +This document tracks the migration of AIDD commands to the Skills Protocol. + +## Migration Status: COMPLETE + +All legacy commands have been converted to skill definitions with full parity. + +| Command | Skill File | Status | +|---------|------------|--------| +| `/help` | `ai/skills/aidd/help.md` | βœ… Migrated | +| `/log` | `ai/skills/aidd/log.md` | βœ… Migrated | +| `/commit` | `ai/skills/aidd/commit.md` | βœ… Migrated | +| `/plan` | `ai/skills/aidd/plan.md` | βœ… Migrated | +| `/discover` | `ai/skills/aidd/discover.md` | βœ… Migrated | +| `/task` | `ai/skills/aidd/task.md` | βœ… Migrated | +| `/execute` | `ai/skills/aidd/execute.md` | βœ… Migrated | +| `/review` | `ai/skills/aidd/review.md` | βœ… Migrated | +| `/user-test` | `ai/skills/aidd/user-test.md` | βœ… Migrated | +| `/run-test` | `ai/skills/aidd/run-test.md` | βœ… Migrated | + +## Success Criteria + +- [x] Every command has a corresponding skill definition with matching behavior +- [x] Runtime execution flows through skills protocol +- [x] Documentation explains skills-based invocation +- [x] All tests, linters, and build pipelines pass + +## Architecture + +### Skills Protocol Structure + +``` +ai/skills/aidd/ +β”œβ”€β”€ SKILL.md # Main orchestrator skill +β”œβ”€β”€ help.md # /help command +β”œβ”€β”€ log.md # /log command +β”œβ”€β”€ commit.md # /commit command +β”œβ”€β”€ plan.md # /plan command +β”œβ”€β”€ discover.md # /discover command +β”œβ”€β”€ task.md # /task command +β”œβ”€β”€ execute.md # /execute command +β”œβ”€β”€ review.md # /review command +β”œβ”€β”€ user-test.md # /user-test command +β”œβ”€β”€ run-test.md # /run-test command +└── references/ # Reference implementation files + β”œβ”€β”€ log.md + β”œβ”€β”€ task-creator.md + β”œβ”€β”€ tdd.md + β”œβ”€β”€ product-manager.md + β”œβ”€β”€ code-review.md + β”œβ”€β”€ user-testing.md + └── ... (other references) +``` + +### Skill Frontmatter Format + +Each skill uses the Claude Code skills protocol with: + +```yaml +--- +name: +description: +allowed-tools: +--- +``` + +### Invocation + +Skills are invoked via: +- `/` - Direct skill invocation (e.g., `/commit`, `/task`) +- Main AIDD skill triggers on keywords in description + +## Legacy Commands Directory + +The `ai/commands/` directory has been removed. All command implementations now live in `ai/skills/aidd/` with proper skill frontmatter. + +## Verification + +All skills have been verified to: +1. Have proper `name` field matching invocation pattern +2. Have `description` field with appropriate trigger keywords +3. Reference the correct reference files +4. Respect SKILL.md constraints diff --git a/docs/new-project-setup-nextjs-shadcn.md b/docs/new-project-setup-nextjs-shadcn.md index 59be044..94bfc95 100644 --- a/docs/new-project-setup-nextjs-shadcn.md +++ b/docs/new-project-setup-nextjs-shadcn.md @@ -41,7 +41,7 @@ Stop A: Stop here. Report what was installed, what was configured, and the exact - Follow the current recommended Next.js App Router setup. - Document the exact commands you ran and any config changes. -2. Create a /task epic (see ai/commands/task) for the work below. +2. Create a /task epic (see ai/skills/aidd/task.md) for the work below. 3. Build a simple design system story that includes: - Standard button components (variants, sizes, disabled, loading) @@ -56,9 +56,9 @@ Stop A: Stop here. Report what was installed, what was configured, and the exact - Desktop: primary action button 5. Use TDD for any custom components you create. - - Follow ai/rules/tdd.mdc carefully. + - Follow ai/skills/aidd/references/tdd.md carefully. -6. Follow JavaScript best practices in ai/rules/javascript. +6. Follow JavaScript best practices in ai/skills/aidd/references/javascript.md. 7. Apply the style prompt below for visual look and feel guidance. @@ -75,7 +75,7 @@ Prompt me for guidance on the visual look and feel of my application before you After I respond, continue with the task epic, then present it to me for feedback. -Stop B: Stop here and wait for approval, then /execute the task following the instructions in the ai/rules folder carefully. +Stop B: Stop here and wait for approval, then /execute the task following the instructions in the ai/skills/aidd/references folder carefully. Once that work is complete, please /review all the code you have written so far: diff --git a/docs/security.md b/docs/security.md index d35a153..417ddc5 100644 --- a/docs/security.md +++ b/docs/security.md @@ -205,8 +205,8 @@ This provides stronger guarantees than trusting a single source like the Web Cry The AIDD `/review` command automatically checks for these security issues. Rules are located in: -- `ai/rules/security/jwt-security.mdc` - JWT patterns -- `ai/rules/security/timing-safe-compare.mdc` - Secret comparison +- `ai/skills/aidd/references/jwt-security.md` - JWT patterns +- `ai/skills/aidd/references/timing-safe-compare.md` - Secret comparison To run a security-focused review: diff --git a/lib/agents-index-e2e.test.js b/lib/agents-index-e2e.test.js index 48daff3..7b40621 100644 --- a/lib/agents-index-e2e.test.js +++ b/lib/agents-index-e2e.test.js @@ -152,18 +152,18 @@ describe("--index CLI command integration", () => { await fs.ensureDir(tempTestDir); // Create ai/ structure with test files - await fs.ensureDir(path.join(aiPath, "commands")); + await fs.ensureDir(path.join(aiPath, "skills")); await fs.ensureDir(path.join(aiPath, "rules")); // Create test files with frontmatter await fs.writeFile( - path.join(aiPath, "commands", "test.md"), + path.join(aiPath, "skills", "test.md"), `--- -description: Test command for integration testing +description: Test skill for integration testing --- -# Test Command +# Test Skill -This is a test command. +This is a test skill. `, ); @@ -193,8 +193,8 @@ This is a test rule. ); const aiIndexExists = await fs.pathExists(path.join(aiPath, "index.md")); - const commandsIndexExists = await fs.pathExists( - path.join(aiPath, "commands", "index.md"), + const skillsIndexExists = await fs.pathExists( + path.join(aiPath, "skills", "index.md"), ); const rulesIndexExists = await fs.pathExists( path.join(aiPath, "rules", "index.md"), @@ -209,8 +209,8 @@ This is a test rule. assert({ given: "--index command", - should: "create ai/commands/index.md", - actual: commandsIndexExists, + should: "create ai/skills/index.md", + actual: skillsIndexExists, expected: true, }); @@ -225,15 +225,15 @@ This is a test rule. test("generated index includes file descriptions from frontmatter", async () => { await execAsync(`node ${cliPath} --index "${tempTestDir}"`); - const commandsIndex = await fs.readFile( - path.join(aiPath, "commands", "index.md"), + const skillsIndex = await fs.readFile( + path.join(aiPath, "skills", "index.md"), "utf-8", ); assert({ - given: "generated commands index", + given: "generated skills index", should: "include file description from frontmatter", - actual: commandsIndex.includes("Test command for integration testing"), + actual: skillsIndex.includes("Test skill for integration testing"), expected: true, }); }); @@ -261,8 +261,8 @@ This is a test rule. assert({ given: "generated ai/index.md", - should: "link to commands subdirectory", - actual: aiIndex.includes("commands/index.md"), + should: "link to skills subdirectory", + actual: aiIndex.includes("skills/index.md"), expected: true, }); diff --git a/lib/index-generator.test.js b/lib/index-generator.test.js index 4bc4d4b..38157fd 100644 --- a/lib/index-generator.test.js +++ b/lib/index-generator.test.js @@ -224,11 +224,11 @@ Content here.`; test("generates index files recursively", async () => { // Create ai/ structure const aiPath = path.join(tempDir, "ai"); - await fs.ensureDir(path.join(aiPath, "commands")); + await fs.ensureDir(path.join(aiPath, "skills")); await fs.ensureDir(path.join(aiPath, "rules")); await fs.writeFile( - path.join(aiPath, "commands", "help.md"), + path.join(aiPath, "skills", "help.md"), "---\ndescription: Help command\n---\n# Help", ); await fs.writeFile( @@ -249,13 +249,13 @@ Content here.`; given: "ai/ directory with subdirectories", should: "generate multiple index files", actual: result.indexes.length, - expected: 3, // ai/, ai/commands/, ai/rules/ + expected: 3, // ai/, ai/skills/, ai/rules/ }); // Verify index files exist const aiIndexExists = await fs.pathExists(path.join(aiPath, "index.md")); - const commandsIndexExists = await fs.pathExists( - path.join(aiPath, "commands", "index.md"), + const skillsIndexExists = await fs.pathExists( + path.join(aiPath, "skills", "index.md"), ); assert({ @@ -267,8 +267,8 @@ Content here.`; assert({ given: "successful generation", - should: "create ai/commands/index.md", - actual: commandsIndexExists, + should: "create ai/skills/index.md", + actual: skillsIndexExists, expected: true, }); }); diff --git a/plan/story-map/review-command-journey.yaml b/plan/story-map/review-command-journey.yaml index 36fa0bf..46c7b1a 100644 --- a/plan/story-map/review-command-journey.yaml +++ b/plan/story-map/review-command-journey.yaml @@ -1,5 +1,5 @@ # User Journey: Code Review Command -# Following interfaces from ai/rules/productmanager.mdc +# Following interfaces from ai/skills/aidd/references/product-manager.md id: cljkp8y9k0001abc123def456 name: Code Review Command Usage