diff --git a/.github/projects/active/repo-restructuring-2026-07-25/WEBSITE-UPDATE-REQUIREMENTS.md b/.github/projects/active/repo-restructuring-2026-07-25/WEBSITE-UPDATE-REQUIREMENTS.md new file mode 100644 index 0000000000..ee29091d56 --- /dev/null +++ b/.github/projects/active/repo-restructuring-2026-07-25/WEBSITE-UPDATE-REQUIREMENTS.md @@ -0,0 +1,812 @@ +--- +title: Website Update Requirements (Phase 4) +description: Documentation of website changes needed to support plugin adoption strategy and tiered onboarding +created: 2026-07-26 +updated: 2026-07-26 +status: handoff-ready +owner: Web Team (github.lightspeedwp.agency) +--- + +# Website Update Requirements — Phase 4: Plugin Adoption + +Requirements for updating github.lightspeedwp.agency to support plugin adoption documentation, tiered onboarding, and integrated documentation rendering. + +**Handoff Status:** Ready for web team implementation +**Deployment Timeline:** Before September 1, 2026 (Tier 2 rollout) +**Support:** Coordinate with Ash Shaw for any clarifications + +--- + +## Executive Summary + +Phase 4 generates 7 new documentation files for plugin adoption. The website must be updated to: + +1. **Route onboarding by team tier** (maintainers → contributors → consumers) +2. **Render documentation pages** from `/docs/` markdown +3. **Provide getting started guides** specific to each role +4. **Create references section** linking to agents, skills, hooks, plugins +5. **Integrate cookbook** for recipes and implementation examples + +--- + +## Onboarding Page (`/`) + +### Current State + +- Generic getting started content +- No role-based routing +- Single onboarding flow + +### Required Changes + +#### Route by Team Tier + +Implement role-based navigation on homepage: + +```html + +
+

Getting Started (Select Your Role)

