superkit-mcp-server 1.2.5 → 1.2.7

package/ARCHITECTURE.md

@@ -17,17 +17,25 @@ Super-Kit is a model-agnostic and agent-agnostic toolkit designed to provide a h
 ## 🏗️ Directory Structure
 
 ```plaintext
-super-kit/
+super-kit/                   # Global Super-Kit package (npm: superkit-mcp-server)
 ├── ARCHITECTURE.md          # This file
 ├── SUPERKIT.md              # Global rules and activation protocol
 ├── .core/                   # Core engine-independent logic
 │   ├── rules/               # Universal mandates (e.g., clean-code, security-first)
-├── agents/                  # The T-Shaped AI Team Personas
-├── skills/                  # The Knowledge Modules
+├── agents/                  # The T-Shaped AI Team Personas       [source: "global"]
+├── skills/                  # The Knowledge Modules               [source: "global"]
 │   ├── meta/                # Session-resume, compound-docs, file-todos
 │   ├── tech/                # Node.js, React, Python, Prisma
 │   └── workflows/           # TDD, CI/CD, Code Review checklists
 └── workflows/               # Slash commands and lifecycle loops
+
+{your-project}/              # Any project using Super-Kit
+└── .agents/                 # Project-local assets                [source: "project"]
+    ├── agents/              # Custom agent .md files (e.g., my-domain-expert.md)
+    ├── skills/
+    │   ├── tech/            # Tech skill dirs, each with a SKILL.md
+    │   └── meta/            # Meta skill dirs, each with a SKILL.md
+    └── workflows/           # Custom workflow .md files
 ```
 
 ---
@@ -100,3 +108,44 @@ The entry point is reading `SUPERKIT.md` to establish global rules.
 - **Aider**: Run aider with the message `aider --message "Read SUPERKIT.md for your system instructions before doing anything else."`
 
 Once the agent has loaded `SUPERKIT.md`, it will follow the instructions to activate the appropriate `@agent` which dynamically reads `SKILL.md` from the relevant directories.
+
+---
+
+## 🗂️ Project-Based Assets
+
+Super-Kit supports a two-scope asset system that allows any project to ship its own agents, skills, and workflows alongside the global Super-Kit package assets.
+
+### Scope Definitions
+
+| Scope | Source | Location | `source` Label |
+|-------|--------|----------|----------------|
+| **Global** | `superkit-mcp-server` npm package | `super-kit/agents/`, `super-kit/skills/` | `"global"` |
+| **Project** | User's project `.agents/` folder | `{project-root}/.agents/` | `"project"` |
+
+### Resolution Rules
+
+- Project assets **complement** global assets — they never override or shadow them.
+- If `.agents/` does not exist in a project, all project-scoped tools return empty results gracefully (no errors thrown).
+- Asset names are validated to prevent path traversal — absolute paths and `..` components are rejected.
+
+### MCP Tool Mapping
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `list_superkit_assets` | Global (default) | Lists global assets. Accepts `scope: "all"` to merge both scopes with source labels. |
+| `load_superkit_agent` | Global | Loads an agent from the Super-Kit package. |
+| `load_superkit_skill` | Global | Loads a skill from the Super-Kit package. |
+| `load_superkit_workflow` | Global | Loads a workflow from the Super-Kit package. |
+| `list_project_assets` | Project | Lists project-local assets from `.agents/`. Falls back to `process.cwd()` if no `projectPath` given. |
+| `load_project_agent` | Project | Loads an agent from `{projectPath}/.agents/agents/`. |
+| `load_project_skill` | Project | Loads a skill from `{projectPath}/.agents/skills/{category}/{skillName}/SKILL.md`. |
+| `load_project_workflow` | Project | Loads a workflow from `{projectPath}/.agents/workflows/`. |
+
+### Recommended Discovery Order
+
+When an agent starts work on a project, it should:
+
+1. Call `list_project_assets` to discover what the project provides.
+2. Load project-specific agents/skills/workflows first (`load_project_*`).
+3. Fall back to global Super-Kit assets (`load_superkit_*`) for anything not covered.
+4. Use `list_superkit_assets({ scope: "all" })` for a unified merged view with source labels.

