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:

• Determine repository organization from git remote get-url origin

• Load only the reference file for that organization

• 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:

• Extract the missing package name from error message

• Check if it exists in project's devDependencies or dependencies

• 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 <noreply@anthropic.com> 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