skills.rest
kinncj
kinncjCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

story-issue-sync

Synchronize story markdown files with GitHub Issues bidirectionally.

23|7|Updated Feb 14, 2026
Search Tags:#automation#frontmatter#labels#github-issues#story-sync#dod-checklist
One-click install
npx skills add https://github.com/kinncj/MAPLE --skill story-issue-sync
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: story-issue-sync
Source: https://github.com/kinncj/MAPLE/tree/main/template/.opencode/skills/story-issue-sync
Command: npx skills add https://github.com/kinncj/MAPLE --skill story-issue-sync

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Bidirectional drift between story markdown files and GitHub Issues commonly leads to misalignment in narrative, status, and DoD. This skill ensures the story frontmatter, Gherkin content, and issue state stay aligned with the authoritative issue source.

Core Features & Use Cases

  • Synchronizes story frontmatter (title, labels, status) with the corresponding GitHub Issue to maintain a single source of truth.
  • Propagates updates in the story body and acceptance criteria to the Issue, and writes back issue numbers and URLs to the story frontmatter.
  • Enables drift detection and automated recovery, supporting end-to-end lifecycle management between docs/stories and GitHub Issues.

Quick Start

Create a new story in docs/stories and run the skill to establish the initial linkage to a GitHub Issue.

Frequently Asked Questions about story-issue-sync

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep story markdown files and GitHub Issues in sync?▼

Story docs and GitHub Issues drift when updates happen in one place but not the other, leading to misaligned narrative, status, and acceptance criteria. Bidirectional synchronization automatically propagates changes between story frontmatter and issues to maintain consistency.

How does frontmatter synchronization work for story-driven development?▼

Frontmatter synchronization writes issue numbers and URLs back to story markdown files while applying authoritative status and labels from GitHub Issues. This deterministic update ensures traceable metadata across both artifacts.

Can I sync Gherkin acceptance criteria from story docs to GitHub Issues?▼

Yes, Gherkin acceptance criteria and story body updates are propagated to the corresponding GitHub Issue. This ensures the DoD checklist and narrative stay aligned across both artifacts during story-driven development.

Does story issue sync support automated drift detection and recovery?▼

Yes, automated drift detection and recovery are supported. The skill automatically updates either side as changes occur, ensuring consistent narrative, status, and DoD across story markdown files and GitHub Issues.

How do I establish initial linkage between a new story and a GitHub Issue?▼

Create a new story markdown file in docs/stories and run the synchronization skill. It establishes initial linkage by connecting the story frontmatter to the corresponding GitHub Issue and writing the issue URL back to the file.

Related Skills

Explore More Software Engineering Skills→
dariopalminiodariopalminio
1

story-split

Split large user stories into smaller independent stories using eight splitting patterns.

Community
Advanced
qmuqmu
1

write-release-note

Generate structured release notes from branch story frontmatter to Markdown.

Official
Basic
heymishyheymishy

release

Generate release notes, change requests, deployment checklists, and rollback triggers from DoD-complete stories.

Community
Advanced
HankanmanHankanman
2

github-project-automation

Automate GitHub Projects v2 board creation and issue synchronization from codebase analysis.

Community
Advanced