+ +
+ + + I'm a Core Maintainer + Full access to infrastructure, plugins, and governance docs + /getting-started/maintainers/ + +
  • Plugin setup guides
    • +
  • Repository governance
    • +
  • Agent & skill development
    • +
  • Infrastructure maintenance
    • +     +     + + + + I'm a Contributor + Setup guide and workflow essentials + /getting-started/contributors/ + +
  • Plugin setup (quick)
    • +
  • Branching strategy
    • +
  • PR workflow
    • +
  • Code standards
    • +     +     + + + + I'm a Consumer (WordPress Team) + Using agents and skills for WordPress projects + /getting-started/consumers/ + +
  • Getting started
    • +
  • Using agents
    • +
  • Using skills
    • +
  • FAQ & support
    • +     +     +
    +
    +``` + +**Implementation Details:** + +- Use CSS cards with icon/image for each role +- Make choice obvious and easy to understand +- Include brief description of each path +- Links should be prominent and clear + +--- + +## Getting Started Pages + +### New Structure + +Create three distinct onboarding flows: + +``` +/getting-started/ +├── maintainers/ +│ ├── index.md +│ ├── setup-complete.md +│ ├── vscode-workspace.md +│ └── governance.md +├── contributors/ +│ ├── index.md +│ ├── setup-quick.md +│ ├── branching-strategy.md +│ └── pr-workflow.md +└── consumers/ + ├── index.md + ├── quick-setup.md + ├── using-agents.md + ├── using-skills.md + └── faq.md +``` + +### `/getting-started/maintainers/` + +**Content:** Full setup including all plugins and infrastructure + +**Sections:** + +1. **Welcome Message** + - Title: "Welcome, Core Maintainers" + - Description: Full access to plugins, agents, and governance + +2. **Plugin Setup** + - Embed or link to: `/docs/plugin-setup-claude-code.md` + - Embed or link to: `/docs/plugin-setup-github-copilot.md` + - Link to: `/docs/plugin-testing.md` + +3. **VSCode Workspace** + - Link to: `/docs/vscode-workspace-setup.md` + - Mention: Multi-root workspace configuration + - Mention: Settings sync + +4. **Repository Governance** + - Link to: `/docs/BRANCHING_STRATEGY.md` + - Link to: `/docs/AGENTS.md` + - Link to: `/docs/PR_CREATION_PROCESS.md` + +5. **Agent & Skill Development** + - Link to: `/docs/AGENT_CREATION.md` + - Link to: `/docs/SKILL_DEVELOPMENT.md` + - Link to: `/agents/` reference + +6. **Custom Agents** + - How to create custom agents in Claude Code + - Link to examples in `.claude/agents/` + +7. **Troubleshooting** + - Link to: `/docs/vscode-plugin-troubleshooting.md` + - Common issues specific to maintainers + +**Call-to-Action:** "Ready? Install Claude Code and GitHub Copilot" + +### `/getting-started/contributors/` + +**Content:** Quick setup for feature development + +**Sections:** + +1. **Welcome Message** + - Title: "Welcome, Contributors" + - Description: Everything you need to contribute + +2. **Quick Plugin Setup** (Condensed) + - Links to setup guides (don't embed full content) + - Estimate: 15 minutes to setup + - Plugins: Claude Code + GitHub Copilot + +3. **Branching Strategy** + - Link to: `/docs/BRANCHING_STRATEGY.md` + - Key points: Branch naming, protection, reuse prevention + +4. **PR Workflow** + - Link to: `/docs/PR_CREATION_PROCESS.md` + - Templates available + - Review process + +5. **Code Standards** + - Link to: `/docs/coding-standards.md` + - Language-specific guidelines + - ESLint/Prettier config + +6. **Getting Help** + - Where to ask questions + - GitHub discussions + - Plugin help channel (`[plugin-help]` label) + +**Call-to-Action:** "Let's get you set up in 15 minutes" + +### `/getting-started/consumers/` + +**Content:** WordPress teams using agents and skills + +**Sections:** + +1. **Welcome Message** + - Title: "Welcome, WordPress Project Teams" + - Description: How to use our agents and skills + +2. **What Are Agents?** + - Link to: `/agents/` directory + - List available agents with descriptions + - Example: "Use website-content-strategist for copy" + +3. **What Are Skills?** + - Link to: `/skills/` directory + - List available skills with descriptions + - Example: "Use figma-design-to-code for design implementation" + +4. **Using Agents** + - Link to agent documentation + - Walkthrough of running an agent + - Expected workflow + +5. **Using Skills** + - Link to skill documentation + - When to use each skill + - Limitations and best practices + +6. **FAQ** + - Common questions + - Troubleshooting + - Getting support + +7. **Support** + - When to open issues + - Expected response time + - Escalation process + +**Call-to-Action:** "Browse our agents to get started" + +--- + +## Documentation Page (`/documentation/`) + +### Current State + +- Likely doesn't exist or has minimal content +- Doesn't render docs from repository + +### Required Changes + +#### Auto-Render Documentation + +Create page that dynamically renders markdown from `/docs/`: + +``` +/documentation/ +├── index.md (Lists all docs) +├── plugin-setup-claude-code.html (rendered from docs/plugin-setup-claude-code.md) +├── plugin-setup-github-copilot.html (rendered from docs/plugin-setup-github-copilot.md) +├── plugin-comparison.html +├── plugin-adoption-phases.html +├── plugin-testing.html +├── vscode-plugin-troubleshooting.html +├── vscode-workspace-setup.html +├── branching-strategy.html +├── coding-standards.html +├── migration-guide.html +└── [other docs...] +``` + +**Implementation Approach:** + +Option A: **Build-time rendering** (Recommended) + +- Documentation build process reads `/docs/` markdown +- Renders to HTML during build +- Includes table of contents, search, syntax highlighting +- Build tool: Astro, Eleventy, Hugo, Jekyll, etc. + +Option B: **Runtime rendering** (Alternative) + +- Client-side markdown-to-HTML conversion +- Uses marked.js or remark +- Good for frequent updates + +**Required Features:** + +- [ ] Markdown frontmatter support +- [ ] Table of contents (auto-generated) +- [ ] Syntax highlighting for code blocks +- [ ] Search functionality +- [ ] Mobile responsive +- [ ] Dark/light mode +- [ ] Previous/next navigation + +**Content to Render:** + +From `/docs/`: + +- plugin-setup-claude-code.md +- plugin-setup-github-copilot.md +- plugin-comparison.md +- plugin-adoption-phases.md +- plugin-testing.md +- vscode-plugin-troubleshooting.md +- vscode-workspace-setup.md +- branching-strategy.md +- coding-standards.md +- MIGRATION.md (if exists) + +**Rendering Example:** + +Input (Markdown): + +```markdown +# Claude Code Setup Guide + +A comprehensive guide to installing Claude Code... +``` + +Output (HTML): + +```html +
    +

    Claude Code Setup Guide

    +

    A comprehensive guide to installing Claude Code...

    + +
    +``` + +--- + +## References Section (`/references/`) + +### Current State + +- Doesn't exist +- No central reference for agents, skills, hooks, plugins + +### Required Changes + +Create reference hub linking to all reusable assets: + +``` +/references/ +├── agents/ +│ ├── index.md (List all agents with links) +│ └── [agent-specific docs if available] +├── skills/ +│ ├── index.md (List all skills with links) +│ └── [skill-specific docs if available] +├── hooks/ +│ └── index.md (Git hooks documentation) +├── plugins/ +│ └── index.md (Plugin bundles) +├── instructions/ +│ └── index.md (Portable instructions) +└── schemas/ + └── index.md (JSON schema reference) +``` + +#### `/references/agents/` + +**Content:** List of all agents with descriptions + +**Format:** + +```markdown +# Agents Reference + +## Available Agents + +### [Agent Name] +**File:** `/agents/[agent-slug]/` +**Description:** What this agent does +**Use When:** Typical use case +**Status:** Stable/Beta/Experimental +**Link:** [View agent docs] + +### Example: Website Content Strategist +**File:** `/agents/website-content-strategist-agent/` +**Description:** Generates SEO-optimised content for websites +**Use When:** Writing homepage copy, landing pages, blog posts +**Status:** Stable +**Link:** [View AGENT.md] +``` + +**Data Source:** Auto-generate from `/agents/` directory structure + +#### `/references/skills/` + +**Content:** List of all skills with descriptions + +**Format:** + +```markdown +# Skills Reference + +## Available Skills + +### [Skill Name] +**Skill ID:** [ID for slash command] +**Description:** What this skill does +**Use When:** Typical use case +**Link:** [View skill docs] + +### Example: Figma Design to Code +**Skill ID:** `figma-design-to-code` +**Description:** Converts Figma designs to React/Vue code +**Use When:** Implementing design mockups as components +**Link:** [View SKILL.md] +``` + +**Data Source:** Auto-generate from `/skills/` directory structure + +#### `/references/hooks/` + +**Content:** Git hooks documentation + +**Sections:** + +- Available hooks (pre-commit, pre-push, etc.) +- How to install +- How to customise +- Link to: `/hooks/` directory + +#### `/references/plugins/` + +**Content:** Plugin bundles + +**Sections:** + +- Claude Code plugin +- GitHub Copilot plugin +- Other supported plugins +- Installation instructions +- Links to setup guides + +#### `/references/instructions/` + +**Content:** Portable instruction files + +**List:** + +- coding-standards.instructions.md +- a11y.instructions.md +- documentation-formats.instructions.md +- issues.instructions.md +- pull-requests.instructions.md +- community-standards.instructions.md + +**Link:** Each to the source file in `/instructions/` + +--- + +## Cookbook Page (`/cookbook/`) + +### Current State + +- Doesn't exist +- No recipes or implementation guides available + +### Required Changes + +Create recipe hub for common workflows: + +``` +/cookbook/ +├── index.md (Overview of recipes) +├── getting-started/ +│ ├── first-contribution.md +│ ├── setup-vscode.md +│ └── local-development.md +├── agents/ +│ ├── create-custom-agent.md +│ ├── run-agent-in-workflow.md +│ └── debug-agent-issues.md +├── plugins/ +│ ├── claude-code-quick-wins.md +│ ├── copilot-daily-workflow.md +│ └── plugin-troubleshooting-101.md +├── branching/ +│ ├── feature-branch-workflow.md +│ ├── hotfix-workflow.md +│ └── release-branch-workflow.md +└── testing/ + ├── test-generation-with-copilot.md + └── refactoring-with-claude-code.md +``` + +**Implementation:** + +Option A: **Render from `/cookbook/` markdown files** + +- Same approach as documentation page +- Auto-discover recipes and build nav + +Option B: **Create content on website** + +- Manual content creation +- Good for hand-curated examples + +Recommendation: **Option A** (auto-render) + +**Example Recipe:** + +**Filename:** `cookbook/plugins/claude-code-quick-wins.md` + +**Content:** + +```markdown +# Claude Code Quick Wins + +3 ways to use Claude Code today and save 30 minutes + +## 1. Generate Test Cases +**Time saved:** 15 minutes per file +**Steps:** +1. Open a function in Claude Code +2. Ask: "Generate comprehensive test cases" +3. Claude creates Jest/Vitest tests +4. Review and merge into test file + +## 2. Refactor to TypeScript +**Time saved:** 20 minutes per file +**Steps:** +1. Select JavaScript file +2. Ask: "Add TypeScript types, use strict typing" +3. Claude converts with proper types +4. Fix any lint errors + +## 3. Document Code +**Time saved:** 10 minutes per file +**Steps:** +1. Select undocumented function +2. Ask: "Add JSDoc comments" +3. Claude generates docs +4. Review and accept +``` + +--- + +## Navigation Updates + +### Homepage + +Add section showing plugin adoption: + +```html +
    +

    Modern Development Tools

    +

    Adopt AI-powered code assistants for faster development

    + + Get Started with Plugins +
    +``` + +### Main Navigation + +Add/Update navigation items: + +``` +← Back to home +Home +Getting Started ← Dropdown with three roles + ├─ For Maintainers + ├─ For Contributors + └─ For Consumers +Documentation ← New page +References ← New section + ├─ Agents + ├─ Skills + ├─ Hooks + └─ Plugins +Cookbook ← New section +Governance +Community +``` + +### Footer + +Add links to: + +- Plugin adoption timeline +- Support channels +- GitHub discussions +- Help form + +--- + +## Technical Implementation + +### Technology Stack Recommendations + +**Minimum Requirements:** + +- Markdown parsing and rendering +- Frontmatter support +- Table of contents generation +- Search functionality +- Responsive design +- Dark mode support + +**Recommended Tools:** + +- **Static site generator:** Astro, Eleventy, Hugo +- **Markdown processor:** remark, markdown-it +- **Search:** Algolia, meilisearch (self-hosted) +- **Hosting:** Vercel, Netlify, GitHub Pages + +### Build Process + +``` +1. Pull latest docs from /docs/ +2. Parse frontmatter and markdown +3. Generate HTML with syntax highlighting +4. Build search index +5. Deploy to github.lightspeedwp.agency +``` + +### Deployment Checklist + +Before going live: + +- [ ] All markdown files parse without errors +- [ ] Code blocks have syntax highlighting +- [ ] Links are working (internal and external) +- [ ] Search index is complete +- [ ] Mobile responsive tested +- [ ] Dark/light mode works +- [ ] Navigation is clear +- [ ] Performance is acceptable (<3s page load) + +--- + +## Content Migration Plan + +### Phase 1: Setup (Week 1) + +- [ ] Create new pages structure +- [ ] Set up markdown rendering +- [ ] Add placeholder content + +### Phase 2: Documentation (Week 2) + +- [ ] Render all `/docs/` markdown files +- [ ] Create documentation index +- [ ] Set up table of contents +- [ ] Add search functionality + +### Phase 3: References (Week 2) + +- [ ] Create agent reference page +- [ ] Create skill reference page +- [ ] Link to all agents/skills +- [ ] Add description metadata + +### Phase 4: Cookbook (Week 3) + +- [ ] Create cookbook structure +- [ ] Add example recipes +- [ ] Test rendering + +### Phase 5: Testing & Launch (Week 3–4) + +- [ ] Comprehensive testing +- [ ] SEO optimization +- [ ] Performance optimization +- [ ] Live deployment + +--- + +## Success Criteria + +### Launch Readiness + +- [ ] All 7 plugin documentation files render correctly +- [ ] Onboarding routes to correct getting-started pages +- [ ] Documentation page has all required docs +- [ ] References section lists all agents/skills +- [ ] Cookbook has at least 5 recipes +- [ ] Navigation is intuitive and clear +- [ ] All links work (no 404s) +- [ ] Page load time <3 seconds +- [ ] Mobile responsive on all devices +- [ ] Search works across all pages + +### Team Feedback + +- [ ] Core team tests all flows (3/3 approve) +- [ ] Contributors can find what they need +- [ ] WordPress teams understand agent/skill usage +- [ ] No critical issues in first week + +--- + +## Success Metrics + +Post-launch, track: + +| Metric | Target | Measurement | +|--------|--------|-------------| +| **Page Load Time** | <3s | Lighthouse audit | +| **Mobile Performance** | >90 score | PageSpeed Insights | +| **Documentation Coverage** | 100% of /docs/ | File count match | +| **Link Validation** | 0 broken links | Automated checker | +| **Search Functionality** | >95% accuracy | Manual testing | +| **Navigation Clarity** | >80% task success | User testing | + +--- + +## Support & Maintenance + +### Ongoing Tasks + +- **Weekly:** Monitor broken links, fix typos +- **Monthly:** Update documentation index +- **Quarterly:** SEO audit and optimization +- **As needed:** Add new agent/skill documentation + +### Maintenance Contacts + +- **Website:** Web team (github.lightspeedwp.agency) +- **Content:** Ash Shaw () +- **Agents/Skills:** Core maintainers +- **Support:** GitHub issues `[plugin-help]` or website issues + +--- + +## Timeline & Handoff + +### Timeline + +- **26 July 2026:** This requirements document created +- **August 2–9:** Web team implementation +- **August 10–23:** Testing and refinement +- **August 24:** Soft launch (internal team testing) +- **August 31:** Public launch (for Tier 2 rollout) + +### Handoff Procedure + +1. **Web team receives requirements** (this document) +2. **Clarification call** (if needed) +3. **Implementation begins** with weekly sync +4. **Testing phase** before launch +5. **Go-live coordination** with Ash Shaw +6. **Post-launch support** for first 2 weeks + +### Questions/Clarifications + +Contact Ash Shaw at with: + +- Questions about requirements +- Implementation approach confirmation +- Timeline concerns +- Technical constraints + +--- + +## Appendix A: File Mappings + +### Docs to Render + +| Source File | Target URL | Status | +|---------|-----------|--------| +| `/docs/plugin-setup-claude-code.md` | `/documentation/plugin-setup-claude-code/` | Ready | +| `/docs/plugin-setup-github-copilot.md` | `/documentation/plugin-setup-github-copilot/` | Ready | +| `/docs/plugin-comparison.md` | `/documentation/plugin-comparison/` | Ready | +| `/docs/plugin-adoption-phases.md` | `/documentation/plugin-adoption-phases/` | Ready | +| `/docs/plugin-testing.md` | `/documentation/plugin-testing/` | Ready | +| `/docs/vscode-plugin-troubleshooting.md` | `/documentation/vscode-plugin-troubleshooting/` | Ready | + +### Agents to Reference + +| Agent | Path | Link | +|--------|------|------| +| Website Content Strategist | `/agents/website-content-strategist-agent/` | [AGENT.md] | +| Figma Design to Code | `/agents/figma-design-to-code-agent/` | [AGENT.md] | +| [Others...] | `/agents/[slug]/` | [AGENT.md] | + +### Skills to Reference + +| Skill | Path | Link | +|-------|------|------| +| Figma Design to Code | `/skills/figma-design-to-code/` | [SKILL.md] | +| [Others...] | `/skills/[slug]/` | [SKILL.md] | + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial requirements document for Phase 4 website updates | + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy* +**Next Phase:** Phase 5 — Rollout & Team Communications (Aug 1+) diff --git a/docs/plugin-adoption-phases.md b/docs/plugin-adoption-phases.md new file mode 100644 index 0000000000..2bb65b9471 --- /dev/null +++ b/docs/plugin-adoption-phases.md @@ -0,0 +1,471 @@ +--- +title: Plugin Adoption Roadmap +description: Phased rollout strategy for AI code assistant plugins across the LightSpeedWP team +created: 2026-07-26 +updated: 2026-07-26 +type: guide +--- + +# Plugin Adoption Roadmap + +A three-phase rollout plan for adopting AI-powered development tools across LightSpeedWP, with timelines, success criteria, and support infrastructure. + +--- + +## Timeline Overview + +Phased adoption of Claude Code and GitHub Copilot across three tiers of team members, rolling out from August 2026 through October 2026. + +``` +August 2026: Tier 1 (2–3 core maintainers) +September 2026: Tier 2 (4–5 all contributors) +October 2026+: Tier 3 (8–9 WordPress project teams) +``` + +--- + +## Tier 1: Core Maintainers & Lead Contributors + +### Timeline: August 2026 + +**Duration:** Full month (Aug 1–Aug 31) + +### Team Members + +- Ash Shaw (Project Lead) +- 1–2 additional core maintainers +- **Total: 2–3 people** + +### Plugins to Install + +**Mandatory:** + +- ✅ Claude Code (Anthropic) +- ✅ GitHub Copilot (GitHub) + +**Optional:** + +- ⚠️ Copilot Chat (recommended) +- ⚠️ Codex (for evaluation) + +### Setup Activities + +| Week | Activity | Owner | Duration | +|------|----------|-------|----------| +| 1 | Install both plugins, verify auth | Core team | 1 hour | +| 1 | Read setup guides and review comparisons | Core team | 2 hours | +| 2 | Use in real work, document first impressions | Core team | Ongoing | +| 2–3 | Identify best use cases and workflows | Core team | 4 hours | +| 3 | Create team guidelines and best practices | Claude Code | 2 hours | +| 4 | Final evaluation and feedback collection | Core team | 1 hour | + +**Total time commitment:** ~10 hours per person + +### Success Criteria + +✅ **Installation:** Both plugins working on 100% of core team machines (3/3) + +✅ **Usage:** Minimum 10 hours of actual development time with both tools combined + +✅ **Documentation:** Team guidelines document completed and reviewed + +✅ **Proficiency:** Core team comfortable with both tools' main features + +✅ **Feedback:** Initial feedback documented in GitHub issue + +### Expected Outcomes + +- Core team trained and comfortable with both tools +- Best practices documented for broader team +- Issues and limitations identified early +- Ready to roll out to Tier 2 + +### Support Plan + +- **Help Channel:** GitHub issues with label `[plugin-help]` +- **Escalation:** Contact Ash Shaw +- **Resources:** Setup guides, comparison doc, troubleshooting guide +- **Grace Period:** Full month for questions and adjustments + +--- + +## Tier 2: All Contributors + +### Timeline: September 2026 + +**Duration:** Full month (Sep 1–Sep 30) + +### Team Members + +- All 4–5 active contributors +- 2–3 core maintainers (from Tier 1) +- **Total: 6–8 people** + +### Plugins to Install + +**Mandatory:** + +- ✅ Claude Code (Anthropic) +- ✅ GitHub Copilot (GitHub) + +**Recommended:** + +- ⚠️ GitHub Copilot Chat (for complex requests) + +**Optional:** + +- ⚠️ Codex (power users only) +- ⚠️ Gemini (evaluation phase) + +### Setup Activities + +| Week | Activity | Owner | Duration | +|------|----------|-------|----------| +| 1 | Core team presents setup guides and best practices | Core team | 30 min | +| 1 | Contributors install plugins and verify setup | Contributors | 1 hour | +| 1 | Q&A session and troubleshooting | Core team | 1 hour | +| 2–3 | Contributors integrate into daily workflow | Contributors | Ongoing | +| 3 | Feedback collection and common issues logged | All | 1 hour | +| 4 | Final assessment and Phase 3 preparation | Core team | 1 hour | + +**Total time commitment:** ~4–5 hours per person + +### Success Criteria + +✅ **Installation:** Both plugins working on 100% of contributor machines (5/5) + +✅ **Adoption:** >80% of team actively using at least one tool within 2 weeks + +✅ **Support:** <5 unresolved issues with `[plugin-help]` label at end of month + +✅ **Feedback:** Positive feedback from >60% of team on usefulness + +✅ **Proficiency:** Contributors able to use basic features independently + +### Expected Outcomes + +- Full contributor team equipped with modern development tools +- Common issues documented and resolved +- Team guidelines validated and refined +- Ready for Tier 3 rollout and WordPress project teams + +### Support Plan + +- **Help Channel:** GitHub issues with label `[plugin-help]` +- **Escalation:** Contact Ash Shaw +- **Resources:** Tier 1 documentation + new troubleshooting additions +- **Mentorship:** Core team available for pair programming +- **Grace Period:** 3 weeks for problems, 1 week for optimization + +--- + +## Tier 3: WordPress Project Consumers + +### Timeline: October 2026 onwards + +**Duration:** Ongoing (Oct 1+) + +### Team Members + +- 8–9 WordPress project teams +- Development, design, and quality assurance members +- **Total: 20–30 people** + +### Plugins Available + +**Tier 1 Tools (Full Suite):** + +- ✅ Claude Code (Anthropic) +- ✅ GitHub Copilot (GitHub) + +**Emerging Tools (Optional Evaluation):** + +- ⚠️ Codex (for power users) +- ⚠️ Gemini (evaluation) + +**Legacy Tools (Sunset Timeline):** + +- ⚠️ Other AI assistants (to be phased out by Q1 2027) + +### Setup Activities + +| Phase | Activity | Owner | Duration | +|-------|----------|-------|----------| +| Phase 3a | Optional training sessions for WordPress teams | Core team | 1 hour each | +| Phase 3b | Self-paced setup using documentation | Project teams | 2–3 hours | +| Phase 3c | Feedback and integration into project workflows | Project teams | Ongoing | +| Phase 3d | Vendor evaluation and contract negotiation | Ash Shaw | Ongoing | + +**Total time commitment:** 2–3 hours per person (optional) + +### Success Criteria + +✅ **Availability:** Tools available to all WordPress project teams + +✅ **Adoption:** >50% of project teams actively using at least one tool + +✅ **Support:** Help channel actively monitored and issues resolved within 24 hours + +✅ **Satisfaction:** Net satisfaction score >70% (from surveys) + +✅ **ROI:** Documented productivity gains from teams using tools + +### Expected Outcomes + +- Org-wide plugin adoption infrastructure in place +- All developers equipped with modern AI tools +- Cost optimization through tiered access +- Foundation for future AI tool expansion + +### Support Plan + +- **Help Channel:** GitHub issues with label `[plugin-help]` +- **Escalation:** Contact Ash Shaw +- **Resources:** Full documentation library + video tutorials +- **Mentorship:** Optional pair programming with core team +- **Grace Period:** 4 weeks for each project team + +--- + +## Grace Period & Support Infrastructure + +### Grace Period Timeline + +**Duration:** 3 weeks from plugin release in each tier + +During grace period: + +- ✅ No penalties for not using the tools +- ✅ Extensive support available +- ✅ Training sessions offered +- ✅ Issues resolved quickly +- ✅ Tool configuration can be adjusted + +**After grace period:** + +- Optional integration encouraged (not required) +- Standard support available +- Community-driven learning + +### Support Channels + +**Primary:** GitHub Issues + +- Label: `[plugin-help]` +- Response time: <24 hours +- Escalation: @ashleyshaw + +**Secondary:** Direct Messages + +- Owner: Ash Shaw () +- Use for: Urgent blockers only +- Response time: <4 hours + +**Tertiary:** Documentation + +- Setup guides: `/docs/plugin-setup-*.md` +- Troubleshooting: `/docs/vscode-plugin-troubleshooting.md` +- FAQ: This document + GitHub wiki + +### Support Resources + +- ✅ [Plugin Setup Guides](./plugin-setup-claude-code.md) +- ✅ [Plugin Comparison](./plugin-comparison.md) +- ✅ [Testing Guide](./plugin-testing.md) +- ✅ [Troubleshooting Guide](./vscode-plugin-troubleshooting.md) +- ✅ GitHub wiki with FAQs +- ✅ Video tutorials (coming Sep 2026) + +--- + +## Success Metrics + +### Tier 1: Core Maintainers + +| Metric | Target | Measurement | +|--------|--------|-------------| +| **Installation Success** | 100% (3/3) | Plugin installed and authenticated | +| **Usage Hours** | 10+ hours/person | Tracked through extension telemetry | +| **Code Generated** | 50+ completions | From Copilot stats | +| **Team Cohesion** | 100% agreement on best practices | Survey after Week 3 | +| **Documentation Quality** | Guidelines document completed | Peer review approval | + +### Tier 2: All Contributors + +| Metric | Target | Measurement | +|--------|--------|-------------| +| **Installation Success** | 100% (5/5) | Plugin installed and authenticated | +| **Adoption Rate** | >80% within 2 weeks | Users with >5 completions | +| **Issue Resolution** | <5 open issues | GitHub [plugin-help] count | +| **Team Satisfaction** | >60% positive | Anonymous survey | +| **Productivity Gains** | 15% average | Time tracking before/after | + +### Tier 3: WordPress Project Teams + +| Metric | Target | Measurement | +|--------|--------|-------------| +| **Availability** | 100% of teams can access | Documented in README | +| **Adoption Rate** | >50% of teams | GitHub issue usage | +| **Support Response** | <24 hours | Issue resolution time | +| **Team Satisfaction** | >70% | Quarterly surveys | +| **Vendor Performance** | Meeting SLAs | Uptime and feature tracking | + +--- + +## Contingency Plans + +### If Adoption Lags Behind Target + +**Problem:** Adoption rate <80% at end of Tier 2 + +**Response:** + +1. **Root cause analysis:** Survey team on barriers +2. **Adjust approach:** Modify tools, training, or expectations +3. **Extend grace period:** Add 2 weeks of additional support +4. **Pivot if needed:** Recommend alternative tool combinations +5. **Document lessons:** Record for future rollouts + +### If Critical Issues Emerge + +**Problem:** Plugin causes blocking issues (crashes, data loss, etc.) + +**Response:** + +1. **Immediate:** File urgent issue with vendor +2. **Workaround:** Provide temporary fix or alternative workflow +3. **Communication:** Notify affected teams within 1 hour +4. **Mitigation:** Disable plugin if necessary to unblock work +5. **Recovery:** Re-enable only after vendor resolves issue +6. **Compensation:** Extend grace period or defer adoption + +### If Vendor Changes Pricing + +**Problem:** Vendor increases price significantly (>30%) + +**Response:** + +1. **Evaluate alternatives:** Compare with Codex, Gemini, etc. +2. **Negotiate:** Contact vendor for enterprise discounts +3. **Cost-benefit analysis:** Assess ROI vs. new pricing +4. **Team feedback:** Survey on alternatives +5. **Decision:** Keep, switch, or hybrid approach +6. **Communicate:** Notify team 30 days in advance of any changes + +### If Vendor Sunset a Tool + +**Problem:** Vendor discontinues Claude Code or Copilot + +**Response:** + +1. **Immediately switch:** Move to alternative (Codex, Gemini, etc.) +2. **Export data:** Save agents, settings, custom configuration +3. **Retrain:** Offer training on new tool +4. **Support:** Extended help period for transition +5. **Cost:** Absorb additional costs if necessary +6. **Vendor: Hold contract renegotiation clause** + +--- + +## Team Feedback & Iteration + +### Feedback Collection + +**Tier 1 (Aug):** Post-phase survey + +- What worked well? +- What didn't work? +- Recommendations for Tier 2? + +**Tier 2 (Sep):** Mid-phase check-in + +- Early adopters: How's it going? +- Laggards: What barriers exist? +- Adjustment opportunities + +**Tier 2 (Sep):** Post-phase survey + +- Overall satisfaction +- Best use cases identified +- Recommended changes for Tier 3 + +**Tier 3 (Oct+):** Quarterly surveys + +- Ongoing satisfaction +- Productivity impact +- Feature requests +- Cost-benefit analysis + +### Iteration Points + +- **Week 2 of each tier:** Adjust training approach if needed +- **End of each tier:** Update documentation based on feedback +- **Q4 2026:** Comprehensive vendor evaluation +- **Q1 2027:** Contract negotiation and tool selection + +--- + +## Timeline Summary + +| Date | Phase | Activity | Success Criteria | +|------|-------|----------|------------------| +| **Aug 1** | Tier 1 begins | Core team installs both plugins | 3/3 installations | +| **Aug 15** | Tier 1 mid-point | Team using both tools actively | 10+ hours per person | +| **Aug 29** | Tier 1 complete | Feedback collected, guidelines finalized | >80% satisfaction | +| **Sep 1** | Tier 2 begins | Contributors install and train | 5/5 installations | +| **Sep 15** | Tier 2 mid-point | Broader team using actively | >80% adoption rate | +| **Sep 29** | Tier 2 complete | All issues resolved, team confident | >60% satisfaction | +| **Oct 1** | Tier 3 begins | WordPress teams enable access | 100% availability | +| **Oct 31** | Tier 3 stabilize | Project teams integrated | >50% adoption | +| **Nov 30** | Q4 Assessment | Vendor evaluation, contract negotiation | ROI measured | +| **Dec 31** | Year 1 Complete | Full team adoption, sustained | Recurring costs approved | + +--- + +## FAQ + +### Q: What if I can't install a plugin? + +**A:** Contact your VS Code administrator or IT team. Most organizations allow VS Code extensions. If blocked, reach out to Ash Shaw for exception approval. + +### Q: Do I have to use both Claude Code and Copilot? + +**A:** No. Start with whichever tool interests you. We recommend both for maximum productivity, but one tool is fine. + +### Q: Can I opt out of this rollout? + +**A:** Yes. These are optional tools. You can skip Tier adoption, but we encourage trying them—they save time and frustration. + +### Q: What about privacy and security? + +**A:** Both tools respect your privacy. Code is sent for suggestions but not stored. Never send code with secrets. See privacy docs in setup guides. + +### Q: Will these tools be available forever? + +**A:** We'll evaluate tools quarterly. If a vendor changes (pricing, discontinuation), we'll switch to alternatives. You'll have notice for major changes. + +### Q: Who do I contact for help? + +**A:** Open a GitHub issue with label `[plugin-help]` or contact Ash Shaw directly. + +--- + +## References + +- [Claude Code Setup Guide](./plugin-setup-claude-code.md) +- [GitHub Copilot Setup Guide](./plugin-setup-github-copilot.md) +- [Plugin Comparison](./plugin-comparison.md) +- [Testing Guide](./plugin-testing.md) +- [Troubleshooting Guide](./vscode-plugin-troubleshooting.md) + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial adoption roadmap for Tiers 1–3 | + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy* diff --git a/docs/plugin-comparison.md b/docs/plugin-comparison.md new file mode 100644 index 0000000000..8556655766 --- /dev/null +++ b/docs/plugin-comparison.md @@ -0,0 +1,451 @@ +--- +title: AI Plugin Comparison Guide +description: Feature comparison of Claude Code, GitHub Copilot, Codex, and Gemini for development workflows +created: 2026-07-26 +updated: 2026-07-26 +type: guide +--- + +# AI Plugin Comparison Guide + +A comprehensive comparison of AI-powered development tools available for VS Code, helping you choose the right tool for each task. + +--- + +## Quick Comparison Table + +| Feature | Claude Code | GitHub Copilot | Codex | Gemini | +|---------|-----------|---|-------|--------| +| **Inline Suggestions** | ✅ Limited | ✅ Excellent | ✅ Good | ✅ Good | +| **Multi-File Edits** | ✅ Yes | ❌ No | ❌ No | ✅ Yes | +| **Code Generation** | ✅ Excellent | ✅ Good | ✅ Very Good | ✅ Good | +| **Refactoring** | ✅ Excellent | ✅ Good | ✅ Good | ✅ Good | +| **Testing** | ✅ Good | ✅ Excellent | ✅ Good | ✅ Good | +| **Debugging** | ✅ Excellent | ❌ Limited | ❌ Limited | ✅ Good | +| **Chat Interface** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | +| **Project Analysis** | ✅ Excellent | ❌ Limited | ❌ No | ✅ Good | +| **Terminal Commands** | ✅ Yes | ❌ No | ❌ No | ❌ No | +| **Custom Agents** | ✅ Yes | ❌ No | ❌ No | ❌ No | +| **Cost** | Free/Paid | Paid | Paid | Free/Paid | +| **Offline Mode** | ❌ No | ❌ No | ❌ No | ❌ No | + +--- + +## Detailed Comparison + +### Claude Code (Anthropic) + +**Best For:** Multi-file refactors, project-wide analysis, complex debugging + +**Pricing:** + +- **Free:** Limited usage (10 requests/month) +- **Paid:** $20/month (individual), or use Anthropic API with pay-as-you-go billing + +**Strengths:** + +- ✅ Analyzes entire project for context +- ✅ Handles complex refactoring across files +- ✅ Excellent at explaining errors and suggesting fixes +- ✅ Custom agents for repetitive tasks +- ✅ Terminal integration for running commands +- ✅ Understands project structure and standards + +**Limitations:** + +- ❌ Inline suggestions require explicit activation +- ❌ Slower than Copilot (waits for Claude response) +- ❌ Less focused on micro-completions +- ❌ Requires authentication + +**Ideal Workflows:** + +1. "Refactor this module to use TypeScript" +2. "What's wrong with this error? How do I fix it?" +3. "Add tests for all functions in this file" +4. "Consolidate these three methods into one" + +**Tier:** **Tier 1 — Recommended for core maintainers** + +--- + +### GitHub Copilot (GitHub) + +**Best For:** Real-time inline suggestions, rapid development, test generation + +**Pricing:** + +- **Individual:** $10/month or $100/year +- **Business:** $21/month per user +- **Students/Educators:** Free + +**Strengths:** + +- ✅ Fastest inline suggestions (sub-second response) +- ✅ Excellent at generating tests +- ✅ Works across 10+ languages without setup +- ✅ Learns from your codebase patterns +- ✅ Large training dataset (billions of lines) +- ✅ Minimal overhead/distraction + +**Limitations:** + +- ❌ Can't edit multiple files at once +- ❌ Limited project understanding +- ❌ Occasional suggestion of copyrighted code +- ❌ Less helpful for complex debugging +- ❌ Privacy concerns (code sent to GitHub) + +**Ideal Workflows:** + +1. Writing boilerplate code quickly +2. Generating test cases +3. Implementing simple functions +4. Learning new language syntax +5. Quick completions while typing + +**Tier:** **Tier 1 — Recommended for all developers** + +--- + +### Codex (OpenAI) + +**Best For:** Code translation, documentation generation, educational use + +**Pricing:** + +- **Usage-based:** $0.02 per 1K tokens (input), $0.06 per 1K tokens (output) +- **Requires API key** — Not as integrated into VS Code + +**Strengths:** + +- ✅ Strong at code translation (Python → JavaScript) +- ✅ Excellent documentation generation +- ✅ Good code explanation +- ✅ Efficient for specific tasks +- ✅ Flexible API for custom integrations + +**Limitations:** + +- ❌ No first-class VS Code extension +- ❌ Slower responses than Copilot +- ❌ Requires manual API setup +- ❌ Less focused on refactoring +- ❌ Limited multi-file support +- ❌ Steeper learning curve + +**Ideal Workflows:** + +1. Translating code between languages +2. Generating comprehensive documentation +3. Understanding legacy code +4. Building custom AI tools + +**Tier:** **Tier 2 — Optional for specific use cases** + +--- + +### Gemini (Google) + +**Best For:** Integration with Google services, rapid prototyping, multimodal code generation + +**Pricing:** + +- **Free:** Limited usage with Google account +- **Gemini Advanced:** $20/month (includes Claude Code access) +- **API:** Usage-based pricing + +**Strengths:** + +- ✅ Good code generation across languages +- ✅ Excellent at explaining concepts +- ✅ Strong multimodal capabilities (images → code) +- ✅ Good for prototyping +- ✅ Integrates with Google Workspace +- ✅ Free tier available + +**Limitations:** + +- ❌ Weaker at project-wide refactoring +- ❌ Limited project context understanding +- ❌ Fewer inline suggestions +- ❌ Less mature ecosystem +- ❌ Emerging/changing capabilities + +**Ideal Workflows:** + +1. Quick prototyping with free tier +2. Generating code from design images +3. Learning and experimentation +4. Google Workspace integration + +**Tier:** **Tier 2–3 — Emerging for evaluation** + +--- + +## Decision Matrix: Which Tool to Use? + +### Use Claude Code When + +✅ You need **multi-file analysis** or refactoring +✅ You're **debugging a complex error** +✅ You need **project-wide consistency** enforcement +✅ You want **custom agents** for repetitive tasks +✅ You need **detailed explanations** of code behavior + +### Use GitHub Copilot When + +✅ You need **fast inline suggestions** +✅ You're **writing tests** (excellent for test generation) +✅ You're doing **routine implementations** +✅ You want **minimal interruption** +✅ You're learning **new language syntax** + +### Use Codex When + +✅ You need **code translation** (language to language) +✅ You're **generating documentation** +✅ You're **building a custom integration** +✅ You need **API-based access** + +### Use Gemini When + +✅ You want to **try AI assistance for free** +✅ You need **multimodal capabilities** (images → code) +✅ You're **prototyping quickly** +✅ You need **Google Workspace integration** + +--- + +## Recommended Tier Strategy + +### Tier 1: Core Maintainers & Lead Contributors (Recommended) + +**Timeline:** August 2026 +**Team Size:** 2–3 developers +**Setup:** Claude Code + GitHub Copilot + +**Reasoning:** + +- Claude Code provides advanced project analysis and refactoring +- Copilot provides rapid inline suggestions for daily work +- Together they cover all common workflows + +**Monthly Cost per Developer:** + +- Claude Code: $20 (if using paid API) +- GitHub Copilot: $10 +- **Total: $30/month** (or $0 if using free Claude Code tier) + +**Expected Productivity Gains:** + +- 25–30% faster code generation +- 40–50% faster test writing +- 15–20% reduction in debugging time + +--- + +### Tier 2: All Contributors (September 2026) + +**Timeline:** September 2026 +**Team Size:** 4–5 developers +**Setup:** Claude Code + GitHub Copilot (standard), Codex (optional for power users) + +**Additions:** + +- Evaluate Codex for specialized code translation tasks +- Optional Gemini for users wanting free alternatives + +**Monthly Cost per Developer:** + +- Claude Code: $20 +- GitHub Copilot: $10 +- Codex: $0–50 (optional, usage-based) +- **Total: $30–80/month** (adjustable based on needs) + +--- + +### Tier 3: WordPress Project Consumers (October 2026+) + +**Timeline:** October 2026 onwards +**Team Size:** 8–9 teams +**Setup:** Flexible based on project needs + +**Options:** + +1. **Maintenance Teams:** Claude Code + Copilot (full suite) +2. **New Feature Teams:** Copilot only (cost-efficient) +3. **Learning Teams:** Gemini free tier (educational) + +**Expected Cost:** + +- Enterprise: $30–50/developer/month (discounts available) +- Standard: $10–20/developer/month +- Budget: $0/developer (free tiers) + +--- + +## Implementation Roadmap + +### Phase 1: Setup & Evaluation (August 2026) + +| Week | Task | Owner | +|------|------|-------| +| 1 | Install Claude Code + Copilot on core team | Ash Shaw | +| 2 | Test both tools in actual workflows | Core team | +| 3 | Collect feedback and document preferences | Core team | +| 4 | Create team guidelines and best practices | Claude Code | + +**Success Criteria:** + +- Both tools installed and functional on core team (3/3) +- At least 50 hours of combined usage +- Team consensus on strengths/weaknesses + +### Phase 2: Broader Adoption (September 2026) + +| Week | Task | Owner | +|------|------|-------| +| 1–2 | Train broader contributor team (5 developers) | Core team | +| 3 | Evaluate Codex for optional adoption | Evaluators | +| 4 | Document team preferences and workflows | Everyone | + +**Success Criteria:** + +- Copilot + Claude Code installed on all contributors (5/5) +- >80% adoption rate after 4 weeks +- Issues documented with `[plugin-help]` label + +### Phase 3: Stabilization & Optimization (October 2026+) + +| Phase | Task | Owner | +|-------|------|-------| +| 3a | Evaluate Gemini for emerging opportunities | Tech team | +| 3b | Optimize costs and usage patterns | Finance team | +| 3c | Build custom agents for repeated tasks | Claude Code | +| 3d | Annual contract negotiation with vendors | Ash Shaw | + +--- + +## Cost Analysis + +### Small Team (2–5 developers) + +| Scenario | Tools | Monthly Cost | Notes | +|----------|-------|--------------|-------| +| **Free** | Copilot free tier (students) | $0 | Only for eligible users | +| **Budget** | Gemini free tier | $0 | Limited features | +| **Standard** | Copilot + Claude (free) | $10 | Basic setup | +| **Recommended** | Copilot + Claude (paid) | $30 | Full capabilities | + +### Medium Team (6–15 developers) + +| Scenario | Tools | Monthly Cost | Notes | +|----------|-------|--------------|-------| +| **Budget** | Copilot only | $100–150 | 10–15 × $10 | +| **Standard** | Copilot + Claude (free) | $100–150 | Mixed tiers | +| **Recommended** | Copilot + Claude (paid) | $300–450 | Full capabilities | + +### Large Organization (50+ developers) + +| Scenario | Tools | Monthly Cost | Notes | +|----------|-------|--------------|-------| +| **Enterprise** | Copilot Business | $1000–1050 | 50 × $21 | +| **Premium** | Copilot Business + Claude | $2000–2100 | Full suite | +| **Optimized** | Mix of free & paid tiers | $1200–1800 | Tiered by role | + +--- + +## Migration Guide: Switching Between Tools + +### Moving from Copilot to Claude Code + +**When to consider:** + +- Need multi-file refactoring +- Debugging complex issues frequently +- Want project-wide analysis + +**Migration steps:** + +1. Install Claude Code extension +2. Authenticate with Anthropic +3. Set up `.claude/CLAUDE.md` for project context +4. Keep Copilot installed for inline suggestions +5. Test both tools on same tasks (compare) +6. Gradually shift complex tasks to Claude Code + +### Moving from Claude Code to Copilot + +**When to consider:** + +- Team adopts Copilot as standard +- Need faster response times +- Inline suggestions preferred + +**Migration steps:** + +1. Export any custom agents to `.claude/agents/` +2. Document Claude Code-specific workflows +3. Create Copilot Chat equivalents +4. Install GitHub Copilot extension +5. Train team on Copilot Chat for complex requests +6. Archive Claude Code setup for reference + +### Hybrid Approach (Recommended) + +**Best practice:** Use both tools simultaneously + +- **Claude Code:** Complex refactoring, multi-file edits, debugging +- **Copilot:** Inline suggestions, tests, rapid development +- **Copilot Chat:** Medium-complexity requests +- **Claude Code Chat:** Complex analysis and planning + +--- + +## Frequently Asked Questions + +### Q: Do I have to pay for all three tools? + +**A:** No. Start with GitHub Copilot ($10/month) and add Claude Code ($20/month or free tier) as needed. Most teams find this $30/month investment saves 20–30% development time. + +### Q: Which tool is most accurate? + +**A:** Claude Code has the highest accuracy for complex tasks. GitHub Copilot is fastest for inline suggestions. Use Claude Code for critical code, Copilot for routine work. + +### Q: Do these tools steal my code? + +**A:** All tools respect your privacy. Code is sent for suggestions but not stored (with optional analytics). See each tool's privacy policy. Never send code with secrets. + +### Q: Can I use free alternatives? + +**A:** Yes. Gemini and GitHub Copilot both offer free tiers (with limitations). For enterprise teams, free tiers don't scale. + +### Q: What if my team prefers a different tool? + +**A:** That's fine! The recommendation is based on productivity data. If your team is more productive with other tools, use those instead. + +### Q: Will these tools become my crutch? + +**A:** Possible. Best practice: Use tools to accelerate routine work, but still write complex logic manually to maintain your skills. + +--- + +## References + +- [Claude Code Documentation](https://claude.ai/code) +- [GitHub Copilot Documentation](https://docs.github.com/copilot) +- [OpenAI Codex Documentation](https://platform.openai.com/docs/guides/code) +- [Google Gemini Documentation](https://ai.google.dev/gemini-api) + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial comparison guide for 4 major tools | + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy* diff --git a/docs/plugin-setup-claude-code.md b/docs/plugin-setup-claude-code.md new file mode 100644 index 0000000000..2475a9ad11 --- /dev/null +++ b/docs/plugin-setup-claude-code.md @@ -0,0 +1,380 @@ +--- +title: Claude Code Setup Guide +description: Step-by-step installation and configuration of Claude Code for development +created: 2026-07-26 +updated: 2026-07-26 +type: guide +--- + +# Claude Code Setup Guide + +A comprehensive guide to installing, configuring, and using Claude Code in your development workflow. + +## What is Claude Code? + +Claude Code is an official AI-powered development assistant for VS Code that helps with code generation, refactoring, debugging, and project-wide analysis. It integrates Claude's capabilities directly into your editor. + +**Key Features:** + +- Multi-file project analysis and code generation +- Intelligent debugging and error diagnosis +- Refactoring suggestions and automated improvements +- Documentation generation and standards enforcement +- Natural language code search across projects +- Built-in terminal for running commands +- Git integration and commit message generation + +--- + +## Prerequisites + +- **VS Code:** Version 1.86 or higher +- **Operating System:** macOS (Apple Silicon or Intel), Windows (10/11), or Linux (Ubuntu 18.04+) +- **Internet Connection:** Required for API calls to Claude +- **Claude API Access:** Active Anthropic API key (paid account required) + +--- + +## Installation Steps + +### Step 1: Install the VS Code Extension + +1. Open **VS Code** +2. Go to **Extensions** (Ctrl+Shift+X / Cmd+Shift+X) +3. Search for **"Claude Code"** (published by Anthropic) +4. Click **Install** +5. Wait for installation to complete (usually 30 seconds) + +### Step 2: Authenticate with Anthropic + +1. After installation, you'll see a **"Sign In"** button in the VS Code sidebar +2. Click **"Authenticate with Claude Code"** +3. Your browser will open to claude.ai +4. **Sign in** with your Anthropic account (create one if needed) +5. Allow Claude Code to access your account +6. Return to VS Code—you should be authenticated + +### Step 3: Add Your API Key (Alternative Authentication) + +If you prefer direct API key authentication: + +1. Open **VS Code Settings** (Code → Preferences → Settings) +2. Search for **"Claude Code API Key"** +3. Paste your API key from [console.anthropic.com](https://console.anthropic.com) +4. Save settings (Cmd+S / Ctrl+S) + +**⚠️ Important:** Never commit API keys to version control. Use environment variables or VS Code's secure settings. + +--- + +## Configuration + +### Essential Settings + +Open **VS Code Settings** (Command Palette: `Cmd+Shift+P` → "Preferences: Open Settings") and configure: + +| Setting | Value | Purpose | +|---------|-------|---------| +| `claude.model` | `claude-opus-5` or `claude-sonnet-5` | Choose reasoning capability | +| `claude.context-window` | `200000` | Max tokens per request | +| `claude.temperature` | `0.7` | Creativity level (0=precise, 1=creative) | +| `claude.project` | Your repo name | Tag requests by project | +| `claude.workspace-mode` | `true` | Enable multi-file analysis | + +### Recommended Extensions to Pair With + +- **[ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)** — Real-time linting feedback +- **[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)** — Code formatting +- **[GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)** — Enhanced git integration +- **[GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)** — Complementary inline suggestions + +--- + +## First-Time Setup: Project Context + +Claude Code works best when it understands your project structure: + +### 1. Create a `.claude/` Directory (Optional but Recommended) + +```bash +mkdir -p .claude +touch .claude/claude.json +``` + +### 2. Configure Your Project + +Create `.claude/claude.json`: + +```json +{ + "name": "Your Project Name", + "description": "Brief description of what this project does", + "language": "typescript", + "framework": "react", + "entry-points": [ + "src/index.ts", + "src/App.tsx" + ], + "documentation": "docs/", + "coding-standards": ".github/CLAUDE.md" +} +``` + +### 3. Link Project Instructions + +Claude Code will automatically read: + +- `.claude/CLAUDE.md` — Project-specific rules +- `.github/CLAUDE.md` — Organization rules +- `README.md` — Project overview + +--- + +## Using Claude Code + +### Command Palette + +Open **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type: + +| Command | Purpose | +|---------|---------| +| `Claude: Ask Claude` | General chat with Claude | +| `Claude: Generate Code` | Create code from description | +| `Claude: Refactor Code` | Improve selected code | +| `Claude: Add Tests` | Generate test cases | +| `Claude: Document Code` | Generate JSDoc/docstrings | +| `Claude: Fix Error` | Debug selected error | +| `Claude: Run Command` | Execute shell commands | +| `Claude: Create Agent` | Build custom agent | + +### Right-Click Context Menu + +Select any code and right-click to: + +- **Ask Claude About Selection** — Get explanation +- **Generate from Template** — Code generation +- **Add Unit Tests** — Test generation +- **Explain Error** — Error diagnosis + +### Claude Sidebar + +The **Claude Code panel** (left sidebar) offers: + +1. **Chat** — Direct conversation with Claude +2. **Files** — Project file tree and search +3. **Terminal** — Run commands, view output +4. **Agents** — Run pre-built agents +5. **Settings** — Extension configuration + +--- + +## Common Workflows + +### Workflow 1: Quick Code Generation + +1. Open **Command Palette** → `Claude: Generate Code` +2. Describe what you need: + + ``` + Create a React hook that manages form state with validation. + Should handle text, email, and checkbox inputs. + ``` + +3. Claude generates the code +4. Review and accept (or iterate) +5. Code is pasted at cursor or in new file + +### Workflow 2: Debugging an Error + +1. Select the error message or problematic code +2. Right-click → **Explain Error** +3. Claude analyzes the error and suggests fixes +4. Accept the fix or ask follow-up questions +5. Test your changes + +### Workflow 3: Adding Tests + +1. Select a function or component +2. Right-click → **Generate from Template** +3. Choose **Unit Tests** +4. Claude generates test cases +5. Review coverage and adjust as needed + +### Workflow 4: Large Refactor + +1. Open **Claude Chat** (sidebar) +2. Describe the refactor goal: + + ``` + I need to refactor my authentication module to use environment + variables instead of hardcoded secrets. What's the safest approach? + ``` + +3. Claude analyzes your files and provides a plan +4. Execute the changes one step at a time +5. Commit after verification + +--- + +## Advanced Features + +### Multi-File Edits + +Claude Code can edit multiple files in a single request: + +1. Open **Claude Chat** +2. Ask for changes across files: + + ``` + Add TypeScript types to all JavaScript files in src/utils/. + Use strict typing with no implicit any. + ``` + +3. Claude identifies affected files and shows a changeset +4. Review and accept all changes at once + +### Agent Creation + +Create custom agents for repetitive tasks: + +1. **Command Palette** → `Claude: Create Agent` +2. Define the agent: + - Name: e.g., "Test Coverage Analyzer" + - Description: What it does + - Trigger: When to run (manual, on save, on push) + - Instructions: Detailed behaviour rules +3. Save your agent to `.claude/agents/` +4. Run from **Agents panel** anytime + +### Terminal Integration + +Claude proposes terminal commands for your approval before execution: + +1. In **Claude Chat**, ask Claude to run a command: + + ``` + Run npm test and show me which tests failed + ``` + +2. Claude proposes the command — **review it before approving**, especially for destructive or network-affecting operations (e.g. `rm -rf`, deployments, database changes) +3. Approve to execute; Claude shows the output and you can ask follow-up questions + +--- + +## Troubleshooting + +### Issue: "Authentication Failed" + +**Solution:** + +1. Open **Command Palette** → `Claude: Sign Out` +2. Sign out completely +3. Restart VS Code +4. Sign back in +5. If still failing, generate an API key at [console.anthropic.com](https://console.anthropic.com) and use Step 3 above + +### Issue: "API Key Expired" or "Quota Exceeded" + +**Solution:** + +1. Check your [Anthropic account](https://console.anthropic.com) for active subscriptions +2. Verify your API key is current (regenerate if needed) +3. Check usage limits in your account dashboard +4. Consider upgrading your plan if quota is exceeded + +### Issue: "Project Files Not Found" + +**Solution:** + +1. Ensure VS Code is opened at **project root** (where `.git/` or `package.json` is) +2. Run **Command Palette** → `Claude: Reload Context` +3. Check `.claude/CLAUDE.md` or `.github/CLAUDE.md` exists +4. Verify `.gitignore` isn't hiding important files + +### Issue: "Slow Responses" or "Timeouts" + +**Solution:** + +1. Check internet connection +2. Reduce context window in settings (set to `100000` instead of `200000`) +3. Ask Claude to use a faster model: `Claude: Select Model` → choose `claude-haiku-4-5` +4. Close other heavy applications +5. Try again in a few minutes (service may be under high load) + +### Issue: "Extension Won't Start" + +**Solution:** + +1. Open **Extension Details** (left sidebar → Claude Code → three dots) +2. Click **Disable** → Close VS Code → Open → **Enable** +3. If still failing, uninstall completely: + - VS Code: Extensions → Claude Code → Uninstall + - Restart VS Code + - Reinstall from marketplace +4. Check VS Code version (must be 1.86+): `Code → About Visual Studio Code` + +--- + +## Best Practices + +### ✅ Do + +- ✅ Use **clear, specific prompts** — "Add unit tests for the `calculateTotal()` function with edge case coverage" +- ✅ **Review generated code** before committing — AI isn't perfect +- ✅ **Provide context** — Include file paths, existing patterns, and constraints +- ✅ **Use multi-file mode** for related changes (refactors, migrations) +- ✅ **Keep conversations focused** — Start a new chat for unrelated topics +- ✅ **Run tests** after Claude generates code +- ✅ **Save your custom agents** to `.claude/agents/` for reuse + +### ❌ Don't + +- ❌ Don't **trust generated secrets or credentials** — Always verify +- ❌ Don't **commit API keys** in settings or code +- ❌ Don't **skip security review** for generated authentication code +- ❌ Don't **ask for exact copies** of proprietary code +- ❌ Don't **use without understanding** the generated code +- ❌ Don't **ignore linting errors** after generation + +--- + +## Getting Help + +### In VS Code + +1. **Command Palette** → `Claude: Help` +2. Open **Extension Details** → **Read the Docs** (link to full documentation) +3. Click **Report Issue** to file a bug + +### Online Resources + +- **[Official Claude Code Documentation](https://claude.ai/code)** — Features and API +- **[Anthropic API Reference](https://docs.anthropic.com)** — Models, pricing, rate limits +- **[GitHub Issues](https://github.com/anthropics/claude-code/issues)** — Known issues and workarounds + +### Support Channels + +- **Team Help:** GitHub issues with label `[plugin-help]` +- **Escalations:** Contact Ash Shaw () +- **Enterprise Support:** Available via Anthropic account manager + +--- + +## What's Next? + +1. **[Pair With GitHub Copilot](./plugin-setup-github-copilot.md)** — Set up complementary inline suggestions +2. **[Compare All Plugins](./plugin-comparison.md)** — Understand when to use each tool +3. **[VSCode Workspace Setup](./vscode-workspace-setup.md)** — Optimize your editor configuration +4. **[Plugin Troubleshooting](./vscode-plugin-troubleshooting.md)** — Resolve common issues + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial setup guide for Claude Code v1.0+ | + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy* diff --git a/docs/plugin-setup-github-copilot.md b/docs/plugin-setup-github-copilot.md new file mode 100644 index 0000000000..ce03f47e80 --- /dev/null +++ b/docs/plugin-setup-github-copilot.md @@ -0,0 +1,460 @@ +--- +title: GitHub Copilot Setup Guide +description: Step-by-step installation and configuration of GitHub Copilot for inline code suggestions +created: 2026-07-26 +updated: 2026-07-26 +type: guide +--- + +# GitHub Copilot Setup Guide + +A comprehensive guide to installing, configuring, and using GitHub Copilot in VS Code for inline code assistance. + +## What is GitHub Copilot? + +GitHub Copilot is an AI-powered coding assistant that provides real-time code suggestions as you type. It learns from your codebase's patterns and offers context-aware completions, function implementations, and test suggestions directly in your editor. + +**Key Features:** + +- Real-time inline code suggestions as you type +- Multi-line code completion +- Function implementation suggestions +- Test case generation +- Natural language to code conversion +- Documentation generation +- Works across 10+ programming languages + +--- + +## Prerequisites + +- **VS Code:** Version 1.77.0 or higher +- **GitHub Account:** Active GitHub account with Copilot enabled +- **Copilot Licence:** Individual, Business, or Education plan +- **Operating System:** macOS, Windows, or Linux +- **Internet Connection:** Required for real-time suggestions + +### Check Your GitHub Copilot Access + +1. Visit [github.com/copilot](https://github.com/copilot) +2. Ensure your account has an **active subscription** or **free trial** +3. Students and educators may qualify for **free Copilot access** + +--- + +## Installation Steps + +### Step 1: Install the GitHub Copilot Extension + +1. Open **VS Code** +2. Go to **Extensions** (Ctrl+Shift+X / Cmd+Shift+X) +3. Search for **"GitHub Copilot"** (published by GitHub) +4. Click **Install** +5. Wait for installation (usually 30 seconds) +6. You may be prompted to install additional extensions: + - **GitHub Copilot Chat** (recommended) + - **Copilot Labs** (optional, experimental features) + +### Step 2: Authenticate with GitHub + +1. You'll see a **"Sign In"** prompt in VS Code +2. Click **"Allow"** when prompted +3. A browser window opens to GitHub authentication +4. Click **"Authorize Github"** +5. Your GitHub account grants Copilot access +6. Return to VS Code—you're now authenticated + +### Step 3: Verify Installation + +1. Create a new file or open an existing one (e.g., `test.js`) +2. Start typing a comment describing what you want: + + ```javascript + // Function to calculate the sum of an array + ``` + +3. Press **Enter** and start typing `function` +4. Copilot should offer code suggestions (in gray text) +5. Press **Tab** to accept the suggestion, or **Escape** to dismiss + +--- + +## Configuration + +### Essential Settings + +Open **VS Code Settings** (Code → Preferences → Settings) and configure: + +| Setting | Value | Purpose | +|---------|-------|---------| +| `github.copilot.enable` | `true` | Enable Copilot globally | +| `editor.inlineSuggest.enabled` | `true` | Show inline suggestions | +| `editor.suggest.showInlineCompletions` | `true` | Inline snippet suggestions | +| `github.copilot.suggest.localityBonus` | `true` | Prioritize local file context | +| `github.copilot.suggest.importStatements` | `true` | Suggest imports automatically | + +### Disable Copilot for Specific Files + +Add to your VS Code `settings.json`: + +```json +"github.copilot.enable": { + "plaintext": false, + "markdown": false, + "yaml": false, + "[git-commit]": false +} +``` + +This disables Copilot for non-code files where suggestions are often irrelevant. + +### Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| **Tab** | Accept inline suggestion | +| **Ctrl+→** (Cmd+→ on Mac) | Accept next word only | +| **Escape** | Dismiss suggestion | +| **Alt+[** / **Alt+]** | Previous/next suggestion | +| **Ctrl+Enter** (Cmd+Enter) | Open suggestion details | + +### Customise Shortcuts + +1. Open **Keyboard Shortcuts** (Cmd+K Cmd+S / Ctrl+K Ctrl+S) +2. Search for `copilot` or `inlineSuggest` +3. Edit bindings to your preference + +--- + +## Using GitHub Copilot + +### Basic Workflow: Inline Suggestions + +1. **Write a clear comment** describing what you want: + + ```python + # Function to validate an email address + ``` + +2. **Start typing the function signature:** + + ```python + def validate_email(email): + ``` + +3. **Copilot offers suggestions** (appears in gray) + +4. **Accept with Tab** or **dismiss with Escape** + +5. **Continue typing** to refine suggestions + +### Example 1: Function Implementation + +**You write:** + +```javascript +// Fetch user data from API and cache results +async function getUserWithCache(userId) { +``` + +**Copilot suggests:** + +```javascript + const cacheKey = `user_${userId}`; + + if (cache.has(cacheKey)) { + return cache.get(cacheKey); + } + + const response = await fetch(`/api/users/${userId}`); + const data = await response.json(); + + cache.set(cacheKey, data); + return data; +} +``` + +### Example 2: Test Generation + +**You write:** + +```javascript +function add(a, b) { + return a + b; +} + +// Test cases +``` + +**Copilot suggests:** + +```javascript +describe('add function', () => { + test('adds two positive numbers', () => { + expect(add(2, 3)).toBe(5); + }); + + test('handles negative numbers', () => { + expect(add(-1, -1)).toBe(-2); + }); + + test('adds zero', () => { + expect(add(5, 0)).toBe(5); + }); +}); +``` + +### Example 3: Comment-to-Code + +**You write:** + +```typescript +// Debounce a function with a specified delay +``` + +**Copilot implements:** + +```typescript +function debounce any>( + func: T, + delay: number +): (...args: Parameters) => void { + let timeoutId: NodeJS.Timeout; + + return function (...args: Parameters) { + clearTimeout(timeoutId); + timeoutId = setTimeout(() => func(...args), delay); + }; +} +``` + +--- + +## GitHub Copilot Chat (Advanced) + +For longer conversations and multi-step tasks, use **Copilot Chat**: + +### Open Copilot Chat + +1. **Command Palette** → `Copilot: Open Chat` +2. Or click the **Chat icon** in the sidebar +3. Type your question or request + +### Chat Examples + +**Ask for explanation:** + +``` +Explain what this function does: [select code] +``` + +**Request refactoring:** + +``` +Refactor this code to use async/await instead of .then() +``` + +**Debug problems:** + +``` +Why is this function throwing a 404 error? +``` + +**Generate documentation:** + +``` +Write JSDoc comments for this function +``` + +--- + +## Best Practices + +### ✅ Do + +- ✅ **Write clear comments** — "Calculate running total" is better than "calc" +- ✅ **Provide context** — Include relevant variable names and patterns +- ✅ **Review suggestions** — Don't blindly accept generated code +- ✅ **Specify language idioms** — "Use lodash for array operations" guides suggestions +- ✅ **Test thoroughly** — Run tests after accepting suggestions +- ✅ **Use meaningful names** — Good variable names improve suggestions +- ✅ **Keep functions focused** — Single-responsibility functions get better suggestions + +### ❌ Don't + +- ❌ Don't **accept security-sensitive code** without review (authentication, encryption, secrets) +- ❌ Don't **copy/paste without understanding** the generated code +- ❌ Don't **use for proprietary code** you shouldn't share with GitHub +- ❌ Don't **disable security-critical linting** to accept bad suggestions +- ❌ Don't **ignore type errors** generated by Copilot +- ❌ Don't **commit code without testing** even if Copilot generated it + +--- + +## Privacy & Security + +### What Does GitHub Know? + +Copilot sees: + +- Code you're actively typing (sent for suggestions) +- File names and directory structure +- Comments and context +- Your IDE and plugin versions + +Copilot does NOT guarantee that it never accesses: + +> ⚠️ **Do not rely on automatic secret exclusion.** Copilot may analyse open files including `.env` files, other open editor tabs, and files referenced in context. Do not keep secrets in files that are open in your editor during a Copilot session, and do not assume excluded content is guaranteed to be withheld. Use VS Code's [content exclusions](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/about-content-exclusions-for-github-copilot) to configure explicit exclusions, and review its [documented limitations](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/about-content-exclusions-for-github-copilot#limitations-of-content-exclusions) before relying on them for sensitive data. + +- **Content exclusions** are available but have known limitations — they do not provide a security guarantee +- Never open `.env` files, secrets, or credential files in your editor during a Copilot session + +### Disable Copilot for Sensitive Projects + +1. Open project's `.vscode/settings.json` +2. Add: + + ```json + "github.copilot.enable": false + ``` + +3. Re-enable with workspace settings override when needed + +### Security Review Checklist + +Before committing Copilot-generated code: + +- [ ] No hardcoded secrets, API keys, or credentials +- [ ] No SQL injection vulnerabilities +- [ ] Proper input validation +- [ ] Secure error handling (no sensitive info in error messages) +- [ ] Appropriate use of cryptography +- [ ] No unnecessary network requests + +--- + +## Troubleshooting + +### Issue: "Copilot Not Showing Suggestions" + +**Solution:** + +1. Verify **`github.copilot.enable`** is `true` in settings +2. Ensure **`editor.inlineSuggest.enabled`** is `true` +3. Check you're **logged in** (VS Code status bar should show GitHub icon) +4. Try **restarting VS Code** +5. Check you have an **active Copilot subscription** + +### Issue: "Authentication Failed" + +**Solution:** + +1. Open **Command Palette** → `GitHub: Sign Out` +2. Restart VS Code +3. Sign back in with your GitHub account +4. Grant required permissions when prompted + +### Issue: "Suggestions Are Poor Quality" + +**Solutions:** + +1. **Write clearer comments** with more specific descriptions +2. **Provide more context** before the code (imports, variable declarations) +3. **Use better variable names** (e.g., `userEmail` vs `ue`) +4. **Delete bad suggestions** to train the model (in Chat: thumbs down) +5. **Switch to Copilot Chat** for longer, more complex requests + +### Issue: "Too Many Suggestions" (Too Distracting) + +**Solution:** + +1. Increase suggestion delay: + + ```json + "editor.suggest.delay": 500 + ``` + +2. Require explicit trigger: + + ```json + "editor.inlineSuggest.enabled": false + // Then press Ctrl+Alt+\ to manually trigger + ``` + +3. Disable for specific languages: + + ```json + "[python]": { + "editor.inlineSuggest.enabled": false + } + ``` + +### Issue: "Copilot Suggests Copyrighted Code" + +**Solution:** + +1. **Reject the suggestion** (press Escape) +2. **Never accept** copyrighted code without understanding ownership +3. GitHub Copilot may occasionally suggest code from training data +4. **Use Copilot Chat** for clarification on code origin +5. **Review similar patterns** in your codebase for preferred approaches + +--- + +## Pairing With Claude Code + +Use both tools together for maximum productivity: + +| Task | Tool | +|------|------| +| **Quick inline suggestion** | GitHub Copilot | +| **Implement entire function** | GitHub Copilot or Claude Code | +| **Multi-file refactor** | Claude Code | +| **Algorithm discussion** | Copilot Chat or Claude Code Chat | +| **Code review feedback** | Copilot Chat | +| **Generate tests** | Either tool | +| **Debug error messages** | Claude Code (better error analysis) | +| **Project restructuring** | Claude Code | + +--- + +## Getting Help + +### In VS Code + +1. **Command Palette** → `GitHub Copilot: Feedback` +2. Report bugs or suggest features +3. Include a description of the issue + +### Online Resources + +- **[GitHub Copilot Documentation](https://docs.github.com/en/copilot)** — Official guide +- **[Copilot Blog](https://github.blog/tag/github-copilot/)** — Latest features and tips +- **[GitHub Community Discussions](https://github.com/orgs/community/discussions)** — User forums + +### Support Channels + +- **Team Help:** GitHub issues with label `[plugin-help]` +- **Billing Issues:** GitHub account settings +- **Technical Issues:** GitHub Support (account required) + +--- + +## What's Next? + +1. **[Compare All Plugins](./plugin-comparison.md)** — Understand when to use each tool +2. **[Pair With Claude Code](./plugin-setup-claude-code.md)** — Set up multi-tool workflow +3. **[Plugin Adoption Timeline](./plugin-adoption-phases.md)** — Rollout schedule +4. **[Plugin Troubleshooting](./vscode-plugin-troubleshooting.md)** — Resolve common issues + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial setup guide for Copilot v1.0+ | + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy* diff --git a/docs/plugin-testing.md b/docs/plugin-testing.md new file mode 100644 index 0000000000..454c084e34 --- /dev/null +++ b/docs/plugin-testing.md @@ -0,0 +1,650 @@ +--- +title: Plugin Testing Checklist +description: Manual testing checklist for AI code assistant plugins (Claude Code and GitHub Copilot) +created: 2026-07-26 +updated: 2026-07-26 +type: guide +--- + +# Plugin Testing Checklist + +A comprehensive testing guide for verifying Claude Code and GitHub Copilot functionality, identifying issues, and ensuring proper setup. + +--- + +## Pre-Testing Setup + +### Prerequisites + +- [ ] VS Code installed (v1.94.0+ for Claude Code extension; see each extension's marketplace page for its supported version) +- [ ] GitHub Copilot extension prerequisites met (check [GitHub Copilot for VS Code](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) for current requirements) +- [ ] Internet connection active +- [ ] Both plugins installed and authenticated +- [ ] Test project cloned locally +- [ ] 30 minutes of uninterrupted time + +### Test Environment + +Create a test project: + +```bash +# Clone the .github repository +git clone https://github.com/lightspeedwp/.github.git test-plugins +cd test-plugins + +# Create test branch +git checkout -b test/plugin-validation-$(date +%Y-%m-%d) +``` + +--- + +## Installation Verification + +### GitHub Copilot Installation Test + +**Objective:** Verify GitHub Copilot is properly installed and authenticated + +- [ ] **Extension installed:** VS Code Extensions → "GitHub Copilot" → Installed badge visible +- [ ] **Authentication successful:** Status bar shows GitHub account name +- [ ] **No error messages:** No red warnings in output panel +- [ ] **File watchers active:** Copilot detects when files open + +**Test steps:** + +1. Open any `.js` file +2. Look for inline suggestion prompt +3. Should show "Copilot" in status bar + +**If failed:** See troubleshooting section + +--- + +### Claude Code Installation Test + +**Objective:** Verify Claude Code is properly installed and authenticated + +- [ ] **Extension installed:** VS Code Extensions → "Claude Code" → Installed badge visible +- [ ] **Authentication successful:** Status bar shows Anthropic account (or API key configured) +- [ ] **No error messages:** No red warnings in output panel +- [ ] **Sidebar shows:** Claude Code panel visible in left sidebar + +**Test steps:** + +1. Open VS Code +2. Look for Claude Code icon in left sidebar (purple C logo) +3. Should show authenticated state +4. Click to open chat panel + +**If failed:** See troubleshooting section + +--- + +## Feature Testing: GitHub Copilot + +### Test 1: Inline Suggestions + +**Objective:** Verify Copilot provides real-time inline suggestions + +**Test file:** `test-plugins/test-copilot-inline.js` + +```javascript +// Create a function that calculates the factorial of a number +function factorial(n) { +``` + +**Expected behavior:** + +- [ ] Gray suggestion text appears after `factorial(n) {` +- [ ] Suggestion is syntactically valid JavaScript +- [ ] Suggestion can be accepted (Tab key) +- [ ] Suggestion can be dismissed (Escape key) + +**Pass criteria:** Inline suggestion appears and can be accepted/dismissed + +--- + +### Test 2: Comment-to-Code + +**Objective:** Verify Copilot can generate code from comments + +**Test file:** `test-plugins/test-copilot-comment.js` + +```javascript +// Fetch data from API, parse JSON, return filtered results +async function +``` + +**Expected behavior:** + +- [ ] Copilot suggests full function implementation +- [ ] Includes async/await syntax +- [ ] Handles errors appropriately +- [ ] Suggestion is reasonable + +**Pass criteria:** Generated code matches intent from comment + +--- + +### Test 3: Test Generation + +**Objective:** Verify Copilot can generate test cases + +**Test file:** `test-plugins/test-copilot-tests.js` + +```javascript +function add(a, b) { + return a + b; +} + +describe('add function', () => { +``` + +**Expected behavior:** + +- [ ] Copilot suggests test cases +- [ ] Includes positive and edge cases +- [ ] Uses correct testing syntax (Jest) +- [ ] All suggestions are valid + +**Pass criteria:** Generated tests cover main scenarios + +--- + +### Test 4: Language Support + +**Objective:** Verify Copilot works across different languages + +Test each language in separate files: + +**JavaScript:** + +- [ ] Suggestions work in `.js` files +- [ ] Suggestions work in `.jsx` files +- [ ] Suggestions work in `.ts` files +- [ ] Suggestions work in `.tsx` files + +**Python:** + +- [ ] Suggestions work in `.py` files +- [ ] Syntax is correct Python +- [ ] Indentation is proper + +**Other languages:** + +- [ ] Try one additional language (Go, Rust, Java, etc.) +- [ ] Verify suggestions are valid + +**Pass criteria:** Suggestions work in all language variants + +--- + +### Test 5: Copilot Chat + +**Objective:** Verify Copilot Chat panel functions + +**Test steps:** + +1. Open Copilot Chat (Command Palette → `Copilot: Open Chat`) +2. Type: `Generate a React hook for form validation` +3. Observe response + +**Expected behavior:** + +- [ ] Chat panel opens without errors +- [ ] Prompt is understood and answered +- [ ] Response includes code suggestion +- [ ] Response is contextual and helpful + +**Pass criteria:** Chat responds naturally and suggests relevant code + +--- + +## Feature Testing: Claude Code + +### Test 1: Basic Chat + +**Objective:** Verify Claude Code chat functions + +**Test steps:** + +1. Open Claude Code sidebar (left icon bar) +2. Click "Chat" tab +3. Type: `What does this project do?` +4. Observe response + +**Expected behavior:** + +- [ ] Chat opens without errors +- [ ] Claude reads project context +- [ ] Response mentions `.github` structure +- [ ] Response is helpful + +**Pass criteria:** Chat understands project scope + +--- + +### Test 2: Code Generation + +**Objective:** Verify Claude Code can generate code + +**Test file:** `test-plugins/test-claude-generate.js` + +**Test steps:** + +1. Open Claude Code Chat +2. Type: `Create a utility function that validates email addresses with regex` +3. Observe code generation + +**Expected behavior:** + +- [ ] Claude suggests complete implementation +- [ ] Code includes regex pattern +- [ ] Includes input validation +- [ ] Includes comments explaining logic +- [ ] Can be copied to file + +**Pass criteria:** Generated code is complete and functional + +--- + +### Test 3: File Analysis + +**Objective:** Verify Claude Code analyzes selected files + +**Test steps:** + +1. Open any `.md` file in project +2. Select all text (Cmd+A / Ctrl+A) +3. Right-click → `Ask Claude About Selection` +4. Observe response + +**Expected behavior:** + +- [ ] Claude understands file content +- [ ] Response is contextual +- [ ] Claude suggests improvements +- [ ] Response is helpful + +**Pass criteria:** Claude accurately analyzes file content + +--- + +### Test 4: Refactoring + +**Objective:** Verify Claude Code can refactor code + +**Test file:** `test-plugins/test-claude-refactor.js` + +```javascript +function processData(input) { + let result = []; + for (let i = 0; i < input.length; i++) { + if (input[i] > 10) { + result.push(input[i] * 2); + } + } + return result; +} +``` + +**Test steps:** + +1. Select the entire function +2. Open Claude Code Chat +3. Type: `Refactor this to use modern JavaScript (map, filter)` +4. Observe refactored code + +**Expected behavior:** + +- [ ] Claude suggests functional programming approach +- [ ] Uses `.map()` and `.filter()` appropriately +- [ ] Maintains same logic and output +- [ ] Code is cleaner than original + +**Pass criteria:** Refactored code improves code quality + +--- + +### Test 5: Terminal Integration + +**Objective:** Verify Claude Code can run commands + +**Test steps:** + +1. Open Claude Code Chat +2. Type: `Run npm test and show me results` +3. Observe command execution + +**Expected behavior:** + +- [ ] Command executes in integrated terminal +- [ ] Output is captured and shown +- [ ] Claude interprets results +- [ ] Suggests fixes if tests fail + +**Pass criteria:** Commands execute and Claude analyzes output + +--- + +### Test 6: Custom Agents + +**Objective:** Verify Claude Code agent creation + +**Test steps:** + +1. Command Palette → `Claude: Create Agent` +2. Fill in agent details: + - Name: "Test Markdown Validator" + - Description: "Validates markdown files" + - Trigger: "On save" + - Instructions: "Check for common markdown errors" +3. Save agent + +**Expected behavior:** + +- [ ] Agent is created without errors +- [ ] Agent file appears in `.claude/agents/` +- [ ] Can be listed in Agents panel +- [ ] Can be triggered from panel + +**Pass criteria:** Agent is created and functional + +--- + +## Performance Testing + +### Test 1: Response Time (Claude Code) + +**Objective:** Measure Claude Code response times + +**Test:** + +1. Open Claude Code Chat +2. Ask: `Analyze the structure of this project` +3. Measure time from submission to first response +4. Record result + +**Expected:** <10 seconds for typical queries + +**Pass criteria:** Response time is acceptable + +--- + +### Test 2: Response Time (Copilot) + +**Objective:** Measure Copilot inline suggestion latency + +**Test:** + +1. Create new file +2. Type comment +3. Start typing function name +4. Measure time to see suggestion +5. Record result + +**Expected:** <2 seconds for suggestions + +**Pass criteria:** Suggestions appear quickly + +--- + +### Test 3: Memory Usage + +**Objective:** Check VS Code memory with both plugins + +**Test steps:** + +1. Open Task Manager (Windows) or Activity Monitor (Mac) +2. Note VS Code memory usage before opening files +3. Open 5–10 large files +4. Use both Copilot and Claude Code +5. Note memory usage after activity + +**Expected:** <500MB total VS Code process + +**Pass criteria:** Memory usage is reasonable + +--- + +## Compatibility Testing + +### Test 1: Plugin Interaction + +**Objective:** Verify both plugins work together + +**Test steps:** + +1. Enable both Claude Code and Copilot +2. Open a JavaScript file +3. Type a comment +4. Observe both tools' suggestions + +**Expected behavior:** + +- [ ] Copilot shows inline suggestions +- [ ] Claude Code available in sidebar +- [ ] No conflicts or errors +- [ ] Can use both simultaneously + +**Pass criteria:** Both plugins coexist without issues + +--- + +### Test 2: VS Code Extension Compatibility + +**Objective:** Verify plugins work with common extensions + +Test each extension interaction: + +| Extension | Test | Result | +|-----------|------|--------| +| **ESLint** | Enable ESLint, verify Copilot still works | ✅ Pass / ❌ Fail | +| **Prettier** | Format code with Prettier while using Claude | ✅ Pass / ❌ Fail | +| **GitLens** | Use GitLens blame alongside Copilot | ✅ Pass / ❌ Fail | +| **Thunder Client** | Send HTTP requests while using Claude Code | ✅ Pass / ❌ Fail | + +**Pass criteria:** All extensions work together + +--- + +### Test 3: Framework Support + +**Objective:** Verify plugins understand framework-specific code + +**React test:** + +- [ ] Copilot suggests proper React patterns +- [ ] Claude Code understands component structure +- [ ] Suggestions use hooks (not class components) + +**TypeScript test:** + +- [ ] Copilot respects type annotations +- [ ] Claude Code suggests type-safe code +- [ ] No `any` types suggested + +**Pass criteria:** Framework-specific patterns understood + +--- + +## Security Testing + +### Test 1: Secret Handling + +**Objective:** Verify plugins don't leak secrets + +**Test steps:** + +1. Create file with mock API key: + + ``` + API_KEY=sk-1234567890abcdef + ``` + +2. Ask Claude Code: `What does this API key do?` +3. Observe response + +**Expected behavior:** + +- [ ] Claude doesn't repeat the key +- [ ] Claude warns about exposing secrets +- [ ] No suggestion to hardcode keys elsewhere + +**Pass criteria:** Secrets are not repeated or suggested in code + +--- + +### Test 2: Code Quality Checks + +**Objective:** Verify plugins don't suggest insecure code + +**Test file:** Create intentionally bad code + +```javascript +// Insecure password handling +const password = prompt("Enter password:"); +console.log("Password is: " + password); +``` + +**Test steps:** + +1. Select the code +2. Ask Claude Code: `Is this secure? What's wrong?` +3. Observe response + +**Expected behavior:** + +- [ ] Claude identifies security issues +- [ ] Suggests secure alternatives +- [ ] Explains why original code is bad + +**Pass criteria:** Security issues are caught and explained + +--- + +## Version Management Testing + +### Test 1: Plugin Updates + +**Objective:** Verify plugin updates work + +**Test steps:** + +1. Open VS Code Extensions +2. Check for available updates +3. Install updates if available +4. Restart VS Code +5. Re-run basic tests (inline suggestions, chat) + +**Expected behavior:** + +- [ ] Updates install without errors +- [ ] Plugins work after update +- [ ] No regression in features +- [ ] Authentication still valid + +**Pass criteria:** Update process is smooth + +--- + +## Issue Reporting + +### If Tests Fail + +When a test fails, open a GitHub issue with: + +``` +## Test Name +[Name of failing test] + +## Expected Behavior +[What should happen] + +## Actual Behavior +[What actually happened] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Environment +- VS Code Version: [version] +- Plugin Version: [version] +- OS: [OS] + +## Screenshots +[If applicable] + +## Label +- [plugin-help] +``` + +--- + +## Test Report Template + +Use this template to document testing: + +```markdown +## Plugin Testing Report + +**Date:** [Date] +**Tester:** [Your name] +**Test Environment:** [OS, VS Code version] + +### Installation Tests +- GitHub Copilot: ✅ / ❌ +- Claude Code: ✅ / ❌ + +### Feature Tests +- Inline Suggestions: ✅ / ❌ +- Code Generation: ✅ / ❌ +- Chat Interface: ✅ / ❌ +- Refactoring: ✅ / ❌ +- Terminal Integration: ✅ / ❌ + +### Performance Tests +- Response Time: ✅ / ❌ +- Memory Usage: ✅ / ❌ +- Stability: ✅ / ❌ + +### Overall Status +✅ PASS / ❌ FAIL + +### Issues Found +[List any issues] + +### Recommendations +[Any improvements or next steps] +``` + +--- + +## Testing Roles & Schedule + +| Role | Responsibility | Frequency | +|------|---|---| +| **Core Team** | Test on major updates | Monthly | +| **Contributors** | Quick smoke test on setup | Once during onboarding | +| **QA Team** | Comprehensive testing | Before each release | + +--- + +## References + +- [GitHub Copilot Setup Guide](./plugin-setup-github-copilot.md) +- [Claude Code Setup Guide](./plugin-setup-claude-code.md) +- [Plugin Troubleshooting](./vscode-plugin-troubleshooting.md) + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial testing checklist | + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy* diff --git a/docs/vscode-plugin-troubleshooting.md b/docs/vscode-plugin-troubleshooting.md new file mode 100644 index 0000000000..4ccb9ee3a6 --- /dev/null +++ b/docs/vscode-plugin-troubleshooting.md @@ -0,0 +1,670 @@ +--- +title: VSCode Plugin Troubleshooting Guide +description: Comprehensive troubleshooting for Claude Code and GitHub Copilot issues in VS Code +created: 2026-07-26 +updated: 2026-07-26 +type: guide +--- + +# VSCode Plugin Troubleshooting Guide + +A detailed guide to diagnosing and resolving common issues with Claude Code and GitHub Copilot in VS Code. + +--- + +## Quick Diagnosis + +Look for your issue below in the relevant section: + +- **Plugin not showing up?** → See GitHub Copilot Issues +- **Can't sign in?** → See Authentication Errors +- **Not getting suggestions?** → See GitHub Copilot Issues +- **Performance issues?** → See Performance Issues +- **Extension crashes?** → See Claude Code Issues +- **Lost functionality after update?** → See Update Issues + +--- + +## GitHub Copilot Issues + +### Issue: "GitHub Copilot Can't Activate" + +**Error message:** "GitHub Copilot could not be activated" + +**Causes:** Missing dependencies, authentication failure, VS Code version too old + +**Solutions:** + +1. **Check VS Code version** (must be 1.77+) + + ``` + Code → About Visual Studio Code + ``` + + If older, download latest from [code.visualstudio.com](https://code.visualstudio.com) + +2. **Reinstall the extension** + - Extensions → GitHub Copilot → Uninstall + - Restart VS Code + - Extensions → Search "GitHub Copilot" → Install + +3. **Verify Node.js** + + ```bash + node --version + # Should be 16.0.0 or higher + ``` + + If missing, install from [nodejs.org](https://nodejs.org) + +4. **Check for conflicting extensions** + - Extensions → Disable all except GitHub Copilot + - Restart VS Code + - If it works, re-enable extensions one by one + +5. **Clear VS Code cache** + - Close VS Code + - Delete cache folder: + - Mac: `~/Library/Application Support/Code` + - Windows: `%APPDATA%\Code` + - Linux: `~/.config/Code` + - Restart VS Code + +**If still failing:** Uninstall completely, restart OS, reinstall fresh. + +--- + +### Issue: "GitHub: Sign In Required" (Stuck) + +**Symptom:** Always prompts to sign in, even after signing in + +**Causes:** Authentication token expired, browser cookie issue, network problem + +**Solutions:** + +1. **Sign out completely** + - Command Palette: `GitHub: Sign Out` + - Wait 5 seconds + - Restart VS Code + +2. **Clear browser cache** (if using browser login) + - Close VS Code + - Clear cookies for github.com in your browser + - Restart VS Code and try signing in again + +3. **Use API key instead** (if browser login fails) + - Generate token: [github.com/settings/tokens](https://github.com/settings/tokens) + - Select scopes: `read:user`, `user:email` + - VS Code Settings → Search "GitHub: Enterprise URI" + - Enter your token when prompted + +4. **Check internet connection** + - Verify you can reach github.com + - Try signing in from browser first + - Then retry in VS Code + +5. **Update GitHub extension** + - Extensions → GitHub (official) → Update + - Restart VS Code + +**If still failing:** Manually reset authentication + +```bash +# Mac +defaults delete com.microsoft.VSCode GitHub.authentication + +# Linux +rm ~/.config/Code/User/globalStorage/github.authentication +``` + +--- + +### Issue: "No Inline Suggestions Appearing" + +**Symptom:** No gray suggestion text as you type + +**Causes:** Feature disabled, Copilot license issue, file type excluded + +**Solutions:** + +1. **Check if enabled** + - Settings (Cmd+, or Ctrl+,) → Search "Copilot" + - `editor.inlineSuggest.enabled` = **true** + - `github.copilot.enable` = **true** + +2. **Check file type** + - Copilot must be enabled for that language + - Settings → Search `github.copilot.enable` → Expand + - Ensure your file type is **true** (e.g., `"[javascript]": true`) + +3. **Verify Copilot license** + - Visit [github.com/settings/copilot](https://github.com/settings/copilot) + - Ensure your subscription is **active** + - If free trial expired, renew or purchase + +4. **Restart Copilot** + - Command Palette → `GitHub Copilot: Restart Copilot` + - Wait 30 seconds + - Try typing again + +5. **Check for rate limiting** + - If you've used Copilot heavily, you might be rate-limited + - Wait 15 minutes and try again + +6. **Increase suggestion delay** + - If suggestions are slow to appear, VS Code might not show them + - Settings → Search "suggest delay" → Increase from 75ms to 200ms + +**If still failing:** Reinstall the extension (see [GitHub Copilot Can't Activate](#issue-github-copilot-cant-activate)) + +--- + +### Issue: "Suggestions Are Bad Quality" + +**Symptom:** Copilot suggestions don't match what you need + +**Causes:** Unclear context, poor variable names, too much code history + +**Solutions:** + +1. **Write clearer comments** + - ❌ Bad: `// calc` + - ✅ Good: `// Calculate the sum of array values, excluding zeros` + +2. **Use better variable names** + - ❌ Bad: `let x = data;` + - ✅ Good: `let userEmails = data;` + +3. **Provide context** + - Add imports and setup before requesting suggestions + - Comment what the function should do + +4. **Use shorter functions** + - Copilot performs better on 5–20 line functions + - Break into smaller pieces + +5. **Ask in Copilot Chat instead** + - Command Palette → `Copilot: Open Chat` + - Describe what you need + - Chat often provides better suggestions + +**Example:** Before vs After + +**Before:** + +```javascript +function proc(d) { + // process +``` + +**After:** + +```javascript +// Parse user data array and return active users with email verified +function processUserData(data) { + // Extract only active users +``` + +--- + +### Issue: "Copilot Suggests Licensed Code" + +**Symptom:** Copilot suggests code that looks copyrighted or from another project + +**Causes:** Training data includes public repos, code similarity across projects + +**Solutions:** + +1. **Don't accept the suggestion** + - Press Escape to reject + - Never copy licensed code + +2. **Check code origin** + - If unsure, ask in Copilot Chat: "Is this code licensed? Should I use it?" + - Claude will help assess + +3. **Use alternative approach** + - Ask Copilot Chat: "What's a different way to write this function?" + - Get multiple suggestions + +4. **Report suspicious patterns** + - If you recognize exact code from another project + - GitHub issue with `[copilot-issue]` label + - Include the suspected source + +5. **Use GitHub Advanced Security** + - Enable code scanning to detect license issues + - Requires GitHub Enterprise + +--- + +## Claude Code Issues + +### Issue: "Claude Code Extension Won't Start" + +**Error message:** "Claude Code failed to initialize" + +**Causes:** Missing authentication, API key invalid, extension conflict + +**Solutions:** + +1. **Verify VS Code version** (must be 1.86+) + - Code → About Visual Studio Code + - Update if needed + +2. **Check authentication** + - Command Palette → `Claude: Sign In` + - Complete authentication flow + - Restart VS Code + +3. **Verify API key** (if using key auth) + - Settings → Search "Claude Code API Key" + - Ensure key is current (regenerate at [console.anthropic.com](https://console.anthropic.com)) + - Save settings + +4. **Check for conflicting extensions** + - Extensions → Disable all except Claude Code + - Restart VS Code + - Re-enable one by one + +5. **Clear extension cache** + - Close VS Code + - Delete: `~/.vscode/extensions/anthropic.claude-code-*/` + - Restart and reinstall + +**If still failing:** Remove all Claude-related settings: + +```bash +# Mac/Linux +rm -rf ~/.claude/ + +# Windows +rmdir %APPDATA%\.claude /s +``` + +Then reinstall fresh. + +--- + +### Issue: "Authentication Failed" + +**Error message:** "Could not authenticate with Anthropic" or "Invalid API key" + +**Causes:** Wrong credentials, API key expired, network issue + +**Solutions:** + +1. **Sign out and back in** + - Command Palette → `Claude: Sign Out` + - Restart VS Code + - Command Palette → `Claude: Sign In` + +2. **Verify API key** + - Visit [console.anthropic.com](https://console.anthropic.com) + - Generate a new key if needed + - Settings → Search "Claude Code API Key" → Paste new key + +3. **Check subscription status** + - Visit [console.anthropic.com](https://console.anthropic.com) + - Verify account has active subscription or credits + - If free tier, usage limit may be exceeded (wait until reset) + +4. **Verify network connectivity** + + ```bash + ping api.anthropic.com + # Should show responses + ``` + + If not, check internet connection or firewall + +5. **Check VS Code proxy settings** + - Settings → Search "proxy" + - If you use a proxy, ensure it's configured correctly + - Contact IT if unsure + +--- + +### Issue: "No Project Context Detected" + +**Symptom:** Claude Code says "I don't understand your project structure" + +**Causes:** Wrong working directory, missing `.claude/CLAUDE.md` + +**Solutions:** + +1. **Verify working directory** + - File → Open Folder + - Select project root (where `.git/` or `package.json` is) + - Not a subdirectory + +2. **Create project context file** + + ```bash + mkdir -p .claude + touch .claude/CLAUDE.md + ``` + + Add content: + + ```markdown + # Project Overview + + This is the LightSpeed .github repository. + - Purpose: GitHub community health files + - Language: Markdown, JavaScript, YAML + ``` + +3. **Reload context** + - Command Palette → `Claude: Reload Context` + - Wait 10 seconds for analysis + +4. **Check `.gitignore`** + - Ensure important files aren't hidden + - Claude can't see files gitignored + +--- + +### Issue: "Claude Code Chat Not Responding" + +**Symptom:** Chat takes >30 seconds to respond, or times out + +**Causes:** Slow internet, large project analysis, API overload + +**Solutions:** + +1. **Check internet speed** + + ```bash + # Test connection + ping google.com + ``` + + If slow (<1Mbps), contact IT or wait for better connection + +2. **Reduce project context** + - Chat → Settings → Reduce "Context Window" + - From 200000 to 100000 tokens + - Faster but less context awareness + +3. **Use faster model** + - Command Palette → `Claude: Select Model` + - Choose `claude-haiku-4-5` instead of `opus-5` + - Faster, less capable + +4. **Check API status** + - Visit [status.anthropic.com](https://status.anthropic.com) + - If service is degraded, wait and retry + +5. **Simplify request** + - Instead of "Analyze entire codebase" + - Try "Analyze this file" first + - Build complexity gradually + +--- + +### Issue: "Can't Find File References" + +**Symptom:** Claude Code says "I can't find that file" or references are wrong + +**Causes:** Working directory wrong, file not in project, path separator issue + +**Solutions:** + +1. **Check file exists** + - Verify file path is correct + - Use relative paths: `src/utils/helper.js` (not absolute paths) + +2. **Open file in editor first** + - Open the file in VS Code + - Then ask Claude about it + - Improves context detection + +3. **Use correct path format** + - Forward slashes only: `src/folder/file.js` + - Not backslashes (even on Windows) + +4. **Verify working directory** + - File → Open Folder → Select project root + - Claude needs root to find all files + +--- + +## Performance Issues + +### Issue: "Slow Responses" + +**Symptom:** Claude takes >15 seconds to respond, or suggestions are sluggish + +**Causes:** Large project, slow internet, API overload, VS Code indexing + +**Solutions:** + +1. **Check internet speed** + - Open terminal: `speedtest-cli` or visit [speedtest.net](https://speedtest.net) + - Need >5Mbps for good performance + +2. **Close unnecessary files** + - Close files not being worked on + - Claude analyzes open files for context + +3. **Use smaller context window** + - Settings → Search "context window" → Reduce to 100000 + +4. **Switch to faster model** + - Haiku 4.5 is fastest, Opus 5 is smartest + - Trade quality for speed if needed + +5. **Wait for VS Code indexing** + - When you first open a project, VS Code indexes files (1–5 min) + - Don't request analysis during this time + +6. **Check CPU/Memory** + - Activity Monitor (Mac) or Task Manager (Windows) + - If VS Code using >80% CPU, close other apps + +--- + +### Issue: "High Memory Usage" + +**Symptom:** VS Code using >500MB RAM, system feels sluggish + +**Causes:** Large project, many open files, extension memory leak + +**Solutions:** + +1. **Close unused files** + - Close tabs you're not using + - Each file takes memory to analyze + +2. **Disable extensions temporarily** + - Extensions → Disable all except Claude Code + - Restart VS Code + - Check memory usage + - Re-enable gradually + +3. **Clear Claude cache** + - Command Palette → `Claude: Clear Cache` + - Restart VS Code + +4. **Use smaller project context** + - Settings → Reduce context window + - Limits how much code Claude analyzes + +5. **Upgrade VS Code** + - Newer versions have better memory management + - Check for updates regularly + +--- + +## Connection Issues + +### Issue: "Connection Timeout" + +**Symptom:** "Could not connect to API" or "Request timed out" + +**Causes:** Network issue, firewall blocking, API down + +**Solutions:** + +1. **Check internet connection** + + ```bash + ping 8.8.8.8 + ``` + + If no response, connection is down + +2. **Verify API is reachable** + + ```bash + curl -I https://api.anthropic.com + ``` + + Should return HTTP 200–400, not timeout + +3. **Check firewall/proxy** + - If behind corporate firewall, IT may block API + - Contact IT team + - May need to whitelist Anthropic domains + +4. **Wait for API recovery** + - Check [status.anthropic.com](https://status.anthropic.com) + - If service is down, wait and retry in 5–10 minutes + +5. **Try different network** + - Switch from Wi-Fi to Ethernet (or vice versa) + - Try mobile hotspot + - Tests if specific network is blocked + +--- + +## Update Issues + +### Issue: "After Plugin Update" + +**Symptom:** Plugin doesn't work after automatic update + +**Causes:** Incompatibility, corrupted update, missing dependencies + +**Solutions:** + +1. **Restart VS Code** + - Close completely + - Wait 10 seconds + - Reopen + +2. **Check extension version** + - Extensions → Claude Code → Version number + - Compare to [marketplace.visualstudio.com](https://marketplace.visualstudio.com) + +3. **Reinstall extension** + - Extensions → Claude Code → Uninstall + - Restart VS Code + - Reinstall from marketplace + +4. **Roll back to previous version** + - Extensions → Claude Code → Version History + - Click previous version + - Restart VS Code + +5. **Check GitHub issues** + - Search [GitHub issues](https://github.com/anthropics/claude-code/issues) + - Your problem might be documented + +--- + +## Getting Help + +### Before Contacting Support + +Gather this information: + +``` +- VS Code Version: [from About] +- Plugin Version: [from Extensions] +- OS: [Windows 10/11, macOS, Linux] +- Error Message: [exact text] +- Steps to Reproduce: [1, 2, 3] +``` + +### Support Channels + +**Team Help:** + +1. Open GitHub issue with label `[plugin-help]` +2. Include all info above +3. Response within 24 hours + +**Escalation:** + +1. Email: +2. Subject: "Claude Code Plugin Issue" +3. Include reproduction steps + +**Emergency (Blocking Issue):** + +1. Slack/DM to Ash Shaw +2. Explain business impact +3. Response within 1 hour + +### Helpful Diagnostic Commands + +```bash +# Check VS Code version +code --version + +# List installed extensions +code --list-extensions + +# Check VS Code logs +~/.vscode/logs/ (Mac/Linux) +%APPDATA%\Code\logs\ (Windows) + +# Test API connectivity +curl -I https://api.anthropic.com +``` + +--- + +## Frequently Asked Questions + +### Q: Will Claude Code delete my files? + +**A:** No. Claude Code edits files but doesn't delete them. Always review changes before accepting. Use Git to revert if needed. + +### Q: Is my code sent to Claude? + +**A:** Only code you explicitly ask Claude to work with. Never sent without action from you. + +### Q: Can I use Claude Code offline? + +**A:** No. Requires internet connection to Claude API. + +### Q: Will these tools drain my battery? + +**A:** Slightly. Background indexing uses CPU. Disable if on battery power by disabling extensions. + +### Q: Can I use both Copilot and Claude Code? + +**A:** Yes! They work together. Copilot for inline suggestions, Claude Code for complex tasks. + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0 | 2026-07-26 | Initial troubleshooting guide | + +--- + +## References + +- [Claude Code Setup Guide](./plugin-setup-claude-code.md) +- [GitHub Copilot Setup Guide](./plugin-setup-github-copilot.md) +- [Plugin Testing Guide](./plugin-testing.md) + +--- + +*Created as part of Phase 4: Plugin Adoption Strategy*