PDCA memory loop for Claude Code. Reads three-tier project memory (project-memory, decisions-log, task-history) before every task and writes back after, so iteration 50 has the same context quality as iteration 1. Pairs with superpowers — discipline + memory.
USE THIS SKILL FIRST on any coding task (feat, fix, bug, refactor, plan, design, brainstorm, code review, implement, add feature, write tests, 新功能, 修复, 重构) when the project contains `.github/agent/memory/` or `AGENTS.md`. Loads three-tier project memory (project-memory, decisions-log, task-history) and AGENTS.md BEFORE writing code, then updates task-history (always), decisions-log (on architecture changes) and project-memory (on fact changes) AFTER finishing — the PDCA guardrail that prevents "AI fixed bug X and broke feature Y" across iterations. Also handles INSTALL when the user asks to "install ai-coding-ok", "set up project memory", "initialize AI guardrails", or the project has no `.github/agent/memory/` yet — copy templates and customize placeholders. Also handles UPGRADE when the user says "upgrade ai-coding-ok", "update ai-coding-ok", "升级 ai-coding-ok", or "更新 ai-coding-ok" — diff project files against latest templates and apply framework-level changes while preserving project customizations.
# ai-coding-ok — PDCA Memory Loop
A three-tier memory system + AI coding guardrails. The PDCA closed loop (Plan → Do → Check → Act) keeps project context accurate across sessions and iterations. Works with Claude Code, GitHub Copilot, OpenCode, and Cursor.
## What this skill installs
When activated in a project, the skill copies a curated set of files into the target project:
```
<project-root>/
├── AGENTS.md # Architecture cheatsheet (AI reads first)
├── CLAUDE.md # Claude Code auto-load shim → @AGENTS.md
└── .github/
├── copilot-instructions.md # Global behavior rules (Copilot auto-loads)
├── project-metadata.yml # Machine-readable project facts
├── PULL_REQUEST_TEMPLATE.md
├── ISSUE_TEMPLATE/…
├── workflows/ # CI + memory update reminder
└── agent/
├── system-prompt.md # Agent persona + PDCA workflow
├── coding-standards.md
├── workflows.md # Scenario playbooks
├── prompt-templates.md
└── memory/
├── project-memory.md # 🧠 Long-term memory (facts, constraints)
├── decisions-log.md # 📝 Mid-term memory (ADRs)
└── task-history.md # 📜 Short-term memory (recent tasks)
```
## When to invoke this skill
Determine which mode applies, then follow that mode's instructions.
### Mode A — Install (one-time, on a new project)
**Triggers:**
- The user explicitly asks to install the memory system ("install ai-coding-ok", "set up project memory", "初始化 ai-coding-ok", etc.)
- The project does not yet contain `.github/agent/memory/`
**Action:**
→ Follow the **Installation Playbook** below (Steps 1–8)
---
### Mode B — PDCA Plan (every coding task — before writing code)
**Triggers:**
- The project already contains `.github/agent/memory/`
- The user requests any development work (new feature, bug fix, refactor, design, brainstorming, plan writing, code review, etc.)
**Action (~30 seconds, before any actual work):**
1. Read `AGENTS.md` — architecture cheatsheet
2. Read `.github/agent/memory/project-memory.md` — stable facts and constraints
3. Read `.github/agent/memory/decisions-log.md` — historical technical decisions
4. Read `.github/agent/memory/task-history.md` — recent task context
5. Internally (or to the user) summarize key constraints to confirm understanding
6. **Then continue with the user's original task** (do not stop here)
> ⚠️ Mode B is NOT a replacement for the user's task. It is context loading that happens before the task. If another skill is also triggered (e.g. `writing-plans` from superpowers), execute Mode B first, then enter that skill.
---
### Mode C — PDCA Act (every coding task — after finishing)
**Triggers:**
- A coding/design task has just been completed and final output is about to be returned to the user
**Action (must not skip):**
1. Update `.github/agent/memory/task-history.md` — record this task's summary
2. If architecture/technical decisions changed → update `.github/agent/memory/decisions-log.md`
3. If basic project facts changed (new modules, tech stack changes, etc.) → update `.github/agent/memory/project-memory.md`
4. Include a "Memory Updates" section in the final output, listing which memory files were updated
> ⚠️ If context limits prevent direct file edits, output the required updates as text and tell the user to apply them manually.
---
### Mode D — Upgrade (upgrade an installed ai-coding-ok)
**Triggers:**
- The user says "upgrade ai-coding-ok", "update ai-coding-ok", "升级 ai-coding-ok", or "更新 ai-coding-ok"
**Action:**
→ Follow the **Upgrade Playbook** below
## Language detection
Before Mode A or any user-facing output, detect the user's language:
- If the user's request contains predominantly Chinese characters → use Chinese for all communication, and use templates from `templates/zh/`
- Otherwise → use English, and use templates from `templates/en/`
When in doubt, ask the user once: "Should I install the English or Chinese template? (en/zh)"
## Installation Playbook (Mode A only)
> ⚠️ These steps run only in Mode A (first install). Mode B and Mode C do NOT use this flow.
Follow the steps in order. Do not skip Step 4 (customization) — unfilled `{{placeholders}}` defeat the whole purpose.
### Step 1 — Locate the skill's template directory
The templates live at `<plugin-root>/templates/{en|zh}/`, where `<plugin-root>` is the parent directory of the directory containing this `SKILL.md`. Resolve the absolute path before copying.
If invoked via `claude --plugin-dir`, use:
```
<plugin-dir>/templates/en/ # English projects
<plugin-dir>/templates/zh/ # Chinese projects
```
If invoked from a legacy git-clone install at `~/.claude/skills/ai-coding-ok/`, use:
```
~/.claude/skills/ai-coding-ok/templates/{en|zh}/
```
### Step 2 — Pick the target project
Default target is the current working directory. Confirm with the user only if:
- The cwd is obviously not a project (e.g. `$HOME`, `/tmp`).
- Key files already exist and would be overwritten (see Step 3 conflict check).
### Step 3 — Conflict check (non-destructive)
Before copying anything, check whether any of these paths already exist in the target:
- `AGENTS.md`
- `CLAUDE.md`
- `.github/copilot-instructions.md`
- `.github/agent/` (directory)
If **any** exist, STOP and report to the user. Offer three choices:
1. Overwrite (risky — they may have hand-edits).
2. Copy only missing files (safe, recommended).
3. Abort.
Never silently overwrite existing files.
### Step 4 — Copy templates into the project
Copy the entire contents of the chosen language template directory into the project root. On POSIX:
```bash
cp -rn <plugin-root>/templates/<lang>/. <project-root>/
```
`-n` = no-clobber, keeping the user's existing edits safe. On Windows/Node, do an equivalent merge-copy.
Verify the target files/dirs are present. Fail loudly if any are missing.
### Step 5 — Ask the user what they're building
Do NOT ask the user to fill in placeholders manually. Instead, ask a single plain-language question:
> "In one sentence, what are you building? Example: 'A personal expense tracker that records what I spend each day.'"
(Chinese: "一句话告诉我你想做一个什么东西？")
### Step 6 — Infer and replace placeholders
Based on the user's sentence, infer:
- Project name (`{{project-name}}` / `{{项目名称}}`)
- Project type (`{{project-type}}`, `{{project-type-brief}}`)
- Tech stack (language, framework, DB, ORM, test framework, package manager, etc.)
- Design principles (for a personal tool: "minimalist, practical"; for an internal tool: "maintainability > performance"; etc.)
- User scale, core features, business concepts, architecture, etc.
Then walk every copied file and replace every `{{...}}` placeholder with the inferred value. Files to process:
- `AGENTS.md`
- `CLAUDE.md` (Claude Code shim — typically just `@AGENTS.md`, no placeholder, but verify)
- `.github/copilot-instructions.md`
- `.github/project-metadata.yml`
- `.github/ISSUE_TEMPLATE/config.yml`
- `.github/workflows/ci.yml`
- `.github/workflows/memory-check.yml`
- `.github/agent/system-prompt.md`
- `.github/agent/coding-standards.md`
- `.github/agent/workflows.md`
- `.github/agent/prompt-templates.md`
- `.github/agent/memory/project-memory.md`
- `.github/agent/memory/decisions-log.md`
- `.github/agent/memory/task-history.md`
For `{{YYYY-MM-DD}}` placeholders use today's date.
When uncertain about a choice (e.g. "SQLite vs Postgres?"), pick the simpler one and note it in `decisions-log.md` as ADR-001. The user can override later.
### Step 7 — Bootstrap the first memory entries
After replacement, populate `task-history.md` with a real first entry:
```markdown
### [TASK-001] Install ai-coding-ok and initialize project
- **Date**: <today>
- **Type**: chore
- **Summary**: Installed three-tier memory system and coding standards via the ai-coding-ok skill. Tech stack and constraints were inferred from the user's one-sentence description (<user's exact words>) and applied automatically.
- **Files changed**: AGENTS.md, .github/**/*
- **Notes**: First run — keep `project-memory.md` and `decisions-log.md` in sync as architecture evolves.
```
### Step 8 — Report back to the user
Output:
1. A checklist of files installed and customized.
2. Key inferred decisions (tech stack, design principle) so the user can sanity-check.
3. Next steps: "Open `AGENTS.md` to review. From now on, I will read the memory files before every task and update `task-history.md` after every task."
## Working rules after installation
Once installed, ALL subsequent sessions (this one included) must follow the PDCA loop defined in `.github/agent/system-prompt.md`:
1. **Plan** — Read `AGENTS.md` + `.github/agent/memory/*.md` before touching code.
2. **Do** — Write code AND tests in the same change.
3. **Check** — Run tests. Verify no regression in unrelated features.
4. **Act** — Update `task-history.md` (always), `decisions-log.md` (when architecture changed), `project-memory.md` (when facts changed).
This is the mechanism that prevents "AI fixed bug X and deleted feature Y".
## Compatibility with superpowers
When `superpowers` and `ai-coding-ok` are both installed, **ai-coding-ok is responsible for ensuring PDCA runs end to end**, without depending on superpowers to cooperate.
### Execution paths
```
Path A (with superpowers):
using-superpowers → brainstorming → writing-plans → executing-plans
↑
brainstorming Step 1 reads AGENTS.md (Explore project context)
← The PDCA mandate at the top of AGENTS.md is the hook point
Path B (no superpowers, pure ai-coding-ok):
user request → AI scans skill triggers → invokes ai-coding-ok SKILL.md
← SKILL.md Mode B / Mode C is the hook point
```
### Rule 1: before invoking any superpowers skill
Before invoking `brainstorming` / `writing-plans` / `executing-plans`, run **Mode B** first (read memory files). This carries constraints and historical context into the downstream flow.
### Rule 2: when writing-plans generates a plan
Whatever `writing-plans` produces, append after the **last task** of the plan:
```markdown
### Task N+1: Update project memory (PDCA Act — ⚠️ DO NOT SKIP)
**Files:**
- Modify: `.github/agent/memory/task-history.md`
- Modify: `.github/agent/memory/decisions-log.md` (if architecture changed)
- Modify: `.github/agent/memory/project-memory.md` (if facts changed)
- [ ] Update task-history.md with a summary of this work
- [ ] If this work introduced architecture/tech decisions → record a new ADR in decisions-log.md
- [ ] If project facts changed (new modules, new dependencies, status changes) → update project-memory.md
- [ ] Confirm all memory files are updated
```
### Rule 3: after executing-plans / subagent-driven-development finishes
Run **Mode C** (Act phase) and update memory files. This step is enforced by ai-coding-ok itself, regardless of which superpowers version is installed.
### Rule 4: AGENTS.md is the hook for Path A
`templates/{en,zh}/AGENTS.md` already embeds the PDCA mandate at the top. When `brainstorming` Step 1 (Explore project context) reads AGENTS.md, the AI hits the PDCA requirement directly and executes it. This guarantees PDCA runs even if `ai-coding-ok` SKILL.md is not triggered — AGENTS.md takes over.
## Upgrade Playbook (Mode D only)
> ⚠️ These steps run only in Mode D (upgrade).
### Step 1 — Detect the current version
Read the first line of these files in the project and extract the version marker:
- `AGENTS.md`
- `.github/copilot-instructions.md`
- `.github/agent/system-prompt.md`
- `.github/agent/coding-standards.md`
- `.github/agent/workflows.md`
- `.github/agent/prompt-templates.md`
Version marker formats: `<!-- ai-coding-ok: vX.Y -->` or `# ai-coding-ok: vX.Y`.
If any file lacks a version marker, treat it as v1.0 (initial release, no markers).
Report the detected version to the user:
> "Detected ai-coding-ok version in this project: vX.Y. Latest template version: vX.Y."
### Step 2 — Read the latest templates
Read all template files in `<plugin-root>/templates/<lang>/` — these contain `{{placeholders}}` and represent the latest framework structure.
### Step 3 — Identify framework changes
Diff the **latest template structure** against the **installed files** in the project, file by file:
Strategy:
- Diff at the granularity of Markdown sections (`##` / `###`)
- Identify three change types:
1. **Added section**: in template, not in project → insert
2. **Removed section**: removed from template, still in project → ask the user before deleting
3. **Modified section**: section content changed → smart merge
Output a change summary, e.g. (v2.1.0 → v2.2.0):
```
Upgrade change list:
✅ templates/CLAUDE.md — new (Claude Code auto-load shim, @AGENTS.md import)
✅ all files — version marker bump v2.1.0 → v2.2.0
```
> 📌 **Historical upgrade paths** (look up your current installed version):
>
> | Path | Main changes |
> |------|--------------|
> | v1.0 → v2.0 | AGENTS.md / copilot-instructions.md gain mandatory PDCA section; workflows.md Step 5 gets "⚠️ DO NOT SKIP" annotation; all files get version markers |
> | v2.0 → v2.1.0 | Add `templates/.cursor/rules/ai-coding-ok.mdc` (Cursor support); version markers bumped to v2.1.0 |
> | v2.1.0 → v2.2.0 | Add `templates/CLAUDE.md` (Claude Code auto-load shim → @AGENTS.md); SKILL.md description rewritten (framework only, no project-file impact); version markers bumped to v2.2.0 |
> | v2.2.0 → v3.0.0 | Plugin packaging (`.claude-plugin/plugin.json`, `skills/ai-coding-ok/`); bilingual templates (`templates/en/`, `templates/zh/`); README split (English root, Chinese in `README.zh.md`); version markers bumped to v3.0.0 |
>
> Apply versions in order across multi-step jumps (e.g. v1.0 → v2.0 → v2.1.0 → v2.2.0 → v3.0.0).
### Step 4 — Confirm with the user
Show the change list to the user and ask:
> "These are the planned upgrade changes. Continue? (Y/n)"
⚠️ **Never auto-apply** — upgrade modifies existing files and must be user-confirmed.
### Step 5 — Apply the upgrade
Once confirmed, apply changes file by file:
**5a. Add sections:**
- Find the insertion point (based on positional context in the template)
- Replace `{{placeholders}}` in the new content with values already filled in the project
- Extract filled values from existing project files (project name, tech stack, etc.)
- If the new section has no placeholders (e.g. PDCA mandate block), insert directly
- Insert at the correct position
**5b. Remove sections:**
- Find the section's start and end (heading to next same-level heading)
- Delete the entire section
**5c. Modify sections:**
- Read the new section content from the template
- Replace `{{placeholders}}` with the project's actual values
- Replace the old section in the project
**5d. Bump version markers:**
- Update each file's first-line version marker to the latest version
- If the file lacks a version marker, insert one at line 1
### Step 6 — Verify
- Confirm version markers in all files are updated
- Confirm project-specific content (architecture diagrams, module lists, tech stack) was preserved
- Confirm no `{{placeholders}}` leaked into project files
### Step 7 — Record the upgrade
Append to `.github/agent/memory/task-history.md`:
```markdown
### [TASK-00N] Upgrade ai-coding-ok to vX.Y
- **Date**: <today>
- **Type**: chore
- **Summary**: Auto-upgraded ai-coding-ok framework files via Mode D. Sections added/modified: <change summary>
- **Files changed**: <actual change list>
- **Notes**: <merge details to review, if any>
```
### Step 8 — Report
```markdown
## ai-coding-ok upgrade complete
| Item | Old | New |
|------|-----|-----|
| ai-coding-ok | vX.Y | vX.Y |
### Files changed
- ✅ AGENTS.md — <summary>
- ✅ .github/copilot-instructions.md — <summary>
- ...
### Project customizations preserved
- Project name, tech stack, architecture diagram unchanged
- Memory files (project-memory.md, etc.) unchanged
### Manual review needed
- <if any>
```
## For non-Claude-Code users (Copilot / Cursor / OpenCode)
These tools don't load SKILL.md. Their users get the same value via:
1. Run `install.sh` (or `install.py`) once at the plugin root to copy `templates/<lang>/` into their project.
2. Their tool auto-loads the appropriate file (`.github/copilot-instructions.md` for Copilot; `.cursor/rules/ai-coding-ok.mdc` for Cursor; `AGENTS.md` for OpenCode), which all reference the memory system and PDCA workflow.
3. For initial placeholder customization, paste `scripts/customize-prompt.md` into the tool's chat to trigger replacement.
## References
- `templates/en/`, `templates/zh/` — source of truth for installed files (bilingual since v3.0.0).
- `scripts/customize-prompt.md` — customization prompt for non-Claude-Code tools.
- `scripts/upgrade-prompt.md` — manual upgrade prompt for Copilot / Cursor.
- `scripts/verify.sh` — post-install sanity check.
- `docs/claude-code-quickstart.md` — Claude Code users.
- `docs/copilot-quickstart.md` — Copilot users.
- `docs/superpowers-combo.md` — combo recipes with `superpowers`.
- `docs/faq.md` — common questions.