blocklet-pr

name	blocklet-pr
description	Create standardized Pull Requests for blocklet projects. Performs lint checks, unit tests, version updates, and creates PRs following PR templates. Use `/blocklet-pr` or say "help me submit a PR", "create pull request" to trigger.

Blocklet PR

Help developers create standardized Pull Requests for blocklet projects, ensuring code quality and following project PR templates.

Core Philosophy

"Quality gates + standardized workflow."

PRs are not submitted casually. Before submission, code must pass lint and tests, must be on a working branch (never directly on main branch), and PR content must follow project templates. Enforced standardization reduces human oversight errors.

Prerequisites

• Current directory is a blocklet project (contains blocklet.yml)
• Has code changes to commit

Reference Files

Branch conventions and repository info are read from local reference files (in blocklet-url-analyzer skill directory):

• blocklet-url-analyzer/references/org-arcblock-repos.md - ArcBlock repos (core infrastructure, SDKs, mobile apps)
• blocklet-url-analyzer/references/org-blocklet-repos.md - Blocklet repos (blocklet applications, kits, tools)
• blocklet-url-analyzer/references/org-aigne-repos.md - AIGNE repos (AI agent framework, LLM adapters)

Active Loading Policy (ALP)

Load reference files on-demand based on repository organization. Do not preload all files.

Trigger Condition	Load File
Repository in ArcBlock org	blocklet-url-analyzer/references/org-arcblock-repos.md
Repository in blocklet org	blocklet-url-analyzer/references/org-blocklet-repos.md
Repository in AIGNE-io org	blocklet-url-analyzer/references/org-aigne-repos.md
Uncertain which organization	First read blocklet-url-analyzer/references/README.md

Loading Strategy:

1. Determine repository organization from git remote get-url origin
2. Load only the reference file for that organization
3. If organization unknown, read README.md first for high-density summary

Workflow

Execute the following phases in order.

Phase 1: Workspace Check

Refer to blocklet-branch skill for branch operations. Skill location: blocklet-branch/SKILL.md

1.1 Confirm Remote Repository

Refer to blocklet-branch section 1.1:

