Work Item-Driven Git Workflow

Trigger condition: The task includes a PingCode work item identifier

#<Identifier>

(e.g.

#ABC-42

), and the user asks to develop, fix, implement, continue, review, or merge it. Do not apply this skill's claim, comment, or branch naming rules to ordinary code changes without an identifier; follow the repository's own conventions instead.

All PingCode operations depend entirely on the use-pingcode-cli
skill: first perform its

pc

and login prechecks, then use this workflow; do not invent

pc

commands or parameters. This skill defines only the workflow and Git/documentation standards; refer to

use-pingcode-cli

for API details.

Detailed sub-workflows, Feature breakdown, commit types, and anti-patterns are documented in

reference.md

Hard Rules

Never modify files, commit, or push directly on an integration branch (commonly
```
develop
```
/
```
main
```
, subject to the repository's actual protection rules); all changes must go through a work branch and PR.
Do not proactively
```
commit
```
,
```
push
```
, or merge a PR unless the user explicitly requests it.
Before performing dangerous operations (
```
reset --hard
```
,
```
restore
```
,
```
clean -fd
```
,
```
stash drop
```
, rebasing/amending already-pushed history, or any
```
push --force*
```
), explain the impact and obtain confirmation; never force-push to an integration branch under any circumstances.
Do not claim to have run checks that were not actually executed; report CI failures or missing checks honestly.
Long-term documentation must be centralized under
```
docs/
```
, not scattered across source directories, personal notes, or chat histories.

0. Identify the Identifier and Perform Prechecks

Extract
```
#<Identifier>
```
from the user's message, for example
```
#ABC-42
```
. Remove the
```
#
```
when invoking
```
pc
```
:
```
ABC-42
```
; retain the
```
#
```
in branch names and PR titles.
Load
```
use-pingcode-cli
```
and run
```
pc doctor
```
as specified by it; if the exit code is non-zero, resolve the failed checks and do not continue.
Use
```
pc whoami --json
```
to confirm the current user: use
```
identity.user.name
```
as the login name and
```
identity.user.id
```
as the user ID. The
```
current user
```
refers to this user throughout the rest of the workflow.
Record the repository folder name for use with the cache and temporary worktrees:
bash
```
REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
```

1. Retrieve Work Item Details

bash

pc pjm workitem get ABC-42

Always use
get
with the full identifier. Do not use the global
```
pc pjm workitem list --identifier <number>
```
command to retrieve details; without
```
--project-id
```
, it may match work items with the same number across projects, resulting in ambiguity. Only fall back to
```
pc pjm workitem list --project-id <pid> --identifier <n>
```
for an exact project-scoped lookup when only the number is available and the full identifier cannot be reconstructed.

Fetch comments and attachments at the same time:

bash

pc comments list --principal-type workitem --principal-id <工作项id>

Record
```
id
```
,
```
project.id
```
,
```
type.id
```
,
```
state.id
```
,
```
assignee.id
```
, and
```
parent_id
```
from the response; use these IDs for subsequent type/state resolution and write operations.
When
```
parent_id
```
is not empty, retrieve the parent work item's title and description to understand the broader context.
Use
```
pc pjm workitem list --project-id <项目ID> --parent-id <工作项ID>
```
to query child work items: read titles only first to understand the full scope, then retrieve the details of relevant child work items as needed instead of fetching everything at once.
During Feature breakdown, use
```
pc pjm workitem-relation list <工作项ID>
```
to find related work items and retrieve them as needed.

2. Determine the Work Item Type

Use

pc pjm workitem-type list-for-project --project-id <项目ID>

to resolve the actual types within the project and match them by name. Do not hard-code type IDs or

story

bug

labels.

Feature / product requirement: Do not directly claim or develop it. Move to the
```
Feature Breakdown Process
```
in
```
reference.md
```
and first break it down into independently deliverable user stories.
Not a Feature (an executable work item such as a user story, task, or defect): Continue to Step 3.

3. Check the Status and Assignee

If the status is not an initial state such as
```
Open
```
/
```
Pending
```
, notify the user and ask whether to continue; do not proceed on your own. Resolve state IDs using
```
pc pjm workitem-state list-for-project --project-id <pid> --workitem-type-id <type-id>
```
and identify them by name rather than hard-coding them.
If an assignee is already set and is not the current user, notify the user and ask whether to continue.
If the requirements, solution, or acceptance criteria are unclear, do not guess; ask the user until they are clear.

4. Claim the Work Item (Idempotent)

If the assignee is not the current user, set the assignee to the current user. If the state is not

In Progress

, transition it to

In Progress

. If the target value is already in place, skip the corresponding write and do not attempt to transition the current state again, because this causes a

work item state cannot transition to its current state

error.

bash

pc pjm workitem update <工作项id> --data '{"assignee_id":"<当前用户ID>"}'
pc pjm workitem update <工作项id> --data '{"state_id":"<进行中状态ID>"}'

Read the work item before performing a write operation, then run
```
get
```
again to verify it afterward.
On a 403 or insufficient scope, stop and ask the user to resolve it; do not retry repeatedly.

5. Understand, Break Down, and Plan First

Read the title, description, comments, and attachments, and use the parent, child, and related work items to understand the intended acceptance criteria.
If the work is substantial (cross-module, multi-stage, or parallelizable), first ask the user whether to create child work items of type
```
Task
```
. Create them only after the user agrees, then ask whether to claim and execute them one by one in order.
First present the proposed solution and the files to be changed to the user, without writing anything to disk; begin changing the code only after the user confirms.
Promptly post key conclusions, scope boundaries, implementation progress, and completion summaries to the work item as a plain-text comment:
- Use paragraph breaks and
```
-
```
  /
```
1.
```
  lists; do not use HTML tags.
- To mention someone, use
```
[@<用户ID>|<登录名>]
```
  (resolve the user ID with
```
pc organization user list
```
  ); writing only
```
@登录名
```
  will not trigger a mention.
- Keep process information only in work item comments; do not save a separate local copy.

6. Create a Work Branch

Run the following commands in order. Stop and ask the user if any precondition is not met:

bash

git rev-parse --abbrev-ref HEAD     # 应在集成分支
git status --porcelain              # 应为空
git fetch origin
git pull --ff-only                  # 落后时
git checkout -b '#ABC-42/(feat)user-login'

Branch naming format:

#<Identifier>/(<type>)<kebab-summary>

, for example

#ABC-42/(feat)user-login

#ABC-42/(fix)retry-timeout

Use
```
/
```
between the identifier and the branch name, not a colon;
```
#
```
is allowed in branch names.
Ask the user to confirm the branch name first; when uncertain, validate it with
```
git check-ref-format --branch '<name>'
```
.
If the current branch is not an integration branch, do not switch branches on your own; if the working tree is dirty, ask the user to choose whether to commit, stash, or discard the changes.
Make all changes and commits on the work branch; ask the user before switching branches.

7. Commit and Open a PR

Before committing, run the validations defined by the repository's documentation or CI; run lint, typecheck, test, and build for each affected package or module, and explain why any check could not be run.
Stage only files relevant to this task; inspect
```
git status
```
and
```
git diff
```
before committing.
Use Conventional Commits for the commit message:
```
<type>[optional scope]: <description>
```
. For example, a split commit for
```
feat: #ABC-42 user-login
```
may use
```
feat(auth): add login form
```
.

PR title format:

<type>: #<Identifier> <summary>

, for example

feat: #ABC-42 user-login

After user confirmation, run
```
git push -u origin <branch>
```
and open a PR targeting the integration branch. The PR description must clearly state the changes, rationale, validation, risks, and rollback plan.
Use squash merging by default:
```
gh pr merge <n> --squash --delete-branch
```
; do not use
```
--merge
```
/
```
--rebase
```
/
```
--auto
```
, and do not use
```
--admin
```
to bypass protections.
If the PR is behind its base (
```
BEHIND
```
), run
```
git fetch origin
```
and rebase onto
```
origin/<integration-branch>
```
; do not use
```
--admin
```
, and do not merge the integration branch into the work branch. Rerun validation after rebasing and, after user confirmation, run
```
git push --force-with-lease
```
.
After merging, confirm that the PR is
```
MERGED
```
, switch back to the integration branch, run
```
git pull --ff-only
```
, and delete the local work branch.

8. Post-Merge Wrap-Up

Recheck the work item status: if it is already in a completed state (such as
Fixed
or
Completed
, often transitioned automatically by PR merge automation), do not set it again; only verify the result. Otherwise, transition it to the completed state.
Regardless of whether the status was changed, append a plain-text summary comment covering the delivered work, validation results, and any follow-up work.
Do not store process information locally; preserve long-term lessons according to Step 10.

9. Code Review (As Needed)

When reviewing

#<Identifier>

or a specified PR:

First check the work item status and comments to confirm that there is no ongoing review or existing conclusion. If there is, stop and notify the user unless they explicitly request a new review.
First post a plain-text comment stating that the current user has started the Code Review and include the PR URL as an occupancy marker.
Create an isolated, read-only worktree in the system temporary directory, for example
```
<temp-dir>/${REPO_NAME}-pr<n>
```
; do not run Git or build operations in the current working tree.
Review only the code and standards compliance; whether to run lint, tests, or builds depends on the repository's review policy. Do not claim to have run checks that were not executed; cite PR status checks for CI results.
Conclusions must use only
```
Pass
```
/
```
Reject
```
/
```
Uncertain
```
, with reasons, and the user must choose the outcome.
On the PR side, only submit review comments; do not merge, push, or modify the author's branch. On the work item side, only comment; do not claim the work item or change its status or assignee.
When finished, remove the worktree and temporary branch.

10. Documentation Layering and Knowledge Capture

docs/
is the only root directory for long-term documentation. Create subdirectories by topic:

Directory	Contents
`docs/product/`	Product goals, users and scenarios, requirements, and interaction decisions
`docs/tech/`	Cross-package or cross-component architecture and technical decisions; `DESIGN_<topic>.md` is recommended
`docs/guide/`	New developer onboarding guides, operation manuals, and troubleshooting guides
`docs/decisions/`	Decision records that need long-term retention (ADRs)

Documentation should explain why, not duplicate API schemas, field tables, or facts that can be derived from code; interface facts must have a single source of truth.
Every design document must indicate its status, upstream documents, and revision history. When an earlier conclusion is overturned, append a revision record rather than silently rewriting it.
Package/module
```
README.md
```
files should contain only a minimal entry point and usage instructions and link to
```
docs/
```
; do not create deeply nested docs directories under
```
src/
```
.
When code behavior changes, update the affected
```
docs/
```
in the same PR; documentation that is out of sync means the task is incomplete.

Information is divided into three categories:

Type	Destination	Committed?
Re-discoverable reference data (IDs, name mappings, state values)	Local cache, for reference only	No
Team-valuable lessons, conclusions, and troubleshooting patterns	Ask the user, then write to `docs/` and submit through a PR	Yes
Task process information (clarifications, progress, summaries)	Work item comments	No

The cache directory dynamically uses the current repository folder name and must not be hard-coded:

bash

REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/$REPO_NAME"

Split files by host, include
```
fetchedAt
```
in each entry, and use a default TTL of 7 days.
Real-time API results always take precedence; if a reference has expired, a state cannot transition, or an ID cannot be found, discard the entry, fetch it again, and retry once.
If the cache is corrupted (invalid JSON), ignore it and rebuild it; never write tokens, secrets, or personal privacy data.
During wrap-up, proactively assess whether reusable knowledge was produced, but you must ask the user before writing it. If the user declines, do not save it, and never write it silently.

workitem-driven-development

NPX Install

Tags

SKILL.md Content (Chinese)

Work Item-Driven Git Workflow

Hard Rules

0. Identify the Identifier and Perform Prechecks

1. Retrieve Work Item Details

2. Determine the Work Item Type

3. Check the Status and Assignee

4. Claim the Work Item (Idempotent)

5. Understand, Break Down, and Plan First

6. Create a Work Branch

7. Commit and Open a PR

8. Post-Merge Wrap-Up

9. Code Review (As Needed)

10. Documentation Layering and Knowledge Capture