84 lines
2.1 KiB
Markdown
84 lines
2.1 KiB
Markdown
|
# 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
|