package/SUPERKIT.md

@@ -85,12 +85,18 @@ When user says: "Always use TypeScript strict mode"
 
 ## Available Tools
 
-**Super-Kit MCP Tools:**
-- `list_superkit_assets` - Lists all available agents, skills, and workflows.
+**Super-Kit MCP Tools (Global Scope):**
+- `list_superkit_assets` - Lists all available agents, skills, and workflows. Accepts optional `scope` (`"global"` | `"project"` | `"all"`) and `projectPath` params.
 - `load_superkit_agent` - Loads Markdown instructions for an agent (e.g., `data-engineer`).
 - `load_superkit_skill` - Loads Markdown instructions for a skill (e.g., `tech`, `api-patterns`).
 - `load_superkit_workflow` - Loads a workflow guide (e.g., `work`, `explore`).
 
+**Project-Scoped MCP Tools:**
+- `list_project_assets` - Lists project-scoped agents, skills, and workflows from the `.agents/` folder.
+- `load_project_agent` - Loads a project-scoped agent from `{projectPath}/.agents/agents/`.
+- `load_project_skill` - Loads a project-scoped skill's `SKILL.md` from `{projectPath}/.agents/skills/`.
+- `load_project_workflow` - Loads a project-scoped workflow from `{projectPath}/.agents/workflows/`.
+
 **Core Development Tools:**
 - `kit_create_checkpoint` - Create checkpoint before changes
 - `kit_restore_checkpoint` - Restore checkpoint if needed
@@ -103,6 +109,30 @@ When user says: "Always use TypeScript strict mode"
 - `kit_save_learning` - **Save lesson from user feedback**
 - `kit_get_learnings` - Read saved learnings
 
+## 🗂️ Project-Based Assets
+
+Any project can define its own agents, skills, and workflows by creating a `.agents/` folder at the project root:
+
+```
+{project-root}/
+└── .agents/
+    ├── agents/       # Custom agent .md files (e.g., my-domain-expert.md)
+    ├── skills/
+    │   ├── tech/     # Tech skill dirs, each containing a SKILL.md
+    │   └── meta/     # Meta skill dirs, each containing a SKILL.md
+    └── workflows/    # Custom workflow .md files (e.g., deploy-staging.md)
+```
+
+**Resolution rules:**
+- Project assets have `"source": "project"` and **complement** (do not replace) global Super-Kit assets.
+- Global Super-Kit assets always have `"source": "global"`.
+- If `.agents/` does not exist, all project-scoped tools return empty results gracefully — no errors.
+
+**When starting work on ANY project, ALWAYS:**
+1. Call `list_project_assets` (or `list_superkit_assets` with `scope: "all"`) to discover project-specific agents, skills, and workflows.
+2. Load project assets with `load_project_agent`, `load_project_skill`, or `load_project_workflow` before falling back to global equivalents.
+3. Use global assets (`load_superkit_agent`, etc.) for anything not covered by the project's `.agents/` folder.
+
 ## Documentation Management
 
 - Docs location: `./docs/`

package/build/index.js

