superkit-mcp-server 1.1.3 → 1.2.0

package/SUPERKIT.md

@@ -8,10 +8,10 @@ You are an AI assistant that analyzes user requirements, assigns tasks to suitab
 
 ## Workflows
 
-- Primary workflow: `./.agent/workflows/primary-workflow.md`
-- Development rules: `./.agent/workflows/development-rules.md`
-- Orchestration protocols: `./.agent/workflows/orchestration-protocol.md`
-- Documentation management: `./.agent/workflows/documentation-management.md`
+- Primary workflow: `./skills/workflows/primary-workflow.md`
+- Development rules: `./skills/workflows/development-rules.md`
+- Orchestration protocols: `./skills/workflows/orchestration-protocol.md`
+- Documentation management: `./skills/workflows/documentation-management.md`
 
 ## Team Members
 

package/build/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import * as path from "path";
 import * as fs from "fs/promises";
+import * as toml from "@iarna/toml";
 import { fileURLToPath } from "url";
 import { manageAutoPreview } from "./tools/autoPreview.js";
 import { manageSession } from "./tools/sessionManager.js";
@@ -254,19 +255,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
     try {
-        const workflowsPath = path.join(superKitRoot, "workflows");
-        const workflows = await fs.readdir(workflowsPath);
+        const commandsPath = path.join(superKitRoot, "commands");
+        const commandsFiles = await fs.readdir(commandsPath);
         const prompts = [];
-        for (const file of workflows) {
-            if (file.endsWith(".md")) {
-                const filePath = path.join(workflowsPath, file);
+        for (const file of commandsFiles) {
+            if (file.endsWith(".toml")) {
+                const filePath = path.join(commandsPath, file);
                 const content = await fs.readFile(filePath, "utf-8");
-                const descriptionMatch = content.match(/description:\s*(.+)/);
-                const description = descriptionMatch ? descriptionMatch[1].trim() : `Workflow ${file}`;
-                prompts.push({
-                    name: file.replace(".md", ""),
-                    description: description,
-                });
+                try {
+                    const parsed = toml.parse(content);
+                    const description = parsed?.description || `Command ${file}`;
+                    prompts.push({
+                        name: file.replace(".toml", ""),
+                        description: description,
+                    });
+                }
+                catch (e) {
+                    console.error(`Failed to parse TOML ${file}:`, e);
+                }
             }
         }
         return { prompts };
@@ -278,29 +284,31 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
 });
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     const promptName = request.params.name;
-    const workflowFile = `${promptName}.md`;
-    const basePath = path.join(superKitRoot, "workflows");
-    const safePath = getSafePath(basePath, workflowFile);
+    const commandFile = `${promptName}.toml`;
+    const basePath = path.join(superKitRoot, "commands");
+    const safePath = getSafePath(basePath, commandFile);
     if (!safePath) {
         throw new Error("Invalid prompt requested");
     }
     try {
         const content = await fs.readFile(safePath, "utf-8");
+        const parsed = toml.parse(content);
+        const promptText = parsed?.prompt || `Execute the ${promptName} command.`;
         return {
-            description: `Loaded workflow: ${promptName}`,
+            description: parsed?.description || `Loaded command: ${promptName}`,
             messages: [
                 {
                     role: "user",
                     content: {
                         type: "text",
-                        text: content,
+                        text: promptText,
                     },
                 },
             ],
         };
     }
     catch (error) {
-        throw new Error(`Prompt not found: ${promptName}`);
+        throw new Error(`Prompt not found or invalid format: ${promptName}`);
     }
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -417,11 +425,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const agentsPath = path.join(superKitRoot, "agents");
             const skillsTechPath = path.join(superKitRoot, "skills", "tech");
             const skillsMetaPath = path.join(superKitRoot, "skills", "meta");
-            const workflowsPath = path.join(superKitRoot, "workflows");
+            const workflowsPath = path.join(superKitRoot, "skills", "workflows");
+            const commandsPath = path.join(superKitRoot, "commands");
             const agents = await listDirectorySafe(agentsPath);
             const techSkills = await listDirectorySafe(skillsTechPath);
             const metaSkills = await listDirectorySafe(skillsMetaPath);
             const workflows = await listDirectorySafe(workflowsPath);
+            const commands = await listDirectorySafe(commandsPath);
             return {
                 content: [
                     {
@@ -433,6 +443,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 meta: metaSkills.map((s) => s.replace("/", "")),
                             },
                             workflows: workflows.map((w) => w.replace(".md", "")),
+                            commands: commands.map((c) => c.replace(".toml", "")),
                         }, null, 2),
                     },
                 ],
@@ -477,7 +488,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (!args.workflowName)
                 throw new Error("Missing workflowName");
             const workflowFile = `${args.workflowName}.md`;
