Template System

Template System

How ai-coding-ok's template system works — the bilingual template architecture, placeholder system, and the install process that transforms templates into project files.

---

Overview

ai-coding-ok's core product is a set of template files that get installed into user projects. The templates contain {{placeholders}} that are replaced with project-specific values during installation.

graph TD
    subgraph "Templates (source)"
        EN[templates/en/<br/>18 files with placeholders]
        ZH[templates/zh/<br/>18 files with placeholders]
    end
    subgraph "Install process"
        DETECT[Detect language]
        COPY[Copy files]
        ASK[Ask: what are you building?]
        INFER[Infer tech stack]
        REPLACE[Replace placeholders]
        BOOT[Bootstrap memory]
    end
    subgraph "Installed (output)"
        PROJECT[User's project<br/>18 files with real values]
    end
    EN --> DETECT
    ZH --> DETECT
    DETECT --> COPY --> ASK --> INFER --> REPLACE --> BOOT --> PROJECT

Loading

---

Bilingual architecture

Since v3.0.0, ai-coding-ok maintains two parallel template sets:

templates/
├── en/    ← English templates
└── zh/    ← Chinese templates

Why two separate sets?

Approach	Pros	Cons
Single template + runtime translation	One source to maintain	Translation quality unreliable; placeholder logic complex
Bilingual templates (chosen)	Quality controllable; independently testable	Must sync two sets

Rule: Any change to templates/en/ must be mirrored in templates/zh/, and vice versa. This is enforced by convention (ADR-001).

Language detection

During install (Mode A), the AI detects the user's language:

• Chinese characters in the request → templates/zh/
• Otherwise → templates/en/
• If uncertain → ask the user

---

Complete template file list

#	File	Purpose	Has placeholders?
1	AGENTS.md	Architecture cheatsheet, PDCA mandate	✅
2	CLAUDE.md	Claude Code auto-load shim	✅
3	.claude/settings.local.json	Claude Code hooks	✅ (SOURCE_DIR_PATTERN)
4	.cursor/rules/ai-coding-ok.mdc	Cursor alwaysApply rule	✅
5	.github/copilot-instructions.md	Copilot behavior rules	✅
6	.github/project-metadata.yml	Machine-readable metadata	✅
7	.github/PULL_REQUEST_TEMPLATE.md	PR template	✅
8	.github/ISSUE_TEMPLATE/bug_report.md	Bug report template	✅
9	.github/ISSUE_TEMPLATE/feature_request.md	Feature request template	✅
10	.github/ISSUE_TEMPLATE/config.yml	Issue template config	✅
11	.github/workflows/ci.yml	CI pipeline	✅
12	.github/workflows/memory-check.yml	Memory update check	✅
13	.github/agent/system-prompt.md	Agent persona + PDCA	✅
14	.github/agent/coding-standards.md	Coding conventions	✅
15	.github/agent/workflows.md	Scenario playbooks	✅
16	.github/agent/prompt-templates.md	Prompt library	✅
17	.github/agent/memory/project-memory.md	Long-term memory	✅
18	.github/agent/memory/decisions-log.md	Decision log	✅
19	.github/agent/memory/task-history.md	Task history	✅

---

Placeholder system

What are placeholders?

Placeholders are {{double-braced}} tokens in template files that get replaced during installation:

# Before (template)
# {{project-name}} — Architecture

This is a {{project-type}} built with {{language}} + {{framework}}.

# After (installed)
# expense-tracker — Architecture

This is a personal finance tool built with Python + FastAPI.

Placeholder categories

Category	Examples	Inferred from
Identity	{{project-name}}, {{project-type}}	User's one-sentence description
Tech stack	{{language}}, {{framework}}, {{database}}	Inference from project type
Conventions	{{test-framework}}, {{package-manager}}	Inference from tech stack
Design	{{design-principles}}, {{architecture-pattern}}	Inference from project type
Dates	{{YYYY-MM-DD}}	Today's date
Hooks	{{SOURCE_DIR_PATTERN}}	User's answer to "where's your source code?"

English placeholder reference

Placeholder	Example filled value
{{project-name}}	expense-tracker
{{project-type}}	personal finance CLI tool
{{project-type-brief}}	CLI tool
{{language}}	Python 3.12
{{framework}}	FastAPI
{{database}}	SQLite
{{orm}}	SQLAlchemy
{{test-framework}}	pytest
{{package-manager}}	pip
{{design-principles}}	minimalist, practical, offline-first
{{architecture-pattern}}	MVC
{{core-features}}	expense recording, category tagging, monthly reports
{{user-scale}}	single user
{{SOURCE_DIR_PATTERN}}	^src/\|^tests/
{{YYYY-MM-DD}}	2026-07-14

Chinese placeholder reference

Placeholder	Example filled value
{{项目名称}}	记账工具
{{项目类型}}	个人财务管理 CLI 工具
{{编程语言}}	Python 3.12
{{框架}}	FastAPI
{{数据库}}	SQLite

---

Inference logic

The AI infers placeholders from the user's one-sentence description:

Input: "A personal expense tracker that records what I spend each day"

Inference:
  project-type: personal finance tool
  language: Python 3.12 (default for personal tools)
  framework: FastAPI (if web) or Click (if CLI)
  database: SQLite (single-user, no server needed)
  design-principles: minimalist, practical, offline-first
  user-scale: single user

When uncertain → pick the simpler option and record as ADR-001

---

Placeholder replacement rules

1. All placeholders must be replaced — no {{...}} should remain in installed files
2. Replace in order — identity first (used in other files), then tech stack, then conventions
3. Cross-file consistency — {{project-name}} must be the same everywhere
4. Verify after replacement — verify.sh checks for leftover placeholders (exit code 2)
5. When uncertain, pick simpler — and note the decision in decisions-log.md

---

Adding a new template

When ai-coding-ok needs a new feature that requires template changes:

1. Add the template file to templates/en/ and templates/zh/
2. Use existing placeholders where possible; add new ones only if needed
3. Update SKILL.md:
   • Add to the installed files list in the "What this skill installs" section
   • Add to the placeholder replacement file list in Step 6
4. Update install.sh / install.py: add to the copy list and conflict check
5. Update verify.sh: add to the required files check
6. Bump version markers in all template files

---

Template constraints

Constraint	Reason
Never modify templates during install	Templates are source code, not configuration
Always sync en/ and zh/	Bilingual parity (ADR-001)
Placeholders use {{kebab-case}} (en) or {{中文}} (zh)	Consistency in each language
Version markers on line 1	Upgrade system depends on them
No hardcoded project-specific values	Templates must be generic

---

Next steps

• File Structure — where templates fit in the overall structure
• Placeholder System — detailed placeholder reference
• Custom Templates — creating your own template variants