Agent Skills
› kinncj/Heimdall
› story-issue-sync
story-issue-sync
GitHub维护故事Markdown文件与GitHub Issue的双向一致性。同步标题、正文、标签、状态及DoD检查项，支持新建Issue并回填编号，确保文件叙事与Issue元数据准确对应。
Trigger Scenarios
需要创建新的GitHub Issue以关联故事文件时
故事文件的Gherkin或验收标准发生更改需同步至Issue时
Install
npx skills add kinncj/Heimdall --skill story-issue-sync -g -y
SKILL.md
Frontmatter
{
"name": "story-issue-sync",
"description": "Maintain bidirectional consistency between story markdown files and GitHub Issues. Use when syncing story status with GitHub."
}
SKILL: story-issue-sync
Purpose
Maintain bidirectional consistency between story files (docs/stories/*.md) and GitHub Issues. The file is authoritative for narrative and Gherkin. The issue is authoritative for labels, status, project board position, and DoD checklist state.
Ownership Model
| Attribute | Authoritative source | Sync direction |
|---|---|---|
| Title | Story file (frontmatter title) |
File → Issue |
| Body / Gherkin | Story file | File → Issue (on update) |
issue_number |
Issue (assigned at create) | Issue → File |
issue_url |
Issue | Issue → File |
| Labels | Issue | Issue → File (labels frontmatter) |
| Status / Phase | Issue labels | Issue → File (labels frontmatter) |
| DoD checklist | Issue body (task list) | Issue → File (on review) |
| Project board position | Project v2 | Not persisted to file |
Inputs / Outputs
| Field | Source | Notes |
|---|---|---|
story_file |
docs/stories/*.md |
Path to the story markdown file |
issue_number |
Issue (post-create) | Written back to story frontmatter |
issue_node_id |
gh issue create --json id |
Passed to gh-projects skill for board add |
issue_url |
Issue (post-create) | Written back to story frontmatter |
Create: File → Issue
When a new story file exists with issue_number: null:
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
# Extract frontmatter fields
TITLE=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.search(r'^title:\s*[\"\'](.*?)[\"\']', text, re.MULTILINE)
print(m.group(1) if m else '')
")
LABELS=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.findall(r'^\s+- [\"\'](.*?)[\"\']\s*$', text, re.MULTILINE)
print(','.join(m))
")
MILESTONE=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.search(r'^milestone:\s*[\"\'](.*?)[\"\']', text, re.MULTILINE)
print(m.group(1) if m else '')
")
# Create the issue
RESULT=$(gh issue create \
--title "$TITLE" \
--body-file "$STORY_FILE" \
--label "$LABELS" \
--milestone "$MILESTONE" \
--json number,url,id)
ISSUE_NUMBER=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['number'])")
ISSUE_URL=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
# Write back to story frontmatter
python3 - <<EOF
import re
text = open('$STORY_FILE').read()
text = re.sub(r'^issue_number: null', f'issue_number: $ISSUE_NUMBER', text, flags=re.MULTILINE)
text = re.sub(r'^issue_url: null', f'issue_url: "$ISSUE_URL"', text, flags=re.MULTILINE)
open('$STORY_FILE', 'w').write(text)
EOF
echo "[story-sync] CREATED #$ISSUE_NUMBER ← $STORY_FILE"
Update: File → Issue (body changed)
When story Gherkin or acceptance criteria are edited:
ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
gh issue edit "$ISSUE_NUMBER" \
--body-file "$STORY_FILE"
echo "[story-sync] BODY_UPDATE #$ISSUE_NUMBER ← $STORY_FILE"
Sync: Issue → File (labels changed)
When labels on the issue change (e.g., after PO updates priority or phase advances):
ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
# Fetch current labels from issue
CURRENT_LABELS=$(gh issue view "$ISSUE_NUMBER" \
--json labels \
--jq '[.labels[].name] | join(",")')
# Rewrite labels block in frontmatter
python3 - <<EOF
import re
text = open('$STORY_FILE').read()
label_lines = '\n'.join(f' - "{l}"' for l in "$CURRENT_LABELS".split(',') if l)
text = re.sub(
r'^labels:\n( - .*\n)+',
f'labels:\n{label_lines}\n',
text,
flags=re.MULTILINE
)
open('$STORY_FILE', 'w').write(text)
EOF
echo "[story-sync] LABELS_SYNC #$ISSUE_NUMBER → $STORY_FILE"
Detect Drift (file vs issue)
Run before any update to check whether file and issue are in sync:
ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
FILE_TITLE=$(python3 -c "
import re
m = re.search(r'^title:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else '')
")
ISSUE_TITLE=$(gh issue view "$ISSUE_NUMBER" --json title --jq '.title')
if [ "$FILE_TITLE" != "$ISSUE_TITLE" ]; then
echo "[story-sync] DRIFT title mismatch: file='$FILE_TITLE' issue='$ISSUE_TITLE'"
# File is authoritative for title — update the issue
gh issue edit "$ISSUE_NUMBER" --title "$FILE_TITLE"
fi
Batch Sync (all stories)
find docs/stories -name "*.md" ! -name "_template.md" | while read -r f; do
NUMBER=$(python3 -c "
import re
m = re.search(r'^issue_number:\s*(\d+)', open('$f').read(), re.MULTILINE)
print(m.group(1) if m else '')
")
if [ -z "$NUMBER" ]; then
echo "[story-sync] NEEDS_CREATE $f"
else
echo "[story-sync] HAS_ISSUE $f → #$NUMBER"
fi
done
Failure Modes
| Condition | Action |
|---|---|
Story has issue_number: null |
Create the issue. Never skip. |
| Issue number in file but issue is closed | Log warning. Do not reopen automatically — escalate to human. |
| Title drift detected | File wins. Update issue title. |
| Labels on issue unknown to label set | Log: [story-sync] UNKNOWN_LABEL {name}. Do not remove. |
| Story file missing after issue exists | Log warning. Issue is not deleted. Human decides. |
Logging
[story-sync] CREATED #42 ← docs/stories/user-auth-reset-0001.md
[story-sync] BODY_UPDATE #42 ← docs/stories/user-auth-reset-0001.md
[story-sync] LABELS_SYNC #42 → docs/stories/user-auth-reset-0001.md
[story-sync] DRIFT #42 title mismatch — issue updated
[story-sync] SKIP #42 no changes detected
Version History
- f4ea31f Current 2026-07-05 10:44
