---
namespace: aiwg
name: validate-addon
description: Validate an entire AIWG addon package for completeness and release readiness
platforms: [all]

---

# Validate Addon

You check an entire AIWG addon directory for completeness and release readiness, then produce a detailed structured report covering manifest integrity, artifact completeness, placement violations, and any blocking issues.

## Triggers

- "validate this addon" → check the addon in the current or named directory
- "is this addon ready to release" → run full release readiness check
- "check the <addon-name> addon" → validate the named addon
- "pre-release check on my addon" → run validate-addon
- "addon readiness report" → full validation with report output
- "validate addon at <path>" → validate the addon at the given path

## Trigger Patterns Reference

| Pattern | Example | Action |
|---------|---------|--------|
| Current directory | "validate this addon" | Validate addon at cwd |
| Named addon | "check the aiwg-dev addon" | Find addon by name and validate |
| Path-specific | "validate addon at agentic/code/addons/my-addon" | Validate at given path |
| Release gate | "is this addon ready to release" | Full validation, block on any FAIL |
| Quick check | "any issues with this addon" | Run validation, summarize findings |

## Process

1. **Locate the addon**:
   - If path given: use it
   - If name given: find `agentic/code/addons/<name>/manifest.json`
   - If current directory: look for `manifest.json` in cwd or walk up to nearest addon root

2. **Read and validate `manifest.json`**:
   - File exists at addon root
   - Valid JSON (parseable)
   - Required fields present: `id`, `type`, `name`, `version`, `description`
   - `type` equals `"addon"`
   - `version` follows CalVer format (`YYYY.M.PATCH`, no leading zeros)
   - `core` field present (boolean)
   - `autoInstall` field present (boolean)
   - If `devOnly: true`: confirm this is intentional (it excludes from `aiwg use all`)

3. **Check `README.md`**:
   - File exists at addon root
   - Non-empty content

4. **Validate each skill listed in manifest**:
   For each entry in `manifest.json` `skills` array:
   - `skills/<name>/SKILL.md` exists
   - `description:` frontmatter present
   - `# Title` section present
   - `## Behavior` or `## Process` section present
   - Collect any missing skills (in manifest but no SKILL.md) and orphaned skills (SKILL.md exists but not in manifest)

5. **Validate each agent listed in manifest**:
   For each entry in `manifest.json` `agents` array:
   - Agent `.md` file exists
   - YAML frontmatter present
   - `name:`, `description:`, `model:`, `tools:` fields in frontmatter
   - Collect missing and orphaned agents

6. **Validate each rule listed in manifest**:
   For each entry in `manifest.json` `rules` array:
   - `rules/<name>.md` exists
   - `RULES-INDEX.md` exists in `rules/`
   - Rule name appears in `RULES-INDEX.md`

7. **Check for placement violations**:
   - Search corresponding provider directories (`.claude/skills/`, `.github/agents/`, etc.) for any files whose names match this addon's artifacts
   - For each match: verify a source file exists in `agentic/code/`
   - Flag any deployed files with no source as violations

8. **Check for `.aiwg/` references in addon artifacts**:
   - Search all SKILL.md, agent `.md`, and command `.md` files under the addon for `@.aiwg/` path references
   - Flag any found: these only resolve inside the AIWG repository itself

9. **Compile report**:

   ```
   Addon Validation: <addon-name> v<version>
   Path: agentic/code/addons/<name>/

   Manifest:
     PASS  manifest.json present and valid JSON
     PASS  required fields: id, type, name, version, description
     PASS  version format: 2026.4.0 (CalVer, no leading zeros)
     PASS  devOnly: true (excluded from `aiwg use all` — intentional)

   README:
     PASS  README.md present

   Skills (3 listed):
     PASS  validate-component: SKILL.md present, frontmatter complete
     PASS  validate-addon: SKILL.md present, frontmatter complete
     FAIL  dev-doctor: listed in manifest but SKILL.md missing

   Agents (0 listed):
     PASS  no agents declared

   Rules (4 listed):
     PASS  skill-placement: rule file present, in RULES-INDEX.md
     PASS  no-circular-skill-calls: rule file present, in RULES-INDEX.md
     PASS  component-completeness: rule file present, in RULES-INDEX.md
     FAIL  addon-boundaries: not found in RULES-INDEX.md

   Placement violations:
     PASS  no orphaned deployed files found

   .aiwg/ references:
     PASS  no .aiwg/ path references in deployable artifacts

   Result: FAIL — 2 blocking issues

   Blocking issues:
     1. skills/dev-doctor/SKILL.md missing — create the file or remove from manifest
     2. addon-boundaries not in rules/RULES-INDEX.md — add an entry

   Warnings:
     none
   ```

10. **Report result**: Surface the structured report to the user. Highlight blocking issues in the summary line. For each failure, include the specific remediation step.

## Examples

### Example 1: Fully valid addon

**User**: "Is the aiwg-dev addon ready to release?"

**Output**:
```
Addon Validation: aiwg-dev v1.0.0
Path: agentic/code/addons/aiwg-dev/

Manifest:          PASS (all required fields, valid CalVer)
README:            PASS
Skills (3):        PASS (all present and complete)
Agents (0):        PASS
Rules (4):         PASS (all present and in RULES-INDEX.md)
Placement:         PASS (no violations)
.aiwg/ refs:       PASS

Result: PASS — addon is release-ready
```

### Example 2: Addon with gaps found

**User**: "check the my-new-addon addon"

**Output**:
```
Addon Validation: my-new-addon v2026.4.0
Path: agentic/code/addons/my-new-addon/

Manifest:          PASS
README:            FAIL — README.md missing
Skills (2):
  PASS  my-skill: complete
  FAIL  other-skill: SKILL.md missing (listed in manifest but file not found)
Rules (1):         PASS
Placement:         WARN — .claude/skills/orphan-skill/ found with no agentic/code/ source

Result: FAIL — 2 blocking issues, 1 warning

Blocking issues:
  1. README.md missing — create at agentic/code/addons/my-new-addon/README.md
  2. skills/other-skill/SKILL.md missing — create the file or remove from manifest

Warnings:
  W1. .claude/skills/orphan-skill/ has no source in agentic/code/ — may be a placement violation
      See: agentic/code/addons/aiwg-dev/rules/skill-placement.md
```

## References

- @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/component-completeness.md — Completeness requirements per artifact type
- @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/skill-placement.md — Placement violation detection
- @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/addon-boundaries.md — .aiwg/ reference detection
- @$AIWG_ROOT/agentic/code/addons/aiwg-dev/skills/validate-component/SKILL.md — Per-component validation