feat: add interactive CLI installer for multi-agent rule setup by inariku · Pull Request #166 · awslabs/aidlc-workflows

inariku · 2026-04-01T23:42:35Z

Summary

Adds an interactive CLI tool that installs AI-DLC rules to the correct paths for each supported agent, matching the README instructions exactly.

Closes #165

Changes

Added cli/ directory with an npm package (@inariku/aidlc-install)
Single file CLI (src/index.mjs) using @clack/prompts for interactive UI
Supports all 6 documented agents: Kiro, Amazon Q, Cursor, Cline, Claude Code, GitHub Copilot
Install paths match the README exactly for each agent
Features: agent auto-detection, symlink/copy modes, lock file, uninstall, CI flags

User experience

Before: Users manually run multiple mkdir and cp commands per agent, following README instructions.

After:

npx @inariku/aidlc-install

Interactive prompt auto-detects agents and installs rules to the correct paths.

Checklist

I have reviewed the contributing guidelines
I have performed a self-review of this change
Changes have been tested
Changes are documented

Test Plan

Run npx @inariku/aidlc-install in a project directory
Select agents interactively
Verify files are installed to correct paths per README
Run npx @inariku/aidlc-install list to confirm tracking
Run npx @inariku/aidlc-install remove to clean up
Tested all 6 agents on macOS with both symlink and copy modes

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

- Supports all 6 documented agents (Kiro, Amazon Q, Cursor, Cline, Claude Code, GitHub Copilot) - Interactive agent selection with auto-detection - Symlink and copy installation modes - Lock file for tracking installations - Uninstall (remove) and list commands - CI-friendly flags (--yes, --agent, --copy) Refs: awslabs#165

Copilot

Pull request overview

Adds a new Node-based CLI (npx @inariku/aidlc-install) to install/uninstall AI-DLC rule files for multiple supported coding agents, aiming to automate the manual setup steps currently documented in the repo README.

Changes:

Introduces an interactive/non-interactive CLI with agent auto-detection, install mode selection (symlink/copy), and add/remove/list commands.
Adds per-user config + lockfile under ~/.aidlc/ to remember selections and track installed paths for uninstall.
Adds a dedicated cli/ package with documentation and npm metadata.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`cli/src/index.mjs`	Implements the installer/uninstaller CLI, agent definitions, filesystem operations, and lock/config handling.
`cli/README.md`	Documents usage, supported agents, commands, and CI flags.
`cli/package.json`	Defines the published CLI package metadata, bin entry, dependencies, and pack scripts.
`cli/package-lock.json`	Locks npm dependencies for the CLI package.
`cli/.gitignore`	Ignores CLI build artifacts and vendored rule files during packing.

Files not reviewed (1)

cli/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T23:47:19Z

cli/package-lock.json

+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@inariku/aidlc-install",
+      "version": "0.1.0",


package.json is versioned as 0.1.1, but package-lock.json still has 0.1.0 at the root and in packages[""]. This version skew can cause confusing publishes/installs and should be updated to match the package version.

Suggested change

"version": "0.1.0",

"lockfileVersion": 3,

"requires": true,

