diff --git a/.claude/plans/README.md b/.claude/plans/README.md index b093b690..901aba26 100644 --- a/.claude/plans/README.md +++ b/.claude/plans/README.md @@ -53,16 +53,8 @@ Brief description of what was implemented. Any gotchas or important context for future reference. ``` -## Relationship to RFCs +## See Also -Plans may link to their parent RFC: - -```markdown -# Implementing Feature X - -**RFC:** [/rfc/feature-x.md](/rfc/feature-x.md) - -## Tasks - -... -``` +- [Design Docs](/internal/design/README.md) — Decisions you own +- [RFCs](/rfc/README.md) — Proposals needing buy-in +- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate diff --git a/.claude/skills/README.md b/.claude/skills/README.md index aba7b294..aaff80bd 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -10,7 +10,7 @@ Specialized knowledge for AI agents working on Video.js 10. | Building Lit components | `component` + `aria` | | Building React components | `component` + `aria` | | Writing documentation | `docs` | -| Writing RFCs | `rfc` | +| Writing Design Docs / RFCs | `design` or `rfc` | | Reviewing API/architecture | `api` → `review/workflow.md` | | Reviewing documentation | `docs` → `review/workflow.md` | | Reviewing components | `component` → `review/workflow.md` | @@ -32,11 +32,12 @@ Specialized knowledge for AI agents working on Video.js 10. | [commit-pr](commit-pr/SKILL.md) | Commit changes and create/update PRs with conventions | No | | [component](component/SKILL.md) | Build headless UI components — compound patterns, state, styling | Yes | | [create-skill](create-skill/SKILL.md) | Create new skills with proper structure and conventions | No | +| [design](design/SKILL.md) | Write Design Docs — decisions you own, component specs, feature designs| No | | [docs](docs/SKILL.md) | Write Video.js 10 documentation | Yes | | [gh-issue](gh-issue/SKILL.md) | Analyze GitHub issues and create implementation plans | No | | [git](git/SKILL.md) | Git workflow — commit messages, PRs, branch naming, scope inference | No | | [review-branch](review-branch/SKILL.md) | Review branch changes and suggest improvements | No | -| [rfc](rfc/SKILL.md) | Write RFCs — design docs, architecture proposals, component specs | No | +| [rfc](rfc/SKILL.md) | Write RFCs — proposals needing buy-in (public API, product, DX) | No | ## Review Workflows diff --git a/.claude/skills/design/SKILL.md b/.claude/skills/design/SKILL.md new file mode 100644 index 00000000..1f3edba3 --- /dev/null +++ b/.claude/skills/design/SKILL.md @@ -0,0 +1,205 @@ +--- +name: design +description: >- + Write Design Docs for Video.js 10. Use for architectural decisions, component specs, + feature designs, and internal patterns you own. Triggers: "write design doc", "create design", + "component spec", "feature design", "document decision". +--- + +# Design + +Write Design Docs for Video.js 10. + +Design Docs are for **decisions you own** — architectural choices, component specs, and internal patterns. For proposals needing buy-in from others, use an RFC instead (`rfc/`). + +## Reference Material + +| Task | Load | +| --------------------- | --------------------------------- | +| Any design task | This file (SKILL.md) | +| Choosing structure | `references/structure.md` | +| Feature guidance | `references/features.md` | +| Component guidance | `references/components.md` | +| Simple decision | `templates/decision.md` | +| Feature (single-file) | `templates/feature-single.md` | +| Feature (multi-file) | `templates/feature-multi.md` | +| Component (basic) | `templates/component-basic.md` | +| Component (compound) | `templates/component-compound.md` | + +## When to Write a Design Doc + +**Write a Design Doc when:** + +- Architectural decisions in your area +- Internal implementation choices +- Design patterns or component specs you own +- Documenting decisions for posterity + +**Use an RFC instead when:** + +- Changes public API surface +- Affects product direction +- Affects user-facing developer experience +- Significant changes to core architecture +- Needs buy-in from others + +**Skip both for:** + +- Bug fixes +- Small features in one package +- Implementation details +- Documentation updates + +See `internal/design/README.md` for format and file naming. + +## Principles + +### 1. Start with the Problem + +Every design begins with the pain we're solving. A first-time reader needs context before solutions make sense. + +```markdown +## Problem + +Two concerns, one player: + +1. **Media** — play, pause, volume. Owned by `