How to Troubleshoot AI-DLC Rules Not Loading for a Specific IDE

AI-DLC rules fail to load when the IDE adapter cannot locate the CLI binary, inject the rules file into the workspace, or normalize the output, requiring verification of adapter readiness, prerequisite checks, and workspace inspection.

When using the awslabs/aidlc-workflows repository, each supported IDE (Cursor, Kiro, Cline, etc.) loads AI-DLC rules through a specific adapter that implements the IDEAdapter interface. If rules never appear in your IDE session, the breakdown typically occurs during prerequisite validation, workspace preparation, or output normalization.

Verify the IDE Adapter is Discoverable

The CLI entry point scripts/run_ide_evaluation.py uses ide_harness.registry.list_adapters() to enumerate available adapters [run_ide_evaluation.py L82-L85]. If your IDE name is not listed, the adapter package is not on the Python path or the module cannot be imported.

Run the following command to see all registered adapters:

python run_ide_evaluation.py --list

Check that the desired adapter (e.g., cursor) appears with a status of ready. If it shows not ready or error, proceed to the prerequisite check.

Check IDE-Specific Prerequisites

Each adapter implements IDEAdapter.check_prerequisites() to verify the IDE's automation CLI is installed and reachable. For example, the Cursor adapter looks for the agent binary on the $PATH [cursor.py L53-L61].

Execute a targeted check for your specific IDE:

python run_ide_evaluation.py --ide cursor --check-only

A FAIL indicates the binary is missing or not executable. Install the IDE's automation CLI as described in the adapter's docstring before proceeding.

Confirm Rule Files Are Being Copied

During execution, the adapter creates a temporary workspace and writes the rules into an IDE-specific hidden folder. The Cursor adapter creates aidlc-cursor-xxxx under /tmp [cursor.py L90-L94], then reads config.rules_path (default aidlc-rules/) and writes it to .cursor/rules/aidlc-rules.mdc [cursor.py L102-L108].

Run an evaluation while preserving the workspace for inspection:

python run_ide_evaluation.py --ide cursor \
  --vision docs/writing-inputs/example-vision-scientific-calculator-api.md \
  --tech-env docs/writing-inputs/example-tech-env-scientific-calculator-api.md \
  --output-dir ./tmp/run

After the run, examine ./tmp/run/ide-cursor/<temp-id>/ and verify that .cursor/rules/aidlc-rules.mdc exists and contains the full rule set from aidlc-rules/aws-aidlc-rules/core-workflow.md. If the file is missing, double-check the --rules argument or repository checkout path.

Diagnose Adapter-Level Execution Errors

The driver captures the adapter's return value as an AdapterResult. When the subprocess fails, the error message includes the IDE CLI's stderr (populated in cursor.py and a preview of the CLI output.

Inspect the console output for these specific failure patterns:

• "agent CLI exited with code 1": The CLI rejected the prompt, often because the rule file is malformed [cursor.py L53-L58].
• "Required file not found": The vision or tech-env path is incorrect [cursor.py L8-L11].
• Timeout errors: The IDE is running in interactive UI mode instead of headless [cursor.py L88-L99].

Validate the Normalizer Output

After the IDE finishes, each adapter calls ide_harness.normalizer.normalize_output [cursor.py L73-L76]. The normalizer expects the IDE to have produced an aidlc-docs/ folder inside the workspace. If the IDE never emitted those files, the normalizer creates an empty output directory.

Check the final output directory (e.g., runs/sci-calc/ide-cursor/aidlc-docs/). If empty:

1. Confirm the IDE generated files in the temporary workspace before normalization.
2. Verify that the output_dir argument passed to run_ide_evaluation.py matches your inspection path.

You can manually invoke the normalizer for debugging:

from ide_harness.normalizer import normalize_output
from pathlib import Path

workspace = Path("/tmp/aidlc-cursor-abc123")
output = Path("./debug-run/normalized")
normalize_output(
    source_dir=workspace,
    output_dir=output,
    adapter_name="cursor",
    model_hint="ide:cursor",
    elapsed_seconds=12.3,
)

Common IDE-Specific Quirks

IDE	Symptom	Solution
Cursor	The agent CLI requires --force to apply changes without interactive approval.	Ensure you use the built-in run_ide_evaluation.py, which already includes this flag.
Kiro	Uses pexpect-based interactive sessions that stall without a TTY.	Run the script in a real console or set PYTHONUNBUFFERED=1.
Cline	Returns "not ready" immediately.	Install the cline binary and ensure it is on $PATH.
Copilot	Adapter reports "not ready" despite installation.	Run gh auth login or set the GITHUB_TOKEN environment variable for authentication.

Summary

• Adapter discovery: Run --list to verify the IDE adapter is registered and ready according to ide_harness.registry.
• Prerequisites: Use --check-only to confirm the IDE CLI binary is on $PATH via check_prerequisites().
• Rule injection: Inspect the temporary workspace for .cursor/rules/aidlc-rules.mdc (or IDE-equivalent) to confirm the adapter copied files from aidlc-rules/.
• Error analysis: Review stderr capture in AdapterResult for CLI rejection, missing files, or timeouts.
• Normalization: Verify aidlc-docs/ exists in the output directory; if missing, the IDE failed to generate artifacts before normalize_output ran.

Frequently Asked Questions

Why does my IDE adapter show "not ready" when I run --list?

The ide_harness.registry discovers adapters by importing their modules and calling check_prerequisites(). If the IDE's CLI binary (e.g., agent for Cursor, kiro for Kiro) is not on your $PATH, the adapter reports not ready. Install the automation CLI and ensure it is executable in your shell environment.

Where should I look if the rules file is not appearing in the IDE?

First, check the temporary workspace created by the adapter (e.g., /tmp/aidlc-cursor-xxxx). The rules should be injected into an IDE-specific hidden directory like .cursor/rules/aidlc-rules.mdc [cursor.py L102-L108]. If the file is missing, verify your --rules flag points to the correct directory containing aws-aidlc-rules/core-workflow.md.

What causes the "Required file not found" error during execution?

This FileNotFoundError occurs in the adapter's setup phase [cursor.py L8-L11] when the --vision or --tech-env paths provided to run_ide_evaluation.py do not resolve to actual files. Use absolute paths or verify relative paths from your current working directory.

Why is the aidlc-docs/ folder empty after a successful IDE run?

The normalizer expects the IDE to generate an aidlc-docs/ directory inside the temporary workspace [normalizer.py]. If the folder is empty after normalization, the IDE likely exited without creating artifacts, or the CLI command timed out before generation completed. Check the adapter logs for TimeoutExpired or CLI exit code errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}