# Multi-AI Environment Integration

`ai-flow-kit` is designed to be tool-agnostic. While it works best with Claude Code CLI due to deep MCP integration, you can use it with any AI tool.

## Supported Environments

| Tool | Instruction File | Support Level | Key Features |
|------|------------------|---------------|--------------|
| **Claude Code** | `CLAUDE.md` | Native (Best) | Auto-triggers, full MCP access, session hooks. |
| **Codex** (VS Code extension, ChatGPT desktop app, CLI) | `AGENTS.md` | High | Auto-discovered skills (`.codex/skills/`), MCP via `.codex/config.toml`. |
| **Cursor** | `.cursorrules` | High | Project-wide rules, `@Codebase` context. |
| **Gemini CLI** | `GEMINI.md` | Medium | System instructions support. |
| **GitHub Copilot** | `.github/copilot-instructions.md` | Medium | Inline suggestions, custom instructions. |
| **OpenCode / Generic** | `AI_INSTRUCTIONS.md` | General | Manual context loading. |

Select which tools to configure with `--env`:

```bash
ak init --framework reactjs --env claude,codex
```

Omitting `--env` configures every tool except `generic`.

---

## Tool-Specific Setup

### 1. Cursor AI
When you run `aiflow init`, it generates a `.cursorrules` file. 
- Cursor will automatically read this file to understand the **Gate Workflow**.
- Use `@Codebase` when you need the AI to search across your whole project.
- **Resumption**: If you start a task in Claude Code and switch to Cursor, Cursor will see the generated `AK-Docs/04.Coding/` docs and resume from where you left off.

### 2. Gemini CLI
Pass `GEMINI.md` as system instructions to your Gemini session.
- **Tip**: Always ensure the AI reads `.aiflow/context/current.json` first to load the ticket context.
- Gemini is excellent for large context analysis during Gate 1.

### 3. GitHub Copilot
Copilot uses `.github/copilot-instructions.md` to guide its suggestions.
- This ensures that Copilot's inline completions follow your project's architecture and team rules.

### 4. Codex (OpenAI)

`ak init --env codex` sets up all three local Codex surfaces at once — they share the same
`CODEX_HOME` config, skills and MCP setup, so one install covers every one of them:

| Surface | How to use it |
|---------|---------------|
| **Codex IDE extension** (VS Code / Cursor / Windsurf) | Open the project folder → Codex panel → `/ak-coding` |
| **ChatGPT desktop app** (Codex mode) | Point Codex at this project folder → `/ak-coding` |
| **`codex` CLI** | `cd` into the project → `codex` → `/ak-coding` |

What gets generated:

| File | Purpose |
|------|---------|
| `AGENTS.md` | Instruction file Codex reads automatically at the repo root |
| `.codex/skills/` | All kit skills, auto-discovered and indexed by Codex |
| `.codex/config.toml` | MCP servers (mirrored from `.mcp.json`) + `project_doc_max_bytes` |
| `.aiflow/instructions/` | The full gate workflows, which `AGENTS.md` links to |

**Why `AGENTS.md` links to the workflows instead of containing them.** Codex truncates the
combined `AGENTS.md` chain at `project_doc_max_bytes` — **32 KiB by default**. The assembled
workflow set is around 115 KB, so inlining it the way `CLAUDE.md` does would silently cut the
instructions off mid-gate. `AGENTS.md` therefore stays around 20 KB and points at
`.aiflow/instructions/gate-workflow.md` (plus the BA and QA workflows), which Codex reads on
demand. `.codex/config.toml` also raises the limit to 128 KiB as a safety margin for
multi-framework projects.

**Entry-point skills.** Four skills wrap the workflows so you can start without remembering
file paths:

| Skill | Use it for |
|-------|-----------|
| `/ak-coding` | Start or resume the DEV 5-Gate coding workflow |
| `/ak-create-spec` | BA spec creation |
| `/ak-create-testcase` | QA testcase creation |
| `/ak-ask` | Questions about ai-flow-kit itself |

**Things to know:**

- **No session-start hook.** Unlike Claude Code, Codex will not auto-load a ticket. After
  `ak use <TICKET>`, start a **new** Codex session so it re-reads `AGENTS.md`, then run
  `/ak-coding`.
- **Restart after `ak update` / `ak sync-skills`.** Codex loads skill metadata at session
  start, so new or changed skills need a fresh session.
- **Project trust.** Codex only loads `.codex/config.toml` for projects you have trusted. If
  MCP servers do not appear, trust the project in Codex first.
- **Hand-edited config is never overwritten.** If `.codex/config.toml` exists without the
  `# ai-flow-kit managed` header, the kit leaves it alone and writes the generated version to
  `.aiflow/reference/codex-config.toml` for you to merge.

Verify the whole setup with `ak doctor`, which checks `AGENTS.md` against the active byte
budget, the skill mirror, the workflow files, and MCP drift between `.mcp.json` and
`.codex/config.toml`.

---

## Cross-Tool State Resumption
The "Secret Sauce" of `ai-flow-kit` is its file-based state management:

1. **Context**: Saved in `.aiflow/context/current.json`.
2. **Progress**: Saved as Markdown docs in `AK-Docs/04.Coding/<section>/[functionId]/[ticketId].md`.
3. **Rules**: Saved in `.rules/`.

Because these are standard files, any AI tool can read them. You can:
1. Start **Gate 1** (Analysis) in Claude Code.
2. Review and **Approve** the requirement doc.
3. Switch to **Cursor** or **Codex** for **Gate 3** (Coding) because you prefer the IDE integrations.
4. Switch back to **Claude Code** for **Gate 4** (Self-Review) to use its automated testing power.

When resuming in Codex, run `/ak-coding`: it reads `.aiflow/tasks/[taskId]/task-state.json`
and picks up at the gate already in progress instead of restarting from Gate 1.

---

## Best Practices
- **Always Approve Docs**: Ensure `requirement.md` and `plan.md` are approved (you can just type "APPROVED" in the chat or edit the file to say so).
- **Update Status**: If you make progress in a tool that doesn't have hooks, manually update the `summary.md` or the ticket status.