github-task-sync

What this skill does

# GitHub Task Sync Skill

Seamlessly manage task documentation by syncing between local task directories and GitHub issues. All task documentation (SPEC, PLAN, TEST_PLAN, COMMIT_MESSAGE) lives both locally and on GitHub, with easy push/pull synchronization.

## Overview

This skill provides a complete workflow for managing tasks:

1. **Create** a new GitHub issue with `create-issue.sh`
2. **Push** local task files to GitHub with `push.sh` or `push-file.sh`
3. **Pull** task files from GitHub with `pull.sh` or `pull-file.sh`
4. **Read** task files from GitHub to stdout with `read-issue-file.sh`
5. **Log** work progress with `log-entry.sh` (creates AI Work Log comment with timestamped entries)

## Quick Start

```bash
# Create a new GitHub issue and task directory
./create-issue.sh "Add dark mode toggle" "Implement dark/light theme switcher"

# Work on files locally (SPEC.md, PLAN.md, etc.)

# Push all files to GitHub
./push.sh 188 ./tasks/188-add-dark-mode-toggle

# Or pull the latest from GitHub (automatically creates task directory from issue title)
./pull.sh 188
```

## Scripts

There are 7 scripts in this skill:

1. **create-issue.sh** - Create GitHub issue and initialize task directory
2. **push.sh** - Push all task files to GitHub
3. **push-file.sh** - Push single task file with status summary
4. **pull.sh** - Pull all task files from GitHub
5. **pull-file.sh** - Pull single task file from GitHub
6. **read-issue-file.sh** - Read task file from GitHub to stdout
7. **log-entry.sh** - Add timestamped entry to AI Work Log

### create-issue.sh

Create a new GitHub issue and initialize a task directory. Can also convert existing task directories to GitHub issues. Automatically applies GitHub labels based on issue context.

**Usage:**
```bash
./create-issue.sh <title> [description] [existing-task-dir] [labels]
```

**Arguments:**
- `title` - GitHub issue title
- `description` - Issue description (optional)
- `existing-task-dir` - Path to existing task directory to convert (optional)
- `labels` - Comma-separated labels to apply (optional, e.g., "UI,bug" or "CLI,feature")

**Available labels:**
- `UI` - User interface related issues
- `CLI` - Command-line interface related issues
- `bug` - Bug fixes and issue resolutions
- `feature` - New features and enhancements

**Examples:**
```bash
# Create new issue with title only
./create-issue.sh "Add dark mode toggle"

# Create new issue with title, description, and labels
./create-issue.sh "Add dark mode toggle" "Implement dark/light theme switcher in settings" "" "UI,feature"

# Convert existing task directory to GitHub issue with labels
./create-issue.sh "Fix login button styling" "" ./tasks/login-styling "UI,bug"

# Create issue with description and labels (no existing task dir)
./create-issue.sh "Add date filter to extract" "Filter commits by date range" "" "CLI,feature"
```

**What it does:**
1. Analyzes issue content to determine appropriate labels (optional)
2. Creates a new GitHub issue with the provided title, description, and labels
3. Creates local task directory named `{issue-number}-{title-slug}/`
4. If task files exist, automatically syncs them to GitHub
5. Outputs issue URL and task directory path

**Output:**
```
Creating GitHub issue...
Applying labels: UI,feature
✓ GitHub issue created: https://github.com/<github-user>/<repo-name>/issues/189
✓ Created task directory: tasks/189-add-dark-mode-toggle

✅ Task setup complete!
Issue: https://github.com/<github-user>/<repo-name>/issues/189
Task Directory: tasks/189-add-dark-mode-toggle
Task Number: 189
```

### push.sh

Push all task documentation files (SPEC.md, PLAN.md, TEST_PLAN.md, COMMIT_MESSAGE.md) to a GitHub issue as collapsible comments.

**Usage:**
```bash
./push.sh <issue-url-or-number> [task-directory]
```

**Arguments:**
- `issue-url-or-number` - Full GitHub URL or just the issue number
- `task-directory` - Directory containing task files (optional, defaults to current directory)

