Add aidd-fix skill for structured bug fixing workflow

.husky/pre-commit

@@ -1,8 +1,8 @@
-# Generate index.md files for ai/ folders
+# Generate index.md files for ai/ and aidd-custom/ folders
 node bin/aidd.js --index "$(git rev-parse --show-toplevel)"
 
 # Stage any updated index.md files
-git add 'ai/**/index.md' 2>/dev/null || true
+git add 'ai/**/index.md' 'aidd-custom/**/index.md' 2>/dev/null || true
 
 # Generate ToC for README.md
 npm run toc

AGENTS.md

@@ -41,3 +41,13 @@ If any conflicts are detected between a requested task and the vision document,
 3. Ask the user to clarify how to resolve the conflict before proceeding
 
 Never proceed with a task that contradicts the vision without explicit user approval.
+
+## Custom Skills and Configuration
+
+Project-specific customization lives in `aidd-custom/`. Before starting work,
+read `aidd-custom/index.md` to discover available project-specific skills,
+and read `aidd-custom/config.yml` to load configuration into context.
+
+## Task Index
+
+fix bug => /aidd-fix

README.md

@@ -45,6 +45,7 @@ Includes:
   - [Creating Your Vision Document](#creating-your-vision-document)
   - [How Agents Use the Vision Document](#how-agents-use-the-vision-document)
   - [AGENTS.md File](#agentsmd-file)
+  - [`aidd-custom/` — Project Customization](#aidd-custom--project-customization)
 - [🔧 Cursor Editor Setup](#-cursor-editor-setup)
   - [Automatic Setup (Recommended)](#automatic-setup-recommended)
   - [When to Use `--cursor`](#when-to-use---cursor)
@@ -539,6 +540,12 @@ When you run the AIDD installer, it automatically creates (or updates) an `AGENT
 - Respect the vision document as the source of truth
 - Handle conflicts appropriately
 
+### `aidd-custom/` — Project Customization
+
+The installer also creates `aidd-custom/config.yml` in your project root. This folder is the place for project-specific overrides: custom skills, behavior configuration, and additional agent directives. Agents are instructed to read `aidd-custom/index.md` on startup so your customizations are always in context.
+
+See [docs/aidd-custom.md](docs/aidd-custom.md) for all available options.
+
 ## 🔧 Cursor Editor Setup
 
 The AIDD CLI can automatically set up the AI agent system for **Cursor editor** users.

ai/commands/aidd-fix.md

@@ -0,0 +1,7 @@
+# 🐛 /aidd-fix
+
+Load and execute the skill at `ai/skills/aidd-fix/SKILL.md`.
+
+Constraints {
+  Before beginning, read and respect the constraints in please.mdc.
+}

ai/commands/index.md

@@ -4,6 +4,12 @@ This index provides an overview of the contents in this directory.
 
 ## Files
 
+### 🐛 /aidd-fix
+
+**File:** `aidd-fix.md`
+
+*No description available*
+
 ### Commit
 
 **File:** `commit.md`

ai/index.md

@@ -12,3 +12,7 @@ See [`commands/index.md`](./commands/index.md) for contents.
 
 See [`rules/index.md`](./rules/index.md) for contents.
 
+### 📁 skills/
+
+See [`skills/index.md`](./skills/index.md) for contents.
+

ai/rules/please.mdc

@@ -43,6 +43,7 @@ Commands {
   🔬 /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
+  🐛 /aidd-fix - fix a bug or implement review feedback following the full AIDD fix process
 }
 
 Constraints {

ai/skills/aidd-ecs/index.md

@@ -0,0 +1,18 @@
+# aidd-ecs
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Database.Plugin authoring
+
+**File:** `SKILL.md`
+
+Enforces @adobe/data/ecs best practices. Use this whenever @adobe/data/ecs is imported, when creating or modifying Database.Plugin definitions, or when working with ECS components, resources, transactions, actions, systems, or services.
+
+### Data modeling: components, resources, archetypes
+
+**File:** `data-modeling.md`
+
+*No description available*
+

ai/skills/aidd-fix/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: aidd-fix
+description: >
+  Fix a bug or implement review feedback following the AIDD fix process.
+  Use when a bug has been reported, a failing test needs investigation,
+  or a code review has returned feedback that requires a code change.
+compatibility: Requires git, npm, and a test runner (vitest) available in the project.
+---
+
+Act as a top-tier software quality engineer to diagnose and fix bugs
+following a disciplined TDD process.
+
+Competencies {
+  root cause analysis
+  test-driven development (failing test before implementation)
+  minimal targeted fixes (no scope creep)
+  regression prevention
+  conventional commit discipline
+}
+
+# 🐛 aidd-fix
+
+Fix a bug or implement review feedback following the structured AIDD fix process.
+
+Constraints {
+  Do ONE step at a time. Do not skip steps or reorder them.
+  Run lint and unit tests prior to committing code. Planning and documentation (epics, /plan files, /docs, etc) are exempt.
+  Run e2e tests prior to committing only if `aidd-custom/config.yml` sets `e2eBeforeCommit: true`.
+  Never implement before writing a failing test.
+  Never write a test after implementing — that is not TDD.
+}
+
+## Step 1 — Gain context and validate
+
+Given a bug report or review feedback:
+
+1. Read the relevant source file(s) and colocated test file(s)
+2. Read the task epic in `$projectRoot/tasks/` that covers this area
+3. Reason through or reproduce the issue to confirm it exists
+4. If **no change is needed**: summarize findings and stop — do not modify any files
+
+## Step 2 — Document the requirement in the epic
+
+If a fix is required:
+
+1. Locate the existing task epic that covers this area of the codebase
+2. If no matching epic exists, create one at `$projectRoot/tasks/<name>-epic.md` using `/task`
+3. Add a requirement bullet in **"Given X, should Y"** format that precisely describes the correct behavior
+4. The epic update is its own discrete step — commit it separately or include it in the fix commit with a clear message
+
+epicConstraints {
+  Requirements must follow "Given X, should Y" format exactly.
+  No implementation detail in the requirement — describe observable behavior only.
+}
+
+## Step 3 — TDD: write a failing test first
+
+Using `/execute`:
+
+1. Write a test that captures the new requirement
+2. Run the unit test runner and confirm the test **fails**
+
+  ```sh
+  npm run test:unit
+  ```
+
+3. If the test passes without any implementation change: the bug may already be fixed or the test is wrong — stop and reassess before proceeding
+
+## Step 4 — Implement the fix
+
+1. Write the minimum code needed to make the failing test pass
+2. Run the unit test runner — **fail → fix bug → repeat; pass → continue**
+
+  ```sh
+  npm run test:unit
+  ```
+
+3. Implement ONLY what makes the test pass — do not over-engineer or clean up unrelated code
+
+## Step 5 — Self-review and run all tests
+
+1. Run `/review` to self-review all changes
+2. Resolve any issues found before moving to the next step
+3. Run lint and unit tests to confirm all changes pass:
+
+  ```sh
+  npm run test:unit
+  ```
+
+4. Check `aidd-custom/config.yml` for the `e2eBeforeCommit` setting:
+   - `e2eBeforeCommit: true` → run the full e2e suite before continuing:
+
+     ```sh
+     npm run test:e2e
+     ```
+
+   - `e2eBeforeCommit: false` (the default) → skip local e2e — CI will run the full suite
+
+## Step 6 — Commit and push
+
+Using `/commit`:
+
+1. Stage only the files changed by this fix
+2. Write a conventional commit message following `/commit` (e.g. `type(optional-scope): description`)
+3. Push to the PR branch
+
+  ```sh
+  git push -u origin <branch-name>
+  ```
+
+Commands {
+  🐛 /aidd-fix - fix a bug or review feedback following the full AIDD fix process
+}

ai/skills/aidd-fix/index.md

@@ -0,0 +1,13 @@
+# aidd-fix
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### 🐛 aidd-fix
+
+**File:** `SKILL.md`
+
+Fix a bug or implement review feedback following the AIDD fix process. Use when a bug has been reported, a failing test needs investigation, or a code review has returned feedback that requires a code change.
+
+

ai/skills/aidd-layout/index.md

@@ -0,0 +1,18 @@
+# aidd-layout
+
+This index provides an overview of the contents in this directory.
+
+## Subdirectories
+
+### 📁 references/
+
+See [`references/index.md`](./references/index.md) for contents.
+
+## Files
+
+### Layout and component types
+
+**File:** `SKILL.md`
+
+Enforces UI component layout and composition patterns. Use when designing layouts, creating UI components, spacing, gaps, or when the user asks about component hierarchy, terminal vs layout components, or re-render efficiency.
+

ai/skills/aidd-layout/references/index.md

@@ -0,0 +1,12 @@
+# references
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Layout design tokens
+
+**File:** `design-tokens.md`
+
+*No description available*
+

ai/skills/aidd-lit/index.md

@@ -0,0 +1,12 @@
+# aidd-lit
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Lit element authoring
+
+**File:** `SKILL.md`
+
+Enforces Lit element authoring best practices. Use when creating Lit elements, binding elements, presentations, DatabaseElement, useObservableValues, or when the user asks about Lit UI patterns, reactive binding, or action callbacks.
+

ai/skills/aidd-namespace/index.md

@@ -0,0 +1,18 @@
+# aidd-namespace
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Namespace Example.
+
+**File:** `README.md`
+
+*No description available*
+
+### Type namespace pattern
+
+**File:** `SKILL.md`
+
+Ensures types and related functions are authored and consumed in a modular, discoverable, tree-shakeable pattern. Use when creating types, refactoring type folders, defining schemas, importing types, or when the user mentions type namespaces, constants, or Schema.ToType.
+

ai/skills/aidd-observe/index.md

@@ -0,0 +1,12 @@
+# aidd-observe
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Observe pattern
+
+**File:** `SKILL.md`
+
+Enforces Observe pattern best practices from @adobe/data/observe. Use when working with Observe, observables, reactive data flow, service Observe properties, or when the user asks about Observe.withMap, Observe.withFilter, Observe.fromConstant, Observe.fromProperties, or similar.
+

ai/skills/aidd-react/index.md

@@ -0,0 +1,12 @@
+# aidd-react
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### React component authoring
+
+**File:** `SKILL.md`
+
+Enforces React component authoring best practices. Use when creating React components, binding components, presentations, useObservableValues, or when the user asks about React UI patterns, reactive binding, or action callbacks.
+

ai/skills/aidd-service/index.md

@@ -0,0 +1,12 @@
+# aidd-service
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Service authoring
+
+**File:** `SKILL.md`
+
+Enforces asynchronous data service authoring best practices. Use when creating front-end or back-end services, service interfaces, Observe patterns, AsyncDataService, or when the user asks about service layer, data flow, unidirectional UI, or action/observable design.
+

ai/skills/aidd-structure/index.md

@@ -0,0 +1,12 @@
+# aidd-structure
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### Standard folder structure
+
+**File:** `SKILL.md`
+
+Enforces source code structuring and interdependency best practices. Use when creating folders, moving files, adding imports, or when the user asks about architecture, layering, or module dependencies.
+

ai/skills/index.md

@@ -0,0 +1,42 @@
+# skills
+
+This index provides an overview of the contents in this directory.
+
+## Subdirectories
+
+### 📁 aidd-ecs/
+
+See [`aidd-ecs/index.md`](./aidd-ecs/index.md) for contents.
+
+### 📁 aidd-fix/
+
+See [`aidd-fix/index.md`](./aidd-fix/index.md) for contents.
+
+### 📁 aidd-layout/
+
+See [`aidd-layout/index.md`](./aidd-layout/index.md) for contents.
+
+### 📁 aidd-lit/
+
+See [`aidd-lit/index.md`](./aidd-lit/index.md) for contents.
+
+### 📁 aidd-namespace/
+
+See [`aidd-namespace/index.md`](./aidd-namespace/index.md) for contents.
+
+### 📁 aidd-observe/
+
+See [`aidd-observe/index.md`](./aidd-observe/index.md) for contents.
+
+### 📁 aidd-react/
+
+See [`aidd-react/index.md`](./aidd-react/index.md) for contents.
+
+### 📁 aidd-service/
+
+See [`aidd-service/index.md`](./aidd-service/index.md) for contents.
+
+### 📁 aidd-structure/
+
+See [`aidd-structure/index.md`](./aidd-structure/index.md) for contents.
+