# Plugin Data Convention

Standard convention for plugins that create files in user projects.

## Path Convention

```
.claude/plugin-data/<plugin-name>/<data-type>/
```

Plugins creating files in user projects MUST use this path structure.

## Examples

| Plugin | Path | Purpose |
|--------|------|---------|
| ux | `.claude/plugin-data/ux/audits/` | UX audit findings |
| seo-audit | `.claude/plugin-data/seo-audit/reports/` | SEO audit reports |
| commit | `.claude/plugin-data/commit/history/` | If commit needed state |

## File Naming

Use descriptive, sortable names:

```
<date>-<type>-<subject>.md
```

Examples:
- `2024-01-15-heuristic-checkout-flow.md`
- `2024-01-15-accessibility-homepage.md`
- `2024-01-15-report-full-audit.md`

## Gitignore

User projects should add to `.gitignore`:

```
.claude/plugin-data/
```

This data is transient and project-specific. It should not be committed.

For specific plugin types, consider more granular patterns:

```
# Temporary files
**/.claude/plugin-data/<plugin-name>/tmp/

# Cached data
**/.claude/plugin-data/<plugin-name>/cache/

# Log files
**/.claude/plugin-data/<plugin-name>/*.log
```

## Artifact Lifecycle

When designing functionality that creates plugin data files, consider cleanup needs.

### Lifecycle Types

| Type | Example | Recommended Approach |
|------|---------|---------------------|
| Audit findings | UX heuristic evaluation | Manual cleanup, historical value |
| Temporary state | In-progress work | Auto-archive or TTL-based cleanup |
| Reports | SEO audit summary | Archival policy, version-dated |

### Documentation Requirements

1. **In the skill/workflow**: Document expected lifecycle of created artifacts
2. **In plugin CLAUDE.md**: Add cleanup guidance section

## Plugin Author Checklist

When your plugin creates files in user projects:

- [ ] Use `.claude/plugin-data/<plugin>/` path
- [ ] Choose semantic subdirectory name (audits/, reports/, state/)
- [ ] Document cleanup expectations in workflow
- [ ] Consider if automated cleanup is warranted
- [ ] Add note to generated files about their transient nature
- [ ] Include cleanup guidance in plugin CLAUDE.md