"packages": {

"": {

"name": "@inariku/aidlc-install",

"version": "0.1.0",

"version": "0.1.1",

"lockfileVersion": 3,

"requires": true,

"packages": {

"": {

"name": "@inariku/aidlc-install",

"version": "0.1.1",

Copilot · 2026-04-01T23:47:19Z

cli/README.md

+| Agent | Install Path |
+|-------|-------------|
+| Kiro | `.kiro/steering/aws-aidlc-rules` |
+| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules` |
+| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` |
+| Cline | `.clinerules/core-workflow.md` |
+| Claude Code | `CLAUDE.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |


The markdown table under "Supported Agents" uses || at the start of each row, which renders as an extra empty column in many renderers. Use a single leading | per row to form a standard 2-column table.

Copilot · 2026-04-01T23:47:19Z

cli/README.md

+| Agent | Install Path |
+|-------|-------------|
+| Kiro | `.kiro/steering/aws-aidlc-rules` |
+| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules` |
+| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` |
+| Cline | `.clinerules/core-workflow.md` |
+| Claude Code | `CLAUDE.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |


The "Supported Agents" table lists only the primary rules path, but the installer also writes the rule-details directory (e.g., .aidlc-rule-details/ or .kiro/aws-aidlc-rule-details). Consider documenting both paths per agent here so users know what files/folders will be created/overwritten.

Suggested change

| Agent | Install Path |

|-------|-------------|

| Kiro | `.kiro/steering/aws-aidlc-rules` |

| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules` |

| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` |

| Cline | `.clinerules/core-workflow.md` |

| Claude Code | `CLAUDE.md` |

| GitHub Copilot | `.github/copilot-instructions.md` |

| Agent | Rules Path | Rule Details Path |

|-------|------------|-------------------|

| Kiro | `.kiro/steering/aws-aidlc-rules` | `.kiro/aws-aidlc-rule-details/` |

| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules` | `.aidlc-rule-details/` |

| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` | `.aidlc-rule-details/` |

| Cline | `.clinerules/core-workflow.md` | `.aidlc-rule-details/` |

| Claude Code | `CLAUDE.md` | `.aidlc-rule-details/` |

| GitHub Copilot | `.github/copilot-instructions.md` | `.aidlc-rule-details/` |

Copilot · 2026-04-01T23:47:20Z

cli/src/index.mjs

+    if (isCancel(choice)) cancel();
+    toRemove = relevant.filter((e) => choice.includes(e.agent));
+  }
+


When remove is invoked with --agent and none of the specified agents are installed for this cwd, toRemove becomes empty and the command still proceeds (prompting "Remove rules for ?" and then doing nothing). Add a guard to error out (or at least outro and exit non-zero) when toRemove.length === 0 after filtering.

Suggested change

if (!toRemove || toRemove.length === 0) {

outro("No matching agents found to remove in this project.");

process.exit(1);

}

Copilot · 2026-04-01T23:47:20Z

cli/src/index.mjs

+  for (const entry of toRemove) {
+    for (const p of entry.paths) {
+      if (existsSync(p)) rmSync(p, { recursive: true });
+    }


remove deletes every path recorded in the global lock file without validating that those paths are inside the current project directory. If ~/.aidlc/lock.json is stale or manually edited, this could delete arbitrary filesystem locations. Before deleting, verify each recorded path starts with cwd (or matches the expected install locations for the agent) and refuse to proceed otherwise.

Copilot · 2026-04-01T23:47:20Z

cli/src/index.mjs

+      const mdc = join(cwd, ".cursor", "rules", "ai-dlc-workflow.mdc");
+      const d = join(cwd, ".aidlc-rule-details");
+      return [
+        { dest: mdc, type: "generate-mdc" },
+        { src: detailsDir, dest: d, type: "dir-contents" },
+      ];
+    },
+    paths: [".cursor/rules/ai-dlc-workflow.mdc", ".aidlc-rule-details/"],


Cursor agent detection includes .cursorrules, but installation always writes to .cursor/rules/ai-dlc-workflow.mdc. If a project uses .cursorrules (and not .cursor), the tool will mark Cursor as detected yet install rules where they may not be picked up. Either align detection to the supported install path or add logic to install into .cursorrules when that's what was detected.

Suggested change

const mdc = join(cwd, ".cursor", "rules", "ai-dlc-workflow.mdc");

const d = join(cwd, ".aidlc-rule-details");

return [

{ dest: mdc, type: "generate-mdc" },

{ src: detailsDir, dest: d, type: "dir-contents" },

];

},

paths: [".cursor/rules/ai-dlc-workflow.mdc", ".aidlc-rule-details/"],

const useCursorRulesDir =

existsSync(join(cwd, ".cursorrules")) && !existsSync(join(cwd, ".cursor"));

const baseDir = useCursorRulesDir ? ".cursorrules" : ".cursor";

const mdc = join(cwd, baseDir, "rules", "ai-dlc-workflow.mdc");

const d = join(cwd, ".aidlc-rule-details");

return [

{ dest: mdc, type: "generate-mdc" },

{ src: detailsDir, dest: d, type: "dir-contents" },

];

},

paths: [

".cursor/rules/ai-dlc-workflow.mdc",

".cursorrules/rules/ai-dlc-workflow.mdc",

".aidlc-rule-details/",

],

Copilot · 2026-04-01T23:47:20Z

cli/src/index.mjs

+    value: "claude",
+    label: "Claude Code",
+    hint: "CLAUDE.md",
+    detect: [".claude", "CLAUDE.md"],
+    // cp core-workflow.md ./CLAUDE.md  +  cp -R aws-aidlc-rule-details/* .aidlc-rule-details/
+    install(cwd) {
+      const r = join(cwd, "CLAUDE.md");
+      const d = join(cwd, ".aidlc-rule-details");
+      return [
+        { src: coreWorkflow, dest: r, type: "file" },
+        { src: detailsDir, dest: d, type: "dir-contents" },
+      ];
+    },
+    paths: ["CLAUDE.md", ".aidlc-rule-details/"],
+  },