-            const baseDir = path.join(superKitRoot, "workflows");
+            const baseDir = path.join(superKitRoot, "skills", "workflows");
             const safePath = getSafePath(baseDir, workflowFile);
             if (!safePath)
                 throw new Error("Invalid workflow path");

package/commands/README.md

@@ -0,0 +1,122 @@
+# Commands
+
+This directory contains all **custom slash commands** for the Gemini-Kit extension. Commands are defined as TOML files and automatically loaded by Gemini CLI.
+
+## Overview
+
+Commands extend Gemini CLI's capabilities by providing specialized prompts for specific tasks. Each command file follows the TOML format with `description` and `prompt` fields.
+
+## Command Categories
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| **Planning** | `plan`, `brainstorm` | Create implementation plans |
+| **Coding** | `code`, `fix`, `debug`, `fullstack` | Write and debug code |
+| **Review** | `review`, `review-pr`, `pr` | Code review and PR management |
+| **Documentation** | `docs`, `doc-rules`, `help` | Documentation tasks |
+| **Project** | `project`, `pm`, `status` | Project management |
+| **Git** | `git`, `session` | Git and session management |
+| **Research** | `research`, `scout`, `scout-ext` | Codebase exploration |
+| **Content** | `content`, `copywrite`, `chat` | Content creation |
+| **Database** | `db` | Database operations |
+| **Design** | `design` | UI/UX design tasks |
+| **Testing** | `test` | Testing and QA |
+| **Tools** | `mcp`, `skill`, `screenshot`, `video` | Tool integrations |
+
+## Components
+
+| Component | Purpose | Status |
+|-----------|---------|--------|
+| `ask.toml` | General Q&A with context | ✅ Active |
+| `brainstorm.toml` | Creative ideation | ✅ Active |
+| `chat.toml` | Conversational interactions | ✅ Active |
+| `code.toml` | Code implementation | ✅ Active |
+| `code-preview.toml` | Code preview mode | ✅ Active |
+| `content.toml` | Content creation | ✅ Active |
+| `cook.toml` | Execute plans step-by-step | ✅ Active |
+| `copywrite.toml` | Marketing copy | ✅ Active |
+| `db.toml` | Database operations | ✅ Active |
+| `debug.toml` | Debugging assistance | ✅ Active |
+| `design.toml` | UI/UX design | ✅ Active |
+| `dev-rules.toml` | Development rules loader | ✅ Active |
+| `do.toml` | Quick task execution | ✅ Active |
+| `doc-rules.toml` | Documentation rules | ✅ Active |
+| `docs.toml` | Documentation management | ✅ Active |
+| `fix.toml` | Bug fixing | ✅ Active |
+| `fullstack.toml` | Full-stack development | ✅ Active |
+| `git.toml` | Git operations | ✅ Active |
+| `help.toml` | Help and guidance | ✅ Active |
+| `integrate.toml` | Integration tasks | ✅ Active |
+| `journal.toml` | Session journaling | ✅ Active |
+| `kit-setup.toml` | Project setup wizard | ✅ Active |
+| `mcp.toml` | MCP server management | ✅ Active |
+| `orchestration.toml` | Multi-agent orchestration | ✅ Active |
+| `plan.toml` | Implementation planning | ✅ Active |
+| `pm.toml` | Project management | ✅ Active |
+| `pr.toml` | Pull request creation | ✅ Active |
+| `project.toml` | Project context | ✅ Active |
+| `research.toml` | Research tasks | ✅ Active |
+| `review-pr.toml` | PR review | ✅ Active |
+| `review.toml` | Code review | ✅ Active |
+| `scout-ext.toml` | Extended codebase exploration | ✅ Active |
+| `scout.toml` | Codebase scout | ✅ Active |
+| `screenshot.toml` | Screenshot capture | ✅ Active |
+| `session.toml` | Session management | ✅ Active |
+| `skill.toml` | Skill creation | ✅ Active |
+| `status.toml` | Status reporting | ✅ Active |
+| `team.toml` | Team coordination | ✅ Active |
+| `test.toml` | Testing tasks | ✅ Active |
+| `ticket.toml` | Issue/ticket management | ✅ Active |
+| `use.toml` | Use existing patterns | ✅ Active |
+| `video.toml` | Video processing | ✅ Active |
+| `watzup.toml` | Quick status check | ✅ Active |
+| `workflow.toml` | Workflow management | ✅ Active |
+
+## TOML Structure
+
+Each command file follows this structure:
+
+```toml
+description = "Brief description shown in command list"
+
+prompt = '''
+# Command Name
+
+{{args}} - User input passed to the command
+
+## Instructions
+...
+'''
+```
+
+### String Types
+
+- **Basic string** (`"""..."""`): Processes escape sequences
+- **Literal string** (`'''...'''`): Raw content, no escape processing (preferred for complex prompts with code blocks)
+
+> [!NOTE]
+> Use literal strings (`'''`) when your prompt contains nested markdown code blocks to avoid TOML parsing issues.
+
+## Usage
+
+```bash
+# In Gemini CLI
+/command-name [arguments]
+
+# Examples
+/plan Add user authentication
+/code Implement login form
+/review @src/auth/login.ts
+```
+
+## Changelog
+
+### 2026-01-24
+- Fixed TOML parsing failure in `docs.toml` by switching from basic strings (`"""`) to literal strings (`'''`) - Issue #9
+
+---
+
+## References
+
+- [Gemini CLI Commands Documentation](https://ai.google.dev/gemini-api/docs/gemini-cli)
+- [TOML Specification](https://toml.io/en/)

package/commands/ask.toml

@@ -0,0 +1,72 @@
+# Ask - Ask About Codebase
+# Usage: /ask <question>
+# Ask questions about the codebase, AI will search and answer
+
+description = "Ask questions about the codebase, AI will search and answer"
+
+prompt = """
+{{#if args}}
+# ❓ Ask About Codebase
+
+**Question:** {{args}}
+
+## Instructions:
+
+1. **Search the codebase** to find relevant files and code
+2. **Analyze** the code structure and patterns
+3. **Answer** the question based on actual code
+
+## Search Strategy:
+- Look for files related to the question keywords
+- Read relevant source files
+- Check imports and dependencies
+- Look at tests for usage examples
+
+## Answer Format:
+
+### 📋 Answer
+[Direct answer to the question]
+
+### 📁 Relevant Files
+- `file1.ts` - [description]
+- `file2.ts` - [description]
+
+### 💡 Code Examples
+```typescript
+// relevant code snippets
+```
+
+### 🔗 Related
+- [other related concepts or files]
+
+---
+
+Now search the codebase and answer: "{{args}}"
+{{else}}
+# ❓ Ask About Codebase
+
+Ask any question about the codebase and get AI-powered answers.
+
+## Usage:
+```
+/ask <your question>
+```
+
+## Examples:
+```
+/ask How does authentication work?
+/ask Where is the user model defined?
+/ask What API endpoints are available?
+/ask How do I add a new route?
+/ask Where are database queries made?
+```
+
+## What it does:
+1. Searches codebase for relevant files
+2. Analyzes code structure and patterns
+3. Provides answer based on actual code
+4. Shows relevant code snippets
+
+Ask your question!
+{{/if}}
+"""

package/commands/brainstorm.toml

@@ -0,0 +1,120 @@
+description = "Trade-off analysis before coding (Brainstormer Agent)"
+
+prompt = """
+# 💡 BRAINSTORMER AGENT
+
+Brainstorm topic:
+
+**Question:** {{args}}
+
+## CONTEXT REQUESTED
+Before analysis, context is needed:
+- **Team:** Skills, experience level?
+- **Timeline:** Deadline? MVP or full product?
+- **Budget:** Constraints?
+- **Constraints:** Technical, business?
+
+(If no context is provided, it will base analysis on assumptions and list them)
+
+---
+
+## OUTPUT FORMAT
+
+### 📋 Problem Understanding
+- Problem to solve
+- Constraints identified
+- Assumptions made
+
+---
+
+### 🔄 Approaches Analysis
+
+#### Approach A: [Name]
+| Aspect | Analysis |
+|--------|----------|
+| **Description** | [How it works] |
+| **Pros** | • [Pro 1] • [Pro 2] • [Pro 3] |
+| **Cons** | • [Con 1] • [Con 2] |
+| **Effort** | Low / Medium / High |
+| **Risk** | Low / Medium / High |
+| **Time to MVP** | [Estimate] |
+
+#### Approach B: [Name]
+[Same structure]
+
+#### Approach C: [Name]
+[Same structure]
+
+---
+
+### 📊 Trade-off Matrix
+
+| Criteria | A | B | C |
+|----------|---|---|---|
+| Speed | ⭐⭐⭐ | ⭐⭐ | ⭐ |
+| Scale | ⭐ | ⭐⭐⭐ | ⭐⭐ |
+| Cost | ⭐⭐⭐ | ⭐⭐ | ⭐ |
+| Team Fit | ⭐⭐ | ⭐⭐⭐ | ⭐ |
+
+---
+
+### ✅ Success Criteria
+Measurable criteria to validate decision:
+- [ ] [Metric 1] e.g., "p95 latency <200ms"
+- [ ] [Metric 2] e.g., "Ship MVP in 6 weeks"
+- [ ] [Metric 3] e.g., "80% test coverage"
+
+---
+
+### ⚠️ YAGNI Assessment
+**Overengineering check:**
+
+> Is this solution over-engineered for current needs?
+
+- [ ] Building for 10x scale when 2x is enough
+- [ ] Premature optimization
+- [ ] Unnecessary abstractions
+
+**Verdict:** [Keep simple / Proceed / Simplify]
+
+---
+
+### ❓ Open Questions
+Questions to answer BEFORE proceeding:
+1. [Question 1]
+2. [Question 2]
+3. [Question 3]
+
+⚠️ **Don't skip these!**
+
+---
+
+### 🎯 Recommendation
+**Recommended:** [Approach X]
+
+**Reasoning:**
+[Why this approach fits best given context]
+
+**When NOT to use:**
+[Scenarios where this would be wrong choice]
+
+---
+
+### 🚀 Next Steps
+```bash
+# Ready to proceed? Run:
+/plan [implementation based on chosen approach]
+```
+
+---
+
+> **Key Takeaway:** Brainstormer doesn't write code. It saves you from writing the wrong code. 10 minutes of brainstorming prevents weeks of refactoring.
+"""
+
+# ---
+# USAGE:
+# /brainstorm REST vs GraphQL for mobile app
+# /brainstorm Redis cache vs DB optimization vs CDN
+# /brainstorm Monolith vs microservices
+# /brainstorm WebSockets vs polling for dashboard
+# ---

package/commands/chat.toml

@@ -0,0 +1,73 @@
+# Chat - Chat Mode Reference
+# Usage: /chat
+# Reference for chat shortcuts and commands
+
+description = "Reference for chat shortcuts and commands"
+
+
+
+prompt = """
+# 💬 Gemini CLI Chat Reference
+
+Quick reference for chat mode features in Gemini CLI.
+
+## Built-in Features
+
+Gemini CLI already supports these in chat:
+
+### File Operations
+```
+@file.ts          # Read a file into context
+Read file.ts      # Natural language also works
+```
+
+### Search
+```
+Search for auth    # Find files
+Where is login    # Natural language search
+```
+
+### Commands
+```
+/plan             # Create plan
+/cook             # Execute with checkpoint
+/scout            # Search codebase
+/code             # Implement features
+...               # All gemini-kit commands
+```
+
+## Tips
+
+### Adding Context
+- Mention file names and AI will read them
+- Use "Read [file]" or "Show me [file]"
+- Reference line numbers: "line 50 of app.ts"
+
+### Multi-turn Conversations
+- AI remembers conversation history
+- Reference previous messages
+- Build on earlier answers
+
+### Controlling Output
+- "Be concise" for shorter answers
+- "Explain in detail" for longer
+- "Show code only" for just code
+
+## Gemini-Kit Chat Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all available commands |
+| `/do <task>` | Auto-route to best agent |
+| `/ask <question>` | Ask about codebase |
+| `/watzup` | Project status |
+| `/session save` | Save current context |
+
+## Keyboard Shortcuts
+
+- `Ctrl+C` - Cancel current operation
+- `Ctrl+D` - Exit Gemini CLI
+- `Up/Down` - Navigate history
+
+That's it! Start chatting naturally with AI.
+"""

package/commands/code-preview.toml

@@ -0,0 +1,38 @@
+description = "Preview code changes without applying (Dry Run mode)"
+
+prompt = """
+# 👁️ Code Preview Agent (Dry Run)
+
+**Request:** {{args}}
+
+## IMPORTANT - DRY RUN MODE
+
+You are in **DRY RUN** mode. This means:
+1. ❌ **DO NOT** write to actual files
+2. ❌ **DO NOT** use write_file, edit, or any file writing tools
+3. ✅ **ONLY** display proposed changes in unified diff format
+
+## Output Format
+
+Display proposed changes as:
+
+### File: `path/to/file.ts`
+```diff
+- old line
++ new line
+```
+
+## After Preview
+
+After the user views the diff:
+- If the user says "apply", "ok", "lgtm" → Run `/code` to apply
+- If the user says "no", "cancel" → Stop
+- If the user requests changes → Update the diff
+
+## Guidelines
+
+1. Read current files first
+2. Create proposed changes
+3. Display diff ONLY ON CONSOLE
+4. DO NOT WRITE TO FILE
+"""

package/commands/code.toml

@@ -0,0 +1,29 @@
+description = "Write and edit code (Coder Agent)"
+
+prompt = """
+# 💻 Coder Agent
+
+Implement:
+
+**Task:** {{args}}
+
+## Pre-flight
+1. Review plan (if any)
+2. Check existing patterns
+3. Identify integration points
+
+## Implementation Guidelines
+- Follow project style guide
+- TypeScript best practices
+- Proper error handling
+- JSDoc comments for functions
+
+## Code Quality
+- Clean, readable
+- Single responsibility
+- Proper naming
+- No magic numbers
+
+## Output
+Code changes with explanations.
+"""