Skip to content

refactor: migrate from commands/rules to Skills Protocol #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
2witstudios wants to merge 1 commit into
base: main
Choose a base branch
from
Open

refactor: migrate from commands/rules to Skills Protocol #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!--
REVIEWER INSTRUCTIONS:
Please use the AI review command to conduct a thorough code review.
Run: ai/rules/review
Make sure to reference the JavaScript style guide: ai/rules/javascript/javascript.mdc
Run: /review
Reference the JavaScript style guide: ai/skills/aidd/references/javascript.md
This will help ensure code quality, best practices, and adherence to project standards.
-->
26 changes: 20 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand Down
9 changes: 4 additions & 5 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -52,18 +52,17 @@ 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

## 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.

86 changes: 52 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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**
Expand Down
8 changes: 0 additions & 8 deletions ai/commands/discover.md
View file
Open in desktop

This file was deleted.

8 changes: 0 additions & 8 deletions ai/commands/execute.md
View file
Open in desktop

This file was deleted.

8 changes: 0 additions & 8 deletions ai/commands/help.md
View file
Open in desktop

This file was deleted.

66 changes: 0 additions & 66 deletions ai/commands/index.md
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions ai/commands/log.md
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions ai/commands/plan.md
View file
Open in desktop

This file was deleted.

7 changes: 0 additions & 7 deletions ai/commands/review.md
View file
Open in desktop

This file was deleted.

11 changes: 0 additions & 11 deletions ai/commands/run-test.md
View file
Open in desktop

This file was deleted.

8 changes: 0 additions & 8 deletions ai/commands/task.md
View file
Open in desktop

This file was deleted.

7 changes: 0 additions & 7 deletions ai/commands/user-test.md
View file
Open in desktop

This file was deleted.

8 changes: 2 additions & 6 deletions ai/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Loading