@kuznai/inception-engine 0.10.1 → 0.11.1

package/README.md

@@ -1,11 +1,15 @@
 # inception-engine
 
-Plant skills directly into the minds of your installed AI coding agents — Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, and GitHub Copilot. One command. They'll think they thought of it themselves.
+Plant skills directly into the minds of your installed AI coding agents — Claude Code, Codex, Gemini CLI, Antigravity, and OpenCode. One command. They'll think they thought of it themselves.
 
 Today, inception-engine works as a cross-agent deployer for skills on all listed agents, plus single-file writes and JSON config patches. It also supports MCP server registration and global rules-file deployment for the subset of agents whose config surfaces are implemented and validated today.
 
+GitHub Copilot is no longer treated as a separate instruction or skill target in the product direction when it can consume Claude-native artifacts directly. If Copilot uses `CLAUDE.md` or Claude-style skill layouts without translation, inception-engine should rely on the Claude deployment path instead of maintaining duplicate Copilot-specific surfaces. Dedicated Copilot customization remains justified only where Copilot exposes a materially different interface, such as MCP-related configuration.
+
 The broader portability layer is the roadmap direction, but this README focuses on what is working now.
 
+`init` is available as a bootstrap command, but what works today is intentionally narrow: it scans for directories containing `SKILL.md` and generates starter `skills` entries plus empty `mcpServers` and `agentRules` arrays. It does not infer `files`, `configs`, MCP server definitions, or rules files from the repository yet.
+
 ## Quick Start
 
 ```bash
@@ -32,7 +36,6 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Gemini CLI | `gemini-cli` | `~/.gemini/skills/` | Yes | Yes | Yes |
 | Antigravity | `antigravity` | `~/.gemini/antigravity/skills/` | Yes* | Yes* | Yes* |
 | OpenCode | `opencode` | `~/.config/opencode/skills/` | Yes | Yes | Yes* |
-| GitHub Copilot | `github-copilot` | `~/.copilot/skills/` | Yes | Yes | Yes |
 
 \* Antigravity support is currently based on the implementation's registry path assumptions and local validation, not a strong official doc set equivalent to the other agents.
 
@@ -46,10 +49,13 @@ Managed skills overwrite their previous version. If a target exists but was not
 | File write | All agents via manifest and CLI | All agents |
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
 | MCP Servers | claude-code, gemini-cli; other agents are warned and skipped | claude-code, gemini-cli |
-| Global Rules Files | claude-code, codex, gemini-cli, opencode; other agents are warned and skipped | claude-code, codex, gemini-cli, opencode |
+| Global Rules Files | claude-code, codex, gemini-cli, opencode; github-copilot reads CLAUDE.md natively (deploy via claude-code); other agents are warned and skipped | claude-code, codex, gemini-cli, opencode |
+| `init` manifest generation | Scans `SKILL.md` directories and writes starter `skills` entries | N/A |
 
 Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
 
+For GitHub Copilot specifically, the portability rule is Claude-first: if Copilot accepts the same Claude-native instruction or skill artifact, inception-engine should not add a separate Copilot deployment feature for it.
+
 ## Manifest Format
 
 Create an `inception.json` file at the root of your skills directory:
@@ -60,7 +66,7 @@ Create an `inception.json` file at the root of your skills directory:
     {
       "name": "my-skill",
       "path": "skills/my-skill",
-      "agents": ["claude-code", "codex", "gemini-cli", "antigravity", "opencode", "github-copilot"]
+      "agents": ["claude-code", "codex", "gemini-cli", "antigravity", "opencode"]
     }
   ],
   "files": [
@@ -132,7 +138,7 @@ Each **agentRules** entry deploys a Markdown instruction file to an agent's supp
 - **path** - Relative path to the source Markdown file within the repo
 - **agents** - Array of agent IDs to deploy this file to
 
-Global rules-file deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). Other agents emit a warning and are skipped because their instruction surfaces are different, repo-scoped, or not implemented here yet. Revert removes the deployed rules file.
+Global rules-file deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). For `github-copilot`, no separate deployment is needed because Copilot reads `CLAUDE.md` natively — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Other agents emit a warning and are skipped because their instruction surfaces are different, repo-scoped, or not yet implemented. Revert removes the deployed rules file.
 
 ## Creating Skills
 
@@ -151,11 +157,30 @@ Instructions for the AI agent...
 
 The `name` and `description` fields in the frontmatter are used by most agents. The description determines when the agent activates the skill. inception-engine does not currently validate the frontmatter — missing or malformed fields may cause the skill to be ignored or misbehave at the agent level.
 
+## `init` Command
+
+`init` is meant to bootstrap a repository that already has skill folders. It recursively scans the target directory, treats any directory containing `SKILL.md` as a skill, and writes a starter `inception.json`.
+
+Current `init` behavior:
+
+- Generates `skills` entries using the discovered relative paths
+- Uses the directory name as the manifest skill name
+- Applies either the `--agents` list or all currently known agent IDs
+- Refuses to overwrite an existing `inception.json` unless `--force` is provided
+- Supports `--dry-run` so you can inspect the generated manifest before writing it
+
+Current `init` limitations:
+
+- It does not read or validate YAML frontmatter inside `SKILL.md`
+- It does not infer `files`, `configs`, `mcpServers`, or `agentRules`
+- It does not reconcile generated output with the longer-term Claude-first portability direction
+
 ## CLI Reference
 
 ```
 inception-engine <directory> [options]
 inception-engine revert <directory> [options]
