superkit-mcp-server 1.2.6 → 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.",
@@ -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) {

package/build/tools/ProjectAssets.js

@@ -0,0 +1,177 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// The conventional folder name for project-local Super-Kit assets
+export const PROJECT_ASSETS_DIR = '.agents';
+/**
+ * Resolves the effective project root path.
+ * - If an explicit projectPath is provided, it is resolved to an absolute path.
+ * - Otherwise, falls back to process.cwd().
+ */
+export function resolve_project_path(projectPath) {
+    if (projectPath) {
+        return path.resolve(projectPath);
+    }
+    return process.cwd();
+}
+/**
+ * Returns the absolute path to the .agents/ root for the given project.
+ */
+export function get_project_agents_root(projectPath) {
+    return path.join(resolve_project_path(projectPath), PROJECT_ASSETS_DIR);
+}
+/**
+ * Internal guard: ensures the resolved path stays strictly within the .agents/ root.
+ * Returns the resolved absolute path, or null if a traversal attempt is detected.
+ */
+function safe_project_path(agentsRoot, relative) {
+    // Normalize the root so the startsWith check is reliable on all platforms
+    const normalizedRoot = path.resolve(agentsRoot);
+    const resolved = path.resolve(agentsRoot, relative);
+    // On Windows path.resolve produces lower-cased drive letters consistently,
+    // so this comparison is safe cross-platform.
+    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
+        return null; // traversal detected
+    }
+    return resolved;
+}
+/**
+ * Validates a user-supplied asset name (agentName, skillName, workflowName).
+ * Rejects absolute paths and anything containing path-separator characters.
+ */
+function validate_asset_name(name) {
+    if (!name || typeof name !== 'string') {
+        throw new Error('Asset name must be a non-empty string.');
+    }
+    if (path.isAbsolute(name)) {
+        throw new Error(`Asset name must not be an absolute path: "${name}"`);
+    }
+    // Reject any component that contains a path separator or navigates upward
+    const normalized = path.normalize(name);
+    if (normalized.includes('..') || normalized.startsWith('/') || normalized.startsWith('\\')) {
+        throw new Error(`Asset name contains invalid path components: "${name}"`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Listing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Lists project-scoped agent names (without .md extension) from .agents/agents/.
+ * Returns an empty array if the directory does not exist.
+ */
+export async function list_project_agents(projectPath) {
+    const agentsRoot = get_project_agents_root(projectPath);
+    const agentsDir = path.join(agentsRoot, 'agents');
+    try {
+        const entries = await fs.readdir(agentsDir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name.replace(/\.md$/, ''));
+    }
+    catch {
+        // Directory does not exist — graceful degradation
+        return [];
+    }
+}
+/**
+ * Lists project-scoped skill directory names from .agents/skills/tech/ and .agents/skills/meta/.
+ * Returns empty arrays for each category if the directories do not exist.
+ */
+export async function list_project_skills(projectPath) {
+    const agentsRoot = get_project_agents_root(projectPath);
+    const list_category_skills = async (category) => {
+        const categoryDir = path.join(agentsRoot, 'skills', category);
+        try {
+            const entries = await fs.readdir(categoryDir, { withFileTypes: true });
+            return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+        }
+        catch {
+            return [];
+        }
+    };
+    const [tech, meta] = await Promise.all([
+        list_category_skills('tech'),
+        list_category_skills('meta'),
+    ]);
+    return { tech, meta };
+}
+/**
+ * Lists project-scoped workflow names (without .md extension) from .agents/workflows/.
+ * Returns an empty array if the directory does not exist.
+ */
+export async function list_project_workflows(projectPath) {
+    const agentsRoot = get_project_agents_root(projectPath);
+    const workflowsDir = path.join(agentsRoot, 'workflows');
+    try {
+        const entries = await fs.readdir(workflowsDir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name.replace(/\.md$/, ''));
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Loading helpers
+// ---------------------------------------------------------------------------
+/**
+ * Loads a project-scoped agent's markdown content from:
+ *   {projectPath}/.agents/agents/{agentName}.md
+ */
+export async function load_project_agent_file(agentName, projectPath) {
+    validate_asset_name(agentName);
+    const agentsRoot = get_project_agents_root(projectPath);
+    const relative = path.join('agents', `${agentName}.md`);
+    const safePath = safe_project_path(agentsRoot, relative);
+    if (!safePath) {
+        throw new Error(`Path traversal detected for agent name: "${agentName}"`);
+    }
+    try {
+        return await fs.readFile(safePath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Project agent not found: "${agentName}". ` +
+            `Expected file at: ${safePath}`);
+    }
+}
+/**
+ * Loads a project-scoped skill's SKILL.md content from:
+ *   {projectPath}/.agents/skills/{category}/{skillName}/SKILL.md
+ */
+export async function load_project_skill_file(category, skillName, projectPath) {
+    validate_asset_name(category);
+    validate_asset_name(skillName);
+    const agentsRoot = get_project_agents_root(projectPath);
+    const relative = path.join('skills', category, skillName, 'SKILL.md');
+    const safePath = safe_project_path(agentsRoot, relative);
+    if (!safePath) {
+        throw new Error(`Path traversal detected for skill: category="${category}", skillName="${skillName}"`);
+    }
+    try {
+        return await fs.readFile(safePath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Project skill not found: category="${category}", skillName="${skillName}". ` +
+            `Expected SKILL.md at: ${safePath}`);
+    }
+}
+/**
+ * Loads a project-scoped workflow's markdown content from:
+ *   {projectPath}/.agents/workflows/{workflowName}.md
+ */
+export async function load_project_workflow_file(workflowName, projectPath) {
+    validate_asset_name(workflowName);
+    const agentsRoot = get_project_agents_root(projectPath);
+    const relative = path.join('workflows', `${workflowName}.md`);
+    const safePath = safe_project_path(agentsRoot, relative);
+    if (!safePath) {
+        throw new Error(`Path traversal detected for workflow name: "${workflowName}"`);
+    }
+    try {
+        return await fs.readFile(safePath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Project workflow not found: "${workflowName}". ` +
+            `Expected file at: ${safePath}`);
+    }
+}