create-academic-research 0.1.3 → 0.1.5

package/README.md

@@ -35,9 +35,10 @@ adjacent interdisciplinary CS.
 
 The generated repository is agent-neutral. By default the wizard records
 `agent: universal`, installs one shared project-local `.agents/skills` copy,
-and writes generic MCP snippets. Use `--agent <name>` only when you want to
-force a specific target recognized by the `skills` CLI, such as `claude-code`,
-`codex`, `cursor`, `windsurf`, or another supported local loader.
+and writes generic MCP snippets. Use `--agent <id>` only when you want to force
+a specific target recognized by the `skills` CLI. Run
+`npx academic-research agents list` inside a generated project to see every
+supported target and alias.
 
 ## Default Experience
 
@@ -76,6 +77,7 @@ Inside a generated project:
 ```bash
 npx academic-research doctor
 npx academic-research rename --title "New Title" --slug new-title --package new_title
+npx academic-research agents list
 npx academic-research skills presets
 npx academic-research skills install --preset default
 npx academic-research skills install --preset enhanced
@@ -134,8 +136,9 @@ The create wizard can install that project-local package automatically.
 Those skills are portable `SKILL.md` instructions, but they require an
 agent/runtime that can load skills or include the relevant instructions in
 context. They are not automatic capabilities of every raw model API.
-Use `--agent <agent>` for explicit setup, for example `--agent codex` or
-`--agent claude-code`.
+Use `--agent <id>` for explicit setup with any id from
+`academic-research agents list`. The shorthand `--agent claude` is normalized
+to the supported `claude-code` target.
 Avoid `--agent auto` for unattended setup: the upstream `skills` CLI may expand
 it to every agent it detects on the machine.
 
@@ -166,8 +169,8 @@ Releases are tag-driven. Update `package.json` and `package-lock.json`, commit
 the change, create `vX.Y.Z`, and push the tag:
 
 ```bash
