# Codex Agent Instructions (AGENTS.md)

You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.

This file is read by every local Codex surface — the **Codex IDE extension** (VS Code / Cursor / Windsurf), **Codex mode in the ChatGPT desktop app**, and the **`codex` CLI**. They share the same `CODEX_HOME` config, skills, and MCP setup, so the instructions below apply identically in all three.

> **Important:** Codex has no session-start hook. At the beginning of **every** session, read `.aiflow/context/current.json` yourself to load the ticket context, then check `AK-Docs/04.Coding/` for existing progress before starting any task.

Gate 1 does **not** auto-start under Codex. Wait for the developer to type **"start"**, **"Gate 1"**, **"Analyze ticket"**, or to run the `ak-coding` skill.

## Where things live

| What | Path | Notes |
|------|------|-------|
| Ticket context | `.aiflow/context/current.json` | Written by `ak use <TICKET>` |
| Task progress | `AK-Docs/04.Coding/<section>/[functionId]/[ticketId].md` | Read before starting; never re-derive |
| Team rules | `.rules/` | Language + common rules |
| Full gate workflows | `.aiflow/instructions/` | See "Workflow instructions" below |
| Skills | `.codex/skills/*/SKILL.md` | Project-level Codex skills |
| Kit documentation | `.aiflow/docs/` | Start at `.aiflow/docs/INDEX.md` |

## Workflow instructions — read on demand

The complete gate workflows are **not inlined in this file**. Codex caps the combined
`AGENTS.md` chain at `project_doc_max_bytes` (32 KiB by default) and the full workflow set is
far larger, so it would be silently truncated mid-gate. Read the file you need from disk
when you need it:

- **DEV 5-Gate coding workflow** → `.aiflow/instructions/gate-workflow.md` (read this at Gate 1 and keep it open for the whole ticket)
- **BA 4-Gate spec creation** → `.aiflow/instructions/create-spec-workflow.md`
- **QA 4-Gate testcase creation** → `.aiflow/instructions/create-testcase-workflow.md`

Read the relevant file **in full** before starting a gate. Do not work from memory of a
previous session, and do not summarize a workflow file instead of following it.

## Skills

Project skills live in `.codex/skills/`. When a workflow step says **INVOKE:** `<skill-name>`,
read `.codex/skills/<skill-name>/SKILL.md` and follow its instructions exactly.

`.claude/skills/` holds a byte-identical copy of the same skills — `ak init` always
writes it. If a workflow file names a `.claude/skills/...` path, read it as-is; it is the
same file. Only `.codex/skills/` is auto-indexed by Codex.

Four entry-point skills wrap the workflows above:

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

## Interaction Rules

- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
- **NEVER BATCH QUESTIONS:** Only ask one question per message.
- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `.rules/project-conventions.md` if present. These rules override upstream skill defaults.
- **NO AUTO-COMMIT:** Never `git commit`, `git push`, or `git reset --hard` unless the developer explicitly asks. Codex's approval modes do not substitute for this rule.

## Asking about ai-flow-kit itself

If the developer's message is prefixed with `AKQ:` or `[AKQ]:`, OR is a question about ai-flow-kit itself (install/setup, roles, folder structure, CLI commands, memory draft/submit, troubleshooting, switching AI tools) rather than the current ticket — even when no ticket context is loaded — do **not** start Gate 1. Instead follow `.codex/skills/aiflow-help/SKILL.md`.

## Telemetry Command (detect once, use everywhere)

Before the first gate, run this to detect the correct `ak` command for your environment:

```bash
command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
```

Use whichever prints (e.g. `ak` on native Linux/macOS/Windows, `ak.cmd` on WSL without `ak` installed).
All `ak gate ...` examples in the workflow files assume the detected command. Substitute accordingly.