jig

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jig

A jig holds the work and guides the tool so every cut comes out true. This skill holds a task and guides the agent through a repeatable, gated software development lifecycle for the current repository, so every task runs the same accurate path. Deterministic mechanics are Node scripts bundled in this skill under

scripts/

; you run them and interpret the output.

<SKILL_DIR>

below is this skill's base directory — use its absolute path when running commands. Node.js ≥ 18 is required.

夹具（Jig）用于固定工件并引导工具，确保每一次加工都精准无误。本技能用于管理任务，并引导Agent完成当前代码仓库中可重复、受控的软件开发生命周期，确保每一项任务都遵循统一的精准流程。确定性机制由本技能下

scripts/

目录中的Node脚本实现；你可以运行这些脚本并解析输出。下文的

<SKILL_DIR>

指本技能的基础目录——运行命令时请使用其绝对路径。要求Node.js版本≥18。

Dispatch

调度

Parse the sub-command from the user's invocation (the word after

/jig

, or infer from the request) and follow the matching section. If none matches, run status and show the available sub-commands.

从用户的调用中解析子命令（

/jig

后的单词，或从请求中推断），然后遵循对应章节的流程。如果没有匹配项，运行status命令并显示可用的子命令。

init

Scaffold

.jig/

, then run Phase 0 to build Project Memory.

Run:

node "<SKILL_DIR>/scripts/scaffold.mjs" "$(pwd)"

and report created vs. skipped.

Run Phase 0 — understand the codebase: follow
```
<SKILL_DIR>/phases/understand.md
```
to fan out explorer subagents, merge their findings, and populate
```
.jig/memory/
```
.
Decide whether
.jig/
is tracked in git (git repo only) — ask the developer:
- Track it (recommended) — Jig state (spec, plan, progress, review, memory, backlog) is git-versioned and shared, committed alongside the code it describes. Set
```
git.track_state: true
```
  in
```
.jig/config.yml
```
  , then commit the scaffold:
```
git add .jig && git commit -m "chore: initialize jig"
```
  . If the base is protected and rejects a direct commit, tell the developer to commit
```
.jig/
```
  (or open a PR).
- Don't track it —
```
.jig/
```
  stays local-only (never dirties the tree, not shared). Set
```
git.track_state: false
```
  , add
```
.jig/
```
  to
```
.gitignore
```
  , and commit that:
```
git add .gitignore && git commit -m "chore: ignore .jig state"
```
  .
Report which memory files were populated and suggest the user skim
```
.jig/memory/index.md
```
.
Do not overwrite an existing config unless the user explicitly asks (
```
--force
```
).

搭建

.jig/

目录，然后运行第0阶段以构建项目记忆。

运行：
```
node "<SKILL_DIR>/scripts/scaffold.mjs" "$(pwd)"
```
，并报告已创建和已跳过的内容。
运行第0阶段——理解代码库：遵循
```
<SKILL_DIR>/phases/understand.md
```
的指引，调用探索子Agent，合并它们的发现，并填充
```
.jig/memory/
```
目录。
决定是否在git中跟踪
.jig/
目录（仅针对git仓库）——询问开发者：
- 跟踪（推荐）——Jig的状态（需求定义、计划、进度、评审、记忆、待办事项）将通过git进行版本控制并共享，与它所描述的代码一起提交。在
```
.jig/config.yml
```
  中设置
```
git.track_state: true
```
  ，然后提交搭建内容：
```
git add .jig && git commit -m "chore: initialize jig"
```
  。如果主分支受保护且拒绝直接提交，请告知开发者提交
```
.jig/
```
  目录（或打开PR）。
- 不跟踪——
```
.jig/
```
  目录仅保存在本地（永远不会污染代码树，不共享）。设置
```
git.track_state: false
```
  ，将
```
.jig/
```
  添加到
```
.gitignore
```
  中，并提交该更改：
```
git add .gitignore && git commit -m "chore: ignore .jig state"
```
  。
报告已填充的记忆文件，并建议用户浏览
```
.jig/memory/index.md
```
。
除非用户明确要求（使用
```
--force
```
参数），否则不要覆盖现有配置。

task

Create a new task folder for an issue/bug/feature.

Determine a short
```
title
```
from the user's request and a
```
type
```
(
```
feature
```
|
```
bug
```
|
```
chore
```
|
```
refactor
```
; default
```
feature
```
).
Propose a
```
track
```
(process weight): defaults by type are feature/refactor →
```
full
```
, bug/chore →
```
fast
```
; suggest
```
hotfix
```
when the user signals urgency. Confirm title, type, and track in one line before creating, and let the user override the track.

Run:

node "<SKILL_DIR>/scripts/new-task.mjs" "<title>" <type> <track>

(omit

<track>

to accept the type default).

Report the created

taskId

, its

track

, and path (

.jig/tasks/<YYYYMMDD>/<slug>/

The created task folder is

<taskDir>

(

.jig/tasks/<YYYYMMDD>/<slug>/

), at phase

intake

Run Phase 1 — Intake & Clarify: follow
```
<SKILL_DIR>/phases/intake.md
```
(pass
```
<taskDir>
```
). This is an interactive dialogue with the developer.
Run Phase 2 — Spec & Plan: follow
```
<SKILL_DIR>/phases/spec-plan.md
```
(pass
```
<taskDir>
```
), ending at the spec gate.
After the gate is approved (phase
```
implement
```
), run Phase 3 — Implement (
```
<SKILL_DIR>/phases/implement.md
```
; creates a
```
<type>/<slug>
```
feature branch per
```
git.branch
```
), Phase 4 — Test (
```
<SKILL_DIR>/phases/test.md
```
), Phase 5 — Review (
```
<SKILL_DIR>/phases/review.md
```
, review gate), then Phase 6 — Ship (
```
<SKILL_DIR>/phases/ship.md
```
). Ship pushes the branch and opens a PR or leaves commits (
```
ship.mode
```
), refreshes Project Memory, and moves the task to
```
shipped
```
(a branch awaiting merge) or
```
done
```
. When a
```
shipped
```
task's PR is merged, run /jig cleanup
to verify the merge, delete the branch, return to base, and close the task.

为议题/缺陷/功能创建新的任务文件夹。

从用户的请求中确定简短的
```
title
```
和
```
type
```
（
```
feature
```
|
```
bug
```
|
```
chore
```
|
```
refactor
```
；默认值为
```
feature
```
）。
建议一个
```
track
```
（流程权重）：根据类型的默认值为feature/refactor→
```
full
```
，bug/chore→
```
fast
```
；当用户表示紧急时建议使用
```
hotfix
```
。在创建前确认标题、类型和track，允许用户覆盖track。

运行：

node "<SKILL_DIR>/scripts/new-task.mjs" "<title>" <type> <track>

（省略

<track>

以接受类型的默认值）。

报告创建的

taskId

、其

track

和路径（

.jig/tasks/<YYYYMMDD>/<slug>/

）。

创建的任务文件夹为
```
<taskDir>
```
（
```
.jig/tasks/<YYYYMMDD>/<slug>/
```
），处于
```
intake
```
阶段。
运行第1阶段——需求收集与澄清：遵循
```
<SKILL_DIR>/phases/intake.md
```
（传入
```
<taskDir>
```
）。这是与开发者的交互式对话。
运行第2阶段——需求定义与计划：遵循
```
<SKILL_DIR>/phases/spec-plan.md
```
（传入
```
<taskDir>
```
），直至需求定义关卡。
关卡通过后（进入
```
implement
```
阶段），运行第3阶段——实现（
```
<SKILL_DIR>/phases/implement.md
```
；根据
```
git.branch
```
创建
```
<type>/<slug>
```
功能分支）、第4阶段——测试（
```
<SKILL_DIR>/phases/test.md
```
）、第5阶段——评审（
```
<SKILL_DIR>/phases/review.md
```
，评审关卡），然后是第6阶段——发布（
```
<SKILL_DIR>/phases/ship.md
```
）。发布阶段会推送分支并打开PR或保留提交（取决于
```
ship.mode
```
），刷新项目记忆，并将任务状态改为
```
shipped
```
（分支等待合并）或
```
done
```
。当
```
shipped
```
状态的任务PR合并后，运行**
```
/jig cleanup
```
**以验证合并、删除分支、回到主分支，并关闭任务。

status

Show all tasks and their current phase/gate state.

Run:

node "<SKILL_DIR>/scripts/status.mjs"

from the repo root (

$(pwd)

Print the output verbatim.

显示所有任务及其当前阶段/关卡状态。

从仓库根目录（

$(pwd)

）运行：

node "<SKILL_DIR>/scripts/status.mjs"

。

按原样打印输出内容。

config

View, edit, and validate

.jig/config.yml

. Backed by

scripts/config.mjs

; run it from the repo root (

$(pwd)

) and relay the output. Keys are dotted paths (e.g.

gates.review

show (default):
```
node "<SKILL_DIR>/scripts/config.mjs" show
```
— print settings grouped by section with allowed values.

get:

node "<SKILL_DIR>/scripts/config.mjs" get <key>

— print one value.

set:
```
node "<SKILL_DIR>/scripts/config.mjs" set <key> <value>
```
— validate and write one key, preserving comments. On an invalid value it exits non-zero and prints the allowed set; relay that and do not retry blindly.
check:
```
node "<SKILL_DIR>/scripts/config.mjs" check
```
— static validation (
```
OK
```
/
```
WARN
```
/
```
ERR
```
+ summary); exits non-zero if any
```
ERR
```
.

When

git.track_state: true

, commit the changed

.jig/config.yml

after a

set

查看、编辑和验证

.jig/config.yml

。由

scripts/config.mjs

提供支持；从仓库根目录（

$(pwd)

）运行该脚本并传递输出。键为点分隔的路径（例如

gates.review

）。

show（默认）：
```
node "<SKILL_DIR>/scripts/config.mjs" show
```
——按分组打印设置及允许的值。

get：

node "<SKILL_DIR>/scripts/config.mjs" get <key>

——打印单个值。

set：
```
node "<SKILL_DIR>/scripts/config.mjs" set <key> <value>
```
——验证并写入单个键，保留注释。如果值无效，脚本将以非零状态退出并打印允许的取值范围；传递该信息，不要盲目重试。
check：
```
node "<SKILL_DIR>/scripts/config.mjs" check
```
——静态验证（
```
OK
```
/
```
WARN
```
/
```
ERR
```
+ 摘要）；如果存在任何
```
ERR
```
，则以非零状态退出。

当

git.track_state: true

时，在执行

set

后提交修改后的

.jig/config.yml

。

memory-refresh

Re-run Phase 0 to refresh Project Memory (e.g., after significant changes). Follow

<SKILL_DIR>/phases/understand.md

; it overwrites the memory files.

重新运行第0阶段以刷新项目记忆（例如在代码发生重大变更后）。遵循

<SKILL_DIR>/phases/understand.md

；该操作将覆盖记忆文件。

cleanup

Finish a

shipped

task after its PR was merged out-of-band.

Determine the task: if the user gave
```
<YYYYMMDD>/<slug>
```
, use it; else run
```
node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)"
```
and pick a task whose phase is
```
shipped
```
(ask the user if there are several).
Read its state:
```
node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)" "<taskId>"
```
; confirm the phase is
```
shipped
```
. If it is already
```
done
```
, tell the user the task is already cleaned up.
Follow Phase 7 — Cleanup (
```
<SKILL_DIR>/phases/cleanup.md
```
), passing the task folder.

当

shipped

状态的任务其PR已通过外部方式合并后，完成该任务的收尾工作。

确定任务：如果用户提供了
```
<YYYYMMDD>/<slug>
```
，则使用该值；否则运行
```
node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)"
```
并选择一个状态为
```
shipped
```
的任务（如果有多个，询问用户）。
读取任务状态：
```
node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)" "<taskId>"
```
；确认状态为
```
shipped
```
。如果任务已处于
```
done
```
状态，告知用户任务已完成收尾。
遵循第7阶段——收尾（
```
<SKILL_DIR>/phases/cleanup.md
```
），传入任务文件夹。

resume

Resume a paused task from its saved state.

Determine the task: if the user gave
```
<YYYYMMDD>/<slug>
```
, use it; otherwise run
```
node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)"
```
to list resumable tasks (phase ≠ done) and pick one (ask the user if there are several).

Read its state:

node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)" "<taskId>"

(prints

state.json

); note the current

phase

Recover context: read the task's
```
progress.md
```
(and
```
spec.md
```
) under
```
.jig/tasks/<taskId>/
```
.

Re-enter that phase by following its guide (passing the task folder):

intake

→

phases/intake.md

spec_plan

→

phases/spec-plan.md

implement

→

phases/implement.md

test

→

phases/test.md

review

→

phases/review.md

ship

→

phases/ship.md

shipped

→

phases/cleanup.md

. If

phase

done

, tell the user the task is already complete.

Continue the lifecycle from there.

从保存的状态恢复暂停的任务。

确定任务：如果用户提供了
```
<YYYYMMDD>/<slug>
```
，则使用该值；否则运行
```
node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)"
```
列出可恢复的任务（状态≠done）并选择一个（如果有多个，询问用户）。

读取任务状态：

node "<SKILL_DIR>/scripts/resume.mjs" "$(pwd)" "<taskId>"

（打印

state.json

）；记录当前的

phase

。

恢复上下文：读取任务文件夹
```
.jig/tasks/<taskId>/
```
下的
```
progress.md
```
（和
```
spec.md
```
）。

通过遵循对应阶段的指引（传入任务文件夹）重新进入该阶段：

intake

→

phases/intake.md

，

spec_plan

→

phases/spec-plan.md

，

implement

→

phases/implement.md

，

test

→

phases/test.md

，

review

→

phases/review.md

，

ship

→

phases/ship.md

，

shipped

→

phases/cleanup.md

。如果

phase

为

done

，告知用户任务已完成。

从该阶段继续生命周期流程。

backlog

Groom deferred work in

.jig/backlog.md

— e.g. when there's free time to burn it down. This is a maintenance flow, not a lifecycle phase; it reads and prunes the file and promotes items into normal tasks. No dedicated script.

List the open items (
```
- [ ]
```
) from
```
.jig/backlog.md
```
. If there are none, say the backlog is empty and stop.
Context-check each item (or the ones the user cares about) — index-first via
```
.jig/memory/
```
, plus the code: is it still relevant, already solved incidentally, a duplicate, or stale? Give your read per item.
Prune (with the developer's OK): check off (
```
- [x]
```
) or delete items that are already done, obsolete, or no longer wanted. Commit the pruned
```
.jig/backlog.md
```
when
```
git.track_state
```
.
Promote an item the developer picks up now: start it as a normal task — run the task flow (see
```
### task
```
) with the item text as the request. When that task reaches
```
shipped
```
/
```
done
```
, check its source item off in
```
.jig/backlog.md
```
.
Report: items pruned, item(s) promoted to tasks, and how many remain open.

梳理

.jig/backlog.md

中的延期工作——例如当有空闲时间时处理这些任务。这是一个维护流程，不属于生命周期阶段；它会读取并精简文件，并将项目转化为常规任务。没有专用脚本。

列出
```
.jig/backlog.md
```
中的未完成项（
```
- [ ]
```
）。如果没有未完成项，告知用户待办事项为空并停止操作。
检查每个项（或用户关心的项）的上下文——首先通过
```
.jig/memory/
```
索引，再结合代码：该项是否仍然相关、是否已被意外解决、是否重复或已过时？给出每个项的判断。
精简（需获得开发者许可）：勾选（
```
- [x]
```
）或删除已完成、过时或不再需要的项。当
```
git.track_state
```
为true时，提交精简后的
```
.jig/backlog.md
```
。
升级开发者现在要处理的项：将其作为常规任务启动——运行task流程（见
```
### task
```
），将项的文本作为请求。当该任务进入
```
shipped
```
/
```
done
```
状态时，在
```
.jig/backlog.md
```
中勾选对应的源项。
报告：已精简的项数、已升级为任务的项数，以及剩余的未完成项数。

Committing

.jig/

state

提交

.jig/

状态

When

.jig/

is tracked (

git.track_state: true

, chosen at init), its files — a task's

spec.md

progress.md

review.md

state.json

, refreshed

memory/*.md

backlog.md

— are committed alongside the code they describe, never left as a trailing pile of dirt:

Intake & Spec-Plan run on the base before the feature branch exists — they write
```
.jig/
```
but do not commit. Creating the branch at Implement carries those changes onto it, where they fold into the first code commit.
Implement / Test / Review stage
```
.jig/
```
in the same commit as the code/tests/fixes. When a phase has no code to ride with (a clean Review pass, Ship's memory refresh), commit the
```
.jig/
```
changes on their own — on a feature branch these still merge via the PR.
Cleanup runs on the base after the merge — commit and push (
```
git.push
```
) the small final state there directly; if the base is protected and rejects it, report and leave it.

When

.jig/

is not tracked (

git.track_state: false

, gitignored) or the repo is non-git, skip all of this —

.jig/

lives on disk and is still resumable.

当

.jig/

被跟踪时（

git.track_state: true

，在init阶段选择），其文件——任务的

spec.md

progress.md

review.md

state.json

、刷新后的

memory/*.md

、

backlog.md

——会与它们所描述的代码一起提交，永远不会留下未提交的变更：

需求收集与需求定义-计划在功能分支创建前的主分支上运行——它们会写入
```
.jig/
```
但不提交。在实现阶段创建分支时，这些变更会被带到分支上，并融入第一次代码提交。
实现/测试/评审阶段将
```
.jig/
```
的变更与代码/测试/修复一同提交到同一commit中。如果某个阶段没有对应的代码变更（例如评审通过、发布阶段的记忆刷新），则单独提交
```
.jig/
```
的变更——在功能分支上，这些变更仍会通过PR合并。
收尾在合并后的主分支上运行——直接提交并推送（
```
git.push
```
）最后的小变更；如果主分支受保护且拒绝提交，告知用户并停止操作。

当

.jig/

不被跟踪时（

git.track_state: false

，已添加到git忽略）或仓库非git仓库，跳过所有上述操作——

.jig/

仅存储在磁盘上，仍可恢复。

Notes

注意事项

All commands operate on the current working directory as the project root.
If
```
.jig/
```
does not exist when running
```
task
```
/
```
status
```
, tell the user to run
```
/jig init
```
first.

所有命令都以当前工作目录作为项目根目录。
如果运行
```
task
```
/
```
status
```
时
```
.jig/
```
目录不存在，告知用户先运行
```
/jig init
```
。

jig

Original

Translation

Jig

Jig

Dispatch

调度

init

init

task

task

status

status

config

config

memory-refresh

memory-refresh

cleanup

cleanup

resume

resume

backlog

backlog

Committing
`.jig/`
state

提交
`.jig/`
状态

Notes

注意事项

jig

Original

Translation

Jig

Jig

Dispatch

调度

init

init

task

task

status

status

config

config

memory-refresh

memory-refresh

cleanup

cleanup

resume

resume

backlog

backlog

Committing .jig/ state

提交.jig/状态

Notes

注意事项

Committing
`.jig/`
state

提交
`.jig/`
状态