ai-coding-ok

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.