Skip to content

Commit 3f30b85

Browse files
amondnetamondnet
authored
feat: add Firebase and Postgres plugins with documentation (#6)
Add Firebase and Postgres plugins as git submodules: - Firebase plugin: prototype, build & run modern apps with Firebase backend, AI, and operational infrastructure - Postgres plugin: database integration Update plugin infrastructure: - Add Firebase plugin to marketplace.json with Google as author - Add comprehensive Claude Code plugin reference documentation (docs/plugins.md) - Update CLAUDE.md to reference plugin documentation - Configure git submodules for both plugins The Firebase plugin includes Google author attribution and maintains compatibility with both Gemini CLI and Claude Code through MCP server integration.
1 parent bf6b6fa commit 3f30b85

7 files changed

Lines changed: 361 additions & 0 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,15 @@
4848
"source": "github",
4949
"repo": "pleaseai/security-plugin"
5050
}
51+
},
52+
{
53+
"name": "firebase",
54+
"description": "Prototype, build & run modern apps users love with Firebase's backend, AI, and operational infrastructure.",
55+
"author": "Google",
56+
"source": {
57+
"source": "github",
58+
"repo": "pleaseai/firebase-plugin"
59+
}
5160
}
5261
]
5362
}

‎.gitmodules‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,9 @@
1313
[submodule "plugins/spec-kit"]
1414
path = plugins/spec-kit
1515
url = git@github.com:pleaseai/spec-kit-plugin.git
16+
[submodule "plugins/postgres"]
17+
path = plugins/postgres
18+
url = git@github.com:pleaseai/postgres-plugin.git
19+
[submodule "plugins/firebase"]
20+
path = plugins/firebase
21+
url = git@github.com:pleaseai/firebase-plugin.git

‎.idea/forwardedPorts.xml‎

Lines changed: 6 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,7 @@ This project follows strict development standards documented in:
114114
- @docs/STANDARDS.md
115115
- @docs/TDD.md
116116
- @docs/TESTING.md
117+
- @docs/plugins.md - Complete Claude Code plugin reference (manifest schema, components, development tools)
117118

118119
## Plugin Installation
119120