-git tag -a v0.1.3 -m "v0.1.3"
-git push origin main v0.1.3
+git tag -a v0.1.5 -m "v0.1.5"
+git push origin main v0.1.5
 ```
 
 Once the GitHub repository is public, the release workflow validates the tag

package/dist/src/agents.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_AGENT = "universal";
+export declare const AUTO_AGENT = "auto";
+export declare const SUPPORTED_SKILL_AGENT_TARGETS: readonly ["adal", "aider-desk", "amp", "antigravity", "augment", "bob", "claude-code", "cline", "codearts-agent", "codebuddy", "codemaker", "codestudio", "codex", "command-code", "continue", "cortex", "crush", "cursor", "deepagents", "devin", "dexto", "droid", "firebender", "forgecode", "gemini-cli", "github-copilot", "goose", "hermes-agent", "iflow-cli", "junie", "kilo", "kimi-cli", "kiro-cli", "kode", "mcpjam", "mistral-vibe", "mux", "neovate", "openclaw", "opencode", "openhands", "pi", "pochi", "qoder", "qwen-code", "replit", "roo", "rovodev", "tabnine-cli", "trae", "trae-cn", "universal", "warp", "windsurf", "zencoder"];
+export declare const AGENT_TARGET_ALIASES: Record<string, string>;
+export declare function normalizeAgentTarget(agent: string | undefined): string;
+export declare function assertKnownAgentTarget(agent: string | undefined): string;
+export declare function formatAgentTargetList(): string;
+export declare function formatSupportedAgentTargetLines(indent?: string, width?: number): string[];
+export declare function formatAgentAliasLines(indent?: string): string[];

package/dist/src/agents.js

@@ -0,0 +1,126 @@
+export const DEFAULT_AGENT = "universal";
+export const AUTO_AGENT = "auto";
+export const SUPPORTED_SKILL_AGENT_TARGETS = [
+    "adal",
+    "aider-desk",
+    "amp",
+    "antigravity",
+    "augment",
+    "bob",
+    "claude-code",
+    "cline",
+    "codearts-agent",
+    "codebuddy",
+    "codemaker",
+    "codestudio",
+    "codex",
+    "command-code",
+    "continue",
+    "cortex",
+    "crush",
+    "cursor",
+    "deepagents",
+    "devin",
+    "dexto",
+    "droid",
+    "firebender",
+    "forgecode",
+    "gemini-cli",
+    "github-copilot",
+    "goose",
+    "hermes-agent",
+    "iflow-cli",
+    "junie",
+    "kilo",
+    "kimi-cli",
+    "kiro-cli",
+    "kode",
+    "mcpjam",
+    "mistral-vibe",
+    "mux",
+    "neovate",
+    "openclaw",
+    "opencode",
+    "openhands",
+    "pi",
+    "pochi",
+    "qoder",
+    "qwen-code",
+    "replit",
+    "roo",
+    "rovodev",
+    "tabnine-cli",
+    "trae",
+    "trae-cn",
+    "universal",
+    "warp",
+    "windsurf",
+    "zencoder"
+];
+export const AGENT_TARGET_ALIASES = {
+    claude: "claude-code",
+    claude_code: "claude-code"
+};
+const SUPPORTED_AGENT_TARGETS = new Set([
+    AUTO_AGENT,
+    ...SUPPORTED_SKILL_AGENT_TARGETS
+]);
+export function normalizeAgentTarget(agent) {
+    const value = agent?.trim();
+    if (!value)
+        return DEFAULT_AGENT;
+    const normalized = value.toLowerCase();
+    return AGENT_TARGET_ALIASES[normalized] ?? normalized;
+}
+export function assertKnownAgentTarget(agent) {
+    const normalized = normalizeAgentTarget(agent);
+    if (!SUPPORTED_AGENT_TARGETS.has(normalized)) {
+        const value = agent?.trim() || DEFAULT_AGENT;
+        throw new Error([
+            `unknown agent target: ${value}`,
+            `Use ${DEFAULT_AGENT}, ${AUTO_AGENT}, or one supported skills.sh agent id.`,
+            "List targets with: npx -p create-academic-research academic-research agents list",
+            `Supported ids: ${specificAgentTargets().join(", ")}`,
+            `Aliases: ${formatAgentAliasesInline()}`
+        ].join("\n"));
+    }
+    return normalized;
+}
+export function formatAgentTargetList() {
+    const lines = [
+        `${DEFAULT_AGENT}\tRecommended shared project-local .agents/skills copy`,
+        `${AUTO_AGENT}\tLet the skills CLI detect installed agents; may create multiple agent-specific copies`,
+        ...specificAgentTargets().map((agent) => `${agent}\tskills.sh agent id`),
+        ...Object.entries(AGENT_TARGET_ALIASES).map(([alias, target]) => `alias\t${alias}\t${target}`)
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function formatSupportedAgentTargetLines(indent = "  ", width = 100) {
+    const labels = specificAgentTargets();
+    const lines = [];
+    let current = indent;
+    for (const label of labels) {
+        const next = current === indent ? label : `, ${label}`;
+        if (current.length + next.length > width) {
+            lines.push(current);
+            current = `${indent}${label}`;
+        }
+        else {
+            current += next;
+        }
+    }
+    if (current.trim())
+        lines.push(current);
+    return lines;
+}
+export function formatAgentAliasLines(indent = "  ") {
+    return Object.entries(AGENT_TARGET_ALIASES).map(([alias, target]) => `${indent}${alias} -> ${target}`);
+}
+function formatAgentAliasesInline() {
+    return Object.entries(AGENT_TARGET_ALIASES)
+        .map(([alias, target]) => `${alias} -> ${target}`)
+        .join(", ");
+}
+function specificAgentTargets() {
+    return SUPPORTED_SKILL_AGENT_TARGETS.filter((agent) => agent !== DEFAULT_AGENT);
+}

package/dist/src/capabilities.d.ts

@@ -1,6 +1,7 @@
+import { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS } from "./agents.js";
 import { type Runner } from "./runner.js";
 import { type McpToolCommandKey } from "./stack.js";
-export declare const DEFAULT_AGENT = "universal";
+export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
 export interface CapabilityState {
     agent: string;
     preset: string;
@@ -51,4 +52,3 @@ export declare function installMcpTools(root: string, servers: string[], runner?
 export declare function uninstallMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function doctorMcpServers(root: string): Promise<McpDoctorResult>;
 export declare function assertKnownMcpServers(servers: string[]): void;
-export {};

package/dist/src/capabilities.js

@@ -1,10 +1,10 @@
 import { appendFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import YAML from "yaml";
+import { assertKnownAgentTarget, AUTO_AGENT, DEFAULT_AGENT, normalizeAgentTarget, SUPPORTED_SKILL_AGENT_TARGETS } from "./agents.js";
 import { defaultRunner } from "./runner.js";
 import { AGENT_STACK, presetMcpServers } from "./stack.js";
-export const DEFAULT_AGENT = "universal";
-const AUTO_AGENT = "auto";
+export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
 export async function readCapabilities(root) {
     try {
         return readCapabilitiesFile(root);
@@ -18,7 +18,7 @@ export async function readCapabilities(root) {
 }
 export async function writeCapabilities(root, state) {
     const next = {
-        agent: normalizeAgent(state.agent),
+        agent: assertKnownAgentTarget(state.agent),
         preset: state.preset ?? "default",
         scope: "project-local",
         mcp_servers: [...(state.mcp_servers ?? [])]
@@ -42,7 +42,7 @@ export async function buildSkillInstallCommands(root, preset = "default", option
     if (!selected)
         throw new Error(`unknown skill preset: ${preset}`);
     const state = await readCapabilities(root);
-    const agent = normalizeAgent(options.agent ?? state.agent);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
     const commands = [];
     for (const bundleName of selected.skill_bundles) {
         const bundle = AGENT_STACK.skill_bundles[bundleName];
@@ -61,7 +61,7 @@ export async function buildSkillInstallCommands(root, preset = "default", option
 }
 export async function installSkills(root, preset = "default", options = {}, runner = defaultRunner) {
     const state = await readCapabilities(root);
-    const agent = normalizeAgent(options.agent ?? state.agent);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
     const commands = await buildSkillInstallCommands(root, preset, options);
     for (const command of commands) {
         await runner.run(command, { cwd: root });
@@ -135,7 +135,7 @@ export async function enableMcpServers(root, servers, options = {}) {
     const selected = dedupe([...(state.mcp_servers ?? []), ...servers]);
     await writeCapabilities(root, {
         ...state,
-        agent: options.agent ?? state.agent,
+        agent: assertKnownAgentTarget(options.agent ?? state.agent),
         mcp_servers: selected
     });
     return { ok: true, servers: selected };
@@ -147,7 +147,7 @@ export async function disableMcpServers(root, servers, options = {}) {
     const selected = (state.mcp_servers ?? []).filter((server) => !blocked.has(server));
     await writeCapabilities(root, {
         ...state,
-        agent: options.agent ?? state.agent,
+        agent: assertKnownAgentTarget(options.agent ?? state.agent),
         mcp_servers: selected
     });
     return { ok: true, servers: selected };
@@ -269,7 +269,7 @@ async function writeCapabilityProfile(root, state) {
     const lines = [
         "# Agent Capability Profile",
         "",
-        `- Agent target: \`${normalizeAgent(state.agent)}\``,
+        `- Agent target: \`${assertKnownAgentTarget(state.agent)}\``,
         `- Preset: \`${state.preset ?? "default"}\``,
         "- Scope: `project-local`",
         "",