**Examples:**
```bash
# Using issue number
./push.sh 188 ./tasks/188-account-deletion

# Using full URL
./push.sh https://github.com/<github-user>/<repo-name>/issues/188 ./tasks/188-account-deletion

# Using current directory
./push.sh 188
```

**What it does:**
- Uploads all four task file types as separate collapsible comments
- Each file type gets a unique marker so it can be updated independently
- Creates new comments or updates existing ones
- Each file wrapped in `<details>` section that starts collapsed

**Output:**
```
📤 Syncing task files to GitHub issue #188 in <github-user>/<repo-name>

Processing SPEC.md...
  + Creating new comment...
  ✓ Created

Processing PLAN.md...
  ↻ Updating existing comment (ID: 123456789)...
  ✓ Updated

...
✅ Sync complete!
View the issue: https://github.com/<github-user>/<repo-name>/issues/188
```

### push-file.sh

Update a single task file comment on a GitHub issue with a status summary and file content.

**Usage:**
```bash
./push-file.sh <issue-url-or-number> <file-type> <status-file> <content-file>
```

**Arguments:**
- `issue-url-or-number` - GitHub issue URL or issue number
- `file-type` - One of: `SPEC`, `PLAN`, `TEST_PLAN`, `COMMIT_MESSAGE`
- `status-file` - File containing status summary (2 paragraphs + optional bullets)
- `content-file` - File containing the full file content

**Examples:**
```bash
# Update SPEC with status and content
./push-file.sh 188 SPEC SPEC-STATUS.md SPEC.md

# Update PLAN after review
./push-file.sh 188 PLAN plan-status.txt PLAN.md
```

**Status File Format:**
The status file should contain a 2-paragraph summary describing the document state:

```markdown
**Status:** [Draft | Complete | Review Needed | etc.]

This is the first paragraph explaining the current state of the document.
It should describe what has been completed, what's pending, or any key status information.

This is the second paragraph providing additional context or details about the document state.

- Key point 1 (optional)
- Key point 2 (optional)
```

**What it does:**
- Creates or updates a single comment for the specified file type
- Combines the status summary with the file content in a collapsible section
- Each file type has a unique marker for independent updates

**Output:**
```
↻ Updating SPEC comment on issue #188 (ID: 123456789)...
✓ Updated successfully

View the issue: https://github.com/<github-user>/<repo-name>/issues/188
```

### pull.sh

Pull all task documentation files from a GitHub issue to a local task directory. **Automatically determines the task directory name** from the issue title.

**Usage:**
```bash
./pull.sh <issue-url-or-number>
```

**Arguments:**
- `issue-url-or-number` - GitHub issue URL or issue number

**Examples:**
```bash
# Pull using issue number
./pull.sh 188

# Pull using full URL
./pull.sh https://github.com/<github-user>/<repo-name>/issues/188
```

**What it does:**
1. Fetches the issue title from GitHub
2. Converts the title to a URL-safe slug
3. Creates task directory as `tasks/{issue-number}-{title-slug}/`
4. Fetches all four task files from GitHub issue comments
5. Extracts content from collapsible sections
6. Writes each to local file (SPEC.md, PLAN.md, etc.)

**Output:**
```
📥 Fetching issue #188 from <github-user>/<repo-name>...
📥 Pulling task files from GitHub issue #188: "Account deletion and data export"
📁 Task directory: tasks/188-account-deletion-and-data-export

Pulling SPEC.md...
  ✓ Pulled to SPEC.md

Pulling PLAN.md...
  ✓ Pulled to PLAN.md

...
✅ Pull complete!
Task directory: tasks/188-account-deletion-and-data-export
```

### pull-file.sh

Pull a single task file from a GitHub issue to a local file.

**Usage:**
```bash
./pull-file.sh <issue-url-or-number> <file-type> [output-file]
```

**Arguments:**
- `issue-url-or-number` - GitHub issue URL or issue number
- `file-type` - One of: `SPEC`, `PLAN`, `TEST_PLAN`, `COMMIT_MESSAGE`
- `output-file` - File to write to (default: `{file-type}.md` in current directory)

**Examples:**
```bash
# Pull SPEC to SPEC.