Arpan.AITools 1.0.0

AI Coding Tools — Usage Guide

A no-agent, no-extension workflow for applying AI-generated code changes to any project directly from your browser using the ai-tool .NET Global Tool.

The Big Picture

Your Project
    │
    ▼
[1] ai-tool pack  ──►  aiArtifacts/*-context.txt
                                    │
                                    ▼
                         [2] Paste into Browser AI
                             (ChatGPT / Claude / Gemini)
                                    │
                             Ask for changes
                                    │
                                    ▼
                         [3] Save AI response
                             ──► aiArtifacts/ai-response.xml
                                    │
                                    ▼
                         [4] ai-tool apply
                                    │
                                    ▼
                             Code lands in your project ✅

Prerequisites

• .NET 10 SDK installed on your machine.
• Git installed and on your PATH (the target project must be a git repo)
• A browser AI account: ChatGPT, Claude, or Gemini

Installation

Install the tool globally using the .NET CLI. Once installed, the ai-tool command is available in any terminal window.

dotnet tool install --global Arpan.AITools

(Note: If installing locally during development, use dotnet tool install --global --add-source ./bin/Release/ Arpan.AITools).

Uninstallation

To remove the global tool from your machine:

dotnet tool uninstall --global Arpan.AITools

Updating the Tool

To update the tool to the latest version from NuGet:

dotnet tool update --global Arpan.AITools

(Note: If updating locally during development, use dotnet tool update --global --add-source ./bin/Release/ Arpan.AITools).

Step 0 — Initialize AI Workspace (Optional)

If you want to configure which files to hide from the AI before you pack your code, run the init command:

ai-tool init

This automatically creates a default .aiignore file and patches your .gitignore so your AI context files never accidentally get committed. You can edit the .aiignore file to add custom files and folders you want to exclude.

Step 1 — Pack Your Project Context

Open your terminal, navigate to your project directory, and run the pack command to compile your project's source code into AI-readable context files.

cd D:\Code\Github\you\your-project
ai-tool pack

Output: One *-context.txt file per project layer, saved to aiArtifacts\:

aiArtifacts\
    YourApp.WebApi-context.txt
    YourApp.DataProvider-context.txt
    YourApp.SharedContracts-context.txt
    YourApp-Solution-context.txt

Tip: You don't always need to upload all files. If you're only changing the API layer, just upload YourApp.WebApi-context.txt.

Step 2 — Give Context to the AI

1. Open your browser AI (ChatGPT, Claude, or Gemini).
2. Set the System Prompt — paste the contents of ai-system-prompt.md (see the System Prompt section below) into the system / custom instructions area. You only need to do this once per chat session.
3. Upload the context file(s) — attach the relevant *-context.txt file(s) from aiArtifacts\.
4. Describe what you want — ask the AI to add a feature, fix a bug, refactor code, delete files, etc.

Step 3 — Save the AI Response

The AI will respond with a valid XML document (wrapped in <ai-response> with CDATA sections). Save it as ai-response.xml in the aiArtifacts\ folder.

Option A — Copy & Paste (Works with all AI tools)

1. Select the entire AI response text in the browser.
2. Copy it (Ctrl+C).
3. Open Notepad (or any editor), paste, and save as:

   aiArtifacts\ai-response.xml
   

Option B — Download (ChatGPT with Code Interpreter)

Ask ChatGPT directly:

"Save your response to a file called ai-response.xml and give me a download link."

ChatGPT will generate a downloadable file. Place it in aiArtifacts\.

VS Code Tip — Collapse & Expand File Blocks

Since the response is valid XML, open ai-response.xml in VS Code to get full folding support. You can collapse each <file> and <patch> block to inspect the structure at a glance before running the tool.

Step 4 — Apply the AI Response

Inside your project directory, run the apply command to apply the changes.

ai-tool apply

What the tool does

1. Warns if your git working tree has uncommitted changes.
2. Phase 1 — Applies <file> blocks (creates or overwrites full files).
3. Phase 2 — Applies <patch> blocks (targeted search-and-replace).
4. Phase 3 — Applies <delete> blocks (removes files).
5. Phase 4 — Cleans up any folders left empty after deletions.
6. Prints a summary and runs git diff --stat so you see exactly what changed.

After the run

• If all patches succeeded → git diff --stat output is printed automatically.
• If some patches failed → paths are saved to aiArtifacts\failed-patches.txt. Go back to the AI and ask:

  "Some patches failed for these files. Please give me full <file> blocks instead: [paste failed-patches.txt contents]"

System Prompt

The system prompt tells the AI exactly what format to use in its responses.

Where to paste it:

• ChatGPT: Settings → Personalization → Custom Instructions (top box)
• Claude: Start a new Project → Project Instructions
• Gemini: System instructions (in Gemini Advanced / API settings)

The full system prompt text is in:

ai-system-prompt.md

Open the file and copy everything from the ▼ COPY FROM HERE ▼ marker to the end of the file. Paste that into your AI tool's system instructions.

What it generates in your project

When you run ai-tool pack or ai-tool skeleton in your project folder, it creates an aiArtifacts folder. This folder is strictly for AI working files and will automatically be added to your .gitignore.

YourProjectRoot\
└── aiArtifacts\                ← Auto-created, gitignored
    ├── *-context.txt           ← Output of ai-tool pack
    ├── *-skeleton.xml          ← Output of ai-tool skeleton
    ├── ai-response.xml         ← AI response you paste/download here (valid XML)
    └── failed-patches.txt      ← Created only when patches fail

Note: If you don't have an .aiignore file, the tool will automatically create a default one for you.