Initial commit

2025-11-29 18:00:44 +08:00
commit e89a943b71
19 changed files with 5272 additions and 0 deletions
--- a/skills/draft-github-issues/SKILL.md
+++ b/skills/draft-github-issues/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: draft-github-issues
+description: Drafts GitHub issues as YAML files from plans or requirements. Use when converting plans to issue format or structuring multiple related issues with parent-child relationships. Needs git repository with remote (for repo detection) and optional plan file or verbal requirements. Trigger with phrases like 'draft issues [from file-path]', 'create issue draft', 'draft github issues for [description]'.
+allowed-tools: "Read, Write, Edit, Task(analyst)"
+---
+
+Base directory for this skill: {baseDir}
+
+## Workflow
+
+**Draft Mode:** Generate YAML from plan/requirements → save to tmp/issues/
+**Refine Mode:** Analyze and improve existing YAML draft
+
+Publishing happens separately via `publish-github-issues` skill.
+
+<drafting>
+
+## Draft Issues from Requirements
+
+**Input:** Plan file path, text description, or verbal requirement
+
+**Process:**
+
+1. Parse requirement into logical issues (pattern: data → logic → UI)
+2. Determine issue set name from requirement (ask only if ambiguous)
+3. Detect repository from git remote (ask if not found: format owner/repo)
+4. Generate outcome-focused titles and acceptance criteria
+5. Evaluate each issue for technical context (see analyst usage below)
+6. Save YAML to `./tmp/issues/{name}-{timestamp}.yml`
+7. Report which issues were enriched with analyst context
+
+**Output:**
+
+```
+Draft saved: ./tmp/issues/user-search-20251102-143022.yml
+
+Enriched 3 of 4 issues with technical context.
+
+Next: Review file, then refine or publish using publish-github-issues skill.
+```
+
+</drafting>
+
+<analyst_usage>
+
+## When to Use Analyst Subagent
+
+**Invoke analyst for:**
+
+- Multiple systems/models (integration)
+- Performance/scale requirements (>100 records, <200ms, etc.)
+- Security keywords (auth, permissions, tenant, isolation)
+- Background jobs, async processing, queues
+- New functionality in unfamiliar domain
+
+**Skip analyst for:**
+
+- Standard CRUD (add field, basic form)
+- UI-only changes (text, styling, layout)
+- Copying existing pattern explicitly
+
+**Analyst request:** "Provide technical breadcrumbs: primary domain, similar patterns, integration points, gotchas (3-5 bullets)"
+
+**Technical Context Format in issue body:**
+
+```yaml
+### Technical Context
+- Primary domain: [models/controllers]
+- Similar pattern: [existing feature]
+- Integration points: [connections]
+- Consider: [gotcha/constraint]
+```
+
+</analyst_usage>
+
+<refinement>
+
+## Refine Draft (Optional)
+
+**Input:** Path to draft YAML file
+
+**Process:**
+
+1. Read and parse YAML
+2. Analyze each issue:
+   - Titles outcome-focused (WHAT not HOW)?
+   - Acceptance criteria specific and testable?
+   - Parent-child relationships logical?
+   - Labels appropriate?
+   - Technical context present where valuable?
+3. Apply improvements directly to file
+4. Report changes made
+
+**Output:**
+
+```
+Refined tmp/issues/user-search-20251102.yml
+
+Changes:
+- Issue #2: Changed title from "Implement SearchService" to "Enable search functionality"
+- Issue #3: Added specific acceptance criteria for error handling
+- Issue #4: Added technical context (was missing analyst breadcrumbs)
+
+File updated.
+```
+
+</refinement>
+
+<yaml_format>
+
+## YAML Structure
+
+See `{baseDir}/references/YAML-FORMAT.md` for complete specification.
+
+**Quick reference:**
+
+- `repository` (required): owner/repo
+- `defaults` (optional): labels, milestone
+- `issues` (required): array with ref, title, body
+- Per-issue optional: parent_ref, milestone, labels
+
+</yaml_format>
+
+## Examples
+
+### Draft from Plan File
+
+**User:** "Draft issues from docs/plans/paddle-integration.md"
+
+```
+Reading docs/plans/paddle-integration.md...
+Analyzing requirements...
+Invoking analyst for technical context (3 of 3 issues)...
+
+Draft saved: tmp/issues/paddle-integration-20251105.yml
+
+Enriched 3 of 3 issues with technical context.
+
+Next: Review file, then publish using publish-github-issues skill.
+```
+
+### Draft from Verbal Requirements
+
+**User:** "Draft issues for adding user authentication with OAuth providers"
+
+```
+Detecting repository: myorg/myapp
+Generating issues...
+Invoking analyst for security context...
+
+Draft saved: tmp/issues/user-auth-20251105.yml
+
+Enriched 2 of 3 issues with technical context.
+
+Next: Review file, then publish using publish-github-issues skill.
+```
+
+### Refine Draft
+
+**User:** "Refine tmp/issues/paddle-integration-20251105.yml"
+
+```
+Reading tmp/issues/paddle-integration-20251105.yml...
+Analyzing structure and content...
+
+Refined tmp/issues/paddle-integration-20251105.yml
+
+Changes:
+- Issue #2: Changed title to be more outcome-focused
+- Issue #2: Added specific acceptance criteria for webhook events
+- Issue #3: Added technical context about data migration risks
+
+File updated.
+
+Next: Review changes, then publish using publish-github-issues skill.
+```
--- a/skills/draft-github-issues/references/YAML-FORMAT.md
+++ b/skills/draft-github-issues/references/YAML-FORMAT.md
@@ -0,0 +1,211 @@
+# YAML Format Specification
+
+Complete reference for GitHub issue YAML files.
+
+## Top-Level Structure
+
+```yaml
+repository: owner/repo  # REQUIRED
+project: 6              # OPTIONAL - GitHub project number
+
+defaults:               # OPTIONAL - Default values for all issues
+  labels: [label1, label2]
+  milestone: "Milestone Name"
+
+issues:                 # REQUIRED - Array of issue definitions
+  - ref: issue1
+    title: "Issue Title"
+    body: "Issue body"
+  - ref: issue2
+    # ... more issues
+```
+
+## Required Fields
+
+### `repository`
+- Format: `owner/repo` (e.g., `myorg/myapp`)
+- The GitHub repository where issues will be created
+
+### `issues`
+- Array of issue objects
+- At least one issue required
+
+### Per-Issue Fields
+
+Each issue requires:
+
+**`ref`** (string)
+- Unique identifier for this issue within the YAML file
+- Used for parent-child linking via `parent_ref`
+- Not sent to GitHub (internal reference only)
+- Recommended: lowercase with hyphens (e.g., `parent-issue`, `login-feature`)
+
+**`title`** (string)
+- Issue title displayed on GitHub
+- Keep concise (< 80 characters recommended)
+- Should be outcome-focused (WHAT, not HOW)
+- Examples:
+  - ✅ "Enable search functionality"
+  - ❌ "Implement SearchService class"
+
+**`body`** (string, multiline)
+- Issue description in Markdown
+- Use `|` for multiline content
+- Supports GitHub Flavored Markdown
+
+## Optional Fields
+
+### Top-Level Optional
+
+**`project`** (integer)
+- GitHub project number (not project name)
+- All created issues added to this project
+
+**`defaults`** (object)
+- Default values applied to all issues
+- Can be overridden per-issue
+- Supported: `labels`, `milestone`
+
+### Per-Issue Optional
+
+**`parent_ref`** (string)
+- Reference to parent issue's `ref`
+- Creates parent-child relationship
+- Parent issue must be defined BEFORE child in YAML
+
+**`milestone`** (string)
+- Milestone name (exact match required)
+- Overrides default milestone if specified
+
+**`labels`** (array of strings)
+- Labels to apply
+- Overrides default labels if specified
+- Labels don't need to exist (GitHub auto-creates)
+
+## Issue Body Format
+
+Standard format for issue bodies:
+
+```markdown
+## Overview
+Brief description of what needs to be accomplished (the outcome).
+
+## Acceptance Criteria
+- [ ] Specific, testable criterion
+- [ ] Another testable criterion
+- [ ] Final criterion
+
+## Technical Context
+- Primary domain: [models/controllers involved]
+- Similar pattern: [existing feature to reference]
+- Integration points: [connections to other systems]
+- Consider: [gotchas, constraints, or performance notes]
+```
+
+**Notes:**
+- **Overview**: Outcome-focused (what users/system can do after)
+- **Acceptance Criteria**: Specific, testable, observable
+- **Technical Context**: Optional - add when issue involves integration, performance, security, or unfamiliar domains
+
+## Complete Example
+
+```yaml
+repository: myorg/myapp
+project: 6
+
+defaults:
+  labels: [enhancement]
+  milestone: "v2.0"
+
+issues:
+  # Parent issue
+  - ref: search-feature
+    title: "Enable search functionality"
+    milestone: "v2.1"  # Override default
+    labels: [enhancement, search]
+    body: |
+      ## Overview
+      Add full-text search to allow users to find posts and comments quickly.
+
+      ## Acceptance Criteria
+      - [ ] Search bar visible in header on all pages
+      - [ ] Results page displays matching posts and comments
+      - [ ] Results are paginated (20 per page)
+      - [ ] Search works across post titles, bodies, and comments
+
+      ## Technical Context
+      - Primary domain: Posts, Comments models; SearchController
+      - Similar pattern: Existing filter functionality in app/controllers/posts_controller.rb
+      - Consider: PostgreSQL full-text search vs external service (start simple)
+
+  # Child issue 1
+  - ref: search-indexing
+    parent_ref: search-feature
+    title: "Build search indexing"
+    body: |
+      ## Overview
+      Create database indices to support full-text search.
+
+      ## Acceptance Criteria
+      - [ ] Migration adds search columns to posts and comments
+      - [ ] Background job updates search indices on content changes
+      - [ ] Search query returns results in < 200ms for typical queries
+
+      ## Technical Context
+      - Primary domain: Posts, Comments models; db/migrate
+      - Similar pattern: Existing index patterns in schema.rb
+      - Consider: Use PostgreSQL tsvector type, GIN index
+
+  # Child issue 2
+  - ref: search-ui
+    parent_ref: search-feature
+    title: "Build search UI"
+    body: |
+      ## Overview
+      Create user interface for search functionality.
+
+      ## Acceptance Criteria
+      - [ ] Search bar component in header
+      - [ ] Results page shows post/comment matches with highlighting
+      - [ ] Pagination controls (prev/next, page numbers)
+      - [ ] Empty state when no results found
+
+      ## Technical Context
+      - Primary domain: SearchController, app/views/search
+      - Similar pattern: Pagination in app/views/posts/index.html.erb
+      - Integration points: Uses search indexing from #search-indexing
+```
+
+## Title Guidelines
+
+Titles should describe the outcome, not implementation:
+
+**Good (outcome-focused):**
+- "Enable search functionality"
+- "Users can filter posts by category"
+- "Support OAuth authentication"
+
+**Bad (implementation-focused):**
+- "Implement SearchService class"
+- "Add filter method to PostsController"
+- "Install Devise gem"
+
+## Technical Context Guidelines
+
+Add Technical Context section when issue involves:
+- **Integration**: Multiple systems/models working together
+- **Performance**: Scale requirements (>100 records, <200ms response)
+- **Security**: Auth, permissions, tenant isolation
+- **Background processing**: Jobs, queues, async work
+- **Unfamiliar domains**: New functionality in unknown territory
+
+Skip Technical Context for:
+- Standard CRUD (add field, basic form)
+- UI-only changes (text, styling, layout)
+- Copying existing pattern explicitly
+
+**Format (3-5 bullets):**
+- Primary domain: Where code lives
+- Similar pattern: Existing feature to reference
+- Integration points: Connections to other parts
+- Consider: Gotchas, constraints, performance notes
--- a/skills/draft-github-issues/scripts/create_issues.sh
+++ b/skills/draft-github-issues/scripts/create_issues.sh
@@ -0,0 +1,91 @@
+#!/bin/bash
+# Create GitHub issues from YAML file using gh CLI
+# Usage: ./create_issues.sh path/to/issues.yml
+
+set -e
+
+YAML_FILE="$1"
+
+if [ -z "$YAML_FILE" ]; then
+  echo "Error: YAML file path required"
+  echo "Usage: $0 path/to/issues.yml"
+  exit 1
+fi
+
+if [ ! -f "$YAML_FILE" ]; then
+  echo "Error: File not found: $YAML_FILE"
+  exit 1
+fi
+
+# Check gh CLI is installed and authenticated
+if ! command -v gh &> /dev/null; then
+  echo "Error: gh CLI not found. Install: https://cli.github.com"
+  exit 1
+fi
+
+if ! gh auth status &> /dev/null; then
+  echo "Error: gh not authenticated. Run: gh auth login"
+  exit 1
+fi
+
+# Get repo from git remote (fallback to current directory check)
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "")
+if [ -z "$REPO" ]; then
+  echo "Error: Not in a GitHub repository or remote not configured"
+  exit 1
+fi
+
+echo "Creating issues in $REPO from $YAML_FILE"
+echo ""
+
+# This script expects Claude to parse the YAML and call gh commands
+# for each issue. The script serves as a wrapper and validator.
+#
+# Claude will:
+# 1. Parse YAML to extract issues
+# 2. Create parent issues first (store their numbers)
+# 3. Create child issues, updating body to reference parent number
+# 4. Handle labels, milestones, assignees
+#
+# This script just validates environment and provides helper functions
+
+# Helper: Create single issue
+# Args: title body [labels] [milestone] [assignees]
+create_issue() {
+  local title="$1"
+  local body="$2"
+  local labels="$3"
+  local milestone="$4"
+  local assignees="$5"
+
+  local cmd="gh issue create --repo $REPO --title \"$title\" --body \"$body\""
+
+  if [ -n "$labels" ]; then
+    cmd="$cmd --label \"$labels\""
+  fi
+
+  if [ -n "$milestone" ]; then
+    cmd="$cmd --milestone \"$milestone\""
+  fi
+
+  if [ -n "$assignees" ]; then
+    cmd="$cmd --assignee \"$assignees\""
+  fi
+
+  eval "$cmd"
+}
+
+# Export function for Claude to use
+export -f create_issue
+export REPO
+
+echo "Environment validated. Ready to create issues."
+echo "Repository: $REPO"
+echo ""
+
+# Note: This script is invoked by Claude with specific gh commands
+# based on parsed YAML structure. Claude handles:
+# - YAML parsing
+# - Issue ordering (parents before children)
+# - Reference resolution (ref -> issue numbers)
+# - Error handling and reporting