@kafka0102/onespec 0.1.2

package/README.md

@@ -0,0 +1,84 @@
+# OneSpec
+
+> 中文说明见 [README-zh.md](README-zh.md)
+
+OneSpec is a Codex skill package for running an OpenSpec + Superpowers workflow.
+
+## Install
+
+Use one of these installation methods.
+
+### Via `npm install -g`
+
+Install the CLI globally:
+
+```bash
+npm install -g @kafka0102/onespec
+```
+
+Then install the bundled skills into Codex:
+
+```bash
+onespec init --scope global --yes
+```
+
+Or install into the current project only:
+
+```bash
+onespec init . --scope project --yes
+```
+
+### Via `npx`
+
+If you publish the package to npm:
+
+```bash
+npx @kafka0102/onespec init
+```
+
+### Via Repository Source
+
+Install the skill bundle directly from this repository:
+
+```bash
+npx skills add https://github.com/kafka0102/onespec/tree/main/assets/skills-en -a codex -y
+```
+
+For the Chinese bundle:
+
+```bash
+npx skills add https://github.com/kafka0102/onespec/tree/main/assets/skills -a codex -y
+```
+
+The `skills` CLI does not parse `owner/repo/tree/<ref>/...` shorthand correctly. Use the full GitHub URL above, or the shorthand form with an explicit ref such as `kafka0102/onespec/assets/skills#main`.
+
+## Use
+
+`npm install -g @kafka0102/onespec` only installs the `onespec` CLI.
+`onespec init` is the step that copies the bundled skills into Codex.
+
+After `onespec init`, restart Codex and invoke the OneSpec skills in your task.
+During active work, OneSpec keeps runtime state in `openspec/changes/<change-id>/.onespec.yaml`; archive is the point where that file is cleaned up.
+
+## Release
+
+To publish from GitHub Actions:
+
+1. Recommended: configure npm Trusted Publishing for `@kafka0102/onespec` and this GitHub repository.
+2. Fallback: if you do not use Trusted Publishing, add repository secret `NPM_TOKEN` with an npm granular access token that has publish permission for `@kafka0102/onespec` and `bypass 2FA` enabled.
+3. Update `package.json` version.
+4. Create and push a matching tag such as `v0.1.2`.
+
+```bash
+git tag v0.1.2
+git push origin main --tags
+```
+
+The workflow at `.github/workflows/publish.yml` runs on `v*` tags, checks that the tag matches `package.json`, runs `npm test`, previews the published package, and then publishes to npm.
+
+It now supports both modes:
+
+1. Trusted Publishing if no `NPM_TOKEN` secret is configured.
+2. Token-based publishing if `NPM_TOKEN` is present.
+
+If npm returns `E403` with a message about 2FA or granular access tokens, the token is not valid for publishing under npm's current policy. Replace it with a granular token that can bypass 2FA, or switch the package to Trusted Publishing.

