github-sync

What This Skill Does

The github-sync skill serves as the primary guidance and configuration interface for integrating your SpecWeave specifications with GitHub Projects. It facilitates a robust, two-way synchronization mechanism where your permanent living documentation—stored as Specs—is kept in perfect alignment with your project management workflows on GitHub. By utilizing this skill, you ensure that your team remains aligned, with user stories automatically translating into actionable GitHub issues and project progress updates.

Installation

To integrate this capability, use the OpenClaw command: clawhub install openclaw/skills/skills/anton-abyzov/sw-github-sync. Once installed, the agent will recognize relevant queries regarding your sync configuration and provide guidance on maintaining your project health without needing to manually map every task.

Use Cases

• Project Onboarding: Configure new repositories for sync to ensure all future SpecWeave work is tracked in GitHub automatically.
• Troubleshooting: Resolve synchronization conflicts or connectivity issues when GitHub projects fail to reflect the latest spec changes.
• Credential Management: Receive step-by-step assistance in setting up fine-grained personal access tokens required for API interaction.
• Workflow Optimization: Learn how to structure specs effectively to ensure they generate clean, manageable GitHub projects and issue boards.

Example Prompts

1. "How do I link my current SpecWeave specs to a new GitHub organization project board?"
2. "I'm seeing an authentication error when trying to sync my documentation to GitHub; how can I troubleshoot this?"
3. "Can you explain the difference between syncing specs versus increments, and why I should stick to the current architecture?"

Tips & Limitations

• Always sync Specs: Remember that GitHub sync is designed for permanent features. Do not attempt to sync temporary increment files as they do not provide long-term tracking value.
• Use Commands: Remember that for the actual execution of data transfer, utilize the /sw-github:sync-spec command rather than asking the agent to perform the sync process via general conversation.
• Metadata Integrity: Ensure your spec frontmatter is well-formatted to allow the agent to successfully read and write externalLinks metadata back into your documents.