| name | github-workflow |
| description | Strict rules for synchronizing tasks with GitHub Issues and managing Pull Requests. Activate this skill whenever planning features, opening PRs, or closing tasks. |
GitHub Issue Sync & PR Workflow Rules
When planning or implementing new features, you must use the automated JSON-driven issue sync tool located at scripts/gh-issue-sync.cjs to synchronize your task checklist with the GitHub issue tracker.
1. Tool Setup & Location
- Script:
scripts/gh-issue-sync.cjs (executable Node.js script)
- Sample Config:
scripts/issues.sample.json
2. Issue Tracking Workflow
Active Constraint: Before writing ANY code for any feature or logic change, you MUST explicitly execute the following steps to track the task:
- Plan & Draft: Create a temporary JSON file (e.g.,
scripts/feature-xyz-plan.json) containing the Epic description and target sub-issues. Follow the schema defined in scripts/issues.sample.json.
- Dry Run: Preview the CLI commands that will run:
node scripts/gh-issue-sync.cjs scripts/feature-xyz-plan.json --dry-run
- Apply & Link: Generate the Epic and sub-issues on GitHub:
node scripts/gh-issue-sync.cjs scripts/feature-xyz-plan.json
Note: The script automatically links all sub-issues to the parent Epic.
Tech Debt Tracking (Immediate Logging)
Active Constraint: The moment you identify any of the 10 catalogued tech debt categories during your work, you MUST pause your current workflow and immediately execute gh issue create --title "Tech Debt: [Topic]" --body "[Details]" --label "tech debt" before taking any other action.
The 10 categories are:
- Code smells
- Duplication
- Over-complexity
- Fragile coupling
- Missing safety guards
- Missing tests
- Security hygiene
- Deprecated patterns
- Config drift
- Documentation debt
3. Resolving and Closing Tasks
4. Pull Request Requirements
Active Constraint: Before creating a Pull Request (gh pr create), you MUST ensure the following criteria are met:
- Existing Issue Verification: A GitHub issue MUST exist for the work being PR'd.
- Issue Linking: The PR description or commit message MUST contain
Closes #<issue-number> or Resolves #<issue-number> for all associated issues. A single PR may close multiple issues (e.g., closing the final sub-issue and the parent Epic simultaneously).
- Issue Content Constraints: The GitHub issue(s) being resolved MUST contain:
- A clear description of the problem or feature.
- An analysis section detailing how to resolve or implement the fix/change.
- A documented implementation plan.
If the issue lacks these elements, you MUST update the issue (
gh issue edit) with this information BEFORE opening the PR.
5. Pre-Commit / Pre-PR Checks
Active Constraint: Before pushing commits and opening a PR, you MUST actively execute the following verification steps:
- Branch Sync: You MUST execute
git fetch origin && git merge origin/master to ensure your feature branch is strictly up-to-date with master. If there are any merge conflicts, you MUST resolve them and re-build any affected components (e.g. ui-dist) before proceeding.
- Go Formatting: Execute
gofmt -w . to format all modified Go files.
- UI Builds: If you modify any React UI source files (under
ui/), you MUST execute the UI build to sync pkg/server/ui-dist. Execute exactly:
cd ui && CI=true pnpm install && pnpm run build && cd .. && rm -rf pkg/server/ui-dist && cp -r ui/dist pkg/server/ui-dist
6. CI Failure Remediation
Active Constraint: If a Pull Request fails its CI checks (e.g., a GitHub Action fails), you MUST NOT leave the failed jobs in the repository history. After addressing the underlying issue and pushing the fix to get the build passing again, you MUST actively clean up and delete the failed job runs using the GitHub CLI (e.g., gh run delete <run-id>). This ensures the repository maintains a clean history of only successful ("green") jobs and prevents failed runs from triggering false-positive corrective actions.
Last Updated: 2026-07-21 | Last Reviewed: 2026-07-21
