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

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

Phase 0: Safety Checks (Required)

• 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

• 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)

• 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)

• 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

• 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)

• 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

• 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

10. 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)

11. Create initial scaffolding

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

12. Show scaffolding diff

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

Phase 5: Core Implementation (Lit Web Components First)

13. 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

14. Verify build

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

15. Pause for review

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

Phase 6: Framework Integrations

16. Integrate with frameworks

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

17. Add Storybook stories

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

Phase 7: Documentation & Examples

18. Write documentation

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

19. Update examples

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

Phase 8: Final Review & Commit

20. Final verification

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

21. 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

22. 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