@@ -307,7 +307,7 @@ function dedupe(values) {
     return [...new Set(values)];
 }
 function renderSkillCommand(command, agent) {
-    const normalized = normalizeAgent(agent);
+    const normalized = assertKnownAgentTarget(agent);
     const agentFlag = normalized === AUTO_AGENT ? "" : `--agent '${normalized}'`;
     return command.replaceAll("{agent_flag}", agentFlag).replaceAll("{agent}", normalized);
 }
@@ -352,7 +352,7 @@ function splitCommand(command) {
 function normalizeCapabilityState(value) {
     const record = typeof value === "object" && value !== null ? value : {};
     return {
-        agent: normalizeAgent(typeof record.agent === "string" ? record.agent : undefined),
+        agent: assertKnownAgentTarget(typeof record.agent === "string" ? record.agent : undefined),
         preset: typeof record.preset === "string" ? record.preset : "default",
         scope: "project-local",
         mcp_servers: Array.isArray(record.mcp_servers)
@@ -397,12 +397,8 @@ async function removeSkillsFromLock(root, skills) {
         await writeFile(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
     }
 }
-function normalizeAgent(agent) {
-    const value = agent?.trim();
-    return value ? value : DEFAULT_AGENT;
-}
 function mcpSnippetFileName(agent) {
-    const normalized = normalizeAgent(agent);
+    const normalized = normalizeAgentTarget(agent);
     return normalized === DEFAULT_AGENT || normalized === AUTO_AGENT ? "mcp.json" : `${normalized}-mcp.json`;
 }
 async function removeInactiveMcpSnippets(outputDir, activeFile) {

package/dist/src/cli.d.ts

@@ -1,3 +1,4 @@
 type CliMode = "create" | "lifecycle";
 export declare function main(argv?: string[], mode?: CliMode): Promise<number>;
+export declare function formatInteractiveCreateGuide(): string;
 export {};

package/dist/src/cli.js

@@ -5,6 +5,7 @@ import { disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, i
 import { createProject, doctorProject, renameProject } from "./project.js";
 import { askCreateOptions } from "./prompts.js";
 import { AGENT_STACK, presetMcpServers } from "./stack.js";
+import { formatAgentAliasLines, formatAgentTargetList, formatSupportedAgentTargetLines } from "./agents.js";
 import { packageify, slugify, titleFromSlug } from "./names.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 const packageVersion = readPackageVersion();
@@ -16,8 +17,8 @@ const MCP_FLAGS = flagSchema(["help"], ["root", "agent"]);
 export async function main(argv = process.argv.slice(2), mode = "create") {
     try {
         if (mode === "create")
-            return createMain(argv);
-        return lifecycleMain(argv);
+            return await createMain(argv);
+        return await lifecycleMain(argv);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -61,7 +62,7 @@ async function createMain(argv) {
         : undefined;
     const installMcpToolsLock = flagBool(parsed.flags, "install-mcp-tools") ? true : undefined;
     const answers = interactive
-        ? await askCreateOptions(defaults, {
+        ? await askInteractiveCreateOptions(defaults, {
             installSkills: installSkillsLock,
             installMcpTools: installMcpToolsLock
         })
@@ -83,6 +84,10 @@ async function createMain(argv) {
     console.log("Next: cd into the project and run `npx academic-research doctor`.");
     return 0;
 }
+async function askInteractiveCreateOptions(defaults, locks) {
+    console.log(formatInteractiveCreateGuide());
+    return askCreateOptions(defaults, locks);
+}
 async function lifecycleMain(argv) {
     const command = argv[0] ?? "help";
     if (command === "--help" || command === "-h") {
@@ -97,6 +102,8 @@ async function lifecycleMain(argv) {
         return doctorCommand(argv.slice(1));
     if (command === "rename")
         return renameCommand(argv.slice(1));
+    if (command === "agents")
+        return agentsCommand(argv.slice(1));
     if (command === "skills")
         return skillsCommand(argv.slice(1));
     if (command === "mcp")
@@ -133,6 +140,21 @@ async function renameCommand(argv) {
     console.log(`Renamed project to ${result.slug}`);
     return 0;
 }
+async function agentsCommand(argv) {
+    const subcommand = argv[0] ?? "list";
+    const parsed = parseFlags(argv.slice(1), ROOT_FLAGS);
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h" || flagBool(parsed.flags, "help")) {
+        printAgentsHelp();
+        return 0;
+    }
+    if (subcommand === "list") {
+        assertOnlyOptions(parsed.flags, "agents list", []);
+        assertNoArguments(parsed.positionals, "agents list");
+        process.stdout.write(formatAgentTargetList());
+        return 0;
+    }
+    throw new Error(`unknown agents command: ${subcommand}`);
+}
 async function skillsCommand(argv) {
     const subcommand = argv[0] ?? "list";
     const parsed = parseFlags(argv.slice(1), SKILLS_FLAGS);
@@ -388,6 +410,33 @@ function mcpInstallMode(installCommand, runtimeCommand) {
         return installCommand;
     return runtimeCommand ? "runtime-only" : "manual";
 }
+export function formatInteractiveCreateGuide() {
+    const presetLines = Object.entries(AGENT_STACK.presets).map(([name, preset]) => `  ${name.padEnd(10)} ${preset.description}`);
+    return [
+        "Setup choices:",
+        "",
+        "Capability presets:",
+        ...presetLines,
+        "",
+        "Agent target:",
+        "  universal  Recommended. One shared project-local .agents/skills copy.",
+        "  auto       Let the skills CLI detect installed agents; may create multiple agent-specific copies.",
+        "  <id>       Any supported skills.sh agent id.",
+        "",
+        "Supported specific agent ids:",
+        ...formatSupportedAgentTargetLines(),
+        "",
+        "Aliases:",
+        ...formatAgentAliasLines(),
+        "",
+        "Skill and MCP behavior:",
+        "  Skills are copied into the project, not installed globally.",
+        "  MCP records are written into configs/capabilities.yaml and docs/agent/generated/.",
+        "  MCP installers are optional and run only finite installer commands.",
+        "  runtime-only MCP servers are configured for the MCP client but have no install step.",
+        ""
+    ].join("\n");
+}
 function printCreateHelp() {
     console.log([
         "Usage: create-academic-research <project-name> [options]",
@@ -401,7 +450,7 @@ function printCreateHelp() {
         "  --package <name>         Python package name. Default: normalized project name.",
         "  --preset <name>           Capability preset: minimal, default, enhanced, literature, writing, full.",
         "  --profile <name>          Project profile metadata. Default: academic-general.",
-        "  --agent <name>            Agent target. Default: universal.",
+        "  --agent <id>              Agent target: universal, auto, or a supported skills.sh id.",
         "  --install-skills          Install project-local skills without prompting.",
         "  --no-install-skills       Skip project-local skill installation.",
         "  --install-mcp-tools       Run finite external MCP install commands after creation.",
@@ -420,7 +469,7 @@ function printMissingTargetHelp() {
 }
 function printLifecycleHelp() {
     console.log([
-        "Usage: academic-research <doctor|rename|skills|mcp>",
+        "Usage: academic-research <doctor|rename|agents|skills|mcp>",
         "",
         "Manage a generated academic research repository after creation.",
         "",
@@ -429,6 +478,21 @@ function printLifecycleHelp() {
         "  -v, --version            Show package version."
     ].join("\n"));
 }
+function printAgentsHelp() {
+    console.log([
+        "Usage: academic-research agents <list>",
+        "",
+        "List supported project-local agent targets.",
+        "",
+        "Targets:",
+        "  universal                 Recommended shared project-local .agents/skills copy.",
+        "  auto                      Let the skills CLI detect installed agents.",
+        "  <id>                      A supported skills.sh agent id.",
+        "",
+        "Options:",
+        "  -h, --help                Show this help."
+    ].join("\n"));
+}
 function printSkillsHelp() {
     console.log([
         "Usage: academic-research skills <list|status|presets|install|remove|uninstall|update> [options]",
@@ -438,7 +502,7 @@ function printSkillsHelp() {
         "Options:",
         "  --root <path>            Project root for list, status, install, remove, uninstall, update.",
         "  --preset <name>          Capability preset for install.",
-        "  --agent <name>           Agent selector for install. Default: project capability agent.",
+        "  --agent <id>             Agent selector for install. Default: project capability agent.",
         "  -h, --help               Show this help."
     ].join("\n"));
 }
@@ -450,7 +514,7 @@ function printMcpHelp() {
         "",
         "Options:",
         "  --root <path>            Project root for project-state commands.",
-        "  --agent <name>           Agent for enable/disable generated snippets.",
+        "  --agent <id>             Agent for enable/disable generated snippets.",
         "  -h, --help               Show this help."
     ].join("\n"));
 }

package/dist/src/project.js

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { DEFAULT_AGENT, initializeCapabilities, installSkills } from "./capabilities.js";
+import { assertKnownAgentTarget } from "./agents.js";
 import { copyDirectory, exists, isNonEmptyDirectory, movePath, readJson, writeJson } from "./files.js";
 import { packageify, slugify, titleFromSlug } from "./names.js";
 import { AGENT_STACK } from "./stack.js";
@@ -90,9 +91,9 @@ export async function createProject(options) {
     const slug = slugify(options.slug ?? title);
     const packageName = packageify(options.packageName ?? slug);
     const preset = options.preset ?? "default";
-    const agent = options.agent ?? DEFAULT_AGENT;
+    const agent = assertKnownAgentTarget(options.agent ?? DEFAULT_AGENT);
     if (!AGENT_STACK.presets[preset]) {
-        throw new Error(`unknown capability preset: ${preset}`);
+        throw new Error(`unknown capability preset: ${preset}. Expected one of: ${Object.keys(AGENT_STACK.presets).join(", ")}`);
     }
     await mkdir(dirname(target), { recursive: true });
     await copyDirectory(templateRoot, target);
@@ -205,7 +206,7 @@ async function writeGeneratedPackageJson(root, { slug }) {
     const path = join(root, "package.json");
     const data = await readJson(path);
     const existingSpec = data.devDependencies?.["create-academic-research"];
-    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "^0.1.3";
+    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "0.1.5";
     data.name = slug;
     data.devDependencies = {
         ...(data.devDependencies ?? {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-academic-research",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Create and manage agent-ready academic research repositories.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -53,6 +53,7 @@ Project-local skills and MCP records are managed with:
 
 ```bash
 npx academic-research skills presets
+npx academic-research agents list
 npx academic-research skills install --preset default
 npx academic-research skills install --preset enhanced
 npx academic-research skills list

package/template/package.json

@@ -12,6 +12,6 @@
     "mcp:doctor": "academic-research mcp doctor"
   },
   "devDependencies": {
-    "create-academic-research": "^0.1.3"
+    "create-academic-research": "0.1.5"
   }
 }