+inception-engine init <directory> [options]
 ```
 
 ### Commands
@@ -164,6 +189,7 @@ inception-engine revert <directory> [options]
 |---|---|
 | `<directory>` | Deploy skills from the manifest in the given directory |
 | `revert <directory>` | Remove previously deployed skills declared in the manifest |
+| `init <directory>` | Scan a directory for skill folders and generate `inception.json` |
 
 ### Options
 
@@ -171,6 +197,7 @@ inception-engine revert <directory> [options]
 |---|---|
 | `--dry-run` | Show what would be done without making changes |
 | `--agents <list>` | Comma-separated list of agent IDs to target (overrides deploy detection; restricts revert) |
+| `--force` | `init` only; overwrite an existing `inception.json` |
 | `--verbose` | Show detailed output including file paths |
 | `--debug` | Show full error stack traces |
 | `--help` | Show help message |
@@ -192,6 +219,12 @@ npx @kuznai/inception-engine revert ./my-skills-repo
 
 # Preview what would be removed
 npx @kuznai/inception-engine revert ./my-skills-repo --dry-run
+
+# Generate a starter manifest from discovered skill folders
+npx @kuznai/inception-engine init ./my-skills-repo
+
+# Preview the generated manifest without writing it
+npx @kuznai/inception-engine init ./my-skills-repo --dry-run
 ```
 
 ## Sample Skills
@@ -201,6 +234,7 @@ The `limbo/` directory contains exceptional sample skills for testing purposes o
 Try them out:
 
 ```bash
+npx @kuznai/inception-engine init limbo --dry-run
 npx @kuznai/inception-engine limbo --dry-run
 ```
 

package/dist/config/agents.js

@@ -139,7 +139,10 @@ export const AGENT_REGISTRY = [
             detectPaths: "documented",
             detectBinary: "documented",
         },
-        // mcpConfigPath and agentRulesPath omitted: rules live in repo, not home dir; MCP config unclear
+        // agentRulesPath omitted: Copilot reads CLAUDE.md natively (Claude-first portability rule).
+        // Deploy via the "claude-code" agentRules entry — it reaches Copilot automatically.
+        // mcpConfigPath omitted: Copilot MCP config surface is not implemented here yet.
+        claudeNativeInstruction: true,
         policyNote: "Organization policies may override locally deployed skills. Verify with your GitHub org admin if deployed skills are not active.",
     },
 ];

