@superclaude-org/superflag 3.1.2 → 3.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +20 -20
- package/README.md +466 -466
- package/SUPERFLAG.md +80 -0
- package/dist/install.js +39 -94
- package/dist/install.js.map +1 -1
- package/dist/server.js +3 -3
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/flags.yaml +1509 -270
- package/hooks/superflag.py +192 -192
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,467 +1,467 @@
|
|
|
1
|
-
# SuperFlag
|
|
2
|
-
|
|
3
|
-
> **🚀 TYPESCRIPT MIGRATION COMPLETE**: SuperFlag has been fully migrated to TypeScript/Node.js with MCP support!
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
> **Note**: This project was inspired by the pioneering work in [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) and [SuperGemini Framework](https://github.com/SuperClaude-Org/SuperGemini_Framework). Special thanks to [SuperClaude-Org](https://github.com/SuperClaude-Org) team members [@NomenAK](https://github.com/NomenAK) and [@mithun50](https://github.com/mithun50) whose work made this possible.
|
|
10
|
-
|
|
11
|
-
SuperFlag provides 18 contextual flags that guide AI assistant behavior through precise directives. It exposes an MCP stdio server for seamless integration with modern AI development tools.
|
|
12
|
-
|
|
13
|
-
## Migration Notice
|
|
14
|
-
|
|
15
|
-
**Python version is DEPRECATED** - All users should migrate to the TypeScript version:
|
|
16
|
-
|
|
17
|
-
### For Existing Python Users
|
|
18
|
-
```bash
|
|
19
|
-
# 1. Uninstall old Python version
|
|
20
|
-
superflag uninstall # Remove configurations
|
|
21
|
-
pip uninstall superflag # Remove package
|
|
22
|
-
|
|
23
|
-
# 2. Install new TypeScript version
|
|
24
|
-
npm install -g @superclaude-org/superflag
|
|
25
|
-
superflag install cc # Configure Claude Code
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## Quick Start
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
# Install globally
|
|
32
|
-
npm install -g @superclaude-org/superflag
|
|
33
|
-
|
|
34
|
-
# Interactive installation (choose platforms)
|
|
35
|
-
superflag install
|
|
36
|
-
|
|
37
|
-
# Direct installation for Claude Code
|
|
38
|
-
superflag install cc
|
|
39
|
-
|
|
40
|
-
# MCP server automatically registered during installation
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Then use flags in your AI assistant:
|
|
44
|
-
- "Fix this bug --analyze --strict"
|
|
45
|
-
- "Refactor --auto" (auto-select optimal flags)
|
|
46
|
-
- "--save" (create handoff documentation)
|
|
47
|
-
|
|
48
|
-
## 18 Available Flags
|
|
49
|
-
|
|
50
|
-
| Flag | Purpose |
|
|
51
|
-
|------|---------|
|
|
52
|
-
| `--analyze` | Multi-perspective systematic analysis |
|
|
53
|
-
| `--auto` | AI selects optimal flag combination |
|
|
54
|
-
| `--collab` | Co-develop solutions through trust-based iteration |
|
|
55
|
-
| `--concise` | Minimal, professional communication |
|
|
56
|
-
| `--discover` | Research existing solutions before building |
|
|
57
|
-
| `--explain` | Progressive disclosure explanations |
|
|
58
|
-
| `--git` | Version control best practices |
|
|
59
|
-
| `--lean` | Essential focus only, eliminate waste |
|
|
60
|
-
| `--load` | Load handoff documentation context |
|
|
61
|
-
| `--parallel` | Multi-agent concurrent processing |
|
|
62
|
-
| `--performance` | Speed and efficiency optimization |
|
|
63
|
-
| `--readonly` | Analysis only, no modifications |
|
|
64
|
-
| `--refactor` | Safe code structure improvements |
|
|
65
|
-
| `--reset` | Reset session state, clear flag cache |
|
|
66
|
-
| `--save` | Create handoff documentation |
|
|
67
|
-
| `--seq` | Sequential step-by-step thinking |
|
|
68
|
-
| `--strict` | Zero-error enforcement with transparency |
|
|
69
|
-
| `--todo` | Structured task management |
|
|
70
|
-
|
|
71
|
-
## Installation
|
|
72
|
-
|
|
73
|
-
### Prerequisites
|
|
74
|
-
- Node.js 16+
|
|
75
|
-
- Target platform installed (Claude Code, Gemini CLI, or Continue)
|
|
76
|
-
|
|
77
|
-
### Quick Setup (All Platforms)
|
|
78
|
-
```bash
|
|
79
|
-
# Install package globally
|
|
80
|
-
npm install -g @superclaude-org/superflag
|
|
81
|
-
|
|
82
|
-
# Interactive installation - choose your platforms
|
|
83
|
-
superflag install
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
The interactive installer will:
|
|
87
|
-
- Detect installed platforms
|
|
88
|
-
- Let you select which ones to configure
|
|
89
|
-
- **Automatically register MCP servers** for all platforms
|
|
90
|
-
- Set up configuration files and flag detection
|
|
91
|
-
|
|
92
|
-
### Platform-Specific Installation
|
|
93
|
-
|
|
94
|
-
#### Claude Code
|
|
95
|
-
```bash
|
|
96
|
-
# Direct installation (MCP server auto-registered)
|
|
97
|
-
superflag install cc
|
|
98
|
-
|
|
99
|
-
# Verify connection
|
|
100
|
-
claude mcp list
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Creates:
|
|
104
|
-
- `~/.claude/CLAUDE.md` - References SuperFlag
|
|
105
|
-
- `~/.claude/SUPERFLAG.md` - Flag instructions
|
|
106
|
-
- `~/.claude/hooks/superflag.py` - Flag detection hook
|
|
107
|
-
|
|
108
|
-
**Manual MCP Registration (if auto-registration fails):**
|
|
109
|
-
```bash
|
|
110
|
-
# Add MCP server manually
|
|
111
|
-
claude mcp add superflag npx @superclaude-org/superflag@latest -s user
|
|
112
|
-
|
|
113
|
-
# Or add to ~/.claude.json
|
|
114
|
-
{
|
|
115
|
-
"mcpServers": {
|
|
116
|
-
"superflag": {
|
|
117
|
-
"command": "npx",
|
|
118
|
-
"args": ["@superclaude-org/superflag@latest"],
|
|
119
|
-
"env": {}
|
|
120
|
-
}
|
|
121
|
-
}
|
|
122
|
-
}
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
#### Gemini CLI
|
|
126
|
-
```bash
|
|
127
|
-
# Direct installation (MCP server auto-registered)
|
|
128
|
-
superflag install gemini
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Creates:
|
|
132
|
-
- `~/.gemini/GEMINI.md` - References SuperFlag
|
|
133
|
-
- `~/.gemini/SUPERFLAG.md` - Flag instructions
|
|
134
|
-
|
|
135
|
-
**Manual MCP Registration (if auto-registration fails):**
|
|
136
|
-
```json
|
|
137
|
-
// Edit ~/.gemini/settings.json
|
|
138
|
-
{
|
|
139
|
-
"mcpServers": {
|
|
140
|
-
"superflag": {
|
|
141
|
-
"type": "stdio",
|
|
142
|
-
"command": "npx",
|
|
143
|
-
"args": ["@superclaude-org/superflag@latest"],
|
|
144
|
-
"env": {}
|
|
145
|
-
}
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
#### Continue (VS Code Extension)
|
|
151
|
-
```bash
|
|
152
|
-
# Direct installation (MCP server auto-registered)
|
|
153
|
-
superflag install cn
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
Creates:
|
|
157
|
-
- `~/.continue/config.yaml` - SuperFlag rules
|
|
158
|
-
- `~/.continue/mcpServers/superflag.yaml` - MCP server configuration
|
|
159
|
-
|
|
160
|
-
**Manual MCP Registration (if auto-registration fails):**
|
|
161
|
-
```yaml
|
|
162
|
-
# Create ~/.continue/mcpServers/superflag.yaml
|
|
163
|
-
name: SuperFlag
|
|
164
|
-
command: npx
|
|
165
|
-
args:
|
|
166
|
-
- '@superclaude-org/superflag@latest'
|
|
167
|
-
env: {}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### Batch Installation
|
|
171
|
-
```bash
|
|
172
|
-
# Install for all supported platforms
|
|
173
|
-
superflag install all
|
|
174
|
-
|
|
175
|
-
# Install for specific combinations
|
|
176
|
-
superflag install cc gemini # Claude Code + Gemini CLI
|
|
177
|
-
superflag install cn # Continue only
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
## Usage
|
|
181
|
-
|
|
182
|
-
### Natural Language with Flags
|
|
183
|
-
All platforms support using flags in natural conversation:
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
# Auto mode - AI selects appropriate flags
|
|
187
|
-
"Optimize this code --auto"
|
|
188
|
-
|
|
189
|
-
# Specific flag combinations
|
|
190
|
-
"--analyze --strict" # Thorough analysis with zero-error enforcement
|
|
191
|
-
"--save --explain" # Create documentation with detailed explanations
|
|
192
|
-
"--reset --todo" # Reset session and start task tracking
|
|
193
|
-
|
|
194
|
-
# Sequential workflows
|
|
195
|
-
"Review architecture --discover --analyze --seq"
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
### Platform-Specific Usage
|
|
199
|
-
|
|
200
|
-
#### Claude Code
|
|
201
|
-
```bash
|
|
202
|
-
# Direct chat with flags
|
|
203
|
-
"Fix this bug --analyze --strict"
|
|
204
|
-
"Create documentation --save --explain"
|
|
205
|
-
|
|
206
|
-
# MCP tool access (advanced)
|
|
207
|
-
get_directives(['--flag1', '--flag2'])
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
#### Gemini CLI
|
|
211
|
-
```bash
|
|
212
|
-
# Chat with flags
|
|
213
|
-
"Refactor this code --auto --performance"
|
|
214
|
-
|
|
215
|
-
# MCP server commands
|
|
216
|
-
@superflag --analyze --todo
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
#### Continue (VS Code)
|
|
220
|
-
```bash
|
|
221
|
-
# In Continue chat
|
|
222
|
-
"Optimize this function --performance --lean"
|
|
223
|
-
|
|
224
|
-
# Use @ to access MCP tools
|
|
225
|
-
@get_directives(['--strict', '--analyze'])
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
### Session Management
|
|
229
|
-
- **Duplicate Detection**: Repeated flags show brief reminders instead of full directives
|
|
230
|
-
- **Session Reset**: Use `--reset` when switching tasks or contexts
|
|
231
|
-
- **Persistence**: Flag states persist through `/clear` or `/compact` - use `--reset` to reinitialize
|
|
232
|
-
|
|
233
|
-
## The `--auto` Flag
|
|
234
|
-
|
|
235
|
-
`--auto` enables intelligent flag selection:
|
|
236
|
-
|
|
237
|
-
| Usage | Behavior |
|
|
238
|
-
|-------|----------|
|
|
239
|
-
| `--auto` only | AI selects complete flag set automatically |
|
|
240
|
-
| `--auto --strict --analyze` | AI applies specified flags + may add others |
|
|
241
|
-
| `--strict --analyze` | Only specified flags, no auto-selection |
|
|
242
|
-
|
|
243
|
-
**Note**: Do not include `--auto` in direct `get_directives()` calls - it's for natural language use only.
|
|
244
|
-
|
|
245
|
-
## Configuration Files
|
|
246
|
-
|
|
247
|
-
### Claude Code
|
|
248
|
-
```
|
|
249
|
-
~/.claude/
|
|
250
|
-
├── CLAUDE.md # References @SUPERFLAG.md
|
|
251
|
-
├── SUPERFLAG.md # Flag instructions (auto-updated)
|
|
252
|
-
└── hooks/
|
|
253
|
-
└── superflag.py # Flag detection hook
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
### Gemini CLI
|
|
257
|
-
```
|
|
258
|
-
~/.gemini/
|
|
259
|
-
├── GEMINI.md # References @SUPERFLAG.md
|
|
260
|
-
├── SUPERFLAG.md # Flag instructions (auto-updated)
|
|
261
|
-
└── settings.json # MCP server configuration (auto-registered)
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
### Continue
|
|
265
|
-
```
|
|
266
|
-
~/.continue/
|
|
267
|
-
├── config.yaml # SuperFlag rules and configuration
|
|
268
|
-
└── mcpServers/
|
|
269
|
-
└── superflag.yaml # MCP server settings (auto-registered)
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
### Shared Configuration
|
|
273
|
-
```
|
|
274
|
-
~/.superflag/
|
|
275
|
-
└── flags.yaml # Flag definitions and directives (all platforms)
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
## Configuration File Contents
|
|
279
|
-
|
|
280
|
-
### What Gets Created
|
|
281
|
-
|
|
282
|
-
**~/.claude/CLAUDE.md**
|
|
283
|
-
```markdown
|
|
284
|
-
@SUPERFLAG.md
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
**~/.gemini/GEMINI.md**
|
|
288
|
-
```markdown
|
|
289
|
-
@SUPERFLAG.md
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
**~/.continue/config.yaml**
|
|
293
|
-
```yaml
|
|
294
|
-
rules:
|
|
295
|
-
- title: SuperFlag
|
|
296
|
-
pattern: '--\w+'
|
|
297
|
-
message: >-
|
|
298
|
-
Flag detected. Execute MCP: get_directives([detected_flags])
|
|
299
|
-
|
|
300
|
-
Available: --analyze, --strict, --performance, --refactor, --lean, --discover, --explain, --save, --parallel,
|
|
301
|
-
--todo, --seq, --concise, --git, --readonly, --load, --collab, --reset, --auto
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
**~/.continue/mcpServers/superflag.yaml**
|
|
305
|
-
```yaml
|
|
306
|
-
name: SuperFlag
|
|
307
|
-
command: npx
|
|
308
|
-
args:
|
|
309
|
-
- '@superclaude-org/superflag@latest'
|
|
310
|
-
env: {}
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
**~/.gemini/settings.json** (MCP section)
|
|
314
|
-
```json
|
|
315
|
-
{
|
|
316
|
-
"mcpServers": {
|
|
317
|
-
"superflag": {
|
|
318
|
-
"type": "stdio",
|
|
319
|
-
"command": "npx",
|
|
320
|
-
"args": ["@superclaude-org/superflag@latest"],
|
|
321
|
-
"env": {}
|
|
322
|
-
}
|
|
323
|
-
}
|
|
324
|
-
}
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
**~/.superflag/flags.yaml**
|
|
328
|
-
```yaml
|
|
329
|
-
# Contains all 18 flag definitions and their directives
|
|
330
|
-
# This file is shared across all platforms
|
|
331
|
-
# Auto-updated when SuperFlag package is updated
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
## Development
|
|
335
|
-
|
|
336
|
-
### Local Development
|
|
337
|
-
```bash
|
|
338
|
-
# Clone repository
|
|
339
|
-
git clone <repository>
|
|
340
|
-
cd superflag
|
|
341
|
-
|
|
342
|
-
# Install dependencies
|
|
343
|
-
npm install
|
|
344
|
-
|
|
345
|
-
# Build TypeScript
|
|
346
|
-
npm run build
|
|
347
|
-
|
|
348
|
-
# Test locally
|
|
349
|
-
npm link
|
|
350
|
-
superflag --version
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
### Version Management
|
|
354
|
-
Update version in `src/version.ts` - all other files sync automatically during build.
|
|
355
|
-
|
|
356
|
-
## Uninstallation
|
|
357
|
-
|
|
358
|
-
### Interactive Uninstallation
|
|
359
|
-
```bash
|
|
360
|
-
# Interactive removal - choose platforms to remove
|
|
361
|
-
superflag uninstall
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
### Platform-Specific Removal
|
|
365
|
-
```bash
|
|
366
|
-
# Remove from specific platforms
|
|
367
|
-
superflag uninstall cc # Claude Code only
|
|
368
|
-
superflag uninstall gemini # Gemini CLI only
|
|
369
|
-
superflag uninstall cn # Continue only
|
|
370
|
-
superflag uninstall all # All platforms
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
### Complete Removal
|
|
374
|
-
```bash
|
|
375
|
-
# Remove all configurations and package
|
|
376
|
-
superflag uninstall all
|
|
377
|
-
npm uninstall -g @superclaude-org/superflag
|
|
378
|
-
```
|
|
379
|
-
|
|
380
|
-
**Safety Features:**
|
|
381
|
-
- Configuration files are backed up to `~/flags.yaml.backup_YYYYMMDD_HHMMSS` before removal
|
|
382
|
-
- Interactive confirmation for each platform
|
|
383
|
-
- Selective removal - keep other platforms intact
|
|
384
|
-
|
|
385
|
-
## Migration from Python
|
|
386
|
-
|
|
387
|
-
### What Changed
|
|
388
|
-
- ✅ **Language**: Python → TypeScript/Node.js
|
|
389
|
-
- ✅ **Performance**: Faster startup and execution
|
|
390
|
-
- ✅ **Installation**: `pip` → `npm`
|
|
391
|
-
- ✅ **Dependencies**: No Python runtime required
|
|
392
|
-
- ✅ **MCP Integration**: Native TypeScript MCP support
|
|
393
|
-
|
|
394
|
-
### Breaking Changes
|
|
395
|
-
- Python package completely deprecated
|
|
396
|
-
- `pip install superflag` no longer supported
|
|
397
|
-
- Configuration file locations remain the same
|
|
398
|
-
- Flag behavior and directives unchanged
|
|
399
|
-
|
|
400
|
-
### Migration Steps
|
|
401
|
-
1. **Backup**: Export any custom configurations
|
|
402
|
-
2. **Uninstall**: Remove Python version completely
|
|
403
|
-
3. **Install**: Set up TypeScript version
|
|
404
|
-
4. **Verify**: Test flag functionality
|
|
405
|
-
5. **Cleanup**: Remove Python environments if no longer needed
|
|
406
|
-
|
|
407
|
-
## Troubleshooting
|
|
408
|
-
|
|
409
|
-
### Common Issues
|
|
410
|
-
|
|
411
|
-
**Auto-Registration Failed**
|
|
412
|
-
If MCP server wasn't automatically registered during installation:
|
|
413
|
-
|
|
414
|
-
```bash
|
|
415
|
-
# For Claude Code
|
|
416
|
-
claude mcp add superflag npx @superclaude-org/superflag@latest -s user
|
|
417
|
-
|
|
418
|
-
# For Gemini CLI - manually edit ~/.gemini/settings.json
|
|
419
|
-
{
|
|
420
|
-
"mcpServers": {
|
|
421
|
-
"superflag": {
|
|
422
|
-
"type": "stdio",
|
|
423
|
-
"command": "npx",
|
|
424
|
-
"args": ["@superclaude-org/superflag@latest"],
|
|
425
|
-
"env": {}
|
|
426
|
-
}
|
|
427
|
-
}
|
|
428
|
-
}
|
|
429
|
-
|
|
430
|
-
# For Continue - create ~/.continue/mcpServers/superflag.yaml
|
|
431
|
-
name: SuperFlag
|
|
432
|
-
command: npx
|
|
433
|
-
args:
|
|
434
|
-
- '@superclaude-org/superflag@latest'
|
|
435
|
-
env: {}
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
**MCP Connection Issues**
|
|
439
|
-
```bash
|
|
440
|
-
# Check server status (Claude Code)
|
|
441
|
-
claude mcp list
|
|
442
|
-
|
|
443
|
-
# Re-register if needed
|
|
444
|
-
claude mcp remove superflag
|
|
445
|
-
superflag install cc # Auto-register again
|
|
446
|
-
```
|
|
447
|
-
|
|
448
|
-
**Flags Not Working**
|
|
449
|
-
- Restart your AI platform after installation
|
|
450
|
-
- Verify configuration files exist:
|
|
451
|
-
- Claude Code: `~/.claude/SUPERFLAG.md`
|
|
452
|
-
- Gemini CLI: `~/.gemini/SUPERFLAG.md`
|
|
453
|
-
- Continue: `~/.continue/config.yaml`
|
|
454
|
-
- Check MCP server connection (platform-specific)
|
|
455
|
-
|
|
456
|
-
**Version Conflicts**
|
|
457
|
-
- Ensure Python version is completely removed
|
|
458
|
-
- Use `npm list -g @superclaude-org/superflag` to verify installation
|
|
459
|
-
- Clear platform caches if switching from manual to auto-registration
|
|
460
|
-
|
|
461
|
-
## License
|
|
462
|
-
|
|
463
|
-
MIT
|
|
464
|
-
|
|
465
|
-
---
|
|
466
|
-
|
|
1
|
+
# SuperFlag
|
|
2
|
+
|
|
3
|
+
> **🚀 TYPESCRIPT MIGRATION COMPLETE**: SuperFlag has been fully migrated to TypeScript/Node.js with MCP support!
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
> **Note**: This project was inspired by the pioneering work in [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) and [SuperGemini Framework](https://github.com/SuperClaude-Org/SuperGemini_Framework). Special thanks to [SuperClaude-Org](https://github.com/SuperClaude-Org) team members [@NomenAK](https://github.com/NomenAK) and [@mithun50](https://github.com/mithun50) whose work made this possible.
|
|
10
|
+
|
|
11
|
+
SuperFlag provides 18 contextual flags that guide AI assistant behavior through precise directives. It exposes an MCP stdio server for seamless integration with modern AI development tools.
|
|
12
|
+
|
|
13
|
+
## Migration Notice
|
|
14
|
+
|
|
15
|
+
**Python version is DEPRECATED** - All users should migrate to the TypeScript version:
|
|
16
|
+
|
|
17
|
+
### For Existing Python Users
|
|
18
|
+
```bash
|
|
19
|
+
# 1. Uninstall old Python version
|
|
20
|
+
superflag uninstall # Remove configurations
|
|
21
|
+
pip uninstall superflag # Remove package
|
|
22
|
+
|
|
23
|
+
# 2. Install new TypeScript version
|
|
24
|
+
npm install -g @superclaude-org/superflag
|
|
25
|
+
superflag install cc # Configure Claude Code
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Quick Start
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# Install globally
|
|
32
|
+
npm install -g @superclaude-org/superflag
|
|
33
|
+
|
|
34
|
+
# Interactive installation (choose platforms)
|
|
35
|
+
superflag install
|
|
36
|
+
|
|
37
|
+
# Direct installation for Claude Code
|
|
38
|
+
superflag install cc
|
|
39
|
+
|
|
40
|
+
# MCP server automatically registered during installation
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Then use flags in your AI assistant:
|
|
44
|
+
- "Fix this bug --analyze --strict"
|
|
45
|
+
- "Refactor --auto" (auto-select optimal flags)
|
|
46
|
+
- "--save" (create handoff documentation)
|
|
47
|
+
|
|
48
|
+
## 18 Available Flags
|
|
49
|
+
|
|
50
|
+
| Flag | Purpose |
|
|
51
|
+
|------|---------|
|
|
52
|
+
| `--analyze` | Multi-perspective systematic analysis |
|
|
53
|
+
| `--auto` | AI selects optimal flag combination |
|
|
54
|
+
| `--collab` | Co-develop solutions through trust-based iteration |
|
|
55
|
+
| `--concise` | Minimal, professional communication |
|
|
56
|
+
| `--discover` | Research existing solutions before building |
|
|
57
|
+
| `--explain` | Progressive disclosure explanations |
|
|
58
|
+
| `--git` | Version control best practices |
|
|
59
|
+
| `--lean` | Essential focus only, eliminate waste |
|
|
60
|
+
| `--load` | Load handoff documentation context |
|
|
61
|
+
| `--parallel` | Multi-agent concurrent processing |
|
|
62
|
+
| `--performance` | Speed and efficiency optimization |
|
|
63
|
+
| `--readonly` | Analysis only, no modifications |
|
|
64
|
+
| `--refactor` | Safe code structure improvements |
|
|
65
|
+
| `--reset` | Reset session state, clear flag cache |
|
|
66
|
+
| `--save` | Create handoff documentation |
|
|
67
|
+
| `--seq` | Sequential step-by-step thinking |
|
|
68
|
+
| `--strict` | Zero-error enforcement with transparency |
|
|
69
|
+
| `--todo` | Structured task management |
|
|
70
|
+
|
|
71
|
+
## Installation
|
|
72
|
+
|
|
73
|
+
### Prerequisites
|
|
74
|
+
- Node.js 16+
|
|
75
|
+
- Target platform installed (Claude Code, Gemini CLI, or Continue)
|
|
76
|
+
|
|
77
|
+
### Quick Setup (All Platforms)
|
|
78
|
+
```bash
|
|
79
|
+
# Install package globally
|
|
80
|
+
npm install -g @superclaude-org/superflag
|
|
81
|
+
|
|
82
|
+
# Interactive installation - choose your platforms
|
|
83
|
+
superflag install
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The interactive installer will:
|
|
87
|
+
- Detect installed platforms
|
|
88
|
+
- Let you select which ones to configure
|
|
89
|
+
- **Automatically register MCP servers** for all platforms
|
|
90
|
+
- Set up configuration files and flag detection
|
|
91
|
+
|
|
92
|
+
### Platform-Specific Installation
|
|
93
|
+
|
|
94
|
+
#### Claude Code
|
|
95
|
+
```bash
|
|
96
|
+
# Direct installation (MCP server auto-registered)
|
|
97
|
+
superflag install cc
|
|
98
|
+
|
|
99
|
+
# Verify connection
|
|
100
|
+
claude mcp list
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Creates:
|
|
104
|
+
- `~/.claude/CLAUDE.md` - References SuperFlag
|
|
105
|
+
- `~/.claude/SUPERFLAG.md` - Flag instructions
|
|
106
|
+
- `~/.claude/hooks/superflag.py` - Flag detection hook
|
|
107
|
+
|
|
108
|
+
**Manual MCP Registration (if auto-registration fails):**
|
|
109
|
+
```bash
|
|
110
|
+
# Add MCP server manually
|
|
111
|
+
claude mcp add superflag npx @superclaude-org/superflag@latest -s user
|
|
112
|
+
|
|
113
|
+
# Or add to ~/.claude.json
|
|
114
|
+
{
|
|
115
|
+
"mcpServers": {
|
|
116
|
+
"superflag": {
|
|
117
|
+
"command": "npx",
|
|
118
|
+
"args": ["@superclaude-org/superflag@latest"],
|
|
119
|
+
"env": {}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
#### Gemini CLI
|
|
126
|
+
```bash
|
|
127
|
+
# Direct installation (MCP server auto-registered)
|
|
128
|
+
superflag install gemini
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Creates:
|
|
132
|
+
- `~/.gemini/GEMINI.md` - References SuperFlag
|
|
133
|
+
- `~/.gemini/SUPERFLAG.md` - Flag instructions
|
|
134
|
+
|
|
135
|
+
**Manual MCP Registration (if auto-registration fails):**
|
|
136
|
+
```json
|
|
137
|
+
// Edit ~/.gemini/settings.json
|
|
138
|
+
{
|
|
139
|
+
"mcpServers": {
|
|
140
|
+
"superflag": {
|
|
141
|
+
"type": "stdio",
|
|
142
|
+
"command": "npx",
|
|
143
|
+
"args": ["@superclaude-org/superflag@latest"],
|
|
144
|
+
"env": {}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
#### Continue (VS Code Extension)
|
|
151
|
+
```bash
|
|
152
|
+
# Direct installation (MCP server auto-registered)
|
|
153
|
+
superflag install cn
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Creates:
|
|
157
|
+
- `~/.continue/config.yaml` - SuperFlag rules
|
|
158
|
+
- `~/.continue/mcpServers/superflag.yaml` - MCP server configuration
|
|
159
|
+
|
|
160
|
+
**Manual MCP Registration (if auto-registration fails):**
|
|
161
|
+
```yaml
|
|
162
|
+
# Create ~/.continue/mcpServers/superflag.yaml
|
|
163
|
+
name: SuperFlag
|
|
164
|
+
command: npx
|
|
165
|
+
args:
|
|
166
|
+
- '@superclaude-org/superflag@latest'
|
|
167
|
+
env: {}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Batch Installation
|
|
171
|
+
```bash
|
|
172
|
+
# Install for all supported platforms
|
|
173
|
+
superflag install all
|
|
174
|
+
|
|
175
|
+
# Install for specific combinations
|
|
176
|
+
superflag install cc gemini # Claude Code + Gemini CLI
|
|
177
|
+
superflag install cn # Continue only
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Usage
|
|
181
|
+
|
|
182
|
+
### Natural Language with Flags
|
|
183
|
+
All platforms support using flags in natural conversation:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
# Auto mode - AI selects appropriate flags
|
|
187
|
+
"Optimize this code --auto"
|
|
188
|
+
|
|
189
|
+
# Specific flag combinations
|
|
190
|
+
"--analyze --strict" # Thorough analysis with zero-error enforcement
|
|
191
|
+
"--save --explain" # Create documentation with detailed explanations
|
|
192
|
+
"--reset --todo" # Reset session and start task tracking
|
|
193
|
+
|
|
194
|
+
# Sequential workflows
|
|
195
|
+
"Review architecture --discover --analyze --seq"
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Platform-Specific Usage
|
|
199
|
+
|
|
200
|
+
#### Claude Code
|
|
201
|
+
```bash
|
|
202
|
+
# Direct chat with flags
|
|
203
|
+
"Fix this bug --analyze --strict"
|
|
204
|
+
"Create documentation --save --explain"
|
|
205
|
+
|
|
206
|
+
# MCP tool access (advanced)
|
|
207
|
+
get_directives(['--flag1', '--flag2'])
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
#### Gemini CLI
|
|
211
|
+
```bash
|
|
212
|
+
# Chat with flags
|
|
213
|
+
"Refactor this code --auto --performance"
|
|
214
|
+
|
|
215
|
+
# MCP server commands
|
|
216
|
+
@superflag --analyze --todo
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
#### Continue (VS Code)
|
|
220
|
+
```bash
|
|
221
|
+
# In Continue chat
|
|
222
|
+
"Optimize this function --performance --lean"
|
|
223
|
+
|
|
224
|
+
# Use @ to access MCP tools
|
|
225
|
+
@get_directives(['--strict', '--analyze'])
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Session Management
|
|
229
|
+
- **Duplicate Detection**: Repeated flags show brief reminders instead of full directives
|
|
230
|
+
- **Session Reset**: Use `--reset` when switching tasks or contexts
|
|
231
|
+
- **Persistence**: Flag states persist through `/clear` or `/compact` - use `--reset` to reinitialize
|
|
232
|
+
|
|
233
|
+
## The `--auto` Flag
|
|
234
|
+
|
|
235
|
+
`--auto` enables intelligent flag selection:
|
|
236
|
+
|
|
237
|
+
| Usage | Behavior |
|
|
238
|
+
|-------|----------|
|
|
239
|
+
| `--auto` only | AI selects complete flag set automatically |
|
|
240
|
+
| `--auto --strict --analyze` | AI applies specified flags + may add others |
|
|
241
|
+
| `--strict --analyze` | Only specified flags, no auto-selection |
|
|
242
|
+
|
|
243
|
+
**Note**: Do not include `--auto` in direct `get_directives()` calls - it's for natural language use only.
|
|
244
|
+
|
|
245
|
+
## Configuration Files
|
|
246
|
+
|
|
247
|
+
### Claude Code
|
|
248
|
+
```
|
|
249
|
+
~/.claude/
|
|
250
|
+
├── CLAUDE.md # References @SUPERFLAG.md
|
|
251
|
+
├── SUPERFLAG.md # Flag instructions (auto-updated)
|
|
252
|
+
└── hooks/
|
|
253
|
+
└── superflag.py # Flag detection hook
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Gemini CLI
|
|
257
|
+
```
|
|
258
|
+
~/.gemini/
|
|
259
|
+
├── GEMINI.md # References @SUPERFLAG.md
|
|
260
|
+
├── SUPERFLAG.md # Flag instructions (auto-updated)
|
|
261
|
+
└── settings.json # MCP server configuration (auto-registered)
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
### Continue
|
|
265
|
+
```
|
|
266
|
+
~/.continue/
|
|
267
|
+
├── config.yaml # SuperFlag rules and configuration
|
|
268
|
+
└── mcpServers/
|
|
269
|
+
└── superflag.yaml # MCP server settings (auto-registered)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### Shared Configuration
|
|
273
|
+
```
|
|
274
|
+
~/.superflag/
|
|
275
|
+
└── flags.yaml # Flag definitions and directives (all platforms)
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
## Configuration File Contents
|
|
279
|
+
|
|
280
|
+
### What Gets Created
|
|
281
|
+
|
|
282
|
+
**~/.claude/CLAUDE.md**
|
|
283
|
+
```markdown
|
|
284
|
+
@SUPERFLAG.md
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**~/.gemini/GEMINI.md**
|
|
288
|
+
```markdown
|
|
289
|
+
@SUPERFLAG.md
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
**~/.continue/config.yaml**
|
|
293
|
+
```yaml
|
|
294
|
+
rules:
|
|
295
|
+
- title: SuperFlag
|
|
296
|
+
pattern: '--\w+'
|
|
297
|
+
message: >-
|
|
298
|
+
Flag detected. Execute MCP: get_directives([detected_flags])
|
|
299
|
+
|
|
300
|
+
Available: --analyze, --strict, --performance, --refactor, --lean, --discover, --explain, --save, --parallel,
|
|
301
|
+
--todo, --seq, --concise, --git, --readonly, --load, --collab, --reset, --auto
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
**~/.continue/mcpServers/superflag.yaml**
|
|
305
|
+
```yaml
|
|
306
|
+
name: SuperFlag
|
|
307
|
+
command: npx
|
|
308
|
+
args:
|
|
309
|
+
- '@superclaude-org/superflag@latest'
|
|
310
|
+
env: {}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
**~/.gemini/settings.json** (MCP section)
|
|
314
|
+
```json
|
|
315
|
+
{
|
|
316
|
+
"mcpServers": {
|
|
317
|
+
"superflag": {
|
|
318
|
+
"type": "stdio",
|
|
319
|
+
"command": "npx",
|
|
320
|
+
"args": ["@superclaude-org/superflag@latest"],
|
|
321
|
+
"env": {}
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
**~/.superflag/flags.yaml**
|
|
328
|
+
```yaml
|
|
329
|
+
# Contains all 18 flag definitions and their directives
|
|
330
|
+
# This file is shared across all platforms
|
|
331
|
+
# Auto-updated when SuperFlag package is updated
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
## Development
|
|
335
|
+
|
|
336
|
+
### Local Development
|
|
337
|
+
```bash
|
|
338
|
+
# Clone repository
|
|
339
|
+
git clone <repository>
|
|
340
|
+
cd superflag
|
|
341
|
+
|
|
342
|
+
# Install dependencies
|
|
343
|
+
npm install
|
|
344
|
+
|
|
345
|
+
# Build TypeScript
|
|
346
|
+
npm run build
|
|
347
|
+
|
|
348
|
+
# Test locally
|
|
349
|
+
npm link
|
|
350
|
+
superflag --version
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
### Version Management
|
|
354
|
+
Update version in `src/version.ts` - all other files sync automatically during build.
|
|
355
|
+
|
|
356
|
+
## Uninstallation
|
|
357
|
+
|
|
358
|
+
### Interactive Uninstallation
|
|
359
|
+
```bash
|
|
360
|
+
# Interactive removal - choose platforms to remove
|
|
361
|
+
superflag uninstall
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### Platform-Specific Removal
|
|
365
|
+
```bash
|
|
366
|
+
# Remove from specific platforms
|
|
367
|
+
superflag uninstall cc # Claude Code only
|
|
368
|
+
superflag uninstall gemini # Gemini CLI only
|
|
369
|
+
superflag uninstall cn # Continue only
|
|
370
|
+
superflag uninstall all # All platforms
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
### Complete Removal
|
|
374
|
+
```bash
|
|
375
|
+
# Remove all configurations and package
|
|
376
|
+
superflag uninstall all
|
|
377
|
+
npm uninstall -g @superclaude-org/superflag
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
**Safety Features:**
|
|
381
|
+
- Configuration files are backed up to `~/flags.yaml.backup_YYYYMMDD_HHMMSS` before removal
|
|
382
|
+
- Interactive confirmation for each platform
|
|
383
|
+
- Selective removal - keep other platforms intact
|
|
384
|
+
|
|
385
|
+
## Migration from Python
|
|
386
|
+
|
|
387
|
+
### What Changed
|
|
388
|
+
- ✅ **Language**: Python → TypeScript/Node.js
|
|
389
|
+
- ✅ **Performance**: Faster startup and execution
|
|
390
|
+
- ✅ **Installation**: `pip` → `npm`
|
|
391
|
+
- ✅ **Dependencies**: No Python runtime required
|
|
392
|
+
- ✅ **MCP Integration**: Native TypeScript MCP support
|
|
393
|
+
|
|
394
|
+
### Breaking Changes
|
|
395
|
+
- Python package completely deprecated
|
|
396
|
+
- `pip install superflag` no longer supported
|
|
397
|
+
- Configuration file locations remain the same
|
|
398
|
+
- Flag behavior and directives unchanged
|
|
399
|
+
|
|
400
|
+
### Migration Steps
|
|
401
|
+
1. **Backup**: Export any custom configurations
|
|
402
|
+
2. **Uninstall**: Remove Python version completely
|
|
403
|
+
3. **Install**: Set up TypeScript version
|
|
404
|
+
4. **Verify**: Test flag functionality
|
|
405
|
+
5. **Cleanup**: Remove Python environments if no longer needed
|
|
406
|
+
|
|
407
|
+
## Troubleshooting
|
|
408
|
+
|
|
409
|
+
### Common Issues
|
|
410
|
+
|
|
411
|
+
**Auto-Registration Failed**
|
|
412
|
+
If MCP server wasn't automatically registered during installation:
|
|
413
|
+
|
|
414
|
+
```bash
|
|
415
|
+
# For Claude Code
|
|
416
|
+
claude mcp add superflag npx @superclaude-org/superflag@latest -s user
|
|
417
|
+
|
|
418
|
+
# For Gemini CLI - manually edit ~/.gemini/settings.json
|
|
419
|
+
{
|
|
420
|
+
"mcpServers": {
|
|
421
|
+
"superflag": {
|
|
422
|
+
"type": "stdio",
|
|
423
|
+
"command": "npx",
|
|
424
|
+
"args": ["@superclaude-org/superflag@latest"],
|
|
425
|
+
"env": {}
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
# For Continue - create ~/.continue/mcpServers/superflag.yaml
|
|
431
|
+
name: SuperFlag
|
|
432
|
+
command: npx
|
|
433
|
+
args:
|
|
434
|
+
- '@superclaude-org/superflag@latest'
|
|
435
|
+
env: {}
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
**MCP Connection Issues**
|
|
439
|
+
```bash
|
|
440
|
+
# Check server status (Claude Code)
|
|
441
|
+
claude mcp list
|
|
442
|
+
|
|
443
|
+
# Re-register if needed
|
|
444
|
+
claude mcp remove superflag
|
|
445
|
+
superflag install cc # Auto-register again
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
**Flags Not Working**
|
|
449
|
+
- Restart your AI platform after installation
|
|
450
|
+
- Verify configuration files exist:
|
|
451
|
+
- Claude Code: `~/.claude/SUPERFLAG.md`
|
|
452
|
+
- Gemini CLI: `~/.gemini/SUPERFLAG.md`
|
|
453
|
+
- Continue: `~/.continue/config.yaml`
|
|
454
|
+
- Check MCP server connection (platform-specific)
|
|
455
|
+
|
|
456
|
+
**Version Conflicts**
|
|
457
|
+
- Ensure Python version is completely removed
|
|
458
|
+
- Use `npm list -g @superclaude-org/superflag` to verify installation
|
|
459
|
+
- Clear platform caches if switching from manual to auto-registration
|
|
460
|
+
|
|
461
|
+
## License
|
|
462
|
+
|
|
463
|
+
MIT
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
467
|
**Need Help?** File issues at: [GitHub Repository](https://github.com/superclaude-org/superflag)
|