Four Modes

Four Modes (A/B/C/D)

ai-coding-ok has four operating modes that cover the full lifecycle: Install, Plan, Act, and Upgrade. Each mode has clear trigger conditions and a defined execution flow.

---

Mode overview

graph TD
    Start([User starts a task]) --> Check{Project has<br/>.github/agent/memory/?}
    Check -->|No| ModeA[Mode A: Install]
    Check -->|Yes| Intent{What is the user asking?}
    Intent -->|"install ai-coding-ok"| ModeA
    Intent -->|"upgrade ai-coding-ok"| ModeD[Mode D: Upgrade]
    Intent -->|Any coding task| ModeB[Mode B: Plan]
    ModeB --> ModeC[Mode C: Act]
    ModeD --> Done([Done])
    ModeA --> Done
    ModeC --> Done

Loading

---

Mode A: Install

Trigger: The project does NOT have .github/agent/memory/ yet, OR the user explicitly says "install ai-coding-ok".

Purpose: One-time setup — copy templates, customize placeholders, bootstrap memory.

Execution flow (8 steps):

Step	Action
1	Detect language (en/zh) from user's input
2	Locate template directory (templates/en/ or templates/zh/)
3	Conflict check — warn if AGENTS.md, CLAUDE.md, or .github/agent/ already exist
4	Copy templates into the project
5	Ask: "What are you building?" (one sentence)
5.5	Ask: "Where does your source code live?" (for hooks)
5.6	Configure Claude Code hooks (if .claude/ exists)
6	Infer tech stack, replace all {{placeholders}}
7	Bootstrap TASK-001 (install record)
8	Report: checklist of installed files + key decisions

Output: A fully customized ai-coding-ok installation in the project. PDCA loop is active immediately.

---

Mode B: Plan

Trigger: The project HAS .github/agent/memory/ AND the user requests any development work (feature, fix, refactor, design, etc.).

Purpose: Load project context before writing code.

Execution flow:

1. Read AGENTS.md — architecture cheatsheet
2. Read .github/agent/system-prompt.md — agent persona and behavior
3. Read .github/agent/workflows.md — scenario workflows
4. Read .github/agent/coding-standards.md — coding conventions
5. Read .github/agent/memory/project-memory.md — project facts
6. Read .github/agent/memory/decisions-log.md — historical decisions
7. Read .github/agent/memory/task-history.md — recent task context

Time cost: ~30 seconds.

Important: Mode B is context loading, NOT a replacement for the user's task. After reading, the AI proceeds with the actual task.

⚠️ If another skill is also triggered (e.g., writing-plans from superpowers), execute Mode B first, then enter that skill.

---

Mode C: Act

Trigger: A coding/design task has just been completed.

Purpose: Write back to memory — close the PDCA loop.

Execution flow:

Priority	Action	Condition
1	Update task-history.md	Always — every task
2	Update decisions-log.md	Architecture/tech decisions changed
3	Update project-memory.md	Project facts changed
4	Update agent docs	AGENTS.md, system-prompt.md, etc. have stale content

Output format: Every response must include a ## Memory Updates section:

## Memory Updates

- ✅ task-history.md — TASK-XXX: [summary]
- ✅ decisions-log.md — ADR-XXX: [new decision] (if applicable)
- ⬜ project-memory.md — no changes needed

⛔ v3.0.1+: The Memory Updates section is mandatory. Omitting it is non-compliant. This is enforced by .github/copilot-instructions.md and .github/agent/system-prompt.md.

When Act CAN be skipped (legitimate exceptions):

• Pure conversation/information questions (no code changed)
• The user explicitly says "don't update memory this time"
• The task was aborted before any changes were made

---

Mode D: Upgrade

Trigger: The user says "upgrade ai-coding-ok", "update ai-coding-ok", or equivalent.

Purpose: Update framework files to the latest version while preserving project customizations.

Execution flow (8 steps):

Step	Action
1	Detect current version from file markers
2	Read latest templates
3	Diff framework changes (added/removed/modified sections)
4	Show change list to user, ask for confirmation
5	Apply changes (merge, preserve project customizations)
6	Bump version markers in all files
7	Record upgrade in task-history.md
8	Report: old → new version, files changed, customizations preserved

Safety: Never auto-applies. Always asks for confirmation. Never overwrites project-specific content (project name, tech stack, architecture diagrams).

---

Mode transition table

From	To	When
(none)	Mode A	No .github/agent/memory/ exists
(none)	Mode B	.github/agent/memory/ exists + any coding task
Mode B	Mode C	Task completed
(any)	Mode D	User says "upgrade"

---

Triggers that activate each mode

Mode A triggers

• install ai-coding-ok
• 初始化 ai-coding-ok
• set up project memory
• 给项目装上三层记忆系统
• Project has no .github/agent/memory/

Mode B triggers

• Any coding task in a project with .github/agent/memory/
• feat: ..., fix: ..., refactor: ..., 新功能, 修复, 重构
• add feature, write tests, code review, implement

Mode C triggers

• Task completion (automatic — no user trigger needed)

Mode D triggers

• upgrade ai-coding-ok
• update ai-coding-ok
• 升级 ai-coding-ok
• 更新 ai-coding-ok

---

Next steps

• PDCA Workflow — how Mode B and Mode C form the PDCA loop
• Five-Layer Defense — how the modes are enforced
• Upgrade ai-coding-ok — detailed Mode D walkthrough