package/assets/skills/onespec/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: onespec
+description: 当用户需要用 OpenSpec 与 Superpowers 管理完整 AI Coding 变更生命周期，或不确定应进入设计、执行还是归档阶段时使用。
+---
+
+# OneSpec 工作流
+
+OneSpec 是组合路由 Skill。它只负责恢复状态、判断阶段并切换到 `onespec-design`、`onespec-execute` 或 `onespec-archive`；具体阶段规则以对应子 Skill 为准。
+
+开始时说明：
+
+> 我正在使用 `onespec` 工作流。
+
+## 恢复优先
+
+每次进入先检查状态，不依赖聊天历史：
+
+```bash
+ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
+. "$ONESPEC_ENV"
+"$ONESPEC_BASH" "$ONESPEC_STATE" list
+```
+
+如果发现相关 change，运行：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+运行时状态文件是 `openspec/changes/<change-id>/.onespec.yaml`。handoff 摘要、哈希和 touched files 都写回这里；archive 前保留，archive 后删除。
+`recover` 的输出是执行合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_gate` 与 `allowed_actions`，再决定是否继续。
+
+## 阶段路由
+
+先判断当前请求属于哪一类：
+
+- `propose`：定义新 change、梳理范围、生成 `proposal.md`、`design.md`、`tasks.md` 与 spec delta。使用 `onespec-design`。
+- `apply`：实现已批准 change、继续已有 change、生成或恢复 Superpowers plan、回填 OpenSpec 状态。使用 `onespec-execute`。
+- `review-closeout`：用户评审、处理反馈、删除 worktree 或执行归档。使用 `onespec-archive`。
+
+如果用户意图不清，只问一个简短问题，不要同时问多个。
+
+默认意图映射：
+
+- 用户说“新需求”、“设计一下”、“写 proposal / spec”、“定义 change”时，进入 `onespec-design`。
+- 用户说“开始实现”、“执行这个 change”、“apply 这个 proposal / change”、“继续做这个 change”、“开始 coding / 开发”、“make plan”时，进入 `onespec-execute`。如果 proposal 尚未批准，`onespec-execute` 必须停止并转回 `onespec-design` 的批准 gate。
+- 用户说“review”、“收尾”、“归档”、“archive”、“删除 worktree”时，进入 `onespec-archive`。
+
+## 共同约束
+
+- OpenSpec 负责“要做什么”、formal artifacts、approval gate、spec delta 与归档语义。
+- Superpowers 负责高歧义需求澄清、实现计划、TDD、分任务 review 与工程执行质量。
+- 不要询问变更名称。根据任务自动生成简短短横线命名的 `change-id`，如冲突则追加数字。
+- 读取最少必要上下文：`openspec/config.yaml`、`openspec/project.md`、相关 `openspec/specs/**`、项目入口文档、当前分支和工作区状态。
+- 只问会改变 proposal、执行路径、分支处理或归档结果的问题。
+- 当阶段规则冲突时，以当前阶段子 Skill 的停止条件为准。
+- 每个阶段子 Skill 定义了强制暂停 gate（如 `onespec-execute` 的"实现完成 Gate"、`onespec-design` 的"批准 Gate"）。路由进入下一阶段前，必须确认上一阶段的 gate 已完成。如果 gate 未完成就试图进入下一阶段，必须拒绝并指出缺失步骤。
+- 如果 `recover` 已经给出 `next_skill`，默认先按它恢复；只有在用户当前请求明确改变阶段，且上一阶段的 gate 已完成时，才允许覆盖该恢复结果。

package/assets/skills/onespec/scripts/onespec-closeout.sh

@@ -0,0 +1,404 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+die() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+valid_change() {
+  local change="$1"
+  [[ -n "$change" ]] || die "change name is required"
+  [[ "$change" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || die "invalid change name: $change"
+  [[ "$change" != *".."* ]] || die "change name must not contain '..'"
+}
+
+change_dir() {
+  local change="$1"
+  if [ -d "openspec/changes/$change" ]; then
+    printf 'openspec/changes/%s\n' "$change"
+  elif [ -d "openspec/changes/archive/$change" ]; then
+    printf 'openspec/changes/archive/%s\n' "$change"
+  else
+    printf 'openspec/changes/%s\n' "$change"
+  fi
+}
+
+state_file() {
+  local change="$1"
+  printf '%s/.onespec.yaml\n' "$(change_dir "$change")"
+}
+
+field_value() {
+  local file="$1"
+  local key="$2"
+  awk -F ': *' -v key="$key" '$1 == key { sub(/^[^:]+: */, ""); print; found=1; exit } END { if (!found) exit 0 }' "$file" 2>/dev/null
+}
+
+get_state_value() {
+  local change="$1"
+  local key="$2"
+  local file
+  file="$(state_file "$change")"
+  [ -f "$file" ] || die "state not found: $file"
+  field_value "$file" "$key"
+}
+
+ensure_git_repo() {
+  git rev-parse --show-toplevel >/dev/null 2>&1 || die "current directory is not inside a git repository"
+}
+
+git_common_dir() {
+  git rev-parse --git-common-dir
+}
+
+current_branch() {
+  local branch
+  branch="$(git branch --show-current 2>/dev/null || true)"
+  printf '%s\n' "${branch:-detached}"
+}
+
+current_workspace_path() {
+  pwd -P
+}
+
+canonicalize_path() {
+  local input="$1"
+  if [ -z "$input" ] || [ "$input" = "unknown" ] || [ ! -d "$input" ]; then
+    printf '%s\n' "$input"
+    return 0
+  fi
+  (
+    cd "$input"
+    pwd -P
+  )
+}
+
+selected_actions_csv() {
+  local joined=""
+  local item
+  for item in "$@"; do
+    if [ -n "$joined" ]; then
+      joined="${joined},${item}"
+    else
+      joined="$item"
+    fi
+  done
+  printf '%s\n' "$joined"
+}
+
+state_destination_in_origin() {
+  local change="$1"
+  local origin_path
+  origin_path="$(canonicalize_path "$(get_state_value "$change" origin_workspace_path)")"
+  [ -n "$origin_path" ] || die "origin workspace path is empty"
+  [ "$origin_path" != "unknown" ] || die "origin workspace path is unknown"
+  printf '%s/openspec/changes/%s/.onespec.yaml\n' "$origin_path" "$change"
+}
+
+normalize_action() {
+  case "$1" in
+    delete-worktree|drop-worktree|cleanup-worktree)
+      echo "delete-worktree"
+      ;;
+    archive|run-archive)
+      echo "archive"
+      ;;
+    "")
+      echo ""
+      ;;
+    *)
+      die "unsupported closeout action: $1"
+      ;;
+  esac
+}
+
+temporary_worktree_status() {
+  local change="$1"
+  local origin_branch origin_path origin_mode current_path current_head temporary reason
+
+  origin_branch="$(get_state_value "$change" origin_branch)"
+  origin_path="$(get_state_value "$change" origin_workspace_path)"
+  origin_mode="$(get_state_value "$change" origin_workspace_mode)"
+  origin_path="$(canonicalize_path "$origin_path")"
+  current_path="$(current_workspace_path)"
+  current_head="$(current_branch)"
+  temporary="false"
+  reason="none"
+
+  if [ "$origin_mode" = "worktree" ]; then
+    temporary="true"
+    reason="origin-workspace-mode"
+  fi
+  if [ -n "$origin_path" ] && [ "$origin_path" != "unknown" ] && [ "$origin_path" != "$current_path" ]; then
+    temporary="true"
+    reason="workspace-path-differs"
+  fi
+  if [ -n "$origin_branch" ] && [ "$origin_branch" != "unknown" ] && [ "$origin_branch" != "$current_head" ]; then
+    temporary="true"
+    if [ "$reason" = "none" ]; then
+      reason="branch-differs"
+    fi
+  fi
+
+  cat <<EOF
+current_branch: $current_head
+current_workspace_path: $current_path
+origin_branch: $origin_branch
+origin_workspace_path: $origin_path
+origin_workspace_mode: $origin_mode
+temporary_worktree: $temporary
+temporary_worktree_reason: $reason
+EOF
+}
+
+recommended_combination() {
+  local change="$1"
+  local worktree_probe temporary recommendation reason
+
+  worktree_probe="$(temporary_worktree_status "$change")"
+  temporary="$(printf '%s\n' "$worktree_probe" | awk -F ': ' '$1 == "temporary_worktree" { print $2 }')"
+
+  recommendation="none"
+  reason="review-only"
+
+  if [ "$temporary" = "true" ]; then
+    recommendation="delete-worktree,archive"
+    reason="temporary-worktree-can-be-cleaned-before-or-with-archive"
+  else
+    recommendation="archive"
+    reason="already-on-target-path"
+  fi
+
+  cat <<EOF
+recommended_actions: $recommendation
+recommended_reason: $reason
+EOF
+}
+
+cmd_inspect() {
+  local change="$1"
+  valid_change "$change"
+  ensure_git_repo
+
+  temporary_worktree_status "$change"
+  cat <<'EOF'
+cleanup_local_branch_after_merge: true
+cleanup_local_worktree_after_merge: true
+cleanup_remote_branch_after_merge: false
+cleanup_local_branch_after_preserve: false
+cleanup_local_worktree_after_preserve: false
+EOF
+  recommended_combination "$change"
+}
+
+cmd_recommend_actions() {
+  local change="$1"
+  valid_change "$change"
+  ensure_git_repo
+  cmd_inspect "$change"
+}
+
+cmd_validate_actions() {
+  local change="$1"
+  shift
+  valid_change "$change"
+  ensure_git_repo
+
+  local -a selected=()
+  local action normalized
+  local already_selected
+  local has_delete_worktree="false"
+  local has_archive="false"
+  local current_head origin_branch temporary valid message
+
+  for action in "$@"; do
+    normalized="$(normalize_action "$action")"
+    [ -n "$normalized" ] || continue
+    already_selected="false"
+    for action in "${selected[@]:-}"; do
+      if [ "$action" = "$normalized" ]; then
+        already_selected="true"
+        break
+      fi
+    done
+    if [ "$already_selected" != "true" ]; then
+      selected+=("$normalized")
+    fi
+  done
+
+  for action in "${selected[@]}"; do
+    case "$action" in
+      delete-worktree) has_delete_worktree="true" ;;
+      archive) has_archive="true" ;;
+    esac
+  done
+
+  valid="true"
+  message="可以执行所选收尾动作。"
+  current_head="$(current_branch)"
+  origin_branch="$(get_state_value "$change" origin_branch)"
+  temporary="$(temporary_worktree_status "$change" | awk -F ': ' '$1 == "temporary_worktree" { print $2 }')"
+
+  if [ "$has_delete_worktree" = "true" ] && [ "$temporary" != "true" ]; then
+    valid="false"
+    message="不能删除 worktree：当前不在临时 worktree。"
+  elif [ "$has_archive" = "true" ] && [ "$has_delete_worktree" = "true" ]; then
+    message="允许先删除临时 worktree，再继续归档。"
+  elif [ "$has_delete_worktree" = "true" ] && [ "$has_archive" != "true" ]; then
+    message="允许仅删除临时 worktree；之后仍可单独执行归档。"
+  elif [ "$has_archive" = "true" ] && [ "$has_delete_worktree" != "true" ]; then
+    if [ "$temporary" = "true" ] || { [ "$origin_branch" != "unknown" ] && [ "$current_head" != "$origin_branch" ]; }; then
+      valid="false"
+      message="不能单独执行归档：当前代码尚未确认位于目标分支。"
+    else
+      message="允许单独执行归档：当前已在目标分支路径上。"
+    fi
+  elif [ "${#selected[@]}" -eq 0 ]; then
+    message="本次不删除 worktree 或归档；之后仍可再次进入收尾。"
+  fi
+
+  cat <<EOF
+selected_actions: $(selected_actions_csv "${selected[@]}")
+valid: $valid
+message: $message
+temporary_worktree: $temporary
+current_branch: $current_head
+origin_branch: $origin_branch
+EOF
+}
+
+run_archive_command() {
+  local change="$1"
+  local archive_bin="${ONESPEC_ARCHIVE_BIN:-openspec}"
+  "$archive_bin" archive "$change" --yes
+}
+
+preserve_runtime_state_in_origin() {
+  local change="$1"
+  local source_file destination_file destination_dir
+  source_file="$(state_file "$change")"
+  destination_file="$(state_destination_in_origin "$change")"
+  destination_dir="$(dirname "$destination_file")"
+
+  mkdir -p "$destination_dir"
+  cp "$source_file" "$destination_file"
+  printf '%s\n' "$destination_file"
+}
+
+delete_current_worktree() {
+  local current_path common_dir
+  current_path="$(current_workspace_path)"
+  common_dir="$(git_common_dir)"
+  git --git-dir="$common_dir" worktree remove --force "$current_path"
+  printf '%s\n' "$current_path"
+}
+
+cmd_run_actions() {
+  local change="$1"
+  shift
+  valid_change "$change"
+  ensure_git_repo
+
+  local validation selected valid archive_selected delete_selected preserved_state removed_worktree
+  validation="$(cmd_validate_actions "$change" "$@")"
+  selected="$(printf '%s\n' "$validation" | awk -F ': ' '$1 == "selected_actions" { print $2 }')"
+  valid="$(printf '%s\n' "$validation" | awk -F ': ' '$1 == "valid" { print $2 }')"
+
+  [ "$valid" = "true" ] || die "$(printf '%s\n' "$validation" | awk -F ': ' '$1 == "message" { print $2 }')"
+  [ -n "$selected" ] || die "run-actions requires at least one closeout action"
+
+  archive_selected="false"
+  delete_selected="false"
+  if printf '%s\n' "$selected" | grep -Eq '(^|,)archive($|,)'; then
+    archive_selected="true"
+  fi
+  if printf '%s\n' "$selected" | grep -Eq '(^|,)delete-worktree($|,)'; then
+    delete_selected="true"
+  fi
+
+  preserved_state=""
+  removed_worktree=""
+
+  # Safe order: archive first, then delete the temporary worktree.
+  if [ "$archive_selected" = "true" ]; then
+    run_archive_command "$change"
+    local script_dir
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+    "${BASH:-bash}" "$script_dir/onespec-state.sh" set "$change" phase archived
+    "${BASH:-bash}" "$script_dir/onespec-state.sh" set "$change" archive archived
+    "${BASH:-bash}" "$script_dir/onespec-closeout.sh" cleanup-runtime "$change" >/dev/null
+  fi
+
+  if [ "$delete_selected" = "true" ]; then
+    if [ "$archive_selected" != "true" ]; then
+      local script_dir
+      script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+      "${BASH:-bash}" "$script_dir/onespec-state.sh" set "$change" phase done
+      "${BASH:-bash}" "$script_dir/onespec-state.sh" set "$change" archive skipped
+      preserved_state="$(preserve_runtime_state_in_origin "$change")"
+    fi
+    removed_worktree="$(delete_current_worktree)"
+  fi
+
+  cat <<EOF
+selected_actions: $selected
+archive_executed: $archive_selected
+worktree_deleted: $delete_selected
+preserved_state_file: ${preserved_state:-none}
+deleted_worktree_path: ${removed_worktree:-none}
+EOF
+}
+
+cmd_cleanup_runtime() {
+  local change="$1"
+  valid_change "$change"
+
+  local file
+  file="$(state_file "$change")"
+  if [ -f "$file" ]; then
+    rm -f "$file"
+    echo "$file"
+  fi
+}
+
+usage() {
+  cat <<'EOF'
+用法:
+  onespec-closeout.sh inspect <change>
+  onespec-closeout.sh recommend-actions <change>
+  onespec-closeout.sh validate-actions <change> [delete-worktree] [archive]
+  onespec-closeout.sh run-actions <change> [delete-worktree] [archive]
+  onespec-closeout.sh cleanup-runtime <change>
+EOF
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  inspect)
+    [ "$#" -eq 2 ] || { usage; exit 2; }
+    cmd_inspect "$2"
+    ;;
+  recommend-actions)
+    [ "$#" -eq 2 ] || { usage; exit 2; }
+    cmd_recommend_actions "$2"
+    ;;
+  validate-actions)
+    [ "$#" -ge 2 ] || { usage; exit 2; }
+    shift
+    cmd_validate_actions "$@"
+    ;;
+  run-actions)
+    [ "$#" -ge 3 ] || { usage; exit 2; }
+    shift
+    cmd_run_actions "$@"
+    ;;
+  cleanup-runtime)
+    [ "$#" -eq 2 ] || { usage; exit 2; }
+    cmd_cleanup_runtime "$2"
+    ;;
+  *)
+    usage
+    exit 2
+    ;;
+esac