REMOTE_URL=$(git remote get-url origin)
ORG=$(echo $REMOTE_URL | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\1/')
REPO=$(echo $REMOTE_URL | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\2/' | sed 's/\.git$//')

1.2 Detect Main Iteration Branch

Read from local reference files to get branch conventions for the repository (following ALP).

Load reference file based on repository organization (from 1.1):

• ArcBlock org → blocklet-url-analyzer/references/org-arcblock-repos.md
• blocklet org → blocklet-url-analyzer/references/org-blocklet-repos.md
• AIGNE-io org → blocklet-url-analyzer/references/org-aigne-repos.md
• Unknown → First read blocklet-url-analyzer/references/README.md

Default branch conventions (if no specific info found in references):

Organization	Default Main Branch
ArcBlock	dev
blocklet	main
AIGNE-io	main

Output variables: MAIN_BRANCH, MAIN_BRANCH_REASON

1.3 Detect Branch Naming Conventions

Read from local reference files to get branch prefix conventions for the repository.

Default prefix conventions (if no specific info found in references):

Prefix	Usage
feat/ or feature/	New features
fix/	Bug fixes
chore/	Maintenance tasks
docs/	Documentation

Output variables: BRANCH_PREFIX_CONVENTION, BRANCH_SEPARATOR

1.4 Branch Check and Creation (Mandatory)

Refer to blocklet-branch sections 6, 7.

Important: Before submitting a PR, you must ensure you are on a working branch; cannot commit directly on the main iteration branch.

CURRENT_BRANCH=$(git branch --show-current)

if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
    echo "⚠️ Currently on main iteration branch $MAIN_BRANCH, must create new branch!"
fi

Situation	Handling
On main iteration branch	Must create new branch (refer to blocklet-branch section 6)
On working branch	Check if branch naming follows convention (refer to blocklet-branch section 7.2)

If on main iteration branch, use AskUserQuestion:

⚠️ Currently on main iteration branch {MAIN_BRANCH}, cannot submit PR directly.

Please select new branch name (will be created based on {MAIN_BRANCH}):

Options:
A. {suggested branch name, generated based on change type and BRANCH_PREFIX_CONVENTION} (Recommended)
B. Enter custom branch name
C. Cancel operation

Create working branch (refer to blocklet-branch section 6.2):

git fetch origin $MAIN_BRANCH
git checkout $MAIN_BRANCH
git pull origin $MAIN_BRANCH
git checkout -b $NEW_BRANCH_NAME

1.5 Check Uncommitted Changes

git status --porcelain

Situation	Handling
Has unstaged changes	Continue flow, will handle later
No changes at all	Prompt no changes to commit, ask user intent

---

Phase 2: Code Quality Checks

2.0 Ensure Dependencies Installed

Before running lint or tests, check if node_modules exists. If not, ask user whether to install dependencies.

Important: Detect and use the project's package manager (check lock files like pnpm-lock.yaml, yarn.lock, package-lock.json, etc.) for all dependency operations.

2.1 Lint Check

Run lint script from package.json (e.g., lint, lint:fix, check).

Handle missing dependency errors:

If lint fails with command not found or Cannot find module errors:

1. Extract the missing package name from error message
2. Check if it exists in project's devDependencies or dependencies
3. If NOT in project dependencies, ask user:
   • Add the package to devDependencies (using project's package manager)
   • Skip lint check
   • Cancel

Never suggest global installation - missing packages should be added to the project.

Result	Handling
Pass	Continue to next step
Fail (auto-fixable)	Try lint:fix, then recheck
Fail (cannot auto-fix)	Stop flow, let user fix
No lint command	Skip

2.2 Unit Tests

Run test script from package.json (e.g., test, test:unit, test:ci).

Handle missing dependency errors: Same as 2.1 - ask user to add missing package to project, never suggest global installation.

Regular test results:

Result	Handling
Pass	Continue to next step
Fail	Stop flow, output failed test cases, let user fix
No test command	Skip, continue to next step (suggest adding tests)

---

Phase 3: Version Update

Important: If the project has a CHANGELOG.md file, version bump is required for every PR, not optional.

3.1 Check If Version Update Required

First check if CHANGELOG.md exists in project root:

test -f CHANGELOG.md && echo "CHANGELOG exists - version bump required"

Situation	Handling
CHANGELOG.md exists	Version bump is required, skip option D
No CHANGELOG.md	Version bump is optional

3.2 Ask Version Update Type

Use AskUserQuestion to ask:

If CHANGELOG.md exists:

Project has CHANGELOG.md - version bump is required.

Please select version update type:
Options:
A. Patch version (x.x.X) (Recommended for bug fixes)
B. Minor version (x.X.0)
C. Major version (X.0.0)

If no CHANGELOG.md:

Do you need to update version and create release?

Options:
A. Yes, update patch version (x.x.X) (Recommended for bug fixes)
B. Yes, update minor version (x.X.0)
C. Yes, update major version (X.0.0)
D. No, skip version update

3.3 Execute Version Update

If user chooses to update version (or if required due to CHANGELOG.md), call blocklet-updater skill:

blocklet-updater skill location: blocklet-updater/SKILL.md

---

Phase 4: Git Commit

4.0 Check for Temporary Files (Pre-staging)

Before staging files, check for temporary database files in the root directory that should be ignored:

# Check for .db files in root directory only (not in subdirectories)
ROOT_DB_FILES=$(git status --porcelain | grep -E '^\?\? .*\.db$' | awk '{print $2}' | grep -v '/')

if [ -n "$ROOT_DB_FILES" ]; then
    echo "⚠️ Found temporary database files in root directory:"
    echo "$ROOT_DB_FILES"
fi

If root .db files found, use AskUserQuestion:

⚠️ Found temporary database files in root directory:

{list of files found}

These .db files are typically generated by tools and should not be committed.

Options:
A. Add *.db to .gitignore and continue (Recommended)
B. Continue anyway (these files will be committed)
C. Cancel, let me handle this manually

If Option A selected:

# Add .db pattern to .gitignore
echo "" >> .gitignore
echo "# Temporary database files" >> .gitignore
echo "*.db" >> .gitignore

git add .gitignore

If Option C selected: EXIT and let user handle manually.

Note: .aigne/ directories and files in subdirectories are NOT temporary files and should not be flagged.

4.1 Stage Changes

git add -A
git status

Display list of files to be committed, use AskUserQuestion to confirm:

The following files will be committed:
{file list}

Continue?
A. Yes, commit all changes (Recommended)
B. No, let me select files to commit
C. Cancel

4.2 Generate Commit Message

Generate standardized commit message based on change type:

Note: Refer to the last 20 commits for the specific prefix, follow historical conventions.

Change Type	Commit Prefix	Example
New feature	feat:	feat: add video preview support
Bug fix	fix:	fix: resolve duplicate upload issue
Documentation	docs:	docs: update API documentation
Refactoring	refactor:	refactor: simplify auth logic
Testing	test:	test: add unit tests for utils
Build/Chore	chore:	chore: bump dependencies

Analyze changes to automatically infer type, then use AskUserQuestion to confirm:

Suggested commit message:

{generated commit message}

Options:
A. Use this message (Recommended)
B. Modify message
C. Cancel

4.3 Execute Commit

git commit -m "$(cat <<'EOF'
{commit_message}

Co-Authored-By: Claude <[e-mail]>
EOF
)"

---

Phase 5: Push Branch

5.1 Check Remote Branch

git ls-remote --heads origin $CURRENT_BRANCH

Situation	Handling
Remote branch doesn't exist	Use -u to push and set upstream
Remote branch exists	Normal push

5.2 Push

git push -u origin $CURRENT_BRANCH

---

Phase 6: Create Pull Request

6.1 Check PR Template

# Find PR template
PR_TEMPLATE=""
if [ -f ".github/PULL_REQUEST_TEMPLATE.md" ]; then
    PR_TEMPLATE=".github/PULL_REQUEST_TEMPLATE.md"
elif [ -f ".github/pull_request_template.md" ]; then
    PR_TEMPLATE=".github/pull_request_template.md"
elif [ -f "docs/PULL_REQUEST_TEMPLATE.md" ]; then
    PR_TEMPLATE="docs/PULL_REQUEST_TEMPLATE.md"
fi

If template found: Read and parse template structure, fill PR content according to template format.

If template not found: Use default PR format.

6.2 Get Target Branch

Use the MAIN_BRANCH detected in Phase 1.2 (from reference files).

Use AskUserQuestion to confirm target branch:

PR target branch:

Options:
A. {MAIN_BRANCH} (Recommended)
B. Other branch

6.3 Link Issue (If Applicable)

Use AskUserQuestion to ask:

Do you need to link an Issue?

Options:
A. No, don't link Issue
B. Yes, link Issue (please enter Issue number)

If linking Issue, add to PR description:

• Closes #123 - Auto-close Issue when merged
• Fixes #123 - Fix Issue
• Relates to #123 - Related but don't auto-close

6.4 Generate PR Content

PR Title: Generate based on commit message or branch name, keep format concise and clear.

Important: PR title must be all lowercase. When converting camelCase words, use hyphens between words (e.g., devDependencies → dev-dependencies). Example: fix: add lerna to dev-dependencies

PR Description (according to template or default format):

## Summary

{Change overview, 2-3 sentences explaining what this PR does}

## Changes

{Specific change list}
- Change 1
- Change 2
- ...

## Related Issues

{If there are linked Issues}
Closes #{issue_number}

## Test Plan

{Verification methods and test points}
- [ ] Verification point 1
- [ ] Verification point 2
- [ ] Unit tests pass
- [ ] Lint check passes

## Screenshots (if applicable)

{If there are UI changes, add screenshots}

6.5 Choose PR Creation Method

After generating PR content, use AskUserQuestion to ask user:

How would you like to create the PR?

Options:
A. Create PR.md file (for manual submission later)
B. Submit PR directly using gh CLI (Recommended)

6.5.1 Option A: Create PR.md File

Create a PR.md file in the repository root with the PR content:

cat > PR.md << 'EOF'
# {pr_title}

**Target Branch**: {TARGET_BRANCH}
**Source Branch**: {CURRENT_BRANCH}

{pr_body}
EOF

echo "✅ PR.md created. You can manually create PR on GitHub using this content."

Output:

===== PR.md Created =====

File: PR.md
Title: {pr_title}
Target Branch: {target_branch}

Next Steps:
1. Open GitHub repository: https://github.com/{ORG}/{REPO}
2. Click "Pull requests" → "New pull request"
3. Select base: {TARGET_BRANCH}, compare: {CURRENT_BRANCH}
4. Copy content from PR.md

6.5.2 Option B: Submit PR using gh CLI

First check gh CLI availability:

# Check if gh is installed
if ! command -v gh &> /dev/null; then
    echo "❌ gh CLI is not installed."
    echo ""
    echo "Install gh CLI:"
    echo "  macOS: brew install gh"
    echo "  Linux: see https://cli.github.com/linux"
    echo "  Windows: winget install GitHub.cli"
    echo ""
    echo "After installation, run: gh auth login"
    exit 1
fi

# Check if gh is authenticated
if ! gh auth status &> /dev/null; then
    echo "❌ gh CLI is not authenticated."
    echo ""
    echo "Run: gh auth login"
    echo "Then retry creating PR."
    exit 1
fi

Status	Handling
gh not installed	Show installation instructions, fallback to PR.md
gh not authenticated	Show gh auth login instructions, fallback to PR.md
gh ready	Create PR

Create PR:

gh pr create \
  --title "{pr_title}" \
  --body "$(cat <<'EOF'
{pr_body}
EOF
)" \
  --base $TARGET_BRANCH

6.6 Output Result

If PR created via gh:

===== PR Created Successfully =====

PR URL: {pr_url}
Title: {pr_title}
Target Branch: {target_branch}
Linked Issues: {issue_numbers or "None"}

===== Next Steps =====
Wait for Code Review

If PR.md created:

===== PR.md Created =====

File: PR.md
Please manually create PR on GitHub.

---

Error Handling

Error	Handling
Lint failed	Show error details, suggest running pnpm run lint:fix
Tests failed	Show failed test cases, let user fix
Push failed	Check permissions, suggest git pull --rebase
gh not installed	Show installation instructions, offer to create PR.md instead
gh not authenticated	Show gh auth login instructions, offer to create PR.md instead
PR creation failed	Show gh error message, offer to create PR.md instead
Same PR already exists	Show existing PR link, ask whether to update

---

Relationship with Other Skills

Skill	Relationship
blocklet-dev-setup	Development environment setup, use before PR
blocklet-updater	Version update, optionally called during PR
blocklet-url-analyzer	Analyze Blocklet URL, locate repository