superkit-mcp-server 1.2.6 → 1.2.8

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/agents/coder.md

@@ -1,3 +1,10 @@
+---
+name: coder
+description: Clean code implementation specialist. Use for writing new features, refactoring existing code, fixing bugs, and creating utilities. Triggers on implement, write, create, build, code, function, feature, refactor.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: inherit
+---
+
 # Coder Agent
 
 ## Role

package/agents/git-manager.md

@@ -1,3 +1,10 @@
+---
+name: git-manager
+description: Git version control specialist. Use for commits, branching, merging, rebasing, conflict resolution, and pull requests. Triggers on commit, branch, merge, rebase, git, conflict, stash, push, pull, PR, changelog.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
 # Git Manager Agent
 
 ## Role

package/agents/planner.md

@@ -1,3 +1,10 @@
+---
+name: planner
+description: Implementation planning specialist. Use when starting complex tasks that need breaking into subtasks, identifying dependencies, or creating step-by-step plans. Triggers on plan, design, architect, break down, strategy, roadmap, phases.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
 # Planner Agent
 
 ## Role

package/agents/reviewer.md

@@ -1,3 +1,10 @@
+---
+name: reviewer
+description: Code review and quality specialist. Use before merges, for security audits, performance reviews, and architecture reviews. Triggers on review, audit, check, quality, inspect, validate, before merge, code smell.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
 # Reviewer Agent
 
 ## Role

package/agents/scout.md

@@ -1,3 +1,10 @@
+---
+name: scout
+description: Codebase exploration specialist. Use to understand new codebases, find files related to a task, identify integration points, and trace code flow. Triggers on explore, find, search, understand, navigate, where is, what file, how does.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
 # Scout Agent
 
 ## Role

package/agents/tester.md

@@ -1,3 +1,10 @@
+---
+name: tester
+description: Testing and quality assurance specialist. Use for writing unit tests, integration tests, E2E tests, and covering edge cases. Triggers on test, spec, unit, integration, coverage, jest, vitest, playwright, cypress, verify.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: inherit
+---
+
 # Tester Agent
 
 ## Role

package/agents/ui-designer.md

@@ -1,3 +1,10 @@
+---
+name: ui-designer
+description: UI/UX design specialist. Use for designing new UI components, improving UX flows, creating mockups, design systems, and accessibility reviews. Triggers on design, ui, ux, mockup, wireframe, layout, component, style, accessibility, dark mode.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
 # UI/UX Designer Agent
 
 ## Role

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.",
@@ -493,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),
                     },
                 ],
             };
@@ -573,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) {