ai-coding-ok

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:

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:

### [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:

### 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:

### [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

## 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.