Install, Connect, and Verify AIWG

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

AIWG gives your AI assistant reusable project context and specialist workflows. This is the canonical first-time setup path. Connect the intended project, verify readiness, then complete a small task with a saved result.

Your project root is the main folder for the project—the folder that usually contains files such as `README.md`, `package.json`, or `.git`. Your provider is the AI tool you are using, such as Claude Code, Codex, Copilot, or Cursor.

One prompt for installation or repair

Open the intended project in your provider and paste:

Install or repair AIWG for this project by following
https://aiwg.io/setup.aiwg.yaml

First identify the project root and provider. Inspect the current installation
without changing it, explain the plan and files that may change, preserve my
existing work, and ask me only for choices you cannot safely determine. Use the
complete supported AIWG setup unless this project already declares a narrower
policy. When finished, verify the engagement state and report the evidence in
plain language.

The linked installer is designed for agent use. It recognizes healthy, outdated, incomplete, duplicate, and source-checkout installations. A healthy installation should not be replaced merely because the agent was asked to check it.

What the agent should do

The agent should:

1. confirm the project root and provider; 2. inspect the installed AIWG version and ownership; 3. repair or install the CLI only after the proposed changes are approved; 4. run the guided interview to save scope, provider, usage, and optional integration choices; 5. review the saved plan, including conflicts and actions that are not ready; 6. apply the approved plan while preserving project-authored instructions; and 7. explain the core readiness and optional integration results.

If the agent cannot determine the project folder, tell it which folder contains your project and ask it to reopen or continue from there. Do not approve a path that points at your home directory or an unrelated repository.

Interview, review, apply

After installing the CLI, the same guided flow is available in a terminal:

Use AIWG to complete this documented outcome: After installing the CLI, the same guided flow is available in a terminal
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Replace `claude` with your provider. The interview saves answers and credential references, then stops before configuration changes. Review writes nothing. Apply asks for confirmation, runs the selected actions, and saves progress after each action. Jev and direct workers are optional and require explicit opt-in. Use the guided setup reference for headless commands, multiple providers, monorepos, scopes, cancellation, and resuming a partial run.

Provider handoff

Tell the agent which tool you are using:

AI tool	What to say
Claude Code	“Connect AIWG to this Claude Code project.”
OpenAI Codex	“Connect AIWG to this Codex workspace.”
GitHub Copilot	“Connect AIWG to this Copilot workspace.”
Cursor	“Connect AIWG to this Cursor project.”
Factory	“Connect AIWG to this Factory project.”
OpenCode	“Connect AIWG to this OpenCode project.”
Warp	“Connect AIWG to this Warp project.”
Devin Desktop	“Connect AIWG to this Devin Desktop project.”
OpenClaw	“Connect AIWG to this OpenClaw workspace.”
Hermes	“Connect AIWG to this Hermes workspace.”
Grok Bot	“Connect AIWG to this Grok Bot workspace.”
Muse Code	“Connect AIWG to this Muse Code workspace.”
OpenHuman	“Connect AIWG to this OpenHuman workspace.”
Oh My Pi	“Connect AIWG to this Oh My Pi project.”
Pi Coding Agent (pi.dev)	“Connect AIWG to this Pi Coding Agent project.”

Some providers can use refreshed context immediately; others need a single restart or workspace reload. The agent should report that need rather than asking you to restart by default.

Verify the result

The apply report is the first readiness evidence. For an independent later check, paste:

Is AIWG active in this project? Read the canonical engagement evidence and
report the engaged state, project root, provider files, installed frameworks
and addons, and exactly one next action. Do not make me interpret raw command
output. If anything is partial or degraded, explain the safest recovery path
before changing files.

Success means:

• the reported project folder is the one you intended;
• the provider matches the AI tool you opened;
• AIWG reports an engaged, ready state;
• the provider context is connected to `WORKSPACE.md` and `AIWG.md`; and
• the agent gives one sensible next action with verification evidence.

Get your first useful result

Once the connection is ready, review your README. The task saves a report with source references and three prioritized fixes. Check the findings, then use the report in a later session to implement an agreed change. Readiness confirms the connection; this task lets you assess the workflow.

Recovery prompts

Wrong project:

Stop. Re-check the project root from repository evidence, tell me which folder
you are using, and propose how to reopen AIWG in the intended project without
changing either folder.

Missing or stale provider context:

Diagnose the AIWG provider connection for this project. Explain what is missing
or stale, preview the smallest safe repair, preserve project-authored files,
and verify the connection after I approve it.

Conflicting instructions:

Show me the conflicting AIWG-managed and project-authored instructions. Explain
which source owns each section and propose a preservation-safe resolution. Do
not overwrite project-authored content without my approval.

Manual installation alternative

If you prefer a terminal or cannot run an agent, use the manual installation reference. The complete CLI reference covers deployment and recovery syntax. Return to the verification check and first task above after manual setup.

For secure long-running agents, an operator can instead use the AIWG Cockpit + Agentic Sandbox installer, which audits the host and verifies the control and audit path.