package/dist/core/adapters/rules.js

@@ -16,6 +16,13 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     await validateSourceFile(source, entry.path);
     for (const agentId of targetAgents) {
         const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (agent?.claudeNativeInstruction) {
+            warnings.push({
+                kind: "confidence",
+                message: `agentRules: agent "${agentId}" reads CLAUDE.md natively — deploy via "claude-code" target to reach Copilot automatically; no separate deployment needed`,
+            });
+            continue;
+        }
         if (!agent?.agentRulesPath) {
             warnings.push({
                 kind: "confidence",

package/dist/core/init.d.ts

@@ -0,0 +1,9 @@
+import type { AgentId } from "../schemas/manifest.ts";
+export interface InitOptions {
+    directory: string;
+    agents: AgentId[] | null;
+    dryRun: boolean;
+    force: boolean;
+    verbose: boolean;
+}
+export declare function runInit(options: InitOptions): Promise<number>;

package/dist/core/init.js

@@ -0,0 +1,99 @@
+import { access, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { dryRunPrefix, logger } from "../logger.js";
+import { AGENT_IDS } from "../schemas/manifest.js";
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+async function findSkillDirs(baseDir, dir, found) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return;
+    }
+    const hasSkillMd = entries.some((e) => e.isFile() && e.name === "SKILL.md");
+    if (hasSkillMd) {
+        const relPath = path.relative(baseDir, dir).split(path.sep).join("/");
+        const name = path.basename(dir);
+        if (SAFE_NAME_RE.test(name)) {
+            found.push({ relPath, name });
+        }
+        else {
+            logger.warn("init", `Skipping "${relPath}": directory name "${name}" is not a valid skill name`);
+        }
+        // Don't recurse into a skill directory
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+            await findSkillDirs(baseDir, path.join(dir, entry.name), found);
+        }
+    }
+}
+function resolveSkillName(relPath, name, namesSeen) {
+    if (!namesSeen.has(name))
+        return name;
+    // Collision: derive unique name from path by replacing separators with hyphens
+    const derived = relPath.replace(/\//g, "-");
+    if (SAFE_NAME_RE.test(derived))
+        return derived;
+    logger.warn("init", `Skipping "${relPath}": could not generate a unique valid name (collision with "${name}")`);
+    return null;
+}
+function buildSkills(found, agents) {
+    const namesSeen = new Set();
+    const skills = [];
+    for (const { relPath, name } of found) {
+        const skillName = resolveSkillName(relPath, name, namesSeen);
+        if (skillName === null)
+            continue;
+        namesSeen.add(skillName);
+        skills.push({ name: skillName, path: relPath, agents });
+    }
+    return skills;
+}
+async function manifestExists(manifestPath) {
+    try {
+        await access(manifestPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runInit(options) {
+    const { directory, dryRun, force, verbose } = options;
+    const agents = options.agents ?? [...AGENT_IDS];
+    const manifestPath = path.join(directory, "inception.json");
+    if (!dryRun && (await manifestExists(manifestPath)) && !force) {
+        logger.error(`Error: ${manifestPath} already exists. Use --force to overwrite.`);
+        return 2;
+    }
+    const found = [];
+    await findSkillDirs(directory, directory, found);
+    if (found.length === 0) {
+        logger.info("No skill directories found (looking for directories containing SKILL.md).");
+        return 0;
+    }
+    const skills = buildSkills(found, agents);
+    if (skills.length === 0) {
+        logger.info("No skills could be added to the manifest.");
+        return 0;
+    }
+    const manifest = { skills, mcpServers: [], agentRules: [] };
+    const json = `${JSON.stringify(manifest, null, 2)}\n`;
+    if (dryRun) {
+        logger.info(`${dryRunPrefix(true)}Would write ${manifestPath} with ${skills.length} skill(s):`);
+        logger.info("");
+        logger.info(json);
+        return 0;
+    }
+    await writeFile(manifestPath, json, "utf-8");
+    logger.info(`Generated ${manifestPath} with ${skills.length} skill(s).`);
+    if (verbose) {
+        for (const s of skills) {
+            logger.detail(`${s.name}  →  ${s.path}`);
+        }
+    }
+    return 0;
+}

package/dist/index.js

@@ -5,6 +5,7 @@ import { AGENT_REGISTRY } from "./config/agents.js";
 import { loadManifest } from "./config/manifest.js";
 import { executeDeploy, planDeploy } from "./core/deploy.js";
 import { detectInstalledAgents } from "./core/detect.js";
+import { runInit } from "./core/init.js";
 import { runPreflight } from "./core/preflight.js";
 import { resolveHome } from "./core/resolve.js";
 import { executeRevert, planRevert, planRevertAll } from "./core/revert.js";
@@ -17,10 +18,17 @@ inception-engine - Deploy AI agent skills
 Usage:
   inception-engine <directory> [options]
   inception-engine revert <directory> [options]
+  inception-engine init <directory> [options]
+
+Commands:
+  <directory>         Deploy skills from the manifest in the given directory
+  revert <directory>  Remove previously deployed skills
+  init <directory>    Scan a directory for skill folders and generate inception.json
 
 Options:
   --dry-run        Show what would be done without doing it
   --agents <list>  Comma-separated list of agent IDs to target
+  --force          (init only) Overwrite an existing inception.json
   --verbose        Show detailed output
   --debug          Show full error stack traces
   --help           Show this help message
@@ -38,6 +46,7 @@ function parseCLI(argv) {
             agents: null,
             verbose: false,
             debug: false,
+            force: false,
         };
     }
     let parsed;
@@ -50,6 +59,7 @@ function parseCLI(argv) {
                 verbose: { type: "boolean", default: false },
                 debug: { type: "boolean", default: false },
                 help: { type: "boolean", default: false },
+                force: { type: "boolean", default: false },
                 agents: { type: "string" },
             },
         });
@@ -66,6 +76,7 @@ function parseCLI(argv) {
             agents: null,
             verbose: false,
             debug: false,
+            force: false,
         };
     }
     let command = "deploy";
@@ -74,6 +85,10 @@ function parseCLI(argv) {
         command = "revert";
         pos = pos.slice(1);
     }
+    else if (pos[0] === "init") {
+        command = "init";
+        pos = pos.slice(1);
+    }
     if (pos.length > 1) {
         throw new UserError("INVALID_ARGS", `Unexpected argument: ${pos[1]}`);
     }
@@ -96,6 +111,7 @@ function parseCLI(argv) {
         agents,
         verbose: values.verbose,
         debug: values.debug,
+        force: values.force,
     };
 }
 async function main() {
@@ -104,6 +120,15 @@ async function main() {
         console.log(USAGE);
         return 0;
     }
+    if (options.command === "init") {
+        return runInit({
+            directory: options.directory,
+            agents: options.agents,
+            dryRun: options.dryRun,
+            force: options.force,
+            verbose: options.verbose,
+        });
+    }
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
     if (options.command === "deploy") {

package/dist/types.d.ts

@@ -21,6 +21,7 @@ export interface AgentConfig {
     provenance: AgentProvenance;
     mcpConfigPath?: AgentPaths;
     agentRulesPath?: AgentPaths;
+    claudeNativeInstruction?: true;
     policyNote?: string;
 }
 export interface PlanWarning {
@@ -85,10 +86,11 @@ export interface PlannedChange {
     confidence?: Confidence;
 }
 export interface CliOptions {
-    command: "deploy" | "revert" | "help";
+    command: "deploy" | "revert" | "init" | "help";
     directory: string;
     dryRun: boolean;
     agents: AgentId[] | null;
     verbose: boolean;
     debug: boolean;
+    force: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",