surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

docs: Add comprehensive plugin documentation (#9797)Browse files

- Add plugins section to main README with link to detailed docs
- Create plugins/README.md with overview of all available plugins
- Add detailed READMEs for agent-sdk-dev, commit-commands, and feature-dev plugins
- Document all commands, agents, usage patterns, and workflows

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Ashwin Bhat authored on Oct 17, 2025 · GitHub committed on Oct 17, 2025 parent 0ea180e · commit cabd74fa9e26

5 changed files+942 -0compared with 0ea180e

MREADME.md

Aplugins/README.md

Aplugins/agent-sdk-dev/README.md

Aplugins/commit-commands/README.md

Aplugins/feature-dev/README.md

MREADME.md+4 -0

		@@ -20,6 +20,10 @@
20	20
21	21	2. Navigate to your project directory and run `claude`.
22	22
	23	+## Plugins
	24	+
	25	+This repository includes several Claude Code plugins that extend functionality with custom commands and agents. See the [plugins directory](./plugins/README.md) for detailed documentation on available plugins.
	26	+
23	27	## Reporting Bugs
24	28
25	29	We welcome your feedback. Use the `/bug` command to report issues directly within Claude Code, or file a [GitHub issue](https://github.com/anthropics/claude-code/issues).

Aplugins/README.md+93 -0

		@@ -1,0 +1,93 @@
	1	+# Claude Code Plugins
	2	+
	3	+This directory contains some official Claude Code plugins that extend functionality through custom commands, agents, and workflows. These are examples of what's possible with the Claude Code plugin system—many more plugins are available through community marketplaces.
	4	+
	5	+## What are Claude Code Plugins?
	6	+
	7	+Claude Code plugins are extensions that enhance Claude Code with custom slash commands, specialized agents, hooks, and MCP servers. Plugins can be shared across projects and teams, providing consistent tooling and workflows.
	8	+
	9	+Learn more in the [official plugins documentation](https://docs.claude.com/en/docs/claude-code/plugins).
	10	+
	11	+## Plugins in This Directory
	12	+
	13	+### [agent-sdk-dev](./agent-sdk-dev/)
	14	+
	15	+Claude Agent SDK Development Plugin
	16	+
	17	+Streamlines the development of Claude Agent SDK applications with scaffolding commands and verification agents.
	18	+
	19	+- Command: `/new-sdk-app` - Interactive setup for new Agent SDK projects
	20	+- Agents: `agent-sdk-verifier-py` and `agent-sdk-verifier-ts` - Validate SDK applications against best practices
	21	+- Use case: Creating and verifying Claude Agent SDK applications in Python or TypeScript
	22	+
	23	+### [commit-commands](./commit-commands/)
	24	+
	25	+Git Workflow Automation Plugin
	26	+
	27	+Simplifies common git operations with streamlined commands for committing, pushing, and creating pull requests.
	28	+
	29	+- Commands:
	30	+ - `/commit` - Create a git commit with appropriate message
	31	+ - `/commit-push-pr` - Commit, push, and create a PR in one command
	32	+ - `/clean_gone` - Clean up stale local branches marked as [gone]
	33	+- Use case: Faster git workflows with less context switching
	34	+
	35	+### [feature-dev](./feature-dev/)
	36	+
	37	+Comprehensive Feature Development Workflow Plugin
	38	+
	39	+Provides a structured 7-phase approach to feature development with specialized agents for exploration, architecture, and review.
	40	+
	41	+- Command: `/feature-dev` - Guided feature development workflow
	42	+- Agents:
	43	+ - `code-explorer` - Deeply analyzes existing codebase features
	44	+ - `code-architect` - Designs feature architectures and implementation blueprints
	45	+ - `code-reviewer` - Reviews code for bugs, quality issues, and project conventions
	46	+- Use case: Building new features with systematic codebase understanding and quality assurance
	47	+
	48	+## Installation
	49	+
	50	+These plugins are included in the Claude Code repository. To use them in your own projects:
	51	+
	52	+1. Install Claude Code globally:
	53	+```bash
	54	+npm install -g @anthropic-ai/claude-code
	55	+```
	56	+
	57	+2. Navigate to your project and run Claude Code:
	58	+```bash
	59	+claude
	60	+```
	61	+
	62	+3. Use the `/plugin` command to install plugins from marketplaces, or configure them in your project's `.claude/settings.json`.
	63	+
	64	+For detailed plugin installation and configuration, see the [official documentation](https://docs.claude.com/en/docs/claude-code/plugins).
	65	+
	66	+## Plugin Structure
	67	+
	68	+Each plugin follows the standard Claude Code plugin structure:
	69	+
	70	+```
	71	+plugin-name/
	72	+├── .claude-plugin/
	73	+│ └── plugin.json # Plugin metadata
	74	+├── commands/ # Slash commands (optional)
	75	+├── agents/ # Specialized agents (optional)
	76	+└── README.md # Plugin documentation
	77	+```
	78	+
	79	+## Contributing
	80	+
	81	+When adding new plugins to this directory:
	82	+
	83	+1. Follow the standard plugin structure
	84	+2. Include a comprehensive README.md
	85	+3. Add plugin metadata in `.claude-plugin/plugin.json`
	86	+4. Document all commands and agents
	87	+5. Provide usage examples
	88	+
	89	+## Learn More
	90	+
	91	+- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview)
	92	+- [Plugin System Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
	93	+- [Agent SDK Documentation](https://docs.claude.com/en/api/agent-sdk/overview)

Aplugins/agent-sdk-dev/README.md+208 -0

		@@ -1,0 +1,208 @@
	1	+# Agent SDK Development Plugin
	2	+
	3	+A comprehensive plugin for creating and verifying Claude Agent SDK applications in Python and TypeScript.
	4	+
	5	+## Overview
	6	+
	7	+The Agent SDK Development Plugin streamlines the entire lifecycle of building Agent SDK applications, from initial scaffolding to verification against best practices. It helps you quickly start new projects with the latest SDK versions and ensures your applications follow official documentation patterns.
	8	+
	9	+## Features
	10	+
	11	+### Command: `/new-sdk-app`
	12	+
	13	+Interactive command that guides you through creating a new Claude Agent SDK application.
	14	+
	15	+What it does:
	16	+- Asks clarifying questions about your project (language, name, agent type, starting point)
	17	+- Checks for and installs the latest SDK version
	18	+- Creates all necessary project files and configuration
	19	+- Sets up proper environment files (.env.example, .gitignore)
	20	+- Provides a working example tailored to your use case
	21	+- Runs type checking (TypeScript) or syntax validation (Python)
	22	+- Automatically verifies the setup using the appropriate verifier agent
	23	+
	24	+Usage:
	25	+```bash
	26	+/new-sdk-app my-project-name
	27	+```
	28	+
	29	+Or simply:
	30	+```bash
	31	+/new-sdk-app
	32	+```
	33	+
	34	+The command will interactively ask you:
	35	+1. Language choice (TypeScript or Python)
	36	+2. Project name (if not provided)
	37	+3. Agent type (coding, business, custom)
	38	+4. Starting point (minimal, basic, or specific example)
	39	+5. Tooling preferences (npm/yarn/pnpm or pip/poetry)
	40	+
	41	+Example:
	42	+```bash
	43	+/new-sdk-app customer-support-agent
	44	+# → Creates a new Agent SDK project for a customer support agent
	45	+# → Sets up TypeScript or Python environment
	46	+# → Installs latest SDK version
	47	+# → Verifies the setup automatically
	48	+```
	49	+
	50	+### Agent: `agent-sdk-verifier-py`
	51	+
	52	+Thoroughly verifies Python Agent SDK applications for correct setup and best practices.
	53	+
	54	+Verification checks:
	55	+- SDK installation and version
	56	+- Python environment setup (requirements.txt, pyproject.toml)
	57	+- Correct SDK usage and patterns
	58	+- Agent initialization and configuration
	59	+- Environment and security (.env, API keys)
	60	+- Error handling and functionality
	61	+- Documentation completeness
	62	+
	63	+When to use:
	64	+- After creating a new Python SDK project
	65	+- After modifying an existing Python SDK application
	66	+- Before deploying a Python SDK application
	67	+
	68	+Usage:
	69	+The agent runs automatically after `/new-sdk-app` creates a Python project, or you can trigger it by asking:
	70	+```
	71	+"Verify my Python Agent SDK application"
	72	+"Check if my SDK app follows best practices"
	73	+```
	74	+
	75	+Output:
	76	+Provides a comprehensive report with:
	77	+- Overall status (PASS / PASS WITH WARNINGS / FAIL)
	78	+- Critical issues that prevent functionality
	79	+- Warnings about suboptimal patterns
	80	+- List of passed checks
	81	+- Specific recommendations with SDK documentation references
	82	+
	83	+### Agent: `agent-sdk-verifier-ts`
	84	+
	85	+Thoroughly verifies TypeScript Agent SDK applications for correct setup and best practices.
	86	+
	87	+Verification checks:
	88	+- SDK installation and version
	89	+- TypeScript configuration (tsconfig.json)
	90	+- Correct SDK usage and patterns
	91	+- Type safety and imports
	92	+- Agent initialization and configuration
	93	+- Environment and security (.env, API keys)
	94	+- Error handling and functionality
	95	+- Documentation completeness
	96	+
	97	+When to use:
	98	+- After creating a new TypeScript SDK project
	99	+- After modifying an existing TypeScript SDK application
	100	+- Before deploying a TypeScript SDK application
	101	+
	102	+Usage:
	103	+The agent runs automatically after `/new-sdk-app` creates a TypeScript project, or you can trigger it by asking:
	104	+```
	105	+"Verify my TypeScript Agent SDK application"
	106	+"Check if my SDK app follows best practices"
	107	+```
	108	+
	109	+Output:
	110	+Provides a comprehensive report with:
	111	+- Overall status (PASS / PASS WITH WARNINGS / FAIL)
	112	+- Critical issues that prevent functionality
	113	+- Warnings about suboptimal patterns
	114	+- List of passed checks
	115	+- Specific recommendations with SDK documentation references
	116	+
	117	+## Workflow Example
	118	+
	119	+Here's a typical workflow using this plugin:
	120	+
	121	+1. Create a new project:
	122	+```bash
	123	+/new-sdk-app code-reviewer-agent
	124	+```
	125	+
	126	+2. Answer the interactive questions:
	127	+```
	128	+Language: TypeScript
	129	+Agent type: Coding agent (code review)
	130	+Starting point: Basic agent with common features
	131	+```
	132	+
	133	+3. Automatic verification:
	134	+The command automatically runs `agent-sdk-verifier-ts` to ensure everything is correctly set up.
	135	+
	136	+4. Start developing:
	137	+```bash
	138	+# Set your API key
	139	+echo "ANTHROPIC_API_KEY=your_key_here" > .env
	140	+
	141	+# Run your agent
	142	+npm start
	143	+```
	144	+
	145	+5. Verify after changes:
	146	+```
	147	+"Verify my SDK application"
	148	+```
	149	+
	150	+## Installation
	151	+
	152	+This plugin is included in the Claude Code repository. To use it:
	153	+
	154	+1. Ensure Claude Code is installed
	155	+2. The plugin commands and agents are automatically available
	156	+
	157	+## Best Practices
	158	+
	159	+- Always use the latest SDK version: `/new-sdk-app` checks for and installs the latest version
	160	+- Verify before deploying: Run the verifier agent before deploying to production
	161	+- Keep API keys secure: Never commit `.env` files or hardcode API keys
	162	+- Follow SDK documentation: The verifier agents check against official patterns
	163	+- Type check TypeScript projects: Run `npx tsc --noEmit` regularly
	164	+- Test your agents: Create test cases for your agent's functionality
	165	+
	166	+## Resources
	167	+
	168	+- [Agent SDK Overview](https://docs.claude.com/en/api/agent-sdk/overview)
	169	+- [TypeScript SDK Reference](https://docs.claude.com/en/api/agent-sdk/typescript)
	170	+- [Python SDK Reference](https://docs.claude.com/en/api/agent-sdk/python)
	171	+- [Agent SDK Examples](https://docs.claude.com/en/api/agent-sdk/examples)
	172	+
	173	+## Troubleshooting
	174	+
	175	+### Type errors in TypeScript project
	176	+
	177	+Issue: TypeScript project has type errors after creation
	178	+
	179	+Solution:
	180	+- The `/new-sdk-app` command runs type checking automatically
	181	+- If errors persist, check that you're using the latest SDK version
	182	+- Verify your `tsconfig.json` matches SDK requirements
	183	+
	184	+### Python import errors
	185	+
	186	+Issue: Cannot import from `claude_agent_sdk`
	187	+
	188	+Solution:
	189	+- Ensure you've installed dependencies: `pip install -r requirements.txt`
	190	+- Activate your virtual environment if using one
	191	+- Check that the SDK is installed: `pip show claude-agent-sdk`
	192	+
	193	+### Verification fails with warnings
	194	+
	195	+Issue: Verifier agent reports warnings
	196	+
	197	+Solution:
	198	+- Review the specific warnings in the report
	199	+- Check the SDK documentation references provided
	200	+- Warnings don't prevent functionality but indicate areas for improvement
	201	+
	202	+## Author
	203	+
	204	+Ashwin Bhat (ashwin@anthropic.com)
	205	+
	206	+## Version
	207	+
	208	+1.0.0

Aplugins/commit-commands/README.md+225 -0

		@@ -1,0 +1,225 @@
	1	+# Commit Commands Plugin
	2	+
	3	+Streamline your git workflow with simple commands for committing, pushing, and creating pull requests.
	4	+
	5	+## Overview
	6	+
	7	+The Commit Commands Plugin automates common git operations, reducing context switching and manual command execution. Instead of running multiple git commands, use a single slash command to handle your entire workflow.
	8	+
	9	+## Commands
	10	+
	11	+### `/commit`
	12	+
	13	+Creates a git commit with an automatically generated commit message based on staged and unstaged changes.
	14	+
	15	+What it does:
	16	+1. Analyzes current git status
	17	+2. Reviews both staged and unstaged changes
	18	+3. Examines recent commit messages to match your repository's style
	19	+4. Drafts an appropriate commit message
	20	+5. Stages relevant files
	21	+6. Creates the commit
	22	+
	23	+Usage:
	24	+```bash
	25	+/commit
	26	+```
	27	+
	28	+Example workflow:
	29	+```bash
	30	+# Make some changes to your code
	31	+# Then simply run:
	32	+/commit
	33	+
	34	+# Claude will:
	35	+# - Review your changes
	36	+# - Stage the files
	37	+# - Create a commit with an appropriate message
	38	+# - Show you the commit status
	39	+```
	40	+
	41	+Features:
	42	+- Automatically drafts commit messages that match your repo's style
	43	+- Follows conventional commit practices
	44	+- Avoids committing files with secrets (.env, credentials.json)
	45	+- Includes Claude Code attribution in commit message
	46	+
	47	+### `/commit-push-pr`
	48	+
	49	+Complete workflow command that commits, pushes, and creates a pull request in one step.
	50	+
	51	+What it does:
	52	+1. Creates a new branch (if currently on main)
	53	+2. Stages and commits changes with an appropriate message
	54	+3. Pushes the branch to origin
	55	+4. Creates a pull request using `gh pr create`
	56	+5. Provides the PR URL
	57	+
	58	+Usage:
	59	+```bash
	60	+/commit-push-pr
	61	+```
	62	+
	63	+Example workflow:
	64	+```bash
	65	+# Make your changes
	66	+# Then run:
	67	+/commit-push-pr
	68	+
	69	+# Claude will:
	70	+# - Create a feature branch (if needed)
	71	+# - Commit your changes
	72	+# - Push to remote
	73	+# - Open a PR with summary and test plan
	74	+# - Give you the PR URL to review
	75	+```
	76	+
	77	+Features:
	78	+- Analyzes all commits in the branch (not just the latest)
	79	+- Creates comprehensive PR descriptions with:
	80	+ - Summary of changes (1-3 bullet points)
	81	+ - Test plan checklist
	82	+ - Claude Code attribution
	83	+- Handles branch creation automatically
	84	+- Uses GitHub CLI (`gh`) for PR creation
	85	+
	86	+Requirements:
	87	+- GitHub CLI (`gh`) must be installed and authenticated
	88	+- Repository must have a remote named `origin`
	89	+
	90	+### `/clean_gone`
	91	+
	92	+Cleans up local branches that have been deleted from the remote repository.
	93	+
	94	+What it does:
	95	+1. Lists all local branches to identify [gone] status
	96	+2. Identifies and removes worktrees associated with [gone] branches
	97	+3. Deletes all branches marked as [gone]
	98	+4. Provides feedback on removed branches
	99	+
	100	+Usage:
	101	+```bash
	102	+/clean_gone
	103	+```
	104	+
	105	+Example workflow:
	106	+```bash
	107	+# After PRs are merged and remote branches are deleted
	108	+/clean_gone
	109	+
	110	+# Claude will:
	111	+# - Find all branches marked as [gone]
	112	+# - Remove any associated worktrees
	113	+# - Delete the stale local branches
	114	+# - Report what was cleaned up
	115	+```
	116	+
	117	+Features:
	118	+- Handles both regular branches and worktree branches
	119	+- Safely removes worktrees before deleting branches
	120	+- Shows clear feedback about what was removed
	121	+- Reports if no cleanup was needed
	122	+
	123	+When to use:
	124	+- After merging and deleting remote branches
	125	+- When your local branch list is cluttered with stale branches
	126	+- During regular repository maintenance
	127	+
	128	+## Installation
	129	+
	130	+This plugin is included in the Claude Code repository. The commands are automatically available when using Claude Code.
	131	+
	132	+## Best Practices
	133	+
	134	+### Using `/commit`
	135	+- Review the staged changes before committing
	136	+- Let Claude analyze your changes and match your repo's commit style
	137	+- Trust the automated message, but verify it's accurate
	138	+- Use for routine commits during development
	139	+
	140	+### Using `/commit-push-pr`
	141	+- Use when you're ready to create a PR
	142	+- Ensure all your changes are complete and tested
	143	+- Claude will analyze the full branch history for the PR description
	144	+- Review the PR description and edit if needed
	145	+- Use when you want to minimize context switching
	146	+
	147	+### Using `/clean_gone`
	148	+- Run periodically to keep your branch list clean
	149	+- Especially useful after merging multiple PRs
	150	+- Safe to run - only removes branches already deleted remotely
	151	+- Helps maintain a tidy local repository
	152	+
	153	+## Workflow Integration
	154	+
	155	+### Quick commit workflow:
	156	+```bash
	157	+# Write code
	158	+/commit
	159	+# Continue development
	160	+```
	161	+
	162	+### Feature branch workflow:
	163	+```bash
	164	+# Develop feature across multiple commits
	165	+/commit # First commit
	166	+# More changes
	167	+/commit # Second commit
	168	+# Ready to create PR
	169	+/commit-push-pr
	170	+```
	171	+
	172	+### Maintenance workflow:
	173	+```bash
	174	+# After several PRs are merged
	175	+/clean_gone
	176	+# Clean workspace ready for next feature
	177	+```
	178	+
	179	+## Requirements
	180	+
	181	+- Git must be installed and configured
	182	+- For `/commit-push-pr`: GitHub CLI (`gh`) must be installed and authenticated
	183	+- Repository must be a git repository with a remote
	184	+
	185	+## Troubleshooting
	186	+
	187	+### `/commit` creates empty commit
	188	+
	189	+Issue: No changes to commit
	190	+
	191	+Solution:
	192	+- Ensure you have unstaged or staged changes
	193	+- Run `git status` to verify changes exist
	194	+
	195	+### `/commit-push-pr` fails to create PR
	196	+
	197	+Issue: `gh pr create` command fails
	198	+
	199	+Solution:
	200	+- Install GitHub CLI: `brew install gh` (macOS) or see [GitHub CLI installation](https://cli.github.com/)
	201	+- Authenticate: `gh auth login`
	202	+- Ensure repository has a GitHub remote
	203	+
	204	+### `/clean_gone` doesn't find branches
	205	+
	206	+Issue: No branches marked as [gone]
	207	+
	208	+Solution:
	209	+- Run `git fetch --prune` to update remote tracking
	210	+- Branches must be deleted from the remote to show as [gone]
	211	+
	212	+## Tips
	213	+
	214	+- Combine with other tools: Use `/commit` during development, then `/commit-push-pr` when ready
	215	+- Let Claude draft messages: The commit message analysis learns from your repo's style
	216	+- Regular cleanup: Run `/clean_gone` weekly to maintain a clean branch list
	217	+- Review before pushing: Always review the commit message and changes before pushing
	218	+
	219	+## Author
	220	+
	221	+Anthropic (support@anthropic.com)
	222	+
	223	+## Version
	224	+
	225	+1.0.0

Aplugins/feature-dev/README.md+412 -0

		@@ -1,0 +1,412 @@
	1	+# Feature Development Plugin
	2	+
	3	+A comprehensive, structured workflow for feature development with specialized agents for codebase exploration, architecture design, and quality review.
	4	+
	5	+## Overview
	6	+
	7	+The Feature Development Plugin provides a systematic 7-phase approach to building new features. Instead of jumping straight into code, it guides you through understanding the codebase, asking clarifying questions, designing architecture, and ensuring quality—resulting in better-designed features that integrate seamlessly with your existing code.
	8	+
	9	+## Philosophy
	10	+
	11	+Building features requires more than just writing code. You need to:
	12	+- Understand the codebase before making changes
	13	+- Ask questions to clarify ambiguous requirements
	14	+- Design thoughtfully before implementing
	15	+- Review for quality after building
	16	+
	17	+This plugin embeds these practices into a structured workflow that runs automatically when you use the `/feature-dev` command.
	18	+
	19	+## Command: `/feature-dev`
	20	+
	21	+Launches a guided feature development workflow with 7 distinct phases.
	22	+
	23	+Usage:
	24	+```bash
	25	+/feature-dev Add user authentication with OAuth
	26	+```
	27	+
	28	+Or simply:
	29	+```bash
	30	+/feature-dev
	31	+```
	32	+
	33	+The command will guide you through the entire process interactively.
	34	+
	35	+## The 7-Phase Workflow
	36	+
	37	+### Phase 1: Discovery
	38	+
	39	+Goal: Understand what needs to be built
	40	+
	41	+What happens:
	42	+- Clarifies the feature request if it's unclear
	43	+- Asks what problem you're solving
	44	+- Identifies constraints and requirements
	45	+- Summarizes understanding and confirms with you
	46	+
	47	+Example:
	48	+```
	49	+You: /feature-dev Add caching
	50	+Claude: Let me understand what you need...
	51	+ - What should be cached? (API responses, computed values, etc.)
	52	+ - What are your performance requirements?
	53	+ - Do you have a preferred caching solution?
	54	+```
	55	+
	56	+### Phase 2: Codebase Exploration
	57	+
	58	+Goal: Understand relevant existing code and patterns
	59	+
	60	+What happens:
	61	+- Launches 2-3 `code-explorer` agents in parallel
	62	+- Each agent explores different aspects (similar features, architecture, UI patterns)
	63	+- Agents return comprehensive analyses with key files to read
	64	+- Claude reads all identified files to build deep understanding
	65	+- Presents comprehensive summary of findings
	66	+
	67	+Agents launched:
	68	+- "Find features similar to [feature] and trace implementation"
	69	+- "Map the architecture and abstractions for [area]"
	70	+- "Analyze current implementation of [related feature]"
	71	+
	72	+Example output:
	73	+```
	74	+Found similar features:
	75	+- User authentication (src/auth/): Uses JWT tokens, middleware pattern
	76	+- Session management (src/session/): Redis-backed, 24hr expiry
	77	+- API security (src/api/middleware/): Rate limiting, CORS
	78	+
	79	+Key files to understand:
	80	+- src/auth/AuthService.ts:45 - Core authentication logic
	81	+- src/middleware/authMiddleware.ts:12 - Request authentication
	82	+- src/config/security.ts:8 - Security configuration
	83	+```
	84	+
	85	+### Phase 3: Clarifying Questions
	86	+
	87	+Goal: Fill in gaps and resolve all ambiguities
	88	+
	89	+What happens:
	90	+- Reviews codebase findings and feature request
	91	+- Identifies underspecified aspects:
	92	+ - Edge cases
	93	+ - Error handling
	94	+ - Integration points
	95	+ - Backward compatibility
	96	+ - Performance needs
	97	+- Presents all questions in an organized list
	98	+- Waits for your answers before proceeding
	99	+
	100	+Example:
	101	+```
	102	+Before designing the architecture, I need to clarify:
	103	+
	104	+1. OAuth provider: Which OAuth providers? (Google, GitHub, custom?)
	105	+2. User data: Store OAuth tokens or just user profile?
	106	+3. Existing auth: Replace current auth or add alongside?
	107	+4. Sessions: Integrate with existing session management?
	108	+5. Error handling: How to handle OAuth failures?
	109	+```
	110	+
	111	+Critical: This phase ensures nothing is ambiguous before design begins.
	112	+
	113	+### Phase 4: Architecture Design
	114	+
	115	+Goal: Design multiple implementation approaches
	116	+
	117	+What happens:
	118	+- Launches 2-3 `code-architect` agents with different focuses:
	119	+ - Minimal changes: Smallest change, maximum reuse
	120	+ - Clean architecture: Maintainability, elegant abstractions
	121	+ - Pragmatic balance: Speed + quality
	122	+- Reviews all approaches
	123	+- Forms opinion on which fits best for this task
	124	+- Presents comparison with trade-offs and recommendation
	125	+- Asks which approach you prefer
	126	+
	127	+Example output:
	128	+```
	129	+I've designed 3 approaches:
	130	+
	131	+Approach 1: Minimal Changes
	132	+- Extend existing AuthService with OAuth methods
	133	+- Add new OAuth routes to existing auth router
	134	+- Minimal refactoring required
	135	+Pros: Fast, low risk
	136	+Cons: Couples OAuth to existing auth, harder to test
	137	+
	138	+Approach 2: Clean Architecture
	139	+- New OAuthService with dedicated interface
	140	+- Separate OAuth router and middleware
	141	+- Refactor AuthService to use common interface
	142	+Pros: Clean separation, testable, maintainable
	143	+Cons: More files, more refactoring
	144	+
	145	+Approach 3: Pragmatic Balance
	146	+- New OAuthProvider abstraction
	147	+- Integrate into existing AuthService
	148	+- Minimal refactoring, good boundaries
	149	+Pros: Balanced complexity and cleanliness
	150	+Cons: Some coupling remains
	151	+
	152	+Recommendation: Approach 3 - gives you clean boundaries without
	153	+excessive refactoring, and fits your existing architecture well.
	154	+
	155	+Which approach would you like to use?
	156	+```
	157	+
	158	+### Phase 5: Implementation
	159	+
	160	+Goal: Build the feature
	161	+
	162	+What happens:
	163	+- Waits for explicit approval before starting
	164	+- Reads all relevant files identified in previous phases
	165	+- Implements following chosen architecture
	166	+- Follows codebase conventions strictly
	167	+- Writes clean, well-documented code
	168	+- Updates todos as progress is made
	169	+
	170	+Notes:
	171	+- Implementation only starts after you approve
	172	+- Follows patterns discovered in Phase 2
	173	+- Uses architecture designed in Phase 4
	174	+- Continuously tracks progress
	175	+
	176	+### Phase 6: Quality Review
	177	+
	178	+Goal: Ensure code is simple, DRY, elegant, and functionally correct
	179	+
	180	+What happens:
	181	+- Launches 3 `code-reviewer` agents in parallel with different focuses:
	182	+ - Simplicity/DRY/Elegance: Code quality and maintainability
	183	+ - Bugs/Correctness: Functional correctness and logic errors
	184	+ - Conventions/Abstractions: Project standards and patterns
	185	+- Consolidates findings
	186	+- Identifies highest severity issues
	187	+- Presents findings and asks what you want to do:
	188	+ - Fix now
	189	+ - Fix later
	190	+ - Proceed as-is
	191	+- Addresses issues based on your decision
	192	+
	193	+Example output:
	194	+```
	195	+Code Review Results:
	196	+
	197	+High Priority Issues:
	198	+1. Missing error handling in OAuth callback (src/auth/oauth.ts:67)
	199	+2. Memory leak: OAuth state not cleaned up (src/auth/oauth.ts:89)
	200	+
	201	+Medium Priority:
	202	+1. Could simplify token refresh logic (src/auth/oauth.ts:120)
	203	+2. Consider extracting OAuth config validation
	204	+
	205	+All tests pass. Code follows project conventions.
	206	+
	207	+What would you like to do?
	208	+```
	209	+
	210	+### Phase 7: Summary
	211	+
	212	+Goal: Document what was accomplished
	213	+
	214	+What happens:
	215	+- Marks all todos complete
	216	+- Summarizes:
	217	+ - What was built
	218	+ - Key decisions made
	219	+ - Files modified
	220	+ - Suggested next steps
	221	+
	222	+Example:
	223	+```
	224	+Feature Complete: OAuth Authentication
	225	+
	226	+What was built:
	227	+- OAuth provider abstraction supporting Google and GitHub
	228	+- OAuth routes and middleware integrated with existing auth
	229	+- Token refresh and session integration
	230	+- Error handling for all OAuth flows
	231	+
	232	+Key decisions:
	233	+- Used pragmatic approach with OAuthProvider abstraction
	234	+- Integrated with existing session management
	235	+- Added OAuth state to prevent CSRF
	236	+
	237	+Files modified:
	238	+- src/auth/OAuthProvider.ts (new)
	239	+- src/auth/AuthService.ts
	240	+- src/routes/auth.ts
	241	+- src/middleware/authMiddleware.ts
	242	+
	243	+Suggested next steps:
	244	+- Add tests for OAuth flows
	245	+- Add more OAuth providers (Microsoft, Apple)
	246	+- Update documentation
	247	+```
	248	+
	249	+## Agents
	250	+
	251	+### `code-explorer`
	252	+
	253	+Purpose: Deeply analyzes existing codebase features by tracing execution paths
	254	+
	255	+Focus areas:
	256	+- Entry points and call chains
	257	+- Data flow and transformations
	258	+- Architecture layers and patterns
	259	+- Dependencies and integrations
	260	+- Implementation details
	261	+
	262	+When triggered:
	263	+- Automatically in Phase 2
	264	+- Can be invoked manually when exploring code
	265	+
	266	+Output:
	267	+- Entry points with file:line references
	268	+- Step-by-step execution flow
	269	+- Key components and responsibilities
	270	+- Architecture insights
	271	+- List of essential files to read
	272	+
	273	+### `code-architect`
	274	+
	275	+Purpose: Designs feature architectures and implementation blueprints
	276	+
	277	+Focus areas:
	278	+- Codebase pattern analysis
	279	+- Architecture decisions
	280	+- Component design
	281	+- Implementation roadmap
	282	+- Data flow and build sequence
	283	+
	284	+When triggered:
	285	+- Automatically in Phase 4
	286	+- Can be invoked manually for architecture design
	287	+
	288	+Output:
	289	+- Patterns and conventions found
	290	+- Architecture decision with rationale
	291	+- Complete component design
	292	+- Implementation map with specific files
	293	+- Build sequence with phases
	294	+
	295	+### `code-reviewer`
	296	+
	297	+Purpose: Reviews code for bugs, quality issues, and project conventions
	298	+
	299	+Focus areas:
	300	+- Project guideline compliance (CLAUDE.md)
	301	+- Bug detection
	302	+- Code quality issues
	303	+- Confidence-based filtering (only reports high-confidence issues ≥80)
	304	+
	305	+When triggered:
	306	+- Automatically in Phase 6
	307	+- Can be invoked manually after writing code
	308	+
	309	+Output:
	310	+- Critical issues (confidence 75-100)
	311	+- Important issues (confidence 50-74)
	312	+- Specific fixes with file:line references
	313	+- Project guideline references
	314	+
	315	+## Usage Patterns
	316	+
	317	+### Full workflow (recommended for new features):
	318	+```bash
	319	+/feature-dev Add rate limiting to API endpoints
	320	+```
	321	+
	322	+Let the workflow guide you through all 7 phases.
	323	+
	324	+### Manual agent invocation:
	325	+
	326	+Explore a feature:
	327	+```
	328	+"Launch code-explorer to trace how authentication works"
	329	+```
	330	+
	331	+Design architecture:
	332	+```
	333	+"Launch code-architect to design the caching layer"
	334	+```
	335	+
	336	+Review code:
	337	+```
	338	+"Launch code-reviewer to check my recent changes"
	339	+```
	340	+
	341	+## Best Practices
	342	+
	343	+1. Use the full workflow for complex features: The 7 phases ensure thorough planning
	344	+2. Answer clarifying questions thoughtfully: Phase 3 prevents future confusion
	345	+3. Choose architecture deliberately: Phase 4 gives you options for a reason
	346	+4. Don't skip code review: Phase 6 catches issues before they reach production
	347	+5. Read the suggested files: Phase 2 identifies key files—read them to understand context
	348	+
	349	+## When to Use This Plugin
	350	+
	351	+Use for:
	352	+- New features that touch multiple files
	353	+- Features requiring architectural decisions
	354	+- Complex integrations with existing code
	355	+- Features where requirements are somewhat unclear
	356	+
	357	+Don't use for:
	358	+- Single-line bug fixes
	359	+- Trivial changes
	360	+- Well-defined, simple tasks
	361	+- Urgent hotfixes
	362	+
	363	+## Requirements
	364	+
	365	+- Claude Code installed
	366	+- Git repository (for code review)
	367	+- Project with existing codebase (workflow assumes existing code to learn from)
	368	+
	369	+## Troubleshooting
	370	+
	371	+### Agents take too long
	372	+
	373	+Issue: Code exploration or architecture agents are slow
	374	+
	375	+Solution:
	376	+- This is normal for large codebases
	377	+- Agents run in parallel when possible
	378	+- The thoroughness pays off in better understanding
	379	+
	380	+### Too many clarifying questions
	381	+
	382	+Issue: Phase 3 asks too many questions
	383	+
	384	+Solution:
	385	+- Be more specific in your initial feature request
	386	+- Provide context about constraints upfront
	387	+- Say "whatever you think is best" if truly no preference
	388	+
	389	+### Architecture options overwhelming
	390	+
	391	+Issue: Too many architecture options in Phase 4
	392	+
	393	+Solution:
	394	+- Trust the recommendation—it's based on codebase analysis
	395	+- If still unsure, ask for more explanation
	396	+- Pick the pragmatic option when in doubt
	397	+
	398	+## Tips
	399	+
	400	+- Be specific in your feature request: More detail = fewer clarifying questions
	401	+- Trust the process: Each phase builds on the previous one
	402	+- Review agent outputs: Agents provide valuable insights about your codebase
	403	+- Don't skip phases: Each phase serves a purpose
	404	+- Use for learning: The exploration phase teaches you about your own codebase
	405	+
	406	+## Author
	407	+
	408	+Sid Bidasaria (sbidasaria@anthropic.com)
	409	+
	410	+## Version
	411	+
	412	+1.0.0