From b13091b2aba9fdcf25226d6c82298eca74897a98 Mon Sep 17 00:00:00 2001 From: Haoyu Zhang Date: Thu, 16 Jul 2026 14:28:31 -0600 Subject: [PATCH 01/15] [openspec]: Add refactoring initiative proposals (8 change specs) Deep-review-driven improvement plan across code quality, docs, testing, benchmarking, dependencies, and optimization. Each change carries a proposal, design, delta specs, and task breakdown. --- .claude/commands/opsx/apply.md | 155 ++++++++++ .claude/commands/opsx/archive.md | 160 ++++++++++ .claude/commands/opsx/explore.md | 172 +++++++++++ .claude/commands/opsx/propose.md | 107 +++++++ .claude/commands/opsx/sync.md | 143 +++++++++ .claude/skills/openspec-apply-change/SKILL.md | 159 ++++++++++ .../skills/openspec-archive-change/SKILL.md | 117 +++++++ .claude/skills/openspec-explore/SKILL.md | 287 ++++++++++++++++++ .claude/skills/openspec-propose/SKILL.md | 111 +++++++ .claude/skills/openspec-sync-specs/SKILL.md | 147 +++++++++ .../changes/add-lint-tooling/.openspec.yaml | 2 + openspec/changes/add-lint-tooling/design.md | 38 +++ openspec/changes/add-lint-tooling/proposal.md | 29 ++ .../specs/code-linting/spec.md | 35 +++ .../specs/continuous-integration/spec.md | 22 ++ openspec/changes/add-lint-tooling/tasks.md | 30 ++ .../changes/cleanup-dead-code/.openspec.yaml | 2 + openspec/changes/cleanup-dead-code/design.md | 39 +++ .../changes/cleanup-dead-code/proposal.md | 30 ++ .../specs/repo-hygiene/spec.md | 30 ++ .../specs/wheel-packaging/spec.md | 17 ++ openspec/changes/cleanup-dead-code/tasks.md | 34 +++ .../changes/extract-benchmarks/.openspec.yaml | 2 + openspec/changes/extract-benchmarks/design.md | 39 +++ .../changes/extract-benchmarks/proposal.md | 32 ++ .../specs/benchmark-cli/spec.md | 44 +++ openspec/changes/extract-benchmarks/tasks.md | 23 ++ .../fix-cuda-correctness/.openspec.yaml | 2 + .../changes/fix-cuda-correctness/design.md | 40 +++ .../changes/fix-cuda-correctness/proposal.md | 33 ++ .../specs/cuda-error-reporting/spec.md | 26 ++ .../specs/pvalue-computation/spec.md | 48 +++ .../changes/fix-cuda-correctness/tasks.md | 36 +++ openspec/changes/improve-docs/.openspec.yaml | 2 + openspec/changes/improve-docs/design.md | 40 +++ openspec/changes/improve-docs/proposal.md | 30 ++ .../specs/code-documentation/spec.md | 21 ++ .../specs/user-documentation/spec.md | 35 +++ openspec/changes/improve-docs/tasks.md | 34 +++ .../optimization-backlog/.openspec.yaml | 2 + .../changes/optimization-backlog/design.md | 35 +++ .../changes/optimization-backlog/proposal.md | 31 ++ .../specs/performance-profiling/spec.md | 26 ++ .../changes/optimization-backlog/tasks.md | 16 + .../changes/restructure-tests/.openspec.yaml | 2 + openspec/changes/restructure-tests/design.md | 37 +++ .../changes/restructure-tests/proposal.md | 29 ++ .../specs/test-suite/spec.md | 58 ++++ openspec/changes/restructure-tests/tasks.md | 36 +++ .../upgrade-dependencies/.openspec.yaml | 2 + .../changes/upgrade-dependencies/design.md | 41 +++ .../changes/upgrade-dependencies/proposal.md | 29 ++ .../specs/build-distribution/spec.md | 39 +++ .../changes/upgrade-dependencies/tasks.md | 27 ++ 54 files changed, 2763 insertions(+) create mode 100644 .claude/commands/opsx/apply.md create mode 100644 .claude/commands/opsx/archive.md create mode 100644 .claude/commands/opsx/explore.md create mode 100644 .claude/commands/opsx/propose.md create mode 100644 .claude/commands/opsx/sync.md create mode 100644 .claude/skills/openspec-apply-change/SKILL.md create mode 100644 .claude/skills/openspec-archive-change/SKILL.md create mode 100644 .claude/skills/openspec-explore/SKILL.md create mode 100644 .claude/skills/openspec-propose/SKILL.md create mode 100644 .claude/skills/openspec-sync-specs/SKILL.md create mode 100644 openspec/changes/add-lint-tooling/.openspec.yaml create mode 100644 openspec/changes/add-lint-tooling/design.md create mode 100644 openspec/changes/add-lint-tooling/proposal.md create mode 100644 openspec/changes/add-lint-tooling/specs/code-linting/spec.md create mode 100644 openspec/changes/add-lint-tooling/specs/continuous-integration/spec.md create mode 100644 openspec/changes/add-lint-tooling/tasks.md create mode 100644 openspec/changes/cleanup-dead-code/.openspec.yaml create mode 100644 openspec/changes/cleanup-dead-code/design.md create mode 100644 openspec/changes/cleanup-dead-code/proposal.md create mode 100644 openspec/changes/cleanup-dead-code/specs/repo-hygiene/spec.md create mode 100644 openspec/changes/cleanup-dead-code/specs/wheel-packaging/spec.md create mode 100644 openspec/changes/cleanup-dead-code/tasks.md create mode 100644 openspec/changes/extract-benchmarks/.openspec.yaml create mode 100644 openspec/changes/extract-benchmarks/design.md create mode 100644 openspec/changes/extract-benchmarks/proposal.md create mode 100644 openspec/changes/extract-benchmarks/specs/benchmark-cli/spec.md create mode 100644 openspec/changes/extract-benchmarks/tasks.md create mode 100644 openspec/changes/fix-cuda-correctness/.openspec.yaml create mode 100644 openspec/changes/fix-cuda-correctness/design.md create mode 100644 openspec/changes/fix-cuda-correctness/proposal.md create mode 100644 openspec/changes/fix-cuda-correctness/specs/cuda-error-reporting/spec.md create mode 100644 openspec/changes/fix-cuda-correctness/specs/pvalue-computation/spec.md create mode 100644 openspec/changes/fix-cuda-correctness/tasks.md create mode 100644 openspec/changes/improve-docs/.openspec.yaml create mode 100644 openspec/changes/improve-docs/design.md create mode 100644 openspec/changes/improve-docs/proposal.md create mode 100644 openspec/changes/improve-docs/specs/code-documentation/spec.md create mode 100644 openspec/changes/improve-docs/specs/user-documentation/spec.md create mode 100644 openspec/changes/improve-docs/tasks.md create mode 100644 openspec/changes/optimization-backlog/.openspec.yaml create mode 100644 openspec/changes/optimization-backlog/design.md create mode 100644 openspec/changes/optimization-backlog/proposal.md create mode 100644 openspec/changes/optimization-backlog/specs/performance-profiling/spec.md create mode 100644 openspec/changes/optimization-backlog/tasks.md create mode 100644 openspec/changes/restructure-tests/.openspec.yaml create mode 100644 openspec/changes/restructure-tests/design.md create mode 100644 openspec/changes/restructure-tests/proposal.md create mode 100644 openspec/changes/restructure-tests/specs/test-suite/spec.md create mode 100644 openspec/changes/restructure-tests/tasks.md create mode 100644 openspec/changes/upgrade-dependencies/.openspec.yaml create mode 100644 openspec/changes/upgrade-dependencies/design.md create mode 100644 openspec/changes/upgrade-dependencies/proposal.md create mode 100644 openspec/changes/upgrade-dependencies/specs/build-distribution/spec.md create mode 100644 openspec/changes/upgrade-dependencies/tasks.md diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md new file mode 100644 index 00000000..45003f8f --- /dev/null +++ b/.claude/commands/opsx/apply.md @@ -0,0 +1,155 @@ +--- +name: "OPSX: Apply" +description: Implement tasks from an OpenSpec change (Experimental) +category: Workflow +tags: [workflow, artifacts, experimental] +--- + +Implement tasks from an OpenSpec change. + +**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. + +**Steps** + +1. **Select the change** + + If a name is provided, use it. Otherwise: + - Infer from conversation context if the user mentioned a change + - Auto-select if only one active change exists + - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select + + Always announce: "Using change: " and how to override (e.g., `/opsx:apply `). + +2. **Check status to understand the schema** + ```bash + openspec status --change "" --json + ``` + Parse the JSON to understand: + - `schemaName`: The workflow being used (e.g., "spec-driven") + - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints + - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) + +3. **Get apply instructions** + + ```bash + openspec instructions apply --change "" --json + ``` + + This returns: + - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema) + - Progress (total, complete, remaining) + - Task list with status + - Dynamic instruction based on current state + + **Handle states:** + - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` + - If `state: "all_done"`: congratulate, suggest archive + - Otherwise: proceed to implementation + + **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files. + +4. **Read context files** + + Read every file path listed under `contextFiles` from the apply instructions output. + The files depend on the schema being used: + - **spec-driven**: proposal, specs, design, tasks + - Other schemas: follow the contextFiles from CLI output + +5. **Show current progress** + + Display: + - Schema being used + - Progress: "N/M tasks complete" + - Remaining tasks overview + - Dynamic instruction from CLI + +6. **Implement tasks (loop until done or blocked)** + + For each pending task: + - Show which task is being worked on + - Make the code changes required + - Keep changes minimal and focused + - Mark task complete in the tasks file: `- [ ]` → `- [x]` + - Continue to next task + + **Pause if:** + - Task is unclear → ask for clarification + - Implementation reveals a design issue → suggest updating artifacts + - Error or blocker encountered → report and wait for guidance + - User interrupts + +7. **On completion or pause, show status** + + Display: + - Tasks completed this session + - Overall progress: "N/M tasks complete" + - If all done: suggest archive + - If paused: explain why and wait for guidance + +**Output During Implementation** + +``` +## Implementing: (schema: ) + +Working on task 3/7: +[...implementation happening...] +✓ Task complete + +Working on task 4/7: +[...implementation happening...] +✓ Task complete +``` + +**Output On Completion** + +``` +## Implementation Complete + +**Change:** +**Schema:** +**Progress:** 7/7 tasks complete ✓ + +### Completed This Session +- [x] Task 1 +- [x] Task 2 +... + +All tasks complete! You can archive this change with `/opsx:archive`. +``` + +**Output On Pause (Issue Encountered)** + +``` +## Implementation Paused + +**Change:** +**Schema:** +**Progress:** 4/7 tasks complete + +### Issue Encountered + + +**Options:** +1.