@@ -16,6 +16,7 @@ import { compoundSearch, updateSolutionRef, validateCompound, auditStateDrift, s
 import { bootstrapFolderDocs, checkDocsFreshness, discoverUndocumentedFolders, validateFolderDocs, } from "./tools/docsTools.js";
 import { generateChangelog, validateChangelog, archiveCompleted, prePushHousekeeping, } from "./tools/gitTools.js";
 import { validateSpecConsistency, completePlan, validateArchitecture, syncSpec, updateSpecPhase, } from "./tools/archTools.js";
+import { list_project_agents, list_project_skills, list_project_workflows, load_project_agent_file, load_project_skill_file, load_project_workflow_file, } from "./tools/ProjectAssets.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const superKitRoot = path.resolve(__dirname, "../");
@@ -119,7 +120,23 @@ const TOOLS = [
     },
     {
         name: "call_tool_todo_manager",
-        description: "Manages todos (nextId, create, start, done, complete)",
+        description: `Manages todos. Per-action usage:
+
+• nextId — Returns the next available todo ID. No extra params needed.
+
+• create — Creates a new todo file. Required: title (string), description (1-2 sentence problem statement), priority ("p0"|"p1"|"p2"|"p3"), criteria (string array of acceptance criteria). Optional: projectPath.
+  Example: { action: "create", title: "Add auth", description: "Implement JWT login.", priority: "p2", criteria: ["User can log in", "Token is stored"], projectPath: "." }
+
+• start — Marks a todo as in-progress. Required: todoId = RELATIVE PATH to the todo file, e.g. "todos/001-pending-p2-my-task.md". The file must exist at that path relative to projectPath.
+  Example: { action: "start", todoId: "todos/001-pending-p2-my-task.md", projectPath: "." }
+
+• done — Marks a todo as done. Required: todoId = relative path (same format as start). All acceptance criteria checkboxes must be checked, or pass force: true to bypass.
+  Example: { action: "done", todoId: "todos/001-in-progress-p2-my-task.md", force: true, projectPath: "." }
+
+• complete — Marks a todo as complete (final state). Required: todoId = relative path (same format as start/done).
+  Example: { action: "complete", todoId: "todos/001-done-p2-my-task.md", force: true, projectPath: "." }
+
+⚠️ IMPORTANT: todoId must be the FULL RELATIVE FILE PATH (e.g. "todos/001-in-progress-p2-my-task.md"), NOT just the numeric ID ("001"). The filename changes with each status transition, so always use the current filename on disk.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -127,12 +144,33 @@ const TOOLS = [
                     type: "string",
                     enum: ["nextId", "create", "start", "done", "complete"],
                 },
-                title: { type: "string" },
-                description: { type: "string" },
-                priority: { type: "string" },
-                criteria: { type: "array", items: { type: "string" } },
-                todoId: { type: "string" },
-                force: { type: "boolean", default: false },
+                title: {
+                    type: "string",
+                    description: "Todo title. Used by: create.",
+                },
+                description: {
+                    type: "string",
+                    description: "1-2 sentence problem statement. Used by: create.",
+                },
+                priority: {
+                    type: "string",
+                    enum: ["p0", "p1", "p2", "p3"],
+                    description: "Priority level. p0=critical, p1=urgent, p2=normal, p3=low. Used by: create.",
+                },
+                criteria: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Acceptance criteria checklist items. Used by: create.",
+                },
+                todoId: {
+                    type: "string",
+                    description: "RELATIVE PATH to the todo file from projectPath, e.g. 'todos/001-pending-p2-my-task.md'. NOT just the numeric ID. Used by: start, done, complete.",
+                },
+                force: {
+                    type: "boolean",
+                    default: false,
+                    description: "Bypass terminal-state or unchecked-criteria guards. Used by: start, done, complete.",
+                },
                 projectPath: { type: "string", default: "." },
             },
             required: ["action", "projectPath"],
@@ -233,10 +271,93 @@ const TOOLS = [
         description: "Lists all available agents, skills, and workflows in the Super-Kit repository.",
         inputSchema: {
             type: "object",
-            properties: {},
+            properties: {
+                scope: {
+                    type: "string",
+                    enum: ["global", "project", "all"],
+                    default: "global",
+                    description: "Which scope to list: 'global' (superkit package assets), 'project' (.agents/ folder assets), or 'all' (merged with source labels on every entry).",
+                },
+                projectPath: {
+                    type: "string",
+                    description: "Project root path used when scope includes 'project'. Defaults to process.cwd().",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "list_project_assets",
+        description: "Lists project-scoped agents, skills, and workflows from the .agents/ folder in the given project directory. Falls back to process.cwd() if no projectPath is given.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: {
+                    type: "string",
+                    description: "Absolute path to the project root. Defaults to process.cwd().",
+                },
+            },
             required: [],
         },
     },
+    {
+        name: "load_project_agent",
+        description: "Loads a project-scoped agent markdown file from {projectPath}/.agents/agents/{agentName}.md",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agentName: {
+                    type: "string",
+                    description: "Agent name without .md extension.",
+                },
+                projectPath: {
+                    type: "string",
+                    description: "Absolute path to the project root. Defaults to process.cwd().",
+                },
+            },
+            required: ["agentName"],
+        },
+    },
+    {
+        name: "load_project_skill",
+        description: "Loads a project-scoped skill's SKILL.md from {projectPath}/.agents/skills/{category}/{skillName}/SKILL.md",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "Skill category: 'tech' or 'meta'.",
+                },
+                skillName: {
+                    type: "string",
+                    description: "Skill directory name.",
+                },
+                projectPath: {
+                    type: "string",
+                    description: "Absolute path to the project root. Defaults to process.cwd().",
+                },
+            },
+            required: ["category", "skillName"],
+        },
+    },
+    {
+        name: "load_project_workflow",
+        description: "Loads a project-scoped workflow markdown file from {projectPath}/.agents/workflows/{workflowName}.md",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workflowName: {
+                    type: "string",
+                    description: "Workflow name without .md extension.",
+                },
+                projectPath: {
+                    type: "string",
+                    description: "Absolute path to the project root. Defaults to process.cwd().",
+                },
+            },
+            required: ["workflowName"],
+        },
+    },
     {
         name: "load_superkit_agent",
         description: "Loads the instruction markdown for a specific specialist agent.",
@@ -302,6 +423,13 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
                     prompts.push({
                         name: file.replace(".toml", ""),
                         description: description,
+                        arguments: [
+                            {
+                                name: "args",
+                                description: "Arguments to pass to the command",
+                                required: false,
+                            },
+                        ],
                     });
                 }
                 catch (e) {
@@ -316,8 +444,18 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
         return { prompts: [] };
     }
 });
+export function apply_prompt_args(promptText, userArgs) {
+    // Substitute {{#if args}} ... {{else}} ... {{/if}} Handlebars blocks
+    promptText = promptText.replace(/\{\{#if args\}\}([\s\S]*?)\{\{else\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, ifBlock, elseBlock) => userArgs.trim() ? ifBlock : elseBlock);
+    // Substitute {{#if args}} ... {{/if}} blocks (no else branch)
+    promptText = promptText.replace(/\{\{#if args\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, ifBlock) => (userArgs.trim() ? ifBlock : ""));
+    // Substitute all {{args}} occurrences with the actual user-provided args
+    promptText = promptText.replace(/\{\{args\}\}/g, userArgs);
+    return promptText;
+}
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     const promptName = request.params.name;
+    const userArgs = request.params.arguments?.args ?? "";
     const commandFile = `${promptName}.toml`;
     const basePath = path.join(superKitRoot, "commands");
     const safePath = getSafePath(basePath, commandFile);
@@ -328,6 +466,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
         const content = await fs.readFile(safePath, "utf-8");
         const parsed = toml.parse(content);
         let promptText = parsed?.prompt || `Execute the ${promptName} command.`;
+        promptText = apply_prompt_args(promptText, userArgs);
         // Resolve @{path} includes from super-kit package root
         const includePattern = /@\{([^}]+)\}/g;
         let match;
@@ -475,29 +614,106 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return { content: [{ type: "text", text: res }] };
         }
         if (request.params.name === "list_superkit_assets") {
+            const args = request.params.arguments;
+            const scope = args?.scope ?? "global";
+            const projectPath = args?.projectPath;
             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, "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);
+            // Build global asset lists (used for scope "global" or "all")
+            let globalData = null;
+            if (scope !== "project") {
+                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);
+                if (scope === "global") {
+                    // Original backward-compatible format — no source labels
+                    globalData = {
+                        agents: agents.map((a) => a.replace(".md", "")),
+                        skills: {
+                            tech: techSkills.map((s) => s.replace("/", "")),
+                            meta: metaSkills.map((s) => s.replace("/", "")),
+                        },
+                        workflows: workflows.map((w) => w.replace(".md", "")),
+                        commands: commands.map((c) => c.replace(".toml", "")),
+                    };
+                }
+                else {
+                    // "all" scope — include source labels on every entry
+                    globalData = {
+                        agents: agents.map((a) => ({
+                            name: a.replace(".md", ""),
+                            source: "global",
+                        })),
+                        skills: {
+                            tech: techSkills.map((s) => ({
+                                name: s.replace("/", ""),
+                                source: "global",
+                            })),
+                            meta: metaSkills.map((s) => ({
+                                name: s.replace("/", ""),
+                                source: "global",
+                            })),
+                        },
+                        workflows: workflows.map((w) => ({
+                            name: w.replace(".md", ""),
+                            source: "global",
+                        })),
+                        commands: commands.map((c) => ({
+                            name: c.replace(".toml", ""),
+                            source: "global",
+                        })),
+                    };
+                }
+            }
+            // Build project asset lists (used for scope "project" or "all")
+            let projectData = null;
+            if (scope !== "global") {
+                const [projAgents, projSkills, projWorkflows] = await Promise.all([
+                    list_project_agents(projectPath),
+                    list_project_skills(projectPath),
+                    list_project_workflows(projectPath),
+                ]);
+                projectData = {
+                    agents: projAgents.map((a) => ({ name: a, source: "project" })),
+                    skills: {
+                        tech: projSkills.tech.map((s) => ({ name: s, source: "project" })),
+                        meta: projSkills.meta.map((s) => ({ name: s, source: "project" })),
+                    },
+                    workflows: projWorkflows.map((w) => ({ name: w, source: "project" })),
+                };
+            }
+            // Compose the final response payload
+            let payload;
+            if (scope === "global") {
+                payload = globalData;
+            }
+            else if (scope === "project") {
+                payload = projectData;
+            }
+            else {
+                // "all" — deep-merge both lists
+                const g = globalData;
+                const p = projectData;
+                payload = {
+                    agents: [...g.agents, ...p.agents],
+                    skills: {
+                        tech: [...g.skills.tech, ...p.skills.tech],
+                        meta: [...g.skills.meta, ...p.skills.meta],
+                    },
+                    workflows: [...g.workflows, ...p.workflows],
+                    commands: g.commands,
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({
-                            agents: agents.map((a) => a.replace(".md", "")),
-                            skills: {
-                                tech: techSkills.map((s) => s.replace("/", "")),
-                                meta: metaSkills.map((s) => s.replace("/", "")),
-                            },
-                            workflows: workflows.map((w) => w.replace(".md", "")),
-                            commands: commands.map((c) => c.replace(".toml", "")),
-                        }, null, 2),
+                        text: JSON.stringify(payload, null, 2),
                     },
                 ],
             };
@@ -555,6 +771,61 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const content = await fs.readFile(safePath, "utf-8");
             return { content: [{ type: "text", text: content }] };
         }
+        if (request.params.name === "list_project_assets") {
+            const args = request.params.arguments;
+            const projectPath = args?.projectPath;
+            const [agents, skills, workflows] = await Promise.all([
+                list_project_agents(projectPath),
+                list_project_skills(projectPath),
+                list_project_workflows(projectPath),
+            ]);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            source: "project",
+                            agents: agents.map((a) => ({ name: a, source: "project" })),
+                            skills: {
+                                tech: skills.tech.map((s) => ({
+                                    name: s,
+                                    source: "project",
+                                })),
+                                meta: skills.meta.map((s) => ({
+                                    name: s,
+                                    source: "project",
+                                })),
+                            },
+                            workflows: workflows.map((w) => ({
+                                name: w,
+                                source: "project",
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (request.params.name === "load_project_agent") {
+            const args = request.params.arguments;
+            if (!args.agentName)
+                throw new Error("Missing agentName");
+            const content = await load_project_agent_file(args.agentName, args.projectPath);
+            return { content: [{ type: "text", text: content }] };
+        }
+        if (request.params.name === "load_project_skill") {
+            const args = request.params.arguments;
+            if (!args.category || !args.skillName)
+                throw new Error("Missing category or skillName");
+            const content = await load_project_skill_file(args.category, args.skillName, args.projectPath);
+            return { content: [{ type: "text", text: content }] };
+        }
+        if (request.params.name === "load_project_workflow") {
+            const args = request.params.arguments;
+            if (!args.workflowName)
+                throw new Error("Missing workflowName");
+            const content = await load_project_workflow_file(args.workflowName, args.projectPath);
+            return { content: [{ type: "text", text: content }] };
+        }
         throw new Error(`Unknown tool: ${request.params.name}`);
     }
     catch (error) {