# ASDM Bootstrapper Installation Guide for AI Agents

This guide provides simple step-by-step instructions for AI agents to automatically install and use the ASDM Bootstrapper CLI tool.

## Installation Overview (Step List)

The complete installation process consists of **7 main steps** (plus prerequisites):

| # | Step | Description |
|---|------|-------------|
| 0 | **Prerequisites** | Verify Node.js environment (Node.js 16+, npm) |
| 1 | **Install ASDM CLI** | Install CLI via npm (recommended) or standalone binary (Windows fallback) |
| 2 | **Detect AI Coding Tool** | Detect current provider (Claude Code / GitHub Copilot / CodeBuddy) |
| 3 | **Generate Commands** | Generate `/asdm-toolset-list` and `/asdm-toolset-install` commands |
| 4 | **Add Default Rules** | Auto-detect tech stack & generate build rules (`asdm-default-rules.mdc`) |
| 5 | **Show Introduction** | Display welcome message and key features overview |
| 6 | **List Toolsets** | List available toolsets from registry |
| 7 | **Verify & Cleanup** | Validate configuration integrity and clean up temporary files |

---

## Prerequisites: Verify Node.js Environment

Before installation, check that Node.js and npm are available:

```bash
node --version
npm --version
```

**Expected Result**: 
- Node.js version 16 or higher
- npm version should be displayed

**If not installed**: Install Node.js from https://nodejs.org/ or use a package manager like `nvm`, `apt`, `brew`, etc.

## Step 1: Install ASDM CLI

### Method A: Install from NPM (Recommended)

Install the ASDM Bootstrapper CLI globally using npm:

```bash
npm install -g @leansoftx/asdm-bootstrapper-cli
```

**Expected Result**: CLI tool installed globally, `asdm` command is now available.

**If npm installation succeeds**, proceed to Step 2.

### Method B: Download Standalone Binary (Windows Only)

If the npm installation fails (e.g., due to network issues, npm registry unavailability, or Node.js incompatibility), you can use the standalone binary as a fallback.

> **⚠️ Platform Restriction**: This method only supports **Windows** environments. If your environment is **not Windows** (e.g., macOS, Linux), please **contact your ASDM administrator** to obtain the ASDM CLI tool manually.

**Step B.1: Download the installation package**

Download the latest CLI package from the ASDM server. The `{server-url}` is the same server address where you obtained this INSTALL.md document.

```bash
# Replace {server-url} with the actual server address (e.g., https://platform.asdm.ai)
curl -L -o asdm-cli-win-latest.zip "{server-url}/_artifacts/downloads/asdm-cli/asdm-cli-win-latest.zip"
```

Alternatively, you can open the following URL directly in a browser to download:

```
{server-url}/_artifacts/downloads/asdm-cli/asdm-cli-win-latest.zip
```

**Step B.2: Extract and install**

Extract the downloaded zip file and place the `asdm-cli.exe` in the user's ASDM CLI directory:

```powershell
# Create the target directory
mkdir -Force "$env:USERPROFILE\.asdm\cli"

# Extract the zip and place the exe
Expand-Archive -Path asdm-cli-win-latest.zip -DestinationPath asdm-cli-temp -Force
Copy-Item -Path asdm-cli-temp\asdm-cli.exe -Destination "$env:USERPROFILE\.asdm\cli\asdm-cli.exe"

# Clean up temporary files
Remove-Item -Path asdm-cli-temp -Recurse -Force
Remove-Item -Path asdm-cli-win-latest.zip -Force
```

After extraction, the CLI binary will be located at:

```
%USERPROFILE%\.asdm\cli\asdm-cli.exe
```

Which resolves to: `C:\Users\<your-username>\.asdm\cli\asdm-cli.exe`

**Step B.3: Add to PATH environment variable**

Add the ASDM CLI directory to your `PATH` so you can run `asdm` from any terminal:

```powershell
# Add to PATH for the current user (persistent)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:USERPROFILE\.asdm\cli", "User")
```

**Step B.4: Verify installation**

> **⚠️ Important**: After adding the directory to PATH, you **must restart your terminal / command prompt / PowerShell** for the PATH change to take effect. Close and reopen your terminal, then run:

```bash
asdm --version
```

**Expected Result**: The ASDM CLI version number is displayed, confirming the installation is successful.

**If `asdm` command is still not found after restarting the terminal**, try using the full path directly:

```bash
"%USERPROFILE%\.asdm\cli\asdm-cli.exe" --version
```

If the full path works but `asdm` alone does not, you may need to log out and log back into your Windows session for the PATH change to propagate.

## Language Detection

Before executing any installation steps or interacting with the user, you must detect and use the current environment's response language:

1. **Detect Response Language**: Analyze the environment settings to determine the primary language:
   - Check system/user language settings or environment configuration
   - Identify the primary language used in project documentation and comments
   - Determine the language preference based on workspace context

2. **Apply Language Consistency**: Ensure all generated content uses the detected language:
   - Use the same language for all installation instructions, prompts, error messages, and guidance
   - Maintain language consistency across all interactions with the user
   - Follow the detected language's writing conventions and formatting

3. **Supported Languages**:
   - English (en)
   - Chinese (zh)
   - Other languages as needed based on environment detection

