File Structure

File Structure

Complete directory tree of ai-coding-ok, with every file explained.

---

Repository root

ai-coding-ok/
├── SKILL.md                          # Skill definition entry point (Mode A/B/C/D)
├── CLAUDE.md                         # Claude Code auto-load shim → @AGENTS.md
├── AGENTS.md                         # Architecture cheatsheet (self-dogfooding)
├── README.md                         # English README (landing page)
├── README.zh.md                      # Chinese README
├── CHANGELOG.md                      # Version history
├── LICENSE                           # MIT
├── install.sh                        # Bash install script
├── install.py                        # Python install script (cross-platform)
│
├── .claude-plugin/
│   └── plugin.json                   # Plugin manifest for /plugin install
│
├── skills/
│   └── ai-coding-ok/
│       └── SKILL.md                  # Canonical English skill definition
│
├── templates/                        # ← PRODUCT SOURCE — do not modify in install
│   ├── en/                           # English templates (18 files)
│   │   ├── AGENTS.md
│   │   ├── CLAUDE.md
│   │   ├── .claude/
│   │   │   └── settings.local.json
│   │   ├── .cursor/
│   │   │   └── rules/
│   │   │       └── ai-coding-ok.mdc
│   │   └── .github/
│   │       ├── copilot-instructions.md
│   │       ├── project-metadata.yml
│   │       ├── PULL_REQUEST_TEMPLATE.md
│   │       ├── ISSUE_TEMPLATE/
│   │       ├── workflows/
│   │       │   ├── ci.yml
│   │       │   └── memory-check.yml
│   │       └── agent/
│   │           ├── system-prompt.md
│   │           ├── coding-standards.md
│   │           ├── workflows.md
│   │           ├── prompt-templates.md
│   │           └── memory/
│   │               ├── project-memory.md
│   │               ├── decisions-log.md
│   │               └── task-history.md
│   └── zh/                           # Chinese templates (same structure)
│       └── ... (same files as en/)
│
├── scripts/
│   ├── verify.sh                     # Installation verification
│   ├── customize-prompt.md           # Manual customization prompt for Copilot
│   └── upgrade-prompt.md             # Manual upgrade prompt for Copilot
│
├── docs/
│   ├── claude-code-quickstart.md     # Claude Code user guide
│   ├── copilot-quickstart.md         # Copilot user guide
│   ├── superpowers-combo.md          # Combo usage with superpowers
│   ├── faq.md                        # Frequently asked questions
│   ├── hook-trigger-remediation-plan.md  # v3.1.0 defense system design doc
│   └── ai-coding-ok-improvement-plan.md  # Improvement proposals
│
└── .github/                          # Self-dogfooding (ai-coding-ok's own memory)
    └── agent/
        ├── system-prompt.md
        ├── coding-standards.md
        ├── workflows.md
        ├── prompt-templates.md
        └── memory/
            ├── project-memory.md
            ├── decisions-log.md
            └── task-history.md

---

Key directories explained

templates/ — The product

This is the source of truth for all files that get installed into user projects. Two language variants (en/ and zh/) with identical structure.

Rule: Never modify templates/ during an install or upgrade. Only modify when developing ai-coding-ok itself.

skills/ai-coding-ok/ — The skill definition

The canonical SKILL.md that Claude Code loads when the plugin is installed. This is the "brain" of ai-coding-ok.

The root SKILL.md is a symlink/copy for legacy git-clone users. The canonical version is in skills/ai-coding-ok/SKILL.md.

scripts/ — Automation

Script	Purpose	Dependencies
install.sh	Install ai-coding-ok into a project	bash only
install.py	Same, cross-platform (Windows)	Python 3.8+ stdlib
verify.sh	Check installation integrity	bash only
customize-prompt.md	Prompt for Copilot to fill placeholders	None (text)
upgrade-prompt.md	Prompt for Copilot to upgrade	None (text)

docs/ — Documentation

User-facing documentation. Separate from the wiki (which is on GitHub wiki).

.github/ — Self-dogfooding

ai-coding-ok uses its own memory system to track its own development. This .github/ directory is the self-dogfooding installation — it's separate from the templates and is not distributed to users.

---

What gets installed in a user's project

<user-project>/
├── AGENTS.md                          # Architecture cheatsheet (AI reads first)
├── CLAUDE.md                          # Claude Code auto-load → @AGENTS.md
├── .cursor/
│   └── rules/
│       └── ai-coding-ok.mdc           # Cursor: alwaysApply PDCA rule
└── .github/
    ├── copilot-instructions.md        # Copilot: auto-loaded behavior rules
    ├── project-metadata.yml           # Machine-readable project facts
    ├── PULL_REQUEST_TEMPLATE.md       # PR template (memory-update checklist)
    ├── ISSUE_TEMPLATE/                # Bug/Feature issue templates
    ├── workflows/
    │   ├── ci.yml                     # CI pipeline template
    │   └── memory-check.yml           # PR memory update reminder
    └── agent/
        ├── system-prompt.md           # Agent persona + PDCA workflow
        ├── coding-standards.md        # Coding conventions
        ├── workflows.md               # Scenario playbooks
        ├── prompt-templates.md        # Prompt template library
        └── memory/
            ├── project-memory.md      # 🧠 Long-term: project facts
            ├── decisions-log.md       # 📝 Mid-term: ADRs
            └── task-history.md        # 📜 Short-term: last 30 tasks

---

Data flow

graph LR
    subgraph "ai-coding-ok repo"
        TPL[templates/en/ + zh/]
        SKILL[skills/ai-coding-ok/SKILL.md]
    end
    subgraph "Install process"
        COPY[Copy files]
        FILL[Fill placeholders]
        BOOT[Bootstrap memory]
    end
    subgraph "User's project"
        AGENTS[AGENTS.md]
        MEMORY[.github/agent/memory/]
        HOOKS[.claude/settings.local.json]
    end
    subgraph "Runtime"
        AI[AI reads memory<br/>before coding]
        ACT[AI writes memory<br/>after coding]
    end
    TPL --> COPY
    SKILL --> COPY
    COPY --> FILL --> BOOT
    BOOT --> AGENTS
    BOOT --> MEMORY
    BOOT --> HOOKS
    AGENTS --> AI
    MEMORY --> AI
    AI --> ACT
    ACT --> MEMORY

Loading

---

Version markers

Every installed file has a version marker on line 1:

<!-- ai-coding-ok: v3.1.0 -->

or

# ai-coding-ok: v3.1.0

These markers are used by the Upgrade system to detect the installed version and determine what changes to apply.

---

Next steps

• Template System — how templates work and how to modify them
• Hooks System — Claude Code hooks configuration
• Version Management — how versioning and upgrades work