Contributing

Contributing

How to contribute to ai-coding-ok. Issues, PRs, template changes, and development workflow.

---

Quick start for contributors

ai-coding-ok is a Markdown + Shell + Python project. No web framework, no database, no frontend. The main areas you might contribute to:

Area	What to edit	Skill needed
Templates	templates/en/ and templates/zh/	Markdown, writing
Skill behavior	skills/ai-coding-ok/SKILL.md	Understanding of AI agent behavior
Install scripts	install.sh, install.py	Bash / Python 3
Documentation	docs/, README.md, wiki	Technical writing
Verification	scripts/verify.sh	Bash

---

Project architecture

ai-coding-ok/
├── templates/en/ + zh/          ← PRODUCT: what gets installed
├── skills/ai-coding-ok/SKILL.md ← BRAIN: skill logic (Mode A/B/C/D)
├── scripts/                     ← TOOLS: install, verify, prompts
├── docs/                        ← DOCS: user guides
└── .github/agent/memory/        ← SELF: dogfooding memory

---

How to contribute

1. Find or create an issue

Check existing issues or open a new one. Describe:

• What you want to change
• Why it should change
• Which files are affected

2. Fork and clone

git clone https://github.com/YOUR_USERNAME/ai-coding-ok.git
cd ai-coding-ok

3. Make your changes

Template changes:

• Edit files in templates/en/ AND templates/zh/ (both must be synced)
• Add new placeholders only if necessary
• Bump version markers if adding new content

Skill behavior changes:

• Edit skills/ai-coding-ok/SKILL.md
• Copy to root: cp skills/ai-coding-ok/SKILL.md SKILL.md

Script changes:

• install.sh: Bash only, no external dependencies
• install.py: Python 3.8+ stdlib only
• verify.sh: Bash only

Documentation changes:

• Edit docs/ files
• Update README.md if the change is user-facing

4. Test

# Test install
mkdir /tmp/test-install && cd /tmp/test-install
bash /path/to/ai-coding-ok/install.sh --copilot

# Test verification
bash /path/to/ai-coding-ok/scripts/verify.sh

# Test Python install (Windows)
python /path/to/ai-coding-ok/install.py --copilot

5. Submit a PR

• Branch: feature/your-change or fix/your-fix
• PR description: what + why + testing done
• Link the related issue

---

Template change guidelines

Must sync en/ and zh/

Every template change must be mirrored in both language directories. This is non-negotiable (ADR-001).

Checklist:

• templates/en/ files updated
• templates/zh/ files updated
• Placeholders consistent between languages
• Version markers bumped

Placeholder rules

• English: {{kebab-case}}
• Chinese: {{中文}}
• Reuse existing placeholders where possible
• Document new placeholders in SKILL.md Step 6

Version marker format

Every template file must start with:

<!-- ai-coding-ok: vX.Y.Z -->

Bump the version when adding new content to templates.

---

SKILL.md change guidelines

What SKILL.md controls

• Mode A/B/C/D trigger conditions
• Install Playbook (8 steps)
• Upgrade Playbook (8 steps)
• Compatibility with superpowers
• Language detection logic

Change checklist

• Does the change affect trigger conditions? Test with various user inputs
• Does the change affect install flow? Test with a fresh install
• Does the change affect upgrade? Test with an upgrade from the previous version
• Is the change backward-compatible? Existing installations should keep working
• After editing skills/ai-coding-ok/SKILL.md, copy to root SKILL.md

---

Script guidelines

Bash (install.sh, verify.sh)

• Use POSIX-compatible syntax (works in bash, zsh, Git Bash)
• No external dependencies (no jq, yq, etc.)
• set -e at the top
• Use cp -n for no-clobber (safe default)
• Always check for existing files before overwriting

Python (install.py)

• Python 3.8+ standard library only
• No pip packages, no conda
• Use pathlib.Path for cross-platform paths
• Handle Windows and POSIX paths
• --dry-run flag for preview
• --force flag for overwrite

---

Documentation guidelines

Wiki pages

Wiki pages are in the GitHub wiki (separate repo). To contribute:

1. Clone the wiki: git clone https://github.com/Mark7766/ai-coding-ok.wiki.git
2. Edit pages or add new ones
3. Submit changes via the wiki's git (or ask a maintainer for access)

docs/ directory

These are in-repo docs. Edit directly and submit a PR.

---

Code style

Markdown

• Use # headings (not underlines)
• Use fenced code blocks with language tags
• Use tables for structured data
• Use emoji for visual cues (🧠 📝 📜 🔄 etc.)
• Keep lines under 120 characters where practical

Shell

#!/usr/bin/env bash
set -euo pipefail

# Function names: lowercase with underscores
function do_something() {
  local variable="value"
  echo "${variable}"
}

# Variables: UPPER_CASE for constants, lower_case for locals
readonly AI_CODING_OK_VERSION="3.1.0"

Python

#!/usr/bin/env python3
"""Module docstring."""

import sys
from pathlib import Path
from typing import Optional


def install_copilot(target: Path, force: bool = False) -> None:
    """Install ai-coding-ok for Copilot."""
    ...

---

Version bumping

When your change affects the framework:

Change type	Version bump
New template file, new placeholder, new mode	MINOR (e.g., v3.1.0 → v3.2.0)
Template content fix, wording improvement	PATCH (e.g., v3.1.0 → v3.1.1)
Structural change (file reorg, new language)	MAJOR (e.g., v3.1.0 → v4.0.0)

Bump version markers in ALL template files.

---

Review process

PRs are reviewed for:

1. Correctness — Does the change work as described?
2. Bilingual parity — Are en/ and zh/ templates synced?
3. Backward compatibility — Will existing installations break?
4. Documentation — Are SKILL.md, README, and wiki updated?
5. Testing — Has the change been tested?

---

Getting help

• GitHub Issues — ask questions, report bugs
• Discussions — propose ideas, get feedback
• FAQ — common questions about using ai-coding-ok