**IMPORTANT**: The language detection is the FIRST step before any installation or user interaction. All output must consistently use the detected language throughout the entire process.

## Step 2: Detect the current AI Coding Tool provider

After installing the ASDM CLI, detect the current AI coding assistant provider (e.g., Claude Code, GitHub Copilot, Tencent CodeBuddy). Using the following guidelines to detect the provider:

- If `.claude` directory exists, use `Claude Code`
- If `.github` directory exists, use `GitHub Copilot`
- If `.codebuddy` directory exists, use `Tencent CodeBuddy`
- If no such folder is found in the current workspace, give user a prompt to select a provider manually

## Step 3: Generate ASDM commands for your AI Coding Tool

Based on the detected AI Coding Tool provider, generate the appropriate command files in the provider's commands directory:

### For Claude Code (`.claude/commands/`):

```bash
mkdir -p .claude/commands/

# asdm-toolset-list command
cat > .claude/commands/asdm-toolset-list.md << 'EOF'
---
description: "List available ASDM toolsets"
---

List available ASDM toolsets for the current workspace.

Use this command when the user requests to view or list ASDM toolsets, e.g., `/asdm-toolset-list`

Execute the following steps:

1. **Detect ASDM CLI**: Check if ASDM CLI is installed on the system (via `asdm --version` command). If not installed, prompt the user to install ASDM CLI first.

2. **Execute list command**: Run `asdm toolset list` command to get the available toolsets list.

3. **Parse output**: Parse the command output and extract toolset information (ID, Name, Description, Version).

4. **Display results**: Display available toolsets to the user in a table format, including:
   - Toolset ID
   - Toolset Name
   - Description
   - Version

5. **Provide installation guidance**: Tell the user how to install the specified toolset, e.g.:
   - Use `/asdm-toolset-install <toolset-id>` command to install

If any error occurs during execution, interrupt and prompt the user to handle manually.
EOF

# asdm-toolset-install command
cat > .claude/commands/asdm-toolset-install.md << 'EOF'
---
description: "Install an ASDM toolset to the current workspace"
argument-hint: "[toolset-id]"
---

Install an ASDM toolset to the current workspace.

Use this command when the user requests to install an ASDM toolset, e.g., `/asdm-toolset-install prd-builder`

Execute the following steps:

1. **Detect ASDM CLI**: Check if ASDM CLI is installed on the system (via `asdm --version` command). If not installed, prompt the user to install ASDM CLI first.

2. **Install toolset**: Run `asdm toolset install {toolset-id}` command to install the specified toolset, where `{toolset-id}` is the toolset ID provided by the user (e.g., prd-builder, context-builder).

3. **Execute installation script**: After installation is complete, read and execute all installation steps from the INSTALL.md file in the toolset installation directory:
   - Read `.asdm/toolsets/{toolset-id}/INSTALL.md`
   - Follow the "Installation Steps" section in the documentation step by step
   - Create necessary directory structure
   - Detect the current AI Coding tool type (Claude Code/GitHub Copilot/Tencent CodeBuddy), and create corresponding shortcut command files based on the detection results

4. **Verify installation**: Check if the installation was successful, including:
   - Whether the toolset directory exists in `.asdm/toolsets/{toolset-id}/`
   - **Whether the AI Coding tool shortcut command files exist**:
     - If Claude Code: Check if the corresponding command file exists in `.claude/commands/`
     - If GitHub Copilot: Check if the corresponding prompt file exists in `.github/prompts/`
     - If Tencent CodeBuddy: Check if the corresponding command file exists in `.codebuddy/commands/`
   - **List the created shortcut commands** for easy use by the user

5. **Summarize report**: Report the installation results to the user, including successfully installed content and available commands.

If any error occurs during installation, interrupt and prompt the user to handle manually.
EOF
```

### For GitHub Copilot (`.github/prompts/`):

```bash
mkdir -p .github/prompts/

# asdm-toolset-list prompt
cat > .github/prompts/asdm-toolset-list.prompt.md << 'EOF'
---
agent: 'agent'
description: 'List available ASDM toolsets'
---

List available ASDM toolsets for the current workspace.

Use this command when the user requests to view or list ASDM toolsets, e.g., `/asdm-toolset-list`

Execute the following steps:

1. **Detect ASDM CLI**: Check if ASDM CLI is installed on the system (via `asdm --version` command). If not installed, prompt the user to install ASDM CLI first.

2. **Execute list command**: Run `asdm toolset list` command to get the available toolsets list.

3. **Parse output**: Parse the command output and extract toolset information (ID, Name, Description, Version).

4. **Display results**: Display available toolsets to the user in a table format, including:
   - Toolset ID
   - Toolset Name
   - Description
   - Version

5. **Provide installation guidance**: Tell the user how to install the specified toolset, e.g.:
   - Use `/asdm-toolset-install <toolset-id>` command to install

If any error occurs during execution, interrupt and prompt the user to handle manually.
EOF

# asdm-toolset-install prompt
cat > .github/prompts/asdm-toolset-install.prompt.md << 'EOF'
---
agent: 'agent'
description: 'Install an ASDM toolset to the current workspace'
argument-hint: 'Enter toolset ID'
---

Install an ASDM toolset to the current workspace.

Use this command when the user requests to install an ASDM toolset, e.g., `/asdm-toolset-install prd-builder`

Execute the following steps:

1. **Detect ASDM CLI**: Check if ASDM CLI is installed on the system (via `asdm --version` command). If not installed, prompt the user to install ASDM CLI first.

2. **Install toolset**: Run `asdm toolset install {toolset-id}` command to install the specified toolset, where `{toolset-id}` is the toolset ID provided by the user (e.g., prd-builder, context-builder).

3. **Execute installation script**: After installation is complete, read and execute all installation steps from the INSTALL.md file in the toolset installation directory:
   - Read `.asdm/toolsets/{toolset-id}/INSTALL.md`
   - Follow the "Installation Steps" section in the documentation step by step
   - Create necessary directory structure
   - Detect the current AI Coding tool type (Claude Code/GitHub Copilot/Tencent CodeBuddy), and create corresponding shortcut command files based on the detection results

4. **Verify installation**: Check if the installation was successful, including:
   - Whether the toolset directory exists in `.asdm/toolsets/{toolset-id}/`
   - **Whether the AI Coding tool shortcut command files exist**:
     - If Claude Code: Check if the corresponding command file exists in `.claude/commands/`
     - If GitHub Copilot: Check if the corresponding prompt file exists in `.github/prompts/`
     - If Tencent CodeBuddy: Check if the corresponding command file exists in `.codebuddy/commands/`
   - **List the created shortcut commands** for easy use by the user

5. **Summarize report**: Report the installation results to the user, including successfully installed content and available commands.

If any error occurs during installation, interrupt and prompt the user to handle manually.
EOF
```