Claude Code detection includes .claude, but installation always writes to ./CLAUDE.md in the project root. The upstream README documents .claude/CLAUDE.md as an alternative supported location; as written, projects already using .claude/ will be detected but still get the file installed to the root. Consider prompting for (or auto-selecting) the target location based on what exists in the repo, to better match the documented setup options.

Copilot · 2026-04-01T23:47:20Z

cli/src/index.mjs

+  if (op.type === "file") {
+    mkdirSync(dirname(op.dest), { recursive: true });
+    copyFileSync(op.src, op.dest);
+    return "copy";
+  }


In "symlink" mode, file operations (Cline / Claude / Copilot core workflow) are still copied via copyFileSync, so these installs will not auto-update even though the UI describes symlink mode as linking to source. Either implement file symlinks for op.type === "file" when mode === "symlink", or adjust the mode description/output so users aren't misled.

Copilot · 2026-04-01T23:47:21Z

cli/src/index.mjs

+} else {
+  runAdd();


Unknown positionals are treated as the default add command (anything other than remove/list falls through to runAdd()). This can mask typos like aidlc-install remvoe. Consider validating command against an allowlist (add, remove, list) and showing help / exiting non-zero on unknown commands.

Suggested change

} else {

runAdd();

} else if (!command || command === "add") {

runAdd();

} else {

console.error(`Unknown command: ${command}`);

showHelp();

process.exitCode = 1;

Copilot · 2026-04-01T23:47:21Z

cli/src/index.mjs

+function trySymlink(src, dest) {
+  try {
+    mkdirSync(dirname(dest), { recursive: true });
+    if (existsSync(dest)) rmSync(dest, { recursive: true });
+    symlinkSync(src, dest, "dir");
+    return true;


trySymlink() uses existsSync(dest) to decide whether to remove the destination before creating a new symlink. existsSync returns false for broken symlinks (it stats the target), so an existing broken link at dest can cause symlinkSync to throw EEXIST and force an unnecessary fallback to copy. Consider using lstatSync/rmSync(dest, { force: true }) (or a try/catch around rmSync) to reliably remove an existing symlink even when its target is missing.

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

cli/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T23:54:55Z

cli/src/index.mjs

+  if (op.type === "dir-contents") {
+    if (mode === "symlink" && trySymlink(op.src, op.dest)) return "symlink";
+    copyDirContents(op.src, op.dest);
+    return "copy";
+  }


Same overwrite concern for dir-contents: if .aidlc-rule-details already exists (or is a symlink), cpSync will copy into/over it rather than replacing it cleanly. Consider removing the destination first when overwriting to keep installs deterministic.

Copilot · 2026-04-01T23:54:56Z

cli/src/index.mjs

+  } else if (flags.agent.length > 0) {
+    toRemove = relevant.filter((e) => flags.agent.includes(e.agent));
+  } else {


If --agent is provided, toRemove = relevant.filter(...) can produce an empty list when none of the requested agents are installed in this cwd. Add a toRemove.length === 0 check before the confirmation prompt and exit with a clear message (and optionally a non-zero status).

Copilot · 2026-04-01T23:54:56Z

cli/src/index.mjs

+  if (op.type === "dir") {
+    if (mode === "symlink" && trySymlink(op.src, op.dest)) return "symlink";
+    copyDir(op.src, op.dest);
+    return "copy";
+  }


For directory installs, the copy path doesn’t remove an existing destination before cpSync. Since the flow warns about overwriting, delete op.dest first (including if it’s a symlink from a prior install) to avoid merges/nesting or copying into a symlink target.

Copilot · 2026-04-01T23:54:56Z

cli/README.md

+| Agent | Install Path |
+|-------|-------------|
+| Kiro | `.kiro/steering/aws-aidlc-rules` |
+| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules` |
+| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` |
+| Cline | `.clinerules/core-workflow.md` |
+| Claude Code | `CLAUDE.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+


The “Supported Agents” table omits the rule-details destinations that are also installed (e.g. .aidlc-rule-details/, .kiro/aws-aidlc-rule-details, .amazonq/aws-aidlc-rule-details). Update this section to include both installed paths so the docs match actual installer behavior.

Suggested change

| Agent | Install Path |

|-------|-------------|

| Kiro | `.kiro/steering/aws-aidlc-rules` |

| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules` |

| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` |

| Cline | `.clinerules/core-workflow.md` |

| Claude Code | `CLAUDE.md` |

| GitHub Copilot | `.github/copilot-instructions.md` |

| Agent | Install Path(s) |

|-------|-----------------|

| Kiro | `.kiro/steering/aws-aidlc-rules`, `.kiro/aws-aidlc-rule-details` |

| Amazon Q Developer | `.amazonq/rules/aws-aidlc-rules`, `.amazonq/aws-aidlc-rule-details` |

| Cursor IDE | `.cursor/rules/ai-dlc-workflow.mdc` |

| Cline | `.clinerules/core-workflow.md` |

| Claude Code | `CLAUDE.md` |

| GitHub Copilot | `.github/copilot-instructions.md` |

The installer also creates a workspace-level `.aidlc-rule-details/` directory that contains shared rule details, alongside the per-agent rule-details directories such as `.kiro/aws-aidlc-rule-details` and `.amazonq/aws-aidlc-rule-details`.

Riku Inada added 3 commits April 2, 2026 07:48

fix: bin path and file permissions

eee2285

docs: add README and bump to 0.1.1

14dbb20

inariku requested review from a team, Copilot, harmjeff, raj-jain-aws, scottschreckengaust and spraja08 April 1, 2026 23:42

inariku requested a review from a team as a code owner April 1, 2026 23:42

github-actions bot added the documentation Improvements or additions to documentation label Apr 1, 2026

Copilot started reviewing on behalf of inariku April 1, 2026 23:43 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

Riku Inada added 2 commits April 2, 2026 08:48

fix: use Node.js for prepack/postpack scripts for Windows compatibility

4537d41

docs: add interactive CLI installer option to Quick Start

c333ec3

Copilot AI review requested due to automatic review settings April 1, 2026 23:50

Copilot started reviewing on behalf of inariku April 1, 2026 23:50 View session

docs: use scope-free package name for portability

ad8df56

Copilot AI reviewed Apr 1, 2026

View reviewed changes

+  if (!toRemove || toRemove.length === 0) {
+    outro("No matching agents found to remove in this project.");
+    process.exit(1);
+  }

Conversation

inariku commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

User experience

Checklist

Test Plan

Acknowledgment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

inariku commented Apr 1, 2026 •

edited

Loading