Contributor PR Workflow

Contributor PR Workflow

Guide a contributor through the end-to-end process of submitting a change to this KB.

Overview

This skill covers the full lifecycle from first clone to PR submission, with automated validation gates at each step. It prevents common mistakes: wrong directory structure, mismatched frontmatter, dirty files, broken links, and Simplified Chinese content.

How It Works

Phase 0: Environment Setup

1. Clone the repo (if first time):

   git clone https://github.com/h30190/HJPLUS_Taiwan_Architect_KB.git
   cd HJPLUS_Taiwan_Architect_KB

2. Sync with latest main:

   git checkout main
   git pull origin main

3. Create a feature branch:

   git checkout -b feat/your-feature-description

4. Ask the contributor: "What are you contributing?"

   • New skill → Phase 1
   • Edit existing skill → Phase 2
   • Rename / restructure → Phase 3
   • Other (fix typo, add reference, translate) → Phase 4

Phase 1: Creating a New Skill

1. Choose the category: Look at raw/ subdirectories to find the right home (建築設計與規劃, 建築法規, 公共工程, etc.).

2. Copy the template:

   cp -r 知識樣板/ raw/<category>/<chinese-entry-name>/

3. Name the entry directory (Traditional Chinese, intuitive name like 排煙窗法規檢討/).

4. Rename the skill directory (inside the Chinese entry, from skill-name-hyphenated/ to lowercase English hyphenated).

5. Clean up optional subdirectories: Delete assets/, references/, scripts/ if not needed.

6. Write SKILL.md:

   • Frontmatter: name MUST match the skill directory name
   • metadata.class is REQUIRED (A/B/C)
   • metadata.status is RECOMMENDED (verified/unverified/draft)
   • license and compatibility are RECOMMENDED
   • Body in English, keep under 500 lines
   • C-class skills MUST include MCP tool examples

7. Write domain.md:

   • Traditional Chinese body
   • OKF frontmatter with type: Knowledge Entry and title matching the # H1 — nothing else
   • 使用情境、學習目標、實務應用

8. Update parent index.md:

   • Open the parent directory's index.md
   • Add a new * [Skill Name](path/SKILL.md) - description entry under ## Skills
   • If no index.md exists and the directory has 2+ children, create one per OKF v0.2

Phase 2: Editing an Existing Skill

1. Never delete SKILL.md or domain.md without a replacement.

2. Sync SKILL.md and domain.md: If you change one, update the other.

3. Preserve frontmatter: name must stay in sync with directory name.

4. If file is lowercase skill.md, rename to SKILL.md:

   git mv <path>/skill.md <path>/SKILL.md

5. B-class skills: Keep <!-- TODO: Taiwan adaptation needed --> markers until adaptation is complete.

6. When adding or removing a skill, update the parent directory's index.md accordingly.

Phase 3: Renaming / Restructuring

1. Use git mv, not OS-level rename:

   git mv <old-path> <new-path>

2. Scan the entire repo for stale references:

   # Search for old directory name in all markdown files
   grep -r "<old-name>" raw/ --include="*.md"

   Every reference must be updated.

3. Update all index.md entries that point to the old path.

4. Update frontmatter name if the skill directory name changed.

Phase 4: Other Changes (Typo, Reference, Translation)

1. Make the change directly on your branch.
2. If touching a skill AND its domain, keep both in sync.
3. No special structure requirements.

Phase 5: Self-Validation (RUN BEFORE SUBMITTING)

Run ALL checks below. If any fails, fix it before proceeding.

Structure Checks

• SKILL.md is uppercase (❌ skill.md is wrong)
• Three-layer structure correct: category/chinese-entry/english-skill-name/SKILL.md category/chinese-entry/domain.md
• domain.md frontmatter has type: Knowledge Entry + title ONLY (no skill fields)
• No .history/, .vscode/, node_modules/, __pycache__/ files in the diff
• Skill directory name is lowercase English hyphenated (❌ pinyin like pai-yan-chuang)
• Skill directory name matches name in SKILL.md frontmatter