‎docs/plugins.md‎

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
# Plugins reference
2+
3+
> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.
4+
5+
<Tip>
6+
For hands-on tutorials and practical usage, see [Plugins](/en/docs/claude-code/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).
7+
</Tip>
8+
9+
This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.
10+
11+
## Plugin components reference
12+
13+
This section documents the four types of components that plugins can provide.
14+
15+
### Commands
16+
17+
Plugins add custom slash commands that integrate seamlessly with Claude Code's command system.
18+
19+
**Location**: `commands/` directory in plugin root
20+
21+
**File format**: Markdown files with frontmatter
22+
23+
For complete details on plugin command structure, invocation patterns, and features, see [Plugin commands](/en/docs/claude-code/slash-commands#plugin-commands).
24+
25+
### Agents
26+
27+
Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.
28+
29+
**Location**: `agents/` directory in plugin root
30+
31+
**File format**: Markdown files describing agent capabilities
32+
33+
**Agent structure**:
34+
35+
```markdown theme={null}
36+
---
37+
description: What this agent specializes in
38+
capabilities: ["task1", "task2", "task3"]
39+
---
40+
41+
# Agent Name
42+
43+
Detailed description of the agent's role, expertise, and when Claude should invoke it.
44+
45+
## Capabilities
46+
- Specific task the agent excels at
47+
- Another specialized capability
48+
- When to use this agent vs others
49+
50+
## Context and examples
51+
Provide examples of when this agent should be used and what kinds of problems it solves.
52+
```
53+
54+
**Integration points**:
55+
56+
* Agents appear in the `/agents` interface
57+
* Claude can invoke agents automatically based on task context
58+
* Agents can be invoked manually by users
59+
* Plugin agents work alongside built-in Claude agents
60+
61+
### Hooks
62+
63+
Plugins can provide event handlers that respond to Claude Code events automatically.
64+
65+
**Location**: `hooks/hooks.json` in plugin root, or inline in plugin.json
66+
67+
**Format**: JSON configuration with event matchers and actions
68+
69+
**Hook configuration**:
70+
71+
```json theme={null}
72+
{
73+
"hooks": {
74+
"PostToolUse": [
75+
{
76+
"matcher": "Write|Edit",
77+
"hooks": [
78+
{
79+
"type": "command",
80+
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
81+
}
82+
]
83+
}
84+
]
85+
}
86+
}
87+
```
88+
89+
**Available events**:
90+
91+
* `PreToolUse`: Before Claude uses any tool
92+
* `PostToolUse`: After Claude uses any tool
93+
* `UserPromptSubmit`: When user submits a prompt
94+
* `Notification`: When Claude Code sends notifications
95+
* `Stop`: When Claude attempts to stop
96+
* `SubagentStop`: When a subagent attempts to stop
97+
* `SessionStart`: At the beginning of sessions
98+
* `SessionEnd`: At the end of sessions
99+
* `PreCompact`: Before conversation history is compacted
100+
101+
**Hook types**:
102+
103+
* `command`: Execute shell commands or scripts
104+
* `validation`: Validate file contents or project state
105+
* `notification`: Send alerts or status updates
106+
107+
### MCP servers
108+
109+
Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools and services.
110+
111+
**Location**: `.mcp.json` in plugin root, or inline in plugin.json
112+
113+
**Format**: Standard MCP server configuration
114+
115+
**MCP server configuration**:
116+
117+
```json theme={null}
118+
{
119+
"mcpServers": {
120+
"plugin-database": {
121+
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
122+
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
123+
"env": {
124+
"DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
125+
}
126+
},
127+
"plugin-api-client": {
128+
"command": "npx",
129+
"args": ["@company/mcp-server", "--plugin-mode"],
130+
"cwd": "${CLAUDE_PLUGIN_ROOT}"
131+
}
132+
}
133+
}
134+
```
135+
136+
**Integration behavior**:
137+
138+
* Plugin MCP servers start automatically when the plugin is enabled
139+
* Servers appear as standard MCP tools in Claude's toolkit
140+
* Server capabilities integrate seamlessly with Claude's existing tools
141+
* Plugin servers can be configured independently of user MCP servers
142+
143+
***
144+
145+
## Plugin manifest schema
146+
147+
The `plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options.
148+
149+
### Complete schema
150+
151+
```json theme={null}
152+
{
153+
"name": "plugin-name",
154+
"version": "1.2.0",
155+
"description": "Brief plugin description",
156+
"author": {
157+
"name": "Author Name",
158+
"email": "author@example.com",
159+
"url": "https://github.com/author"
160+
},
161+
"homepage": "https://docs.example.com/plugin",
162+
"repository": "https://github.com/author/plugin",
163+
"license": "MIT",
164+
"keywords": ["keyword1", "keyword2"],
165+
"commands": ["./custom/commands/special.md"],
166+
"agents": "./custom/agents/",
167+
"hooks": "./config/hooks.json",
168+
"mcpServers": "./mcp-config.json"
169+
}
170+
```
171+
172+
### Required fields
173+
174+
| Field | Type | Description | Example |
175+
| :----- | :----- | :---------------------------------------- | :------------------- |
176+
| `name` | string | Unique identifier (kebab-case, no spaces) | `"deployment-tools"` |
177+
178+
### Metadata fields
179+
180+
| Field | Type | Description | Example |
181+
| :------------ | :----- | :---------------------------------- | :------------------------------------------------- |
182+
| `version` | string | Semantic version | `"2.1.0"` |
183+
| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` |
184+
| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` |
185+
| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
186+
| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
187+
| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
188+
| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
189+
190+
### Component path fields
191+
192+
| Field | Type | Description | Example |
193+
| :----------- | :------------- | :----------------------------------- | :------------------------------------- |
194+
| `commands` | string\|array | Additional command files/directories | `"./custom/cmd.md"` or `["./cmd1.md"]` |
195+
| `agents` | string\|array | Additional agent files | `"./custom/agents/"` |
196+
| `hooks` | string\|object | Hook config path or inline config | `"./hooks.json"` |
197+
| `mcpServers` | string\|object | MCP config path or inline config | `"./mcp.json"` |
198+
199+
### Path behavior rules
200+
201+
**Important**: Custom paths supplement default directories - they don't replace them.
202+
203+
* If `commands/` exists, it's loaded in addition to custom command paths
204+
* All paths must be relative to plugin root and start with `./`
205+
* Commands from custom paths use the same naming and namespacing rules
206+
* Multiple paths can be specified as arrays for flexibility
207+
208+
**Path examples**:
209+
210+
```json theme={null}
211+
{
212+
"commands": [
213+
"./specialized/deploy.md",
214+
"./utilities/batch-process.md"
215+
],
216+
"agents": [
217+
"./custom-agents/reviewer.md",
218+
"./custom-agents/tester.md"
219+
]
220+
}
221+
```
222+
223+
### Environment variables
224+
225+
**`${CLAUDE_PLUGIN_ROOT}`**: Contains the absolute path to your plugin directory. Use this in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.
226+
227+
```json theme={null}
228+
{
229+
"hooks": {
230+
"PostToolUse": [
231+
{
232+
"hooks": [
233+
{
234+
"type": "command",
235+
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
236+
}
237+
]
238+
}
239+
]
240+
}
241+
}
242+
```
243+
244+
***
245+
246+
## Plugin directory structure
247+
248+
### Standard plugin layout
249+
250+
A complete plugin follows this structure:
251+
252+
```
253+
enterprise-plugin/
254+
├── .claude-plugin/ # Metadata directory
255+
│ └── plugin.json # Required: plugin manifest
256+
├── commands/ # Default command location
257+
│ ├── status.md
258+
│ └── logs.md
259+
├── agents/ # Default agent location
260+
│ ├── security-reviewer.md
261+
│ ├── performance-tester.md
262+
│ └── compliance-checker.md
263+
├── hooks/ # Hook configurations
264+
│ ├── hooks.json # Main hook config
265+
│ └── security-hooks.json # Additional hooks
266+
├── .mcp.json # MCP server definitions
267+
├── scripts/ # Hook and utility scripts
268+
│ ├── security-scan.sh
269+
│ ├── format-code.py
270+
│ └── deploy.js
271+
├── LICENSE # License file
272+
└── CHANGELOG.md # Version history
273+
```
274+
275+
<Warning>
276+
The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.
277+
</Warning>
278+
279+
### File locations reference
280+
281+
| Component | Default Location | Purpose |
282+
| :-------------- | :--------------------------- | :--------------------------- |
283+
| **Manifest** | `.claude-plugin/plugin.json` | Required metadata file |
284+
| **Commands** | `commands/` | Slash command markdown files |
285+
| **Agents** | `agents/` | Subagent markdown files |
286+
| **Hooks** | `hooks/hooks.json` | Hook configuration |
287+
| **MCP servers** | `.mcp.json` | MCP server definitions |
288+
289+
***
290+
291+
## Debugging and development tools
292+
293+
### Debugging commands
294+
295+
Use `claude --debug` to see plugin loading details:
296+
297+
```bash theme={null}
298+
claude --debug
299+
```
300+
301+
This shows:
302+
303+
* Which plugins are being loaded
304+
* Any errors in plugin manifests
305+
* Command, agent, and hook registration
306+
* MCP server initialization
307+
308+
### Common issues
309+
310+
| Issue | Cause | Solution |
311+
| :--------------------- | :------------------------------ | :--------------------------------------------------- |
312+
| Plugin not loading | Invalid `plugin.json` | Validate JSON syntax |
313+
| Commands not appearing | Wrong directory structure | Ensure `commands/` at root, not in `.claude-plugin/` |
314+
| Hooks not firing | Script not executable | Run `chmod +x script.sh` |
315+
| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |
316+
| Path errors | Absolute paths used | All paths must be relative and start with `./` |
317+
318+
***
319+
320+
## Distribution and versioning reference
321+
322+
### Version management
323+
324+
Follow semantic versioning for plugin releases:
325+
326+
```json theme={null}
327+
328+
## See also
329+
330+
- [Plugins](/en/docs/claude-code/plugins) - Tutorials and practical usage
331+
- [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces) - Creating and managing marketplaces
332+
- [Slash commands](/en/docs/claude-code/slash-commands) - Command development details
333+
- [Subagents](/en/docs/claude-code/sub-agents) - Agent configuration and capabilities
334+
- [Hooks](/en/docs/claude-code/hooks) - Event handling and automation
335+
- [MCP](/en/docs/claude-code/mcp) - External tool integration
336+
- [Settings](/en/docs/claude-code/settings) - Configuration options for plugins
337+
```

‎plugins/firebase‎

Submodule firebase added at 997151b

‎plugins/postgres‎

Submodule postgres added at b34ba64

0 commit comments

Comments
 (0)