### For Tencent CodeBuddy (`.codebuddy/commands/`):

```bash
mkdir -p .codebuddy/commands/

# asdm-toolset-list command
cat > .codebuddy/commands/asdm-toolset-list.md << 'EOF'
List available ASDM toolsets for the current workspace.

Use this command when the user requests to view or list ASDM toolsets, e.g., `/asdm-toolset-list`

Execute the following steps:

1. **Detect ASDM CLI**: Check if ASDM CLI is installed on the system (via `asdm --version` command). If not installed, prompt the user to install ASDM CLI first.

2. **Execute list command**: Run `asdm toolset list` command to get the available toolsets list.

3. **Parse output**: Parse the command output and extract toolset information (ID, Name, Description, Version).

4. **Display results**: Display available toolsets to the user in a table format, including:
   - Toolset ID
   - Toolset Name
   - Description
   - Version

5. **Provide installation guidance**: Tell the user how to install the specified toolset, e.g.:
   - Use `/asdm-toolset-install <toolset-id>` command to install

If any error occurs during execution, interrupt and prompt the user to handle manually.
EOF

# asdm-toolset-install command
cat > .codebuddy/commands/asdm-toolset-install.md << 'EOF'
Install an ASDM toolset to the current workspace.

Use this command when the user requests to install an ASDM toolset, e.g., `/asdm-toolset-install prd-builder`

Execute the following steps:

1. **Detect ASDM CLI**: Check if ASDM CLI is installed on the system (via `asdm --version` command). If not installed, prompt the user to install ASDM CLI first.

2. **Install toolset**: Run `asdm toolset install {toolset-id}` command to install the specified toolset, where `{toolset-id}` is the toolset ID provided by the user (e.g., prd-builder, context-builder).

3. **Execute installation script**: After installation is complete, read and execute all installation steps from the INSTALL.md file in the toolset installation directory:
   - Read `.asdm/toolsets/{toolset-id}/INSTALL.md`
   - Follow the "Installation Steps" section in the documentation step by step
   - Create necessary directory structure
   - Detect the current AI Coding tool type (Claude Code/GitHub Copilot/Tencent CodeBuddy), and create corresponding shortcut command files based on the detection results

4. **Verify installation**: Check if the installation was successful, including:
   - Whether the toolset directory exists in `.asdm/toolsets/{toolset-id}/`
   - **Whether the AI Coding tool shortcut command files exist**:
     - If Claude Code: Check if the corresponding command file exists in `.claude/commands/`
     - If GitHub Copilot: Check if the corresponding prompt file exists in `.github/prompts/`
     - If Tencent CodeBuddy: Check if the corresponding command file exists in `.codebuddy/commands/`
   - **List the created shortcut commands** for easy use by the user

5. **Summarize report**: Report the installation results to the user, including successfully installed content and available commands.

If any error occurs during installation, interrupt and prompt the user to handle manually.
EOF
```

**Expected Result**: The ASDM commands are generated in your AI Coding Tool's commands directory, enabling you to use `/asdm-toolset-list` and `/asdm-toolset-install` commands.

## Step 4: Add ASDM Default Rules for AI Coding Tool

Add ASDM default rules to ensure consistent AI behavior across the workspace. The rules file (`asdm-default-rules.mdc`) is placed in a `rules` directory at the same level as the `commands` directory.

### 4.1 Detect Project Tech Stack

Scan the current workspace to identify the project's technology stack:

1. **Analyze project structure**: Examine top-level directories and key files to determine the tech stack:
   - **Frontend**: Look for `package.json`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `angular.json`, `vue.config.*` → JavaScript / TypeScript (React, Vue, Angular, Next.js, etc.)
   - **Backend (Java)**: Look for `pom.xml`, `build.gradle`, `build.gradle.kts` → Java / Spring Boot / Gradle
   - **Backend (C#)**: Look for `*.sln`, `*.csproj` → .NET / C#
   - **Backend (Python)**: Look for `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → Python / Django / Flask
   - **Backend (Go)**: Look for `go.mod` → Go
   - **Backend (Rust)**: Look for `Cargo.toml` → Rust
   - **Monorepo**: If multiple tech stacks are detected, handle each sub-project accordingly

2. **Identify all tech stacks present**: A workspace may contain multiple stacks (e.g., a frontend React app + a backend Java service). Record all detected stacks.

### 4.2 Read Project Configuration Files

For each detected tech stack, read the relevant default project configuration files to extract build and compile commands:

- **JavaScript/TypeScript**: Read `package.json` → extract `scripts.build`, `scripts.compile`, `scripts.lint`, `scripts.test`
- **Java (Maven)**: Read `pom.xml` → default build command is `mvn compile` or `./mvnw compile`
- **Java (Gradle)**: Read `build.gradle` or `build.gradle.kts` → default build command is `gradle build` or `./gradlew build`
- **C#/.NET**: Read `*.csproj` → default build command is `dotnet build`
- **Python**: Read `pyproject.toml` or `setup.py` → check for build tools like `pytest`, `mypy`, `ruff`; typical commands: `python -m compileall .` or tool-specific checks
- **Go**: Read `go.mod` → default build command is `go build ./...`
- **Rust**: Read `Cargo.toml` → default build command is `cargo build`

### 4.3 Determine Build Commands

Based on the configuration files read above, determine the correct build/compile commands for each tech stack:

- Use the **project-root-relative path** for each command (e.g., `cd frontend && npm run build`)
- For monorepos, list each sub-project's build command separately
- If a custom build script is defined (e.g., `scripts.build` in `package.json`), prefer it over the default
- Include any necessary install steps if `node_modules` / `vendor` / dependencies are not yet installed

### 4.4 Generate the Rules File

Create the `asdm-default-rules.mdc` file in the appropriate `rules` directory based on the detected AI Coding Tool provider:

#### For Claude Code (`.claude/rules/`):

```bash
mkdir -p .claude/rules/

cat > .claude/rules/asdm-default-rules.mdc << 'RULESEOF'
---
description: ASDM default rules for consistent AI behavior and auto-build on code changes
alwaysApply: true
---

# ASDM Default Rules

## Project Tech Stack

{AUTO_GENERATED_TECH_STACK_INFO}

## Build & Compile Commands

{AUTO_GENERATED_BUILD_COMMANDS}

## ASDM CLI Configuration

The ASDM CLI executable path for this workspace:

- **CLI Command**: `asdm`
- **Executable Path**: `{AUTO_GENERATED_CLI_PATH}`
- **Installation Method**: `{AUTO_GENERATED_INSTALL_METHOD}`
- **CLI Version**: `{AUTO_GENERATED_CLI_VERSION}`

### CLI Invocation Rules

When you need to execute any ASDM CLI command (e.g., `asdm toolset list`, `asdm toolset install`), follow these rules:

1. **Use the full path** if `asdm` is not in PATH: `{AUTO_GENERATED_CLI_PATH}` instead of just `asdm`
2. **Fallback strategy**: If the full path fails, try `asdm` directly (may be available via npm global install or PATH)
3. **Verify availability**: Before invoking, run `{AUTO_GENERATED_CLI_PATH} --version` (or `asdm --version`) to confirm CLI is accessible
4. **Report path issues**: If neither the full path nor `asdm` works, inform the user that the CLI may need reinstallation

### CLI Path Reference by Platform

| Installation Method | Platform | Executable Path |
|---------------------|----------|-----------------|
| npm (Method A) | Any (macOS/Linux/Windows) | Resolved via `which asdm` / `where asdm` at installation time |
| Standalone Binary (Method B) | Windows | `%USERPROFILE%\.asdm\cli\asdm-cli.exe` |

## Auto-Build Policy

When you modify any source code file in this workspace, you MUST:

1. **Execute the build command** corresponding to the modified file's tech stack immediately after making changes
2. **Analyze the build output** for errors and warnings
3. **Auto-fix** any compilation errors found in the build output
4. **Re-run the build** after each fix
5. **Repeat** steps 2-4 until the build succeeds with zero errors
6. **Report** the final build status to the user

### Build Execution Rules

- Always run build commands from the correct project root directory
- If the build fails, do NOT proceed with other tasks — fix compilation errors first
- Warnings should be noted but do not block progress
- If a build error cannot be auto-fixed, report it to the user with the full error context

### Error Fix Loop

```
while (build has errors) {
  1. Parse build error output
  2. Identify the root cause (syntax error, missing import, type mismatch, etc.)
  3. Apply fix to the relevant source file(s)
  4. Re-run the build command
}
```
RULESEOF
```

#### For GitHub Copilot (`.github/rules/`):

```bash
mkdir -p .github/rules/

cat > .github/rules/asdm-default-rules.mdc << 'RULESEOF'
---
description: ASDM default rules for consistent AI behavior and auto-build on code changes
alwaysApply: true
---

# ASDM Default Rules

## Project Tech Stack

{AUTO_GENERATED_TECH_STACK_INFO}

## Build & Compile Commands

{AUTO_GENERATED_BUILD_COMMANDS}

## ASDM CLI Configuration

The ASDM CLI executable path for this workspace:

- **CLI Command**: `asdm`
- **Executable Path**: `{AUTO_GENERATED_CLI_PATH}`
- **Installation Method**: `{AUTO_GENERATED_INSTALL_METHOD}`
- **CLI Version**: `{AUTO_GENERATED_CLI_VERSION}`

### CLI Invocation Rules

When you need to execute any ASDM CLI command (e.g., `asdm toolset list`, `asdm toolset install`), follow these rules:

1. **Use the full path** if `asdm` is not in PATH: `{AUTO_GENERATED_CLI_PATH}` instead of just `asdm`
2. **Fallback strategy**: If the full path fails, try `asdm` directly (may be available via npm global install or PATH)
3. **Verify availability**: Before invoking, run `{AUTO_GENERATED_CLI_PATH} --version` (or `asdm --version`) to confirm CLI is accessible
4. **Report path issues**: If neither the full path nor `asdm` works, inform the user that the CLI may need reinstallation

### CLI Path Reference by Platform

| Installation Method | Platform | Executable Path |
|---------------------|----------|-----------------|
| npm (Method A) | Any (macOS/Linux/Windows) | Resolved via `which asdm` / `where asdm` at installation time |
| Standalone Binary (Method B) | Windows | `%USERPROFILE%\.asdm\cli\asdm-cli.exe` |

## Auto-Build Policy

When you modify any source code file in this workspace, you MUST:

1. **Execute the build command** corresponding to the modified file's tech stack immediately after making changes
2. **Analyze the build output** for errors and warnings
3. **Auto-fix** any compilation errors found in the build output
4. **Re-run the build** after each fix
5. **Repeat** steps 2-4 until the build succeeds with zero errors
6. **Report** the final build status to the user

### Build Execution Rules

- Always run build commands from the correct project root directory
- If the build fails, do NOT proceed with other tasks — fix compilation errors first
- Warnings should be noted but do not block progress
- If a build error cannot be auto-fixed, report it to the user with the full error context

### Error Fix Loop

```
while (build has errors) {
  1. Parse build error output
  2. Identify the root cause (syntax error, missing import, type mismatch, etc.)
  3. Apply fix to the relevant source file(s)
  4. Re-run the build command
}
```
RULESEOF
```

#### For Tencent CodeBuddy (`.codebuddy/rules/`):

```bash
mkdir -p .codebuddy/rules/

cat > .codebuddy/rules/asdm-default-rules.mdc << 'RULESEOF'
---
description: ASDM default rules for consistent AI behavior and auto-build on code changes
alwaysApply: true
---

# ASDM Default Rules

## Project Tech Stack

{AUTO_GENERATED_TECH_STACK_INFO}

## Build & Compile Commands

{AUTO_GENERATED_BUILD_COMMANDS}

## ASDM CLI Configuration

The ASDM CLI executable path for this workspace:

- **CLI Command**: `asdm`
- **Executable Path**: `{AUTO_GENERATED_CLI_PATH}`
- **Installation Method**: `{AUTO_GENERATED_INSTALL_METHOD}`
- **CLI Version**: `{AUTO_GENERATED_CLI_VERSION}`

### CLI Invocation Rules

When you need to execute any ASDM CLI command (e.g., `asdm toolset list`, `asdm toolset install`), follow these rules:

1. **Use the full path** if `asdm` is not in PATH: `{AUTO_GENERATED_CLI_PATH}` instead of just `asdm`
2. **Fallback strategy**: If the full path fails, try `asdm` directly (may be available via npm global install or PATH)
3. **Verify availability**: Before invoking, run `{AUTO_GENERATED_CLI_PATH} --version` (or `asdm --version`) to confirm CLI is accessible
4. **Report path issues**: If neither the full path nor `asdm` works, inform the user that the CLI may need reinstallation

### CLI Path Reference by Platform

| Installation Method | Platform | Executable Path |
|---------------------|----------|-----------------|
| npm (Method A) | Any (macOS/Linux/Windows) | Resolved via `which asdm` / `where asdm` at installation time |
| Standalone Binary (Method B) | Windows | `%USERPROFILE%\.asdm\cli\asdm-cli.exe` |

## Auto-Build Policy

When you modify any source code file in this workspace, you MUST:

1. **Execute the build command** corresponding to the modified file's tech stack immediately after making changes
2. **Analyze the build output** for errors and warnings
3. **Auto-fix** any compilation errors found in the build output
4. **Re-run the build** after each fix
5. **Repeat** steps 2-4 until the build succeeds with zero errors
6. **Report** the final build status to the user

### Build Execution Rules

- Always run build commands from the correct project root directory
- If the build fails, do NOT proceed with other tasks — fix compilation errors first
- Warnings should be noted but do not block progress
- If a build error cannot be auto-fixed, report it to the user with the full error context

### Error Fix Loop

```
while (build has errors) {
  1. Parse build error output
  2. Identify the root cause (syntax error, missing import, type mismatch, etc.)
  3. Apply fix to the relevant source file(s)
  4. Re-run the build command
}
```
RULESEOF
```

### 4.5 Populate Rules with Detected Information

After generating the template rules file, replace the placeholders with actual detected values:

- `{AUTO_GENERATED_TECH_STACK_INFO}`: Replace with the detected tech stack summary, e.g.:
  ```
  - Frontend: TypeScript / React (Vite) — ./frontend
  - Backend: Java 17 / Spring Boot (Maven) — ./backend
  ```

- `{AUTO_GENERATED_BUILD_COMMANDS}`: Replace with the detected build commands, e.g.:
  ```
  - Frontend build: cd frontend && npm run build
  - Backend build: cd backend && ./mvnw compile
  ```

- `{AUTO_GENERATED_CLI_PATH}`: Replace with the resolved absolute path to the ASDM CLI executable, determined during Step 1:
  - **Method A (npm)**: Run `which asdm` (macOS/Linux) or `where asdm` (Windows) and use the result, e.g., `/usr/local/bin/asdm` or `C:\Users\<user>\AppData\Roaming\npm\asdm.cmd`
  - **Method B (standalone binary)**: Use `%USERPROFILE%\.asdm\cli\asdm-cli.exe`
  - If the path cannot be resolved, set to `asdm` (rely on PATH lookup)

- `{AUTO_GENERATED_INSTALL_METHOD}`: Replace with the installation method used, either `npm (Method A)` or `standalone-binary (Method B)`

- `{AUTO_GENERATED_CLI_VERSION}`: Replace with the actual CLI version string obtained from `asdm --version`, e.g., `1.0.3`

**Expected Result**: The `asdm-default-rules.mdc` file is created in the AI Coding Tool's `rules` directory, containing the workspace-specific tech stack info, build commands, and ASDM CLI configuration. This ensures AI agents always know the correct CLI executable path for reliable invocation, auto-execute builds after code changes, and iteratively fix compilation errors.

## Step 5: Show ASDM Introduction

After successful installation, provide the user with a brief introduction to ASDM:

**Action Required**: Display the following introduction to the user:

```
Welcome to ASDM Bootstrapper!

The ASDM Bootstrapper is a command-line interface (CLI) tool designed to help developers 
quickly set up their development environment for ASDM (AI First System Development Methodology) 
projects. It automates the process of downloading and configuring the necessary toolsets 
required for ASDM development.

Key Features:
- List available ASDM toolsets from a centralized registry
- Download and install toolsets into your workspace (.asdm/toolsets/ folder)
- Quick setup for ASDM development environments
```

## Step 6: List Available Toolsets

After generating the ASDM commands, you can use the `/asdm-toolset-list` command (or the AI Coding Tool's equivalent) to list available toolsets:

```bash
/asdm-toolset-list
```

**Expected Output**: The command will display available toolsets in a table format, showing:
- Toolset ID
- Toolset Name
- Description
- Version

**Action Required**: Present the available toolsets to the user as a read-only list. **Do not prompt for selection or installation at this stage.**

## Step 7: Verify Configuration & Cleanup Temporary Files

After all installation steps are complete, perform a comprehensive validation of the installed configuration and clean up any temporary files generated during installation.

### 8.1 Verify File Locations

Check that all expected files exist at their correct locations. Run each check below and record the result:

#### 8.1.1 ASDM CLI Executable

```bash
# Verify CLI is accessible
asdm --version
```

| Check Item | Expected Location | Command to Verify |
|------------|-------------------|-------------------|
| CLI in PATH | Resolved via `which asdm` / `where asdm` | `asdm --version` |
| CLI full path (Method B) | `%USERPROFILE%\.asdm\cli\asdm-cli.exe` (Windows only) | `"%USERPROFILE%\.asdm\cli\asdm-cli.exe" --version` |

**Expected Result**: CLI version number is displayed without error.

**If failed**: The CLI path recorded in `asdm-default-rules.mdc` may be incorrect. Re-run Step 1 or update the `{AUTO_GENERATED_CLI_PATH}` placeholder manually.

#### 8.1.2 Generated Command Files

Verify that command files were created for the detected AI Coding Tool provider:

| Provider | Expected Path | Files to Check |
|----------|-------------|----------------|
| Claude Code | `.claude/commands/` | `asdm-toolset-list.md`, `asdm-toolset-install.md` |
| GitHub Copilot | `.github/prompts/` | `asdm-toolset-list.prompt.md`, `asdm-toolset-install.prompt.md` |
| Tencent CodeBuddy | `.codebuddy/commands/` | `asdm-toolset-list.md`, `asdm-toolset-install.md` |

```bash
# Example for Claude Code — adapt path for your provider
ls -la .claude/commands/asdm-*.md
```

**Expected Result**: Both command files exist and have non-zero content.

**If missing**: Re-run Step 3 to regenerate commands.

#### 8.1.3 Default Rules File

Verify that the rules file was created with correct content:

| Provider | Expected Path |
|----------|-------------|
| Claude Code | `.claude/rules/asdm-default-rules.mdc` |
| GitHub Copilot | `.github/rules/asdm-default-rules.mdc` |
| Tencent CodeBuddy | `.codebuddy/rules/asdm-default-rules.mdc` |

```bash
# Example for Claude Code — adapt path for your provider
ls -la .claude/rules/asdm-default-rules.mdc
```

Additionally, verify that **no unresolved placeholders remain** in the rules file:

```bash
# Check for any remaining {AUTO_GENERATED_*} placeholders
grep -n 'AUTO_GENERATED_' .claude/rules/asdm-default-rules.mdc
# (Adapt path for GitHub Copilot / CodeBuddy)
```

**Expected Result**: Rules file exists, has content > 0 bytes, and grep returns **no matches** (all placeholders replaced).

**If placeholders remain**: Re-run Step 4.5 to populate the remaining placeholders.

#### 8.1.4 Toolset Directory (if Step 7 was executed)

```bash
# Replace {toolset-id} with the actual ID
ls -la .asdm/toolsets/{toolset-id}/
```

**Expected Result**: Toolset directory exists and contains toolset files.

### 8.2 Verify Path Configuration

Validate that all paths written into configuration files are correct and functional:

#### 8.2.1 Validate ASDM CLI Path in Rules

Read the `asdm-default-rules.mdc` file and extract the **Executable Path** value from the **ASDM CLI Configuration** section. Then verify it works:

```bash
# Use the exact path found in rules file
{extracted_cli_path} --version
```

| Validation | Action |
|------------|--------|
| Full path works | ✅ No action needed |
| Full path fails, `asdm` works | ⚠️ Update rules: replace `{AUTO_GENERATED_CLI_PATH}` with resolved `which asdm` / `where asdm` output |
| Both fail | ❌ CLI not properly installed — re-run Step 1 |

#### 8.2.2 Validate Build Commands

For each build command recorded in the rules file's **Build & Compile Commands** section, run a dry test to confirm the command is valid:

```bash
# For each build command, verify it can at least be invoked without compile errors
cd /path/to/project && npm run build --dry-run  # or equivalent
```

> **Note**: A dry-run may not be available for all tools. In that case, simply confirm the project directory exists and the build configuration file (e.g., `package.json`, `pom.xml`) is present.

### 8.3 Cleanup Temporary Files

Remove any temporary files or directories created during the installation process:

#### 8.3.1 Method B Specific Cleanup (if applicable)

If Method B (standalone binary) was used, verify the following temporary artifacts are cleaned up:

| Temp Artifact | Expected State | Action if Still Present |
|---------------|---------------|------------------------|
| `asdm-cli-win-latest.zip` | Deleted | `rm -f asdm-cli-win-latest.zip` |
| `asdm-cli-temp/` directory | Deleted | `rm -rf asdm-cli-temp` |

#### 8.3.2 General Temp File Scan

Scan the workspace root for any other temporary files that may have been left behind during installation:

```bash
# Look for common temp patterns in workspace root
ls -la *.tmp *.temp *.bak *_backup* 2>/dev/null
ls -d *-temp *-tmp *-bak 2>/dev/null
```

**If any temp files are found**, remove them only if they were created by this installation process. Do **not** delete files whose origin is uncertain.

#### 8.3.3 Verify Clean State

After cleanup, confirm no installation-related temp files remain:

```bash
# Final verification — should return no installation-related results
ls -la asdm-cli-* asdm-temp* 2>/dev/null || echo "✅ No installation temp files remaining"
```

### 8.4 Verification Summary Table

After completing all checks above, compile a verification result table:

| # | Check Category | Status | Details |
|---|---------------|:------:|---------|
| 8.1.1 | CLI Executable | `{status}` | Path valid / invalid / reason |
| 8.1.2 | Command Files | `{status}` | N files present / missing list |
| 8.1.3 | Rules File | `{status}` | Exists, size: `{bytes}`, placeholders: none / remaining |
| 8.1.4 | Toolset Dir | `{status}` | N/A (toolset installation is a post-install action) |
| 8.2.1 | CLI Path Valid | `{status}` | Works / needs update / broken |
| 8.2.2 | Build Commands | `{status}` | All valid / issues list |
| 8.3 | Temp Cleanup | `{status}` | Cleaned `{N}` files / nothing to clean |

**Overall Verification Result**: `{ALL_PASSED / PARTIAL_WARNINGS / FAILED}`

**If ALL_PASSED**: Proceed to present the Installation Summary Report.
**If PARTIAL_WARNINGS**: Present summary with warnings noted, but overall install is usable.
**If FAILED**: Present summary with failure details and remediation steps required.

---

## Installation Summary Report

> **⚠️ IMPORTANT**: After completing ALL steps (Step 0 through Step 7), **you MUST present a summary report to the user**. This provides a clear overview of what was done and the result of each step.

### Action Required — Present Summary Table to User

After all installation steps are completed (or if any step failed), display the following summary table:

#### Installation Summary Report

| # | Step | Status | Details |
|---|------|:------:|---------|
| 0 | Prerequisites | `{status}` | Node.js v`{version}`, npm v`{version}` — or failure reason |
| 1 | Install ASDM CLI | `{status}` | Method A/B — version: `{v.x.y.z}` — or failure reason |
| 2 | Detect AI Tool | `{status}` | Detected: Claude Code / GitHub Copilot / CodeBuddy / Manual — or failure reason |
| 3 | Generate Commands | `{status}` | Generated `asdm-toolset-list.md`, `asdm-toolset-install.md` — or failure reason |
| 4 | Default Rules | `{status}` | Created `asdm-default-rules.mdc` — tech stack, build commands, CLI path: `{cli-path}` — or failure reason |
| 5 | Introduction | `{status}` | ASDM welcome message displayed — or failure reason |
| 6 | List Toolsets | `{status}` | Listed `{N}` available toolsets — or failure reason |
| 7 | Verify & Cleanup | `{status}` | Files verified: `{N}/{M}` OK, temp files cleaned: `{N}` — or failure details |

> **Overall Result**: `{OVERALL_STATUS}`

### Summary Table Format

Replace the `{STATUS}`, `{DETAILS}`, and `{OVERALL_STATUS}` placeholders with actual values:

| Step | Status | Details |
|------|--------|---------|
| **0. Prerequisites** | ✅ Success / ⚠️ Skipped / ❌ Failed | Node.js v{version}, npm v{version} — or failure reason |
| **1. Install ASDM CLI** | ✅ Success / ⚠️ Skipped / ❌ Failed | Method A: npm install / Method B: standalone binary — version: {v.x.y.z} — or failure reason |
| **2. Detect AI Tool** | ✅ Success / ❌ Failed | Detected provider: Claude Code / GitHub Copilot / CodeBuddy / Manual selection — or failure reason |
| **3. Generate Commands** | ✅ Success / ❌ Failed | Generated files: `.xxx/commands/asdm-toolset-list.md`, `.xxx/commands/asdm-toolset-install.md` — or failure reason |
| **4. Default Rules** | ✅ Success / ❌ Failed | Created: `asdm-default-rules.mdc` with tech stack: {detected stacks} and build commands — or failure reason |
| **5. Introduction** | ✅ Success / ❌ Failed | ASDM welcome message displayed to user — or failure reason |
| **6. List Toolsets** | ✅ Success / ❌ Failed | Listed {N} available toolsets — or failure reason |
| **7. Verify & Cleanup** | ✅ Success / ❌ Failed | Files verified: {N}/{M} OK, temp files cleaned: {N} — or failure details |

### Status Legend

| Icon | Meaning | When to Use |
|------|---------|-------------|
| ✅ | Success | Step completed without errors |
| ⚠️ | Warning / Skipped | Step was skipped (e.g., CLI already installed) or completed with warnings |
| ❌ | Failed | Step encountered an error and could not complete |

### Overall Result Determination

- **✅ All Steps Completed**: All steps show ✅ or ⚠️ → Overall: `SUCCESS`
- **❌ Failed**: Any step shows ❌ → Overall: `FAILED` — include troubleshooting guidance for failed steps

### Post-Summary Next Steps

After presenting the summary table, provide actionable next steps based on the overall result:

**If SUCCESS:**
```
🎉 ASDM Bootstrapper installed successfully!

Available Toolsets:
  {toolset_list_from_step_6}

Next step — install a toolset to get started:
  • Review the available toolsets listed above
  • Run /asdm-toolset-install <id> to install a toolset of your choice
  • After installation, check .asdm/toolsets/ for your installed toolsets
```

**If FAILED:**
```
❌ Installation incomplete. Troubleshooting:
  • Check the failed step(s) above for error details
  • Ensure network connectivity for npm/download operations
  • Verify Node.js version is 16+
  • Contact your ASDM administrator if issues persist
```

---

## Notes for AI Agents

- **Language Detection is the FIRST step** — detect the user's language preference before any interaction, and use it consistently throughout all steps
- Step 1 has two installation methods: **Method A (npm)** is the recommended approach; **Method B (standalone binary)** is the fallback
- Try Method A first. Only if it fails, proceed to Method B
- Method B (standalone binary) only supports **Windows**. If the user's environment is not Windows and Method A failed, prompt the user to **contact their ASDM administrator** to obtain the CLI tool manually
- When using Method B, the `{server-url}` must match the server address where this INSTALL.md was fetched from
- After Method B installation, remind the user to **restart their terminal** for PATH changes to take effect
- After installing ASDM CLI (Step 1), detect the AI Coding Tool provider and generate commands (Step 2-3)
- **Step 4** automatically detects the workspace tech stack, reads project config files (package.json, pom.xml, etc.), extracts build commands, and writes them into `asdm-default-rules.mdc` in the AI Coding Tool's `rules` directory
- The `asdm-default-rules.mdc` file ensures AI agents auto-execute builds after code changes and iteratively fix compilation errors until the build succeeds
- Show the ASDM introduction after generating commands and rules (Step 5) and before listing toolsets
- Use the generated `/asdm-toolset-list` command to list available toolsets (Step 6) — **present as read-only list, do not prompt for installation**
- Use the generated `/asdm-toolset-install` command to install a toolset — this is a **post-install action**, presented only in the Installation Summary Report's SUCCESS next steps
- **Step 7** is the final verification and cleanup step — it must be executed **after** all other steps (Steps 0–6) complete
- **Step 7.1** checks all file locations: CLI executable, generated command files, default rules file (toolset directory check is N/A since installation is post-install)
- **Step 7.2** validates path configuration: verifies the CLI path in rules is functional, validates build commands can resolve correctly
- **Step 7.3** cleans up temporary files from Method B (zip, extraction temp dir) and scans for any leftover temp artifacts in the workspace root
- **Step 7.4** compiles a verification summary table; based on the result (ALL_PASSED / PARTIAL_WARNINGS / FAILED), decide whether to proceed or require remediation
- The Installation Summary Report must include Step 7 results alongside all previous steps, followed by toolset installation prompt in the SUCCESS section