@activade/open-workflows 1.0.1 → 2.0.0

package/README.md

@@ -1,94 +1,121 @@
 # open-workflows
 
-AI-powered GitHub automation workflows as an OpenCode plugin. Uses **Skills** for customizable PR reviews, issue labeling, documentation sync, and release automation.
-
-Powered by [OpenCode](https://opencode.ai).
+GitHub automation workflows via composite actions. AI-powered reviews, labeling, and doc sync - plus automated releases with npm provenance.
 
 ## Quick Start
 
 ```bash
-bunx open-workflows
+bunx @activade/open-workflows
 ```
 
-The CLI will:
-1. Prompt you to select workflows
-2. Install skills to `.opencode/skill/`
-3. Install GitHub Actions workflows to `.github/workflows/`
-4. Create/update `.opencode/opencode.json`
-
-## What's Installed
-
-### Skills (`.opencode/skill/`)
-
-| Skill | Description |
-|-------|-------------|
-| `pr-review` | AI-powered code review with structured findings |
-| `issue-label` | Auto-label issues based on content |
-| `doc-sync` | Keep docs in sync with code changes |
-| `release-notes` | Semantic versioning and release automation |
-
-### Workflows (`.github/workflows/`)
-
-| Workflow | Trigger | Description |
-|----------|---------|-------------|
-| `pr-review.yml` | Pull request | Reviews PRs using `pr-review` skill |
-| `issue-label.yml` | Issue opened/edited | Labels issues using `issue-label` skill |
-| `doc-sync.yml` | Pull request | Syncs docs using `doc-sync` skill |
-| `release.yml` | Manual dispatch | Creates releases using `release-notes` skill |
-
-## CLI Options
-
-```bash
-bunx open-workflows [OPTIONS]
-
-OPTIONS
-  --skills       Install skills only
-  --workflows    Install workflows only
-  --version, -v  Display version
-  --help, -h     Display help
+The CLI will prompt you to select workflows and install them to `.github/workflows/`.
+
+## Available Actions
+
+| Action | AI | Description |
+|--------|-----|-------------|
+| `pr-review` | Yes | AI-powered code reviews |
+| `issue-label` | Yes | Auto-label issues based on content |
+| `doc-sync` | Yes | Keep docs in sync with code changes |
+| `release` | No | Semantic versioning with npm provenance |
+
+## Manual Usage
+
+### AI-Powered Actions
+
+```yaml
+name: PR Review
+on:
+  pull_request:
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: activadee/open-workflows/actions/pr-review@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-## Plugin Installation
-
-Add to your `opencode.json`:
-
-```json
-{
-  "plugin": ["@activade/open-workflows"]
-}
+### Release Action (No AI)
+
+```yaml
+name: Release
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: 'Version bump'
+        required: true
+        type: choice
+        options: [patch, minor, major]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: activadee/open-workflows/actions/release@main
+        with:
+          bump: ${{ inputs.bump }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-The plugin provides 4 tools for the skills to use:
-- `submit_review` - Post PR review comments
-- `apply_labels` - Apply labels to issues
-- `github_release` - Create GitHub releases
-- `bun_release` - Publish to npm
+No NPM_TOKEN needed - uses OIDC trusted publishing with provenance.
 
-## GitHub Secrets
+## Authentication
 
-Add your API key as a GitHub Actions secret:
+### For AI Actions
 
+**Option 1: API Key**
 ```bash
 gh secret set ANTHROPIC_API_KEY
 ```
 
-For the release workflow, also add:
+**Option 2: Claude Max (OAuth)**
+```bash
+cat ~/.local/share/opencode/auth.json | base64 | gh secret set OPENCODE_AUTH
+```
+
+## CLI Options
 
 ```bash
-gh secret set NPM_TOKEN
+bunx @activade/open-workflows [OPTIONS]
+
+OPTIONS
+  --force, -f    Override existing files without prompts
+  --version, -v  Display version
+  --help, -h     Display help
 ```
 
 ## How It Works
 
-1. GitHub Actions trigger on events (PR, issue, manual)
-2. Workflow runs OpenCode with a task message
-3. OpenCode loads the appropriate skill
-4. Skill guides the AI through the workflow
-5. AI uses the plugin's tools to complete actions
+**AI Actions (pr-review, issue-label, doc-sync):**
+1. Workflow triggers on GitHub event
+2. Composite action sets up Bun and OpenCode
+3. OpenCode runs with the bundled skill
+4. AI analyzes content and takes action
+
+**Release Action:**
+1. Manually triggered with version bump type
+2. Generates changelog from git commits
+3. Publishes to npm with provenance
+4. Creates GitHub release with notes
 
-## Customizing Skills
+## Customizing
 
-Skills are just markdown files. After installation, edit `.opencode/skill/*/SKILL.md` to customize behavior.
+Fork this repository and modify:
+- `actions/*/skill.md` - AI behavior for AI-powered actions
+- `actions/release/src/publish.ts` - Release logic
 
 ## License
 

package/actions/doc-sync/action.yml

@@ -0,0 +1,42 @@
+name: 'Doc Sync'
+description: 'Keep documentation in sync with code changes'
+author: 'activadee'
+
+inputs:
+  model:
+    description: 'Model to use for doc analysis'
+    required: false
+    default: 'anthropic/claude-sonnet-4-5'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v2
+
+    - name: Setup OpenCode auth
+      if: env.OPENCODE_AUTH != ''
+      shell: bash
+      run: |
+        mkdir -p ~/.local/share/opencode
+        echo "$OPENCODE_AUTH" | base64 -d > ~/.local/share/opencode/auth.json
+
+    - name: Configure Git
+      shell: bash
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+
+    - name: Install skill
+      shell: bash
+      run: |
+        mkdir -p .opencode/skill/doc-sync
+        cp "${{ github.action_path }}/skill.md" .opencode/skill/doc-sync/SKILL.md
+
+    - name: Sync Documentation
+      shell: bash
+      run: |
+        bunx opencode-ai@latest run --model "${{ inputs.model }}" \
+          "Load the doc-sync skill and sync documentation for PR ${{ github.event.pull_request.number }}"
+      env:
+        GITHUB_TOKEN: ${{ github.token }}

package/actions/doc-sync/skill.md

@@ -0,0 +1,97 @@
+---
+name: doc-sync
+description: Keep documentation in sync with code changes. Analyzes PR diffs and updates relevant docs using native write and bash tools.
+license: MIT
+---
+
+## What I Do
+
+Analyze pull request changes and update documentation to reflect code changes. Uses native OpenCode tools (`write`, `bash`) for file operations and git commits.
+
+## Workflow
+
+1. **Gather PR context**:
+   ```bash
+   gh pr view <number> --json files,title,body,headRefOid
+   ```
+
+2. **Create todo list**: One item per changed file using `todowrite`
+
+3. **Analyze each file**:
+   - Mark todo as `in_progress`
+   - Identify user-visible changes (APIs, config, behavior)
+   - Note which documentation might need updates
+   - Mark todo as `completed`
+
+4. **After ALL files analyzed**:
+   - Identify affected documentation files
+   - Read current content of each doc file
+   - Plan minimal, precise updates
+
+5. **Update documentation**: Use `write` tool for each file needing changes
+
+6. **Commit and push**: Use `bash` tool for git operations
+
+## Documentation Scope
+
+Check these locations first:
+- `README.md` at repository root
+- Files under `docs/` directory
+- API documentation if present
+- Configuration examples
+- Other markdown files at root
+
+## What to Update
+
+| Code Change | Documentation Update |
+|-------------|---------------------|
+| New feature | Add documentation |
+| Changed behavior | Update existing docs |
+| Removed feature | Remove or mark deprecated |
+| New config option | Document option and defaults |
+| Changed API | Update examples and usage |
+
+## Committing Changes
+
+After updating documentation files with `write`, commit using `bash`:
+
+```bash
+git add README.md docs/
+git commit -m "[skip ci] docs: <description of changes>"
+git push
+```
+
+**Important**: The `[skip ci]` prefix prevents infinite workflow loops.
+
+## Style Guidelines
+
+- Keep documentation concise and accurate
+- Match existing tone and formatting
+- Prefer targeted edits over large rewrites
+- Ensure code examples are syntactically correct
+- Don't invent features not present in the code
+
+## No Changes Needed
+
+If the existing documentation is already accurate:
+- Do NOT create an empty commit
+- Do NOT call any git commands
+- Simply report that no documentation updates were required
+- Explain briefly why the docs are already correct
+
+## Common Mistakes to Avoid
+
+- Do NOT update docs unrelated to the PR
+- Do NOT start editing before completing all file analyses
+- Do NOT generate marketing-style or overly verbose content
+- Do NOT change code examples unless the underlying code changed
+- Do NOT duplicate information across multiple files
+- Do NOT commit with an empty file list
+
+## Example Workflow
+
+1. PR changes `src/config/options.ts` to add new `timeout` option
+2. Analyze: user-visible config change
+3. Check `README.md` and `docs/configuration.md`
+4. Update `docs/configuration.md` with new option description
+5. Commit: `[skip ci] docs: add timeout configuration option`

package/actions/issue-label/action.yml

@@ -0,0 +1,36 @@
+name: 'Issue Label'
+description: 'AI-powered issue labeling based on content analysis'
+author: 'activadee'
+
+inputs:
+  model:
+    description: 'Model to use for labeling'
+    required: false
+    default: 'anthropic/claude-haiku-4-5'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v2
+
+    - name: Setup OpenCode auth
+      if: env.OPENCODE_AUTH != ''
+      shell: bash
+      run: |
+        mkdir -p ~/.local/share/opencode
+        echo "$OPENCODE_AUTH" | base64 -d > ~/.local/share/opencode/auth.json
+
+    - name: Install skill
+      shell: bash
+      run: |
+        mkdir -p .opencode/skill/issue-label
+        cp "${{ github.action_path }}/skill.md" .opencode/skill/issue-label/SKILL.md
+
+    - name: Label Issue
+      shell: bash
+      run: |
+        bunx opencode-ai@latest run --model "${{ inputs.model }}" \
+          "Load the issue-label skill. Scripts are at ${{ github.action_path }}/src/. Label issue ${{ github.event.issue.number }}"
+      env:
+        GITHUB_TOKEN: ${{ github.token }}

package/actions/issue-label/skill.md

@@ -0,0 +1,113 @@
+---
+name: issue-label
+description: Automatically apply appropriate labels to GitHub issues based on content analysis.
+license: MIT
+---
+
+## What I Do
+
+Analyze GitHub issue content and apply up to 3 appropriate labels to help maintainers triage and search issues effectively.
+
+## Workflow
+
+1. **Fetch issue details**: Get title, body, and existing labels
+   ```bash
+   gh issue view <number> --json title,body,labels
+   ```
+
+2. **Fetch repository labels**: List available labels
+   ```bash
+   gh label list --json name,description,color
+   ```
+
+3. **Analyze the issue**:
+   - Determine the main type: bug, feature, documentation, question, etc.
+   - Look for hints about complexity (good-first-issue candidate?)
+   - Match to existing labels
+
+4. **Select labels**: Choose up to 3 existing labels that best describe the issue
+
+5. **Create new labels**: Only if no existing labels fit (rare)
+
+6. **Apply**: Run the apply-labels script (see Applying Labels section)
+
+## Labeling Guidelines
+
+### Use Existing Labels
+Prefer existing labels over creating new ones. Check the repository's label taxonomy first.
+
+### Common Categories
+- `bug` - Something isn't working
+- `feature` or `feature-request` - New functionality
+- `enhancement` - Improvement to existing feature
+- `documentation` - Docs need updates
+- `question` - Needs clarification
+- `good-first-issue` - Good for newcomers
+
+### Label Naming Conventions (for new labels)
+- Lowercase letters only
+- Words separated by hyphens
+- 1-3 words, under 30 characters
+- Example: `needs-reproduction`, `breaking-change`
+
+## Applying Labels
+
+The script path is provided in your task message. Run the apply-labels script:
+
+```bash
+bun "<script_path>/apply-labels.ts" \
+  --repo "owner/repo" \
+  --issue 123 \
+  --labels "bug,needs-triage" \
+  --explanation "Issue describes broken functionality in auth module"
+```
+
+### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--repo` | Yes | Repository in owner/repo format |
+| `--issue` | Yes | Issue number |
+| `--labels` | Yes | Comma-separated label names (max 3) |
+| `--explanation` | Yes | Brief reason for label choices |
+| `--new-labels` | No | JSON array of new labels to create first |
+
+### Creating New Labels
+
+If you need to create new labels (use sparingly):
+
+```bash
+bun "<script_path>/apply-labels.ts" \
+  --repo "owner/repo" \
+  --issue 123 \
+  --labels "bug,needs-reproduction" \
+  --explanation "Bug report lacking steps to reproduce" \
+  --new-labels '[{"name":"needs-reproduction","color":"d93f0b","description":"Issue needs steps to reproduce"}]'
+```
+
+Color is a hex string WITHOUT the leading `#`.
+
+## Decision Process
+
+1. **Read the issue carefully** - title and full body
+2. **Identify the primary type** - bug? feature? question?
+3. **Check for secondary aspects** - affects docs? good for beginners?
+4. **Match to existing labels** - prefer exact matches
+5. **If no match exists** - consider if a new label is truly needed
+6. **Write explanation** - brief justification for choices
+
+## Common Mistakes to Avoid
+
+- Do NOT apply more than 3 labels total
+- Do NOT create many highly specific labels unlikely to be reused
+- Do NOT apply labels that contradict the issue content
+- Do NOT overuse broad labels like `question` when specific ones exist
+- Do NOT create duplicate labels with slight name variations
+- Do NOT omit the explanation argument
+- Do NOT run the script more than once
+
+## Example Explanation
+
+Good: "Labeled as bug and documentation based on steps to reproduce and mention of incorrect docs"
+
+Bad: "Applied some labels"

package/actions/issue-label/src/apply-labels.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+/// <reference types="bun-types" />
+
+/**
+ * Usage: bun apply-labels.ts --repo owner/repo --issue 123 --labels "bug,enhancement" \
+ *        --explanation "Why these labels" [--new-labels '[{"name":"x","color":"fff","description":"..."}]']
+ */
+
+import { parseArgs } from "util";
+
+interface NewLabel {
+  name: string;
+  color: string;
+  description: string;
+}
+
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const isLast = attempt === maxRetries - 1;
+      const msg = error instanceof Error ? error.message : String(error);
+      const isRetryable = msg.includes('rate limit') || msg.includes('timeout') || 
+                          msg.includes('503') || msg.includes('ECONNRESET');
+      if (isLast || !isRetryable) throw error;
+      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+
+async function main() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      repo: { type: 'string' },
+      issue: { type: 'string' },
+      labels: { type: 'string' },
+      explanation: { type: 'string' },
+      'new-labels': { type: 'string' },
+    },
+    strict: true,
+  });
+
+  const { repo, issue, labels, explanation, 'new-labels': newLabelsJson } = values;
+
+  if (!repo || !issue || !labels || !explanation) {
+    console.error('Missing required arguments: --repo, --issue, --labels, --explanation');
+    process.exit(1);
+  }
+
+  const issueNumber = parseInt(issue, 10);
+  if (isNaN(issueNumber)) {
+    console.error('Invalid issue number');
+    process.exit(1);
+  }
+
+  const labelList = labels.split(',').map(l => l.trim()).filter(Boolean);
+  if (labelList.length === 0) {
+    console.error('No labels provided');
+    process.exit(1);
+  }
+
+  if (labelList.length > 3) {
+    console.error('Maximum 3 labels allowed');
+    process.exit(1);
+  }
+
+  const results: string[] = [];
+
+  if (newLabelsJson) {
+    let newLabels: NewLabel[] = [];
+    try {
+      newLabels = JSON.parse(newLabelsJson);
+    } catch {
+      console.error('Invalid JSON for --new-labels');
+      process.exit(1);
+    }
+
+    for (const label of newLabels) {
+      try {
+        await withRetry(() =>
+          Bun.$`gh label create ${label.name} --color ${label.color} --description ${label.description} --repo ${repo}`.quiet()
+        );
+        results.push(`Created label: ${label.name}`);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes('already exists') || msg.includes('Conflict')) {
+          results.push(`Label already exists: ${label.name}`);
+        } else {
+          results.push(`Failed to create label "${label.name}": ${msg}`);
+        }
+      }
+    }
+  }
+
+  const labelArg = labelList.join(',');
+  try {
+    await withRetry(() =>
+      Bun.$`gh issue edit ${issueNumber} --add-label ${labelArg} --repo ${repo}`.quiet()
+    );
+    results.push(`Applied labels: ${labelArg}`);
+    results.push(`Reason: ${explanation}`);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    results.push(`Failed to apply labels: ${msg}`);
+    console.error(results.join('\n'));
+    process.exit(1);
+  }
+
+  console.log(results.join('\n'));
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/actions/pr-review/action.yml

@@ -0,0 +1,36 @@
+name: 'PR Review'
+description: 'AI-powered pull request code review'
+author: 'activadee'
+
+inputs:
+  model:
+    description: 'Model to use for review'
+    required: false
+    default: 'anthropic/claude-sonnet-4-5'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v2
+
+    - name: Setup OpenCode auth
+      if: env.OPENCODE_AUTH != ''
+      shell: bash
+      run: |
+        mkdir -p ~/.local/share/opencode
+        echo "$OPENCODE_AUTH" | base64 -d > ~/.local/share/opencode/auth.json
+
+    - name: Install skill
+      shell: bash
+      run: |
+        mkdir -p .opencode/skill/pr-review
+        cp "${{ github.action_path }}/skill.md" .opencode/skill/pr-review/SKILL.md
+
+    - name: Review PR
+      shell: bash
+      run: |
+        bunx opencode-ai@latest run --model "${{ inputs.model }}" \
+          "Load the pr-review skill. Scripts are at ${{ github.action_path }}/src/. Review PR ${{ github.event.pull_request.number }}"
+      env:
+        GITHUB_TOKEN: ${{ github.token }}