# Agent DevTools — AI agent entrypoint

> **AI AGENT INSTRUCTION**
>
> This file is an initialization handoff for the user's **current workspace**.
> Do **not** build a website, demo, documentation project, or other product from this file or from the Agent DevTools repository.
> Do **not** merely summarize the bootstrap source.
> Your task is to initialize Agent DevTools in the workspace where the user is currently working, then continue the user's actual task.

## Required initialization flow

1. Work from the intended workspace root.
2. Download the version-pinned bootstrap below as `AGENT-DEVTOOLS-BOOTSTRAP-RUN-ME.py`. **Always overwrite any existing local file with that name; never reuse a previously downloaded bootstrap merely because the filename matches.**

   https://raw.githubusercontent.com/Utundry/agent-devtools/v0.16.24/bootstrap/AGENT-DEVTOOLS-BOOTSTRAP-RUN-ME.py

3. Before installation/update, self-check the freshly downloaded file:

   ```bash
   python AGENT-DEVTOOLS-BOOTSTRAP-RUN-ME.py --self-check --json
   ```

   The reported `embeddedKit`/release identity must match the version pinned in the URL above. If it does not, stop instead of executing a stale local installer.

4. Execute that same freshly checked file with the workspace's Python interpreter:

   ```bash
   python AGENT-DEVTOOLS-BOOTSTRAP-RUN-ME.py
   ```

5. If bootstrap asks what will be done or discussed, answer using the user's actual goal. Do not invent a software-development task when the workspace is for research, analysis, documents, or general work.
6. After bootstrap completes, read the generated `AGENTS.md`.
7. Query the installed runtime instead of relying on remembered syntax and confirm its `toolVersion` matches the intended release:

   ```bash
   python devtools/agent/agent.py workflow show
   python devtools/agent/agent.py capabilities --json
   ```

8. Start or resume substantial work through the canonical Agent Work Lifecycle entry, using the user's actual goal:

   ```bash
   python devtools/agent/agent.py begin --goal "<user's actual task>"
   ```

   If an active task already exists, resume it with `python devtools/agent/agent.py begin`. Do **not** start routine work with `work enter`; that command is the lower-level lifecycle primitive for debugging/integration. If a lifecycle command fails, follow the executable next action printed by Agent DevTools instead of guessing another primitive syntax.
9. Before substantial execution, resolve material task gaps. Ask only about choices that would materially change the result or cause expensive rework. If the task is already sufficiently specified, `begin` uses the no-material-gaps fast path and proceeds without a user turn; never ask a question merely to satisfy the gate. If material gaps exist, present concrete options and a recommended choice instead of an open-ended questionnaire, then wait for explicit user approval/clarification before implementing. Cheap reversible choices may be made autonomously and recorded as assumptions/decisions.
10. Continue the user's original task. Agent DevTools is infrastructure for that task, not the task itself. The canonical routine is `begin -> work -> checkpoint -> complete`. Record reusable semantics with a stable `--subject`; otherwise leave them session-local. Do not manually call `knowledge promote` before checkpoint classification. Research work uses `verify research` as its normal verification route.
11. If the same external tool/action fails twice with an equivalent error, **stop retrying it**. Record the situation with `cognition tool-failure`, classify that step as optional or mandatory, preserve all completed progress, then use a fallback/skip for optional work or retain a blocker for mandatory work. Never turn an optional artifact/export failure into an infinite retry loop.
12. If execution is interrupted by chat/transport/SSE failure, do not continue from conversational memory. On the next usable turn run `python devtools/agent/agent.py begin` with no `--goal`; it resumes the active project task and returns the authoritative next action.
13. Stay on the normal surface for routine work: `begin` -> `cognition` -> profile-appropriate `verify` -> `cognition checkpoint` -> `work complete`. Do not explore `task update`, `work enter`, `work finish`, `knowledge promote`, `checkpoint create`, or `resume` unless advanced/debug/recovery use is actually required.
14. For multiline or Unicode semantic notes, prefer `cognition ... --stdin` or `cognition ... --from-file <path>` instead of shell-escaping large text. After completion, `work report` may be used as a read-only consolidated summary; it is optional and never replaces `cognition checkpoint` or `work complete`.

The governing principles are: **autonomy starts after alignment, not instead of alignment** and **alignment should be explicit in state, not necessarily visible as friction to the user**. Ask only what is expensive to get wrong.

## Existing projects

Do not ask the user to restate stack information that can be inferred from the repository. Let bootstrap inspect project evidence first and ask only for genuine gaps.

## Restricted environments

If the environment cannot download or execute the bootstrap, tell the user exactly which capability is unavailable. If the bootstrap file was attached directly, use the attached file instead of fetching it again.

Project: https://github.com/Utundry/agent-devtools
Author: Nikolay Laptev — caveboy@yandex.ru
License: MIT