/implement-github-feature

name: implement-github-feature
description: Design and implement a new feature or component from a GitHub issue. Use for net-new functionality, not bug fixes.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Write, Bash(gh issue view *), Bash(gh pr view *), Bash(git status), Bash(git diff *), Bash(git log *), Bash(git branch *), Bash(git checkout *), Bash(git add *), Bash(git commit *), Bash(npm run build), Bash(npm run lint), Bash(ls *)

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

2. **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

3. **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)

4. **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)

5. **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

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

8. **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

9. **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