implement-github-feature

Usage: /implement-github-feature ISSUE_NUMBER

Example: /implement-github-feature 281

Implement GitHub feature request $ARGUMENTS following AgnosticUI conventions, accessibility standards, and CSS-first principles.

Setup

1. Read project context

- Read .claude/PROJECT_CONTEXT.md - Understand: - Repository structure - Design principles - Accessibility requirements - Branch conventions - Component workflows

Phase 0: Safety Checks (Required)

1. Verify clean starting state

- Run git status - Confirm: - Working directory is clean - Current branch is master - If either condition fails: - STOP - Ask the user to resolve before continuing

Phase 1: Branching

1. Propose feature branch

- Follow convention: issue-$ARGUMENTS/short-descriptive-name - Example: issue-281/selection-card-group - Run: `` git checkout -b issue-$ARGUMENTS/short-description `` - WAIT FOR USER APPROVAL of branch name before proceeding

Phase 2: Issue Analysis & Intent Extraction (No Code)

1. Analyze the GitHub issue

- Fetch full details: `` gh issue view $ARGUMENTS `` - Extract and summarize: - Feature goals - Non-goals / constraints - API expectations - Accessibility requirements - Styling and theming expectations - Framework implications (Lit / React / Vue)

1. Study existing related components

- Identify components this feature will compose or resemble - Read their implementations in v2/lib/src/components/ - Note patterns for: - Props and attributes - Slot usage - CSS custom properties - ::part exposure - Event dispatching - Accessibility implementation - This ensures consistency with established AgnosticUI conventions

1. Confirm feature classification

- This is a: - Net-new component OR - Major enhancement (not a bug fix) - If scope appears ambiguous: - Ask the user before proceeding

Phase 3: Design Proposal (Hard Stop Before Code)

1. Propose high-level design

- Identify: - New components to be created - Public vs internal APIs - Required props vs optional props - Slot usage and responsibilities - Accessibility model (labels, roles, keyboard behavior) - Shadow DOM strategy (::part, ::slotted) - Explicitly call out: - Web Component constraints - CSS-first decisions - What is intentionally not supported

1. Propose file & directory layout

- Core components: - v2/lib/src/components/... - Documentation: - v2/site/docs/components/... - Storybook playgrounds: - Lit - React - Vue - Examples: - Lit / React / Vue test examples

1. WAIT FOR USER APPROVAL

- Do not create files - Do not write code - Proceed only after explicit approval of: - API shape - Accessibility approach - Styling strategy

Phase 4: Scaffolding (Minimal, Intentional)

1. Create initial scaffolding

- Create component directories - Add placeholder files where appropriate - Add minimal README or doc stubs if needed - No implementation logic yet

1. Show scaffolding diff

- Use git diff - Explain what was created and why - WAIT FOR USER APPROVAL

Phase 5: Core Implementation (Lit Web Components First)

1. Implement core component(s)

- Work only in: - v2/lib/src/components/ - Follow: - CSS-first approach - Design token usage - Accessibility requirements - Ensure: - Keyboard interaction works - Labels and semantics are correct - Shadow DOM parts are intentional and minimal

1. Verify build

- Run npm run build in v2/lib/ - Fix any compilation errors - Run npm run lint if available

1. Pause for review

- Explain: - DOM structure - Slot behavior - ::part surface - Accessibility decisions - WAIT FOR USER APPROVAL before proceeding

Phase 6: Framework Integrations

1. Integrate with frameworks

- React playground - Vue playground - Lit playground - APIs should feel idiomatic but map 1:1 conceptually

1. Add Storybook stories

- Demonstrate: - Core use cases - Variants - Accessibility states - Ensure consistency across frameworks

Phase 7: Documentation & Examples

1. Write documentation

- Add VitePress docs: - API - Slots vs props - Styling guidance - Accessibility notes - Update or add playbooks if applicable

1. Update examples

- Verify examples compile and behave correctly - Keep examples minimal and educational

Phase 8: Final Review & Commit

1. Final verification

- Review: - git diff - Accessibility behavior - Styling hooks - API consistency - Ensure no accidental breaking changes

1. Prepare commit

- Stage changes: `` git add . ` - Commit message format: ` Add #$ARGUMENTS: [concise feature description] `` - Show commit contents - WAIT FOR USER APPROVAL before committing

Phase 9: Handoff

1. Explain next steps

- User is on branch: issue-$ARGUMENTS/... - Review with: `` git diff master ` - Push when ready: ` git push -u origin issue-$ARGUMENTS/... ` - Create PR: ` gh pr create --base master --head issue-$ARGUMENTS/... ``

Important Rules

• NEVER work directly on master
• NEVER push without explicit user permission
• ALWAYS stop at design gates
• ALWAYS prioritize accessibility over convenience
• Prefer slots for layout, props for semantics
• CSS custom properties > ::part > ::slotted
• Do not assume intent — if unclear, ask