@pixelcraft-tw/spec (pxs)

Spec-driven development CLI for Claude Code. Write a spec, refine a plan, implement task by task — all powered by AI.

@pixelcraft-tw/spec 是一套為 Claude Code 設計的規格驅動開發 CLI。撰寫規格、拆解計畫、逐步實作，全程 AI 驅動。

Supported backends: Claude Code

---

Installation / 安裝

npm install -g @pixelcraft-tw/spec

Quick Start / 快速開始

# 1. Initialize workflow in your project / 初始化工作流
pxs init

# 2. Create a spec / 建立規格
pxs new login-feature --desc "Add JWT login endpoint"

# 3. Refine spec into implementation plan / 拆解為實作計畫
pxs refine login-feature

# 4. Implement task by task / 逐步實作
pxs implement login-feature

# 5. Check status / 查看狀態
pxs status login-feature

Commands / 指令

pxs init

Initialize .workflow/ directory and Claude Code slash commands for your project.

在專案中初始化 .workflow/ 目錄與 Claude Code slash commands。

Option	Description
--force	Overwrite existing .workflow/ / 覆蓋現有目錄

pxs new <name>

Create a new spec file under .workflow/specs/.

建立新的規格檔案。

Option	Description
--desc <text>	Generate spec from text description / 從文字描述產生規格
--jira <tickets...>	Import from Jira tickets via MCP / 透過 Jira MCP 匯入 ticket 內容
-i, --interactive	Interactive Q&A mode / 互動問答模式

pxs refine <name>

Refine spec and decompose into a step-by-step implementation plan.

精煉規格並拆解為逐步實作計畫。

Option	Description
--skip-clarify	Skip requirement clarification / 跳過需求釐清
--clarify <n>	Max clarification rounds / 最大釐清輪數
@agent /skill	Pass agents or skills to assist / 指定 agent 或 skill 協助

pxs clarify <name>

Run requirement clarification on a spec independently.

獨立執行需求釐清。

pxs implement <name>

Implement code task by task with AI. Each task goes through: implement → commit → test (optional) → AI review → user approval.

AI 逐步實作。每個 task 流程：實作 → commit → 測試（可選）→ AI review → 使用者審核。

After all tasks complete, a final branch code review runs automatically against the full diff, spec, and plan.

所有 task 完成後，自動執行整個 branch 的完整 code review。

Option	Description
--skip-review	Skip final branch code review / 跳過最終 code review
@agent /skill	Pass agents or skills to assist review / 指定 agent 或 skill 協助 review

Test strategies / 測試策略:

Flag	Behavior
--test tdd	TDD: write failing tests → implement → pass → refactor
--test intg	Post-hoc integration tests / 整合測試
--test tdd intg	TDD + integration tests
--test	Post-hoc unit tests / 單元測試
(none)	No tests / 不產生測試

pxs review <name>

View review records.

查看 review 紀錄。

Option	Description
--step <n>	View specific task review / 查看特定 task 的 review
--summary	Summary overview of all tasks / 所有 task 的摘要
(default)	Shows final branch review if completed, otherwise latest task review / 預設顯示 final review 或最新的 task review

pxs status [name]

View workflow status. Without <name>, lists all features.

查看工作流狀態。不帶 <name> 則列出所有 feature。

pxs reset <name>

Reset a feature's phase when state gets stuck. Clears downstream state (tasks, session) as appropriate.

重置 feature 的 phase。當 state 卡住時使用，會清除對應的下游狀態。

Option	Description
--to <phase>	Target phase (default: spec_created) / 目標 phase

Valid targets: spec_created, clarifying, spec_approved, plan_pending_approval, ready_to_implement

pxs diff <name>

Show remaining tasks from the implementation plan, grouped by done/in-progress/remaining with progress percentage.

顯示實作計畫中各 task 的完成狀態，分為已完成、進行中、待做，並顯示進度百分比。

Workflow / 工作流程

pxs init → pxs new → pxs refine → pxs implement → merge
                         │                │
                     pxs clarify      pxs diff (check progress)
                     (optional)       pxs reset (unstick)

implement 流程：

  Task 1 → commit → [test] → AI review → approve/skip
  Task 2 → commit → [test] → AI review → approve/skip
  ...
  All tasks complete
       ↓
  Final Code Review (full branch diff vs spec + plan)
       ↓
  merge / squash-merge / keep-branch

Claude Code Integration

After pxs init, the following slash commands are available in Claude Code:

執行 pxs init 後，可在 Claude Code 中使用以下 slash commands：

Slash Command	Description
/pxs.new	Create a new spec / 建立規格
/pxs.refine	Refine spec into plan / 拆解計畫
/pxs.clarify	Clarify requirements / 釐清需求
/pxs.implement	Implement task by task / 逐步實作
/pxs.review	View reviews / 查看 review
/pxs.status	Check status / 查看狀態
/pxs.reset	Reset feature phase / 重置 feature 狀態
/pxs.diff	Show task progress / 查看 task 進度

Project Structure / 專案結構

.workflow/
├── state.yaml          # Workflow state / 工作流狀態
├── config.yaml         # Project config / 專案設定
├── specs/              # Feature specs / 功能規格
├── plans/              # Implementation plans / 實作計畫
├── reviews/            # AI review records / AI review 紀錄
└── prompts/            # Prompt templates / Prompt 模板

License

MIT