From 852883603397c4ef9ae46d566e3269ccb55346a7 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Thu, 23 Apr 2026 02:36:41 +0800
Subject: [PATCH 01/10] feat: integrate OpenSpec for spec-driven development

- Add OpenSpec configuration and directory structure
- Migrate existing specs to domain-based organization:
  - sorting/webgpu-sorting.md (core sorting requirements)
  - quality/project-enhancement.md (CI/CD, code quality)
  - _archived/core-architecture-v1.md (historical RFC)
- Add custom templates for proposals, specs, and tasks
- Configure Claude Code integration with /opsx: commands
- Update AGENTS.md with OpenSpec workflow documentation
- Remove legacy specs/ directory

Breaking change: specs/ directory moved to openspec/specs/
---
 .claude/commands/opsx/apply.md                | 155 +++++++++
 .claude/commands/opsx/archive.md              | 159 ++++++++++
 .claude/commands/opsx/explore.md              | 181 +++++++++++
 .claude/commands/opsx/propose.md              | 114 +++++++
 .claude/skills/openspec-apply-change/SKILL.md | 159 ++++++++++
 .../skills/openspec-archive-change/SKILL.md   | 116 +++++++
 .claude/skills/openspec-explore/SKILL.md      | 299 ++++++++++++++++++
 .claude/skills/openspec-propose/SKILL.md      | 118 +++++++
 AGENTS.md                                     | 147 +++++++--
 openspec/.templates/design.md                 |  45 +++
 openspec/.templates/proposal.md               |  61 ++++
 openspec/.templates/spec.md                   |  61 ++++
 openspec/.templates/tasks.md                  |  73 +++++
 openspec/archive/.gitkeep                     |   0
 openspec/changes/.gitkeep                     |   0
 openspec/config.yaml                          |  85 +++++
 openspec/specs/_archived/README.md            |  31 ++
 .../specs/_archived/core-architecture-v1.md   |   0
 openspec/specs/infrastructure/README.md       |  22 ++
 openspec/specs/quality/README.md              |  23 ++
 .../specs/quality/project-enhancement.md      |   0
 openspec/specs/sorting/README.md              |  23 ++
 .../specs/sorting/webgpu-sorting.md           |   0
 specs/README.md                               | 112 -------
 24 files changed, 1838 insertions(+), 146 deletions(-)
 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/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 openspec/.templates/design.md
 create mode 100644 openspec/.templates/proposal.md
 create mode 100644 openspec/.templates/spec.md
 create mode 100644 openspec/.templates/tasks.md
 create mode 100644 openspec/archive/.gitkeep
 create mode 100644 openspec/changes/.gitkeep
 create mode 100644 openspec/config.yaml
 create mode 100644 openspec/specs/_archived/README.md
 rename specs/rfc/0001-core-architecture.md => openspec/specs/_archived/core-architecture-v1.md (100%)
 create mode 100644 openspec/specs/infrastructure/README.md
 create mode 100644 openspec/specs/quality/README.md
 rename specs/product/0002-project-quality-enhancement.md => openspec/specs/quality/project-enhancement.md (100%)
 create mode 100644 openspec/specs/sorting/README.md
 rename specs/product/0001-webgpu-sorting.md => openspec/specs/sorting/webgpu-sorting.md (100%)
 delete mode 100644 specs/README.md

diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
new file mode 100644
index 0000000..9bd5b10
--- /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: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --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
+
+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: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**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:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
new file mode 100644
index 0000000..ceeb937
--- /dev/null
+++ b/.claude/commands/opsx/archive.md
@@ -0,0 +1,159 @@
+---
+name: 'OPSX: Archive'
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive 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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
new file mode 100644
index 0000000..41f331b
--- /dev/null
+++ b/.claude/commands/opsx/explore.md
@@ -0,0 +1,181 @@
+---
+name: 'OPSX: Explore'
+description: 'Enter explore mode - think through ideas, investigate problems, clarify requirements'
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+
+```bash
+openspec list --json
+```
+
+This tells you:
+
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type               | Where to Capture             |
+   | -------------------------- | ---------------------------- |
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed        | `specs/<capability>/spec.md` |
+   | Design decision made       | `design.md`                  |
+   | Scope changed              | `proposal.md`                |
+   | New work identified        | `tasks.md`                   |
+   | Assumption invalidated     | Relevant artifact            |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md
new file mode 100644
index 0000000..2df4c24
--- /dev/null
+++ b/.claude/commands/opsx/propose.md
@@ -0,0 +1,114 @@
+---
+name: 'OPSX: Propose'
+description: Propose a new change - create it and generate all artifacts in one step
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+
+   ```bash
+   openspec new change "<name>"
+   ```
+
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+   - Get instructions:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - The instructions JSON includes:
+     - `context`: Project background (constraints for you - do NOT include in output)
+     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+     - `template`: The structure to use for your output file
+     - `instruction`: Schema-specific guidance for this artifact type
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - Read any completed dependency files for context
+   - Create the artifact file using `template` as the structure
+   - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+   - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+   - After creating each artifact, re-run `openspec status --change "<name>" --json`
+   - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+   - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+   - Use **AskUserQuestion tool** to clarify
+   - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000..70a5893
--- /dev/null
+++ b/.claude/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,159 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: '1.0'
+  generatedBy: '1.3.1'
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. 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: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - 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 openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+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: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000..9ceebbc
--- /dev/null
+++ b/.claude/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,116 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: '1.0'
+  generatedBy: '1.3.1'
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000..cfcbf9e
--- /dev/null
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -0,0 +1,299 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: '1.0'
+  generatedBy: '1.3.1'
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+
+```bash
+openspec list --json
+```
+
+This tells you:
+
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type               | Where to Capture             |
+   | -------------------------- | ---------------------------- |
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed        | `specs/<capability>/spec.md` |
+   | Design decision made       | `design.md`                  |
+   | Scope changed              | `proposal.md`                |
+   | New work identified        | `tasks.md`                   |
+   | Assumption invalidated     | Relevant artifact            |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000..1844d0e
--- /dev/null
+++ b/.claude/skills/openspec-propose/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: '1.0'
+  generatedBy: '1.3.1'
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+
+   ```bash
+   openspec new change "<name>"
+   ```
+
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+   - Get instructions:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - The instructions JSON includes:
+     - `context`: Project background (constraints for you - do NOT include in output)
+     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+     - `template`: The structure to use for your output file
+     - `instruction`: Schema-specific guidance for this artifact type
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - Read any completed dependency files for context
+   - Create the artifact file using `template` as the structure
+   - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+   - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+   - After creating each artifact, re-run `openspec status --change "<name>" --json`
+   - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+   - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+   - Use **AskUserQuestion tool** to clarify
+   - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/AGENTS.md b/AGENTS.md
index 6ee6c21..41127de 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,9 +54,16 @@ WebGPU Sorting is a high-performance GPU-accelerated sorting library using WebGP
 │   ├── core/              # Core module tests
 │   ├── sorting/           # Sorting algorithm tests
 │   └── benchmark/         # Benchmark tests
-├── specs/                 # Spec-Driven Development specs
-│   ├── product/           # Product requirements
-│   └── rfc/               # Technical design documents
+├── openspec/              # OpenSpec spec-driven development
+│   ├── specs/             # Source of truth specifications
+│   │   ├── sorting/       # Sorting algorithm specs
+│   │   ├── infrastructure/# WebGPU infrastructure specs
+│   │   ├── quality/       # Quality and tooling specs
+│   │   └── _archived/     # Historical design documents
+│   ├── changes/           # Active change proposals
+│   ├── archive/           # Completed changes
+│   ├── config.yaml        # OpenSpec configuration
+│   └── .templates/        # Spec and proposal templates
 ├── docs/                  # Documentation
 │   ├── setup/             # Getting started guides
 │   ├── tutorials/         # API reference
@@ -133,50 +140,122 @@ npm run docs:serve
 
 ---
 
-## Spec-Driven Development (SDD) Workflow
+## OpenSpec Workflow
 
-This project strictly follows the **Spec-Driven Development (SDD)** paradigm. All code implementations must use the `/specs` directory as the Single Source of Truth.
+This project uses **OpenSpec** for spec-driven development. All specifications in `openspec/specs/` serve as the Single Source of Truth for implementations.
 
-> 本项目严格遵循**规范驱动开发（Spec-Driven Development）**范式。所有的代码实现必须以 `/specs` 目录下的规范文档为唯一事实来源（Single Source of Truth）。
+> 本项目使用 **OpenSpec** 进行规范驱动开发。`openspec/specs/` 中的所有规范文档作为实现的唯一事实来源。
 
-### SDD Workflow Steps
+### OpenSpec Core Workflow
 
-When you (the AI) are asked to develop a new feature, modify an existing feature, or fix a bug, **you MUST strictly follow this workflow. Do NOT skip any steps**:
+```
+/opsx:propose → /opsx:apply → /opsx:archive
+```
+
+When developing features, fixing bugs, or making changes, **follow this workflow**:
+
+#### Step 1: Propose | 提案
+
+Before making any code changes, create a change proposal:
+
+```
+/opsx:propose "Add merge sort algorithm"
+```
+
+This creates a change folder with:
 
-#### Step 1: Review Specs | 审查与分析
+- `proposal.md` - Intent, scope, and approach
+- `specs/` - Delta specs describing ADDED/MODIFIED/REMOVED requirements
+- `tasks.md` - Implementation checklist
 
-- Before writing any code, first read the relevant documents in `/specs` (product docs, RFCs, API definitions).
-- If the user's instruction conflicts with existing specs, **stop coding immediately** and point out the conflict, asking the user whether they want to update the spec first.
+#### Step 2: Apply | 实施
 
-#### Step 2: Spec-First Update | 规范优先
+Once the proposal is approved, implement the changes:
 
-- If this is a new feature, or if existing interfaces/database structures need to change, **you MUST first propose modifying or creating the corresponding Spec documents** (e.g., `/specs/api/openapi.yaml` or an RFC document).
-- Wait for user confirmation on the spec modifications before proceeding to the coding phase.
+```
+/opsx:apply
+```
+
+This executes the tasks from the checklist in order, writing code and marking tasks complete.
 
-#### Step 3: Implementation | 代码实现
+#### Step 3: Archive | 归档
 
-- When writing code, **100% comply with the specs** (including variable names, API paths, data types, status codes, etc.).
-- **Do NOT add features not defined in the spec** (No Gold-Plating).
+After implementation and testing, archive the change:
 
-#### Step 4: Test against Spec | 测试验证
+```
+/opsx:archive
+```
 
-- Write unit tests and integration tests based on the acceptance criteria in `/specs`.
-- Ensure test cases cover all boundary conditions described in the specs.
+This merges delta specs into the main specs and moves the change to the archive.
+
+### OpenSpec Commands
+
+| Command                | Purpose                             | 说明               |
+| ---------------------- | ----------------------------------- | ------------------ |
+| `/opsx:propose "idea"` | Create a new change proposal        | 创建新的变更提案   |
+| `/opsx:apply`          | Implement tasks from current change | 实施当前变更的任务 |
+| `/opsx:archive`        | Complete and archive the change     | 归档已完成的变更   |
+| `/opsx:explore`        | Explore codebase before proposing   | 提案前探索代码库   |
 
 ### Spec Locations
 
-| Directory         | Purpose                                               | 说明                   |
-| ----------------- | ----------------------------------------------------- | ---------------------- |
-| `/specs/product/` | Product feature definitions and acceptance criteria   | 产品功能定义与验收标准 |
-| `/specs/rfc/`     | Technical design documents and architecture decisions | 技术设计文档与架构决策 |
+| Directory                        | Purpose                          | 说明                |
+| -------------------------------- | -------------------------------- | ------------------- |
+| `openspec/specs/sorting/`        | Sorting algorithm specifications | 排序算法规范        |
+| `openspec/specs/infrastructure/` | WebGPU infrastructure specs      | WebGPU 基础设施规范 |
+| `openspec/specs/quality/`        | Quality and tooling specs        | 质量与工具规范      |
+| `openspec/specs/_archived/`      | Historical design documents      | 历史设计文档        |
+| `openspec/changes/`              | Active change proposals          | 活跃的变更提案      |
+| `openspec/archive/`              | Completed changes                | 已完成的变更        |
 
 ### Current Specs
 
-| Spec                                                                       | Type    | Description                                    |
-| -------------------------------------------------------------------------- | ------- | ---------------------------------------------- |
-| [WebGPU Sorting](./specs/product/0001-webgpu-sorting.md)                   | Product | Feature requirements and acceptance criteria   |
-| [Quality Enhancement](./specs/product/0002-project-quality-enhancement.md) | Product | CI/CD, code quality, project metadata          |
-| [Core Architecture](./specs/rfc/0001-core-architecture.md)                 | RFC     | Technical design, data flow, algorithm details |
+| Spec                                                                    | Domain     | Description                                    |
+| ----------------------------------------------------------------------- | ---------- | ---------------------------------------------- |
+| [WebGPU Sorting](./openspec/specs/sorting/webgpu-sorting.md)            | sorting    | Feature requirements and acceptance criteria   |
+| [Project Enhancement](./openspec/specs/quality/project-enhancement.md)  | quality    | CI/CD, code quality, project metadata          |
+| [Core Architecture](./openspec/specs/_archived/core-architecture-v1.md) | \_archived | Technical design, data flow, algorithm details |
+
+### Writing Specs
+
+Follow the existing format with Requirements and Acceptance Criteria:
+
+```markdown
+### Requirement N: [Feature Name]
+
+**User Story:** As a [role], I want [feature] so that [benefit].
+
+#### Acceptance Criteria
+
+1. WHEN [condition], THE [component] SHALL [behavior]
+2. IF [error condition], THEN THE [component] SHALL [error handling]
+```
+
+### Delta Specs
+
+When proposing changes, use markers to indicate modifications:
+
+```markdown
+<!-- ADDED -->
+
+### New Requirement
+
+...
+
+<!-- MODIFIED -->
+
+### Existing Requirement
+
+~ Old text to be removed
+
+- New text to be added
+
+<!-- REMOVED -->
+
+### ~~Deprecated Requirement~~
+
+...
+```
 
 ---
 
@@ -509,10 +588,10 @@ npm run dev
 
 ## Code Generation Rules
 
-- Any external API changes **MUST** update `/specs/api/openapi.yaml` synchronously.
-  - 任何对外部暴露的 API 变更，必须同步修改 `/specs/api/openapi.yaml`。
-- If uncertain about technical details, refer to the architectural conventions in `/specs/rfc/`. **Do NOT invent design patterns on your own**.
-  - 如果遇到不确定的技术细节，请查阅 `/specs/rfc/` 下的架构约定，不要自行捏造设计模式。
+- Any external API changes **MUST** be proposed via `/opsx:propose` and documented in the corresponding spec.
+  - 任何对外部暴露的 API 变更，必须通过 `/opsx:propose` 提案并在相应规范中记录。
+- If uncertain about technical details, refer to the architectural conventions in `openspec/specs/_archived/`. **Do NOT invent design patterns on your own**.
+  - 如果遇到不确定的技术细节，请查阅 `openspec/specs/_archived/` 下的架构约定，不要自行捏造设计模式。
 - All documentation should be in English by default. Chinese translations should be linked or placed in corresponding `.zh.md` files.
   - 所有文档默认使用英文。中文翻译应链接到对应的 `.zh.md` 文件。
 - README.md is in English with a link to README.zh.md at the top.
@@ -520,4 +599,4 @@ npm run dev
 
 ---
 
-**Last Updated**: 2026-04-17
+**Last Updated**: 2026-04-23
diff --git a/openspec/.templates/design.md b/openspec/.templates/design.md
new file mode 100644
index 0000000..fceb46a
--- /dev/null
+++ b/openspec/.templates/design.md
@@ -0,0 +1,45 @@
+# Design Document: {change-name}
+
+## Overview
+
+<!-- High-level technical approach -->
+
+## Architecture Changes
+
+<!-- Diagrams or descriptions of architectural changes -->
+
+## Data Flow
+
+<!-- How data flows through the system after changes -->
+
+## API Changes
+
+<!-- New, modified, or removed APIs -->
+
+## Database/Model Changes
+
+<!-- Schema changes if applicable -->
+
+## Security Considerations
+
+<!-- Any security implications -->
+
+## Performance Considerations
+
+<!-- Performance impact and optimizations -->
+
+## Migration Strategy
+
+<!-- How to migrate existing data/users if needed -->
+
+## Testing Strategy
+
+<!-- How to test the changes -->
+
+## Rollback Plan
+
+<!-- How to revert if issues arise -->
+
+---
+
+**Created**: {date}
diff --git a/openspec/.templates/proposal.md b/openspec/.templates/proposal.md
new file mode 100644
index 0000000..4782737
--- /dev/null
+++ b/openspec/.templates/proposal.md
@@ -0,0 +1,61 @@
+# Change Proposal: {title}
+
+## Metadata
+
+| Field         | Value       |
+| ------------- | ----------- |
+| **Created**   | {date}      |
+| **Status**    | Draft       |
+| **Author**    | {author}    |
+| **Change ID** | {change-id} |
+
+## Intent
+
+<!-- What problem does this solve? Why is it needed? -->
+
+## Scope
+
+<!-- What components/files are affected? -->
+
+### Affected Specs
+
+- [ ] `sorting/` - Sorting algorithm specifications
+- [ ] `infrastructure/` - WebGPU infrastructure specs
+- [ ] `quality/` - Quality and tooling specs
+- [ ] `_archived/` - Historical documents (rarely)
+
+### Affected Code
+
+- [ ] `src/sorting/` - Sorting implementations
+- [ ] `src/core/` - Core WebGPU infrastructure
+- [ ] `src/shaders/` - WGSL compute shaders
+- [ ] `src/benchmark/` - Benchmark utilities
+- [ ] `src/shared/` - Shared types and constants
+- [ ] `test/` - Test files
+
+## Approach
+
+<!-- High-level technical approach -->
+
+## Alternatives Considered
+
+<!-- What other approaches were evaluated? Why were they rejected? -->
+
+## Dependencies
+
+<!-- Does this depend on other changes or external factors? -->
+
+## Risks
+
+<!-- What could go wrong? Mitigation strategies? -->
+
+## Checklist
+
+- [ ] Specs updated in `openspec/changes/{change-id}/specs/`
+- [ ] Tasks defined in `tasks.md`
+- [ ] No conflicts with existing specs
+- [ ] Backward compatibility considered
+
+---
+
+**Next Step**: Run `/opsx:apply` to begin implementation.
diff --git a/openspec/.templates/spec.md b/openspec/.templates/spec.md
new file mode 100644
index 0000000..7c113fb
--- /dev/null
+++ b/openspec/.templates/spec.md
@@ -0,0 +1,61 @@
+# {Domain} Spec: {Feature Name}
+
+## Introduction
+
+<!-- Brief description of the feature -->
+
+## Glossary
+
+<!-- Define terms used in this spec -->
+
+| Term | Definition |
+| ---- | ---------- |
+| ...  | ...        |
+
+## Requirements
+
+### Requirement 1: {Requirement Name}
+
+**User Story:** As a [role], I want [feature] so that [benefit].
+
+#### Acceptance Criteria
+
+1. WHEN [condition], THE [component] SHALL [behavior]
+2. IF [error condition], THEN THE [component] SHALL [error handling]
+3. ...
+
+### Requirement 2: {Next Requirement}
+
+**User Story:** As a [role], I want [feature] so that [benefit].
+
+#### Acceptance Criteria
+
+1. ...
+
+## Properties (for Property-Based Testing)
+
+### Property 1: {Property Name}
+
+_For any_ [input conditions], the [function/component] SHALL [expected behavior].
+
+**Validates:** Requirements X.Y
+
+### Property 2: {Property Name}
+
+_For any_ [input conditions], the [function/component] SHALL [expected behavior].
+
+**Validates:** Requirements X.Y
+
+## Error Handling
+
+| Error Scenario | Handling Approach |
+| -------------- | ----------------- |
+| ...            | ...               |
+
+## Notes
+
+<!-- Additional implementation notes, constraints, or considerations -->
+
+---
+
+**Last Updated**: {date}
diff --git a/openspec/.templates/tasks.md b/openspec/.templates/tasks.md
new file mode 100644
index 0000000..da0aab7
--- /dev/null
+++ b/openspec/.templates/tasks.md
@@ -0,0 +1,73 @@
+# Implementation Tasks: {change-name}
+
+## Metadata
+
+| Field         | Value       |
+| ------------- | ----------- |
+| **Change ID** | {change-id} |
+| **Created**   | {date}      |
+| **Status**    | In Progress |
+
+---
+
+## Status Legend
+
+| Symbol | Meaning     |
+| ------ | ----------- |
+| [ ]    | Not started |
+| [~]    | In progress |
+| [x]    | Completed   |
+| [!]    | Blocked     |
+
+---
+
+## Phase 1: Spec Review
+
+- [ ] Review affected specs in `openspec/specs/`
+- [ ] Identify any spec conflicts or ambiguities
+- [ ] Update delta specs in `openspec/changes/{change-id}/specs/` if needed
+- [ ] Get spec review approval
+
+## Phase 2: Implementation
+
+- [ ] Create/update source files
+- [ ] Update TypeScript type definitions
+- [ ] Update constants (sync with WGSL if applicable)
+- [ ] Handle edge cases and error conditions
+
+## Phase 3: Testing
+
+- [ ] Write unit tests for new functionality
+- [ ] Write property-based tests for correctness properties
+- [ ] Update existing tests if behavior changed
+- [ ] Run full test suite: `npm run test`
+- [ ] Verify coverage meets thresholds
+
+## Phase 4: Documentation
+
+- [ ] Update API documentation (JSDoc comments)
+- [ ] Update `AGENTS.md` if workflow changes
+- [ ] Update user documentation in `docs/`
+- [ ] Update Chinese translations (`.zh.md` files)
+
+## Phase 5: Verification
+
+- [ ] All tests pass: `npm run test`
+- [ ] TypeScript compiles: `npm run typecheck`
+- [ ] ESLint passes: `npm run lint`
+- [ ] Build succeeds: `npm run build`
+- [ ] Manual testing completed
+
+---
+
+## Dependencies
+
+<!-- List any blocking tasks or external dependencies -->
+
+## Notes
+
+<!-- Implementation notes, decisions made, etc. -->
+
+---
+
+**Created**: {date}
diff --git a/openspec/archive/.gitkeep b/openspec/archive/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/openspec/changes/.gitkeep b/openspec/changes/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000..6e16ae4
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,85 @@
+# OpenSpec Configuration for WebGPU Sorting Project
+# Generated: 2026-04-23
+
+project:
+  name: webgpu-sorting
+  version: 1.0.0
+  description: High-performance GPU-accelerated sorting library using WebGPU compute shaders
+
+  repository:
+    type: git
+    url: https://github.com/user/webgpu-sorting
+    branch: master
+
+  tech_stack:
+    language: TypeScript
+    version: '5.3+'
+    frameworks:
+      - WebGPU
+      - WGSL
+    build_tool: Vite
+    test_framework: Vitest
+    package_manager: npm
+
+specs:
+  root: openspec/specs
+
+  domains:
+    - name: sorting
+      description: Core sorting algorithms (Bitonic, Radix, Benchmark, Validation)
+      owners: []
+
+    - name: infrastructure
+      description: WebGPU context and buffer management
+      owners: []
+
+    - name: quality
+      description: CI/CD, code quality, and project metadata
+      owners: []
+
+    - name: _archived
+      description: Historical design documents and superseded specs
+      owners: []
+
+  naming:
+    spec_files: kebab-case.md
+    change_dirs: kebab-case
+    max_title_length: 60
+
+changes:
+  root: openspec/changes
+  archive_root: openspec/archive
+
+  required_artifacts:
+    - proposal.md
+    - tasks.md
+
+  optional_artifacts:
+    - design.md
+    - specs/
+
+workflow:
+  auto_generate_tasks: true
+  require_spec_review: true
+  archive_timestamp_format: '%Y%m%d-%H%M%S'
+
+validation:
+  require_change_markers: true
+  trace_to_code: false
+
+templates:
+  proposal: .templates/proposal.md
+  design: .templates/design.md
+  tasks: .templates/tasks.md
+  spec: .templates/spec.md
+
+docs:
+  languages:
+    - en
+    - zh
+  translation_suffix: '.zh.md'
+  auto_generate: false
+
+integration:
+  agents_file: AGENTS.md
+  contributing_file: CONTRIBUTING.md
diff --git a/openspec/specs/_archived/README.md b/openspec/specs/_archived/README.md
new file mode 100644
index 0000000..9980348
--- /dev/null
+++ b/openspec/specs/_archived/README.md
@@ -0,0 +1,31 @@
+# Archived Specifications
+
+Historical design documents and superseded specifications. These documents are preserved for reference but are no longer actively maintained.
+
+> 归档规范 - 历史设计文档和已废弃的规范。这些文档保留供参考，但不再主动维护。
+
+## Documents
+
+| Document                                             | Original Status | Description                                       |
+| ---------------------------------------------------- | --------------- | ------------------------------------------------- |
+| [core-architecture-v1.md](./core-architecture-v1.md) | Accepted        | Core architecture design (migrated from RFC 0001) |
+
+## Purpose
+
+The `_archived` domain serves as:
+
+1. **Historical Reference** - Preserving design decisions and their rationale
+2. **Documentation Context** - Understanding how the system evolved
+3. **Onboarding Material** - Helping new contributors understand the architecture
+
+## When to Archive
+
+Documents should be moved here when:
+
+- An RFC has been fully implemented and the design is stable
+- A specification has been superseded by a newer version
+- A feature has been deprecated or removed
+
+## Related
+
+- Active specifications: [../sorting/](../sorting/), [../quality/](../quality/)
diff --git a/specs/rfc/0001-core-architecture.md b/openspec/specs/_archived/core-architecture-v1.md
similarity index 100%
rename from specs/rfc/0001-core-architecture.md
rename to openspec/specs/_archived/core-architecture-v1.md
diff --git a/openspec/specs/infrastructure/README.md b/openspec/specs/infrastructure/README.md
new file mode 100644
index 0000000..b1bcf08
--- /dev/null
+++ b/openspec/specs/infrastructure/README.md
@@ -0,0 +1,22 @@
+# Infrastructure Domain
+
+WebGPU infrastructure specifications including GPU context management, buffer handling, and error handling.
+
+> 基础设施域 - WebGPU 基础设施规范，包括 GPU 上下文管理、缓冲区处理和错误处理。
+
+## Status
+
+This domain is reserved for future specifications. Current implementation is documented in:
+
+- [Core Architecture (Archived)](../_archived/core-architecture-v1.md)
+
+## Components
+
+- **GPUContext** - WebGPU initialization and lifecycle
+- **BufferManager** - GPU buffer creation and data transfer
+- **Error Handling** - Custom error classes for WebGPU operations
+
+## Related Domains
+
+- [../sorting/](../sorting/) - Core sorting algorithms
+- [../quality/](../quality/) - CI/CD and code quality standards
diff --git a/openspec/specs/quality/README.md b/openspec/specs/quality/README.md
new file mode 100644
index 0000000..b090f0a
--- /dev/null
+++ b/openspec/specs/quality/README.md
@@ -0,0 +1,23 @@
+# Quality Domain
+
+Project quality standards including CI/CD configuration, code quality tools, and documentation requirements.
+
+> 质量域 - 项目质量标准，包括 CI/CD 配置、代码质量工具和文档要求。
+
+## Specifications
+
+| Spec                                               | Description                           | 说明                        |
+| -------------------------------------------------- | ------------------------------------- | --------------------------- |
+| [project-enhancement.md](./project-enhancement.md) | CI/CD, code quality, project metadata | CI/CD、代码质量、项目元数据 |
+
+## Components
+
+- **CI/CD Pipelines** - GitHub Actions workflows
+- **Code Quality** - ESLint, Prettier, TypeScript configurations
+- **Git Hooks** - Husky + lint-staged for pre-commit checks
+- **Test Coverage** - Vitest coverage configuration
+
+## Related Domains
+
+- [../sorting/](../sorting/) - Core sorting algorithms
+- [../infrastructure/](../infrastructure/) - WebGPU infrastructure
diff --git a/specs/product/0002-project-quality-enhancement.md b/openspec/specs/quality/project-enhancement.md
similarity index 100%
rename from specs/product/0002-project-quality-enhancement.md
rename to openspec/specs/quality/project-enhancement.md
diff --git a/openspec/specs/sorting/README.md b/openspec/specs/sorting/README.md
new file mode 100644
index 0000000..5f927c3
--- /dev/null
+++ b/openspec/specs/sorting/README.md
@@ -0,0 +1,23 @@
+# Sorting Domain
+
+Core sorting algorithms and performance requirements for the WebGPU Sorting library.
+
+> 排序域 - WebGPU 排序库的核心排序算法与性能需求。
+
+## Specifications
+
+| Spec                                     | Description                       | 说明             |
+| ---------------------------------------- | --------------------------------- | ---------------- |
+| [webgpu-sorting.md](./webgpu-sorting.md) | Core sorting feature requirements | 核心排序功能需求 |
+
+## Components
+
+- **BitonicSorter** - Bitonic sort implementation (O(n log²n))
+- **RadixSorter** - Radix sort implementation (O(n × k))
+- **Benchmark** - Performance benchmarking utilities
+- **Validator** - Sorting result validation
+
+## Related Domains
+
+- [../infrastructure/](../infrastructure/) - WebGPU context and buffer management
+- [../quality/](../quality/) - CI/CD and code quality standards
diff --git a/specs/product/0001-webgpu-sorting.md b/openspec/specs/sorting/webgpu-sorting.md
similarity index 100%
rename from specs/product/0001-webgpu-sorting.md
rename to openspec/specs/sorting/webgpu-sorting.md
diff --git a/specs/README.md b/specs/README.md
deleted file mode 100644
index 51aa984..0000000
--- a/specs/README.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# Specifications Directory
-
-This directory contains all specification documents following the **Spec-Driven Development (SDD)** paradigm. These specs serve as the **Single Source of Truth** for all code implementations.
-
-> 本目录包含遵循**规范驱动开发（SDD）**范式的所有规范文档。这些规范作为所有代码实现的**唯一事实来源**。
-
----
-
-## Directory Structure | 目录结构
-
-```
-specs/
-├── product/    # Product requirements (PRDs) | 产品需求文档
-├── rfc/        # Technical design documents (RFCs) | 技术设计文档
-├── api/        # API interface definitions | API 接口定义
-├── db/         # Database/model definitions | 数据库/模型定义
-└── testing/    # BDD test specifications | BDD 测试规范
-```
-
----
-
-## Current Specifications | 当前规范
-
-### Product Specs | 产品规范
-
-| Spec                                                                                 | Description                       | 说明                        |
-| ------------------------------------------------------------------------------------ | --------------------------------- | --------------------------- |
-| [0001-webgpu-sorting.md](./product/0001-webgpu-sorting.md)                           | Core sorting feature requirements | 核心排序功能需求            |
-| [0002-project-quality-enhancement.md](./product/0002-project-quality-enhancement.md) | CI/CD, code quality, metadata     | CI/CD、代码质量、项目元数据 |
-
-### RFCs | 技术设计
-
-| RFC                                                          | Status   | Description              | 说明         |
-| ------------------------------------------------------------ | -------- | ------------------------ | ------------ |
-| [0001-core-architecture.md](./rfc/0001-core-architecture.md) | Accepted | Core architecture design | 核心架构设计 |
-
-### API Specs | API 规范
-
-Reserved for future API formalization needs. Current API is defined via TypeScript interfaces.
-
-> 预留用于未来 API 形式化需求。当前 API 通过 TypeScript 接口定义。
-
-### DB Specs | 数据模型规范
-
-Reserved for data model specifications. Current models are TypeScript interfaces.
-
-> 预留用于数据模型规范。当前模型为 TypeScript 接口。
-
-### Testing Specs | 测试规范
-
-Reserved for BDD feature files. Current tests use Vitest with property-based testing.
-
-> 预留用于 BDD 功能文件。当前测试使用 Vitest 和属性测试。
-
----
-
-## Specification Naming Convention | 规范命名约定
-
-### Product Specs
-
-Format: `NNNN-feature-name.md`
-
-- `NNNN`: Zero-padded number (0001, 0002, ...)
-- `feature-name`: Kebab-case feature name
-
-### RFCs
-
-Format: `NNNN-topic-name.md`
-
-- `NNNN`: Zero-padded RFC number
-- `topic-name`: Kebab-case topic name
-
-### RFC Status Values
-
-| Status       | Description                           |
-| ------------ | ------------------------------------- |
-| `Proposed`   | Under discussion                      |
-| `Accepted`   | Approved and ready for implementation |
-| `Rejected`   | Not approved                          |
-| `Deprecated` | No longer relevant                    |
-| `Superseded` | Replaced by newer RFC                 |
-
----
-
-## How to Use | 如何使用
-
-### For AI Agents | 给 AI 代理
-
-1. **Always read specs first** before writing code
-2. Follow the workflow in [AGENTS.md](../AGENTS.md)
-3. If specs conflict with requirements, update specs first
-
----
-
-### For Contributors | 给贡献者
-
-1. New features require a product spec
-2. Architecture changes require an RFC
-3. Update specs before changing code
-4. See [CONTRIBUTING.md](../CONTRIBUTING.md) for details
-
----
-
-## Related Documents | 相关文档
-
-- [AGENTS.md](../AGENTS.md) - AI workflow instructions
-- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
-- [docs/](../docs/) - User documentation
-
----
-
-**Last Updated**: 2026-04-17

From a47da7c9f9840d1628351c854156405b3fdc2d70 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:59:30 +0800
Subject: [PATCH 02/10] chore: update .gitignore to exclude .omc directory

Add .omc/ to gitignore for oh-my-claudecode local data.
---
 .gitignore | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.gitignore b/.gitignore
index 43df80d..d10f4fa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,3 +55,9 @@ pnpm-debug.log*
 # WebGPU specific
 *.spv
 *.spirv
+
+# Claude Code personal settings
+CLAUDE.local.md
+
+# oh-my-claudecode
+.omc/

From b59de09cc7cd5b6e63cec03fcdd02546579473c2 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:59:37 +0800
Subject: [PATCH 03/10] style: format ESLint config and harden pre-commit hook

- Reformat .eslintrc.cjs with consistent 2-space indentation
- Add site/scripts to ESLint overrides for console statements
- Use npx --no-install in pre-commit to avoid implicit installs
---
 .eslintrc.cjs     | 82 +++++++++++++++++++++--------------------------
 .husky/pre-commit |  2 +-
 2 files changed, 37 insertions(+), 47 deletions(-)

diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index 94f4da7..41e6f52 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -1,51 +1,41 @@
 /** @type {import('eslint').Linter.Config} */
 module.exports = {
-    root: true,
-    env: {
-        browser: true,
-        es2022: true,
-        node: true,
+  root: true,
+  env: {
+    browser: true,
+    es2022: true,
+    node: true,
+  },
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier'],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint'],
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    'no-console': ['warn', { allow: ['warn', 'error'] }],
+    'prefer-const': 'error',
+    'no-var': 'error',
+  },
+  ignorePatterns: ['dist/', 'node_modules/', '*.wgsl', 'coverage/', '.eslintrc.cjs'],
+  overrides: [
+    {
+      files: ['test/**/*.ts', '**/*.test.ts'],
+      rules: {
+        'no-console': 'off',
+        '@typescript-eslint/no-explicit-any': 'off',
+      },
     },
-    extends: [
-        'eslint:recommended',
-        'plugin:@typescript-eslint/recommended',
-        'prettier',
-    ],
-    parser: '@typescript-eslint/parser',
-    parserOptions: {
-        ecmaVersion: 'latest',
-        sourceType: 'module',
+    {
+      files: ['examples/**/*.ts', 'site/scripts/**/*.ts'],
+      rules: {
+        'no-console': 'off',
+      },
     },
-    plugins: ['@typescript-eslint'],
-    rules: {
-        '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-        '@typescript-eslint/explicit-function-return-type': 'off',
-        '@typescript-eslint/no-explicit-any': 'warn',
-        '@typescript-eslint/no-non-null-assertion': 'warn',
-        'no-console': ['warn', { allow: ['warn', 'error'] }],
-        'prefer-const': 'error',
-        'no-var': 'error',
-    },
-    ignorePatterns: [
-        'dist/',
-        'node_modules/',
-        '*.wgsl',
-        'coverage/',
-        '.eslintrc.cjs',
-    ],
-    overrides: [
-        {
-            files: ['test/**/*.ts', '**/*.test.ts'],
-            rules: {
-                'no-console': 'off',
-                '@typescript-eslint/no-explicit-any': 'off',
-            },
-        },
-        {
-            files: ['examples/**/*.ts'],
-            rules: {
-                'no-console': 'off',
-            },
-        },
-    ],
+  ],
 };
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 2312dc5..041c660 100644
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1 +1 @@
-npx lint-staged
+npx --no-install lint-staged

From 964f335cd3a58787bbd40f25a4a89122495c51a8 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:59:46 +0800
Subject: [PATCH 04/10] chore: update package metadata for project positioning

- Refine description to mention WGSL, TypeScript API, demo
- Reorganize keywords for better discoverability
- Update homepage to GitHub Pages URL
---
 package.json | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/package.json b/package.json
index 1ec8deb..52c73ef 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "webgpu-sorting",
   "version": "1.0.1",
-  "description": "High-performance GPU sorting algorithms using WebGPU compute shaders",
+  "description": "WebGPU + WGSL sorting reference project with Bitonic Sort, Radix Sort, live demo, and TypeScript API",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,13 +11,14 @@
   ],
   "keywords": [
     "webgpu",
-    "gpu",
+    "wgsl",
     "sorting",
     "bitonic-sort",
     "radix-sort",
-    "compute-shader",
-    "wgsl",
-    "parallel-computing"
+    "compute-shaders",
+    "gpu-computing",
+    "benchmark",
+    "typescript"
   ],
   "author": "WebGPU Sorting Contributors",
   "license": "MIT",
@@ -28,7 +29,7 @@
   "bugs": {
     "url": "https://github.com/LessUp/webgpu-sorting/issues"
   },
-  "homepage": "https://github.com/LessUp/webgpu-sorting#readme",
+  "homepage": "https://lessup.github.io/webgpu-sorting/",
   "engines": {
     "node": ">=18.0.0"
   },

From 811c683f8ab78b483b958fa8ca7f7fb9a13077a9 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:59:56 +0800
Subject: [PATCH 05/10] docs: consolidate and simplify AI instruction files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Refactor AGENTS.md into concise project guide (~400 lines → ~120 lines)
- Add CLAUDE.md for Claude/Codex-specific guidance
- Add .github/copilot-instructions.md for Copilot integration
- Remove generic boilerplate, focus on project-specific rules
- Establish clear source-of-truth hierarchy and workflow
---
 .github/copilot-instructions.md |  44 +++
 AGENTS.md                       | 643 ++++----------------------------
 CLAUDE.md                       |  47 +++
 3 files changed, 172 insertions(+), 562 deletions(-)
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 CLAUDE.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..9801400
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,44 @@
+# GitHub Copilot Instructions
+
+This repository uses OpenSpec for non-trivial changes.
+
+## Before editing
+
+- Check `AGENTS.md` for project-wide workflow and architectural guidance.
+- If the task affects behavior, workflow, docs architecture, public positioning, or engineering policy, work from an OpenSpec change first.
+
+Preferred flow:
+
+```text
+/opsx:explore → /opsx:propose → /opsx:apply → /review → /opsx:archive
+```
+
+## What good changes look like here
+
+- small, scoped, serial changes
+- high-signal workflow simplification instead of automation sprawl
+- docs that match the real repo structure
+- minimal duplication across README, docs, Pages, and AI instruction files
+
+## Validation commands
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
+
+## Tooling policy
+
+- Prefer committed repo config first.
+- Recommend global tooling only when it clearly improves this project's workflow.
+- Keep MCP/plugin usage minimal and justified.
+- Avoid heavy parallel `/fleet` usage unless the work is clearly independent and worth the cost.
+
+## Public surfaces to keep aligned
+
+- `README.md`
+- `docs/README.md`
+- `site/`
+- GitHub repository description / homepage / topics
diff --git a/AGENTS.md b/AGENTS.md
index 41127de..1bda60f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,602 +1,121 @@
-<!-- From: /home/shane/dev/webgpu-sorting/AGENTS.md -->
+# AGENTS.md
 
-# AI Agent Instructions: WebGPU Sorting
+Project instructions for AI coding agents working in `LessUp/webgpu-sorting`.
 
-## Project Overview
+## Mission
 
-WebGPU Sorting is a high-performance GPU-accelerated sorting library using WebGPU compute shaders. It implements two parallel sorting algorithms—**Bitonic Sort** and **Radix Sort**—to achieve sorting performance tens of times faster than JavaScript's native `Array.sort()`.
+Keep this repository coherent, trustworthy, and easy to finish. This is a WebGPU sorting library, benchmark/demo app, and GitHub Pages showcase; changes should improve one of those surfaces without creating new drift elsewhere.
 
-> 本项目是一个基于 WebGPU 计算着色器的高性能 GPU 排序库，实现了双调排序（Bitonic Sort）和基数排序（Radix Sort）两种并行排序算法。
+## Source of truth
 
-### Technology Stack
+When information conflicts, follow this order:
 
-| Category        | Technology                     |
-| --------------- | ------------------------------ |
-| Language        | TypeScript 5.3+                |
-| GPU API         | WebGPU                         |
-| Shader Language | WGSL (WebGPU Shading Language) |
-| Build Tool      | Vite 5.0+                      |
-| Test Framework  | Vitest 1.2+                    |
-| Package Manager | npm                            |
-| Node.js Version | 18.x or 20.x (see `.nvmrc`)    |
+1. Active OpenSpec change artifacts in `openspec/changes/<change-id>/`
+2. Stable specs in `openspec/specs/`
+3. Code and tests in `src/` and `test/`
+4. Public docs and site content (`README*`, `docs/`, `site/`)
 
-### Browser Compatibility
+Do not implement a non-trivial change before there is an OpenSpec change that covers it.
 
-- Chrome 113+ / Edge 113+ (Fully supported)
-- Firefox Nightly (Requires `dom.webgpu.enabled` flag)
-- Safari 18+ (Requires macOS 14+)
+## Repository map
 
----
+| Path                         | Role                                          |
+| ---------------------------- | --------------------------------------------- |
+| `openspec/`                  | Specs, proposal artifacts, templates, archive |
+| `src/core/`                  | WebGPU context, buffers, validation, errors   |
+| `src/sorting/`               | Bitonic and radix sorter implementations      |
+| `src/shaders/`               | WGSL compute shaders                          |
+| `src/benchmark/`             | Benchmark helpers                             |
+| `src/main.ts` + `index.html` | Browser demo                                  |
+| `site/`                      | GitHub Pages site source and build scripts    |
+| `docs/`                      | User-facing documentation                     |
+| `.github/workflows/`         | CI, Pages, release, security automation       |
 
-## Directory Structure
-
-```
-├── src/                    # Source code
-│   ├── core/              # Core WebGPU infrastructure
-│   │   ├── GPUContext.ts      # WebGPU initialization & lifecycle
-│   │   ├── BufferManager.ts   # GPU buffer management
-│   │   ├── Validator.ts       # Sorting result validation
-│   │   └── errors.ts          # Custom error classes
-│   ├── sorting/           # Sorting algorithm implementations
-│   │   ├── BitonicSorter.ts   # Bitonic sort (O(n log²n))
-│   │   └── RadixSorter.ts     # Radix sort (O(n × k))
-│   ├── shaders/           # WGSL compute shaders
-│   │   ├── bitonic.wgsl       # Bitonic sort shader
-│   │   └── radix.wgsl         # Radix sort shader
-│   ├── benchmark/         # Performance benchmarking
-│   │   └── Benchmark.ts       # Benchmark utility
-│   ├── shared/            # Shared utilities
-│   │   ├── types.ts           # TypeScript type definitions
-│   │   └── constants.ts       # Constants (workgroup size, radix, etc.)
-│   ├── index.ts           # Public API exports
-│   └── main.ts            # Demo UI application
-├── test/                  # Test suite
-│   ├── core/              # Core module tests
-│   ├── sorting/           # Sorting algorithm tests
-│   └── benchmark/         # Benchmark tests
-├── openspec/              # OpenSpec spec-driven development
-│   ├── specs/             # Source of truth specifications
-│   │   ├── sorting/       # Sorting algorithm specs
-│   │   ├── infrastructure/# WebGPU infrastructure specs
-│   │   ├── quality/       # Quality and tooling specs
-│   │   └── _archived/     # Historical design documents
-│   ├── changes/           # Active change proposals
-│   ├── archive/           # Completed changes
-│   ├── config.yaml        # OpenSpec configuration
-│   └── .templates/        # Spec and proposal templates
-├── docs/                  # Documentation
-│   ├── setup/             # Getting started guides
-│   ├── tutorials/         # API reference
-│   └── architecture/      # Technical deep-dives
-├── examples/              # Usage examples
-├── .github/workflows/     # CI/CD workflows
-└── dist/                  # Build output (generated)
-```
-
----
-
-## Build and Development Commands
-
-### Essential Commands
+## Commands that matter
 
 ```bash
-# Install dependencies
-npm install
-
-# Start development server
-npm run dev
-
-# Build for production
-npm run build
-
-# Build with bundle analysis
-npm run build:analyze
-
-# Preview production build
-npm run preview
-```
-
-### Testing Commands
-
-```bash
-# Run all tests once
-npm run test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage
-npm run test:coverage
-```
-
-### Code Quality Commands
-
-```bash
-# Lint TypeScript files
 npm run lint
-
-# Lint and fix issues
-npm run lint:fix
-
-# Format all files
-npm run format
-
-# Check formatting without fixing
-npm run format:check
-
-# Type check without emitting
 npm run typecheck
+npm run test
+npm run build
 ```
 
-### Documentation Commands
+Useful supporting commands:
 
 ```bash
-# Generate TypeDoc API documentation
-npm run docs:generate
-
-# Serve generated docs locally
-npm run docs:serve
-```
-
----
-
-## OpenSpec Workflow
-
-This project uses **OpenSpec** for spec-driven development. All specifications in `openspec/specs/` serve as the Single Source of Truth for implementations.
-
-> 本项目使用 **OpenSpec** 进行规范驱动开发。`openspec/specs/` 中的所有规范文档作为实现的唯一事实来源。
-
-### OpenSpec Core Workflow
-
-```
-/opsx:propose → /opsx:apply → /opsx:archive
-```
-
-When developing features, fixing bugs, or making changes, **follow this workflow**:
-
-#### Step 1: Propose | 提案
-
-Before making any code changes, create a change proposal:
-
-```
-/opsx:propose "Add merge sort algorithm"
-```
-
-This creates a change folder with:
-
-- `proposal.md` - Intent, scope, and approach
-- `specs/` - Delta specs describing ADDED/MODIFIED/REMOVED requirements
-- `tasks.md` - Implementation checklist
-
-#### Step 2: Apply | 实施
-
-Once the proposal is approved, implement the changes:
-
-```
-/opsx:apply
-```
-
-This executes the tasks from the checklist in order, writing code and marking tasks complete.
-
-#### Step 3: Archive | 归档
-
-After implementation and testing, archive the change:
-
-```
-/opsx:archive
-```
-
-This merges delta specs into the main specs and moves the change to the archive.
-
-### OpenSpec Commands
-
-| Command                | Purpose                             | 说明               |
-| ---------------------- | ----------------------------------- | ------------------ |
-| `/opsx:propose "idea"` | Create a new change proposal        | 创建新的变更提案   |
-| `/opsx:apply`          | Implement tasks from current change | 实施当前变更的任务 |
-| `/opsx:archive`        | Complete and archive the change     | 归档已完成的变更   |
-| `/opsx:explore`        | Explore codebase before proposing   | 提案前探索代码库   |
-
-### Spec Locations
-
-| Directory                        | Purpose                          | 说明                |
-| -------------------------------- | -------------------------------- | ------------------- |
-| `openspec/specs/sorting/`        | Sorting algorithm specifications | 排序算法规范        |
-| `openspec/specs/infrastructure/` | WebGPU infrastructure specs      | WebGPU 基础设施规范 |
-| `openspec/specs/quality/`        | Quality and tooling specs        | 质量与工具规范      |
-| `openspec/specs/_archived/`      | Historical design documents      | 历史设计文档        |
-| `openspec/changes/`              | Active change proposals          | 活跃的变更提案      |
-| `openspec/archive/`              | Completed changes                | 已完成的变更        |
-
-### Current Specs
-
-| Spec                                                                    | Domain     | Description                                    |
-| ----------------------------------------------------------------------- | ---------- | ---------------------------------------------- |
-| [WebGPU Sorting](./openspec/specs/sorting/webgpu-sorting.md)            | sorting    | Feature requirements and acceptance criteria   |
-| [Project Enhancement](./openspec/specs/quality/project-enhancement.md)  | quality    | CI/CD, code quality, project metadata          |
-| [Core Architecture](./openspec/specs/_archived/core-architecture-v1.md) | \_archived | Technical design, data flow, algorithm details |
-
-### Writing Specs
-
-Follow the existing format with Requirements and Acceptance Criteria:
-
-```markdown
-### Requirement N: [Feature Name]
-
-**User Story:** As a [role], I want [feature] so that [benefit].
-
-#### Acceptance Criteria
-
-1. WHEN [condition], THE [component] SHALL [behavior]
-2. IF [error condition], THEN THE [component] SHALL [error handling]
-```
-
-### Delta Specs
-
-When proposing changes, use markers to indicate modifications:
-
-```markdown
-<!-- ADDED -->
-
-### New Requirement
-
-...
-
-<!-- MODIFIED -->
-
-### Existing Requirement
-
-~ Old text to be removed
-
-- New text to be added
-
-<!-- REMOVED -->
-
-### ~~Deprecated Requirement~~
-
-...
-```
-
----
-
-## Architecture Overview
-
-### Layer Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Demo UI Layer                          │
-│  (src/main.ts - Interactive benchmark interface)            │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Public API Layer                         │
-│  ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐   │
-│  │ BitonicSorter │ │  RadixSorter  │ │    Benchmark    │   │
-│  └───────────────┘ └───────────────┘ └─────────────────┘   │
-│  (src/sorting/, src/benchmark/)                             │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   WebGPU Core Layer                         │
-│  ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐   │
-│  │   GPUContext  │ │ BufferManager │ │    Validator    │   │
-│  └───────────────┘ └───────────────┘ └─────────────────┘   │
-│  (src/core/)                                                │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    WGSL Compute Shaders                     │
-│  ┌─────────────────┐  ┌─────────────────┐                  │
-│  │  bitonic.wgsl   │  │   radix.wgsl    │                  │
-│  └─────────────────┘  └─────────────────┘                  │
-│  (src/shaders/)                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Data Flow
-
-```
-Input Array (CPU)
-       │
-       ▼
-┌──────────────────┐
-│ Upload to GPU    │ ← writeBuffer()
-│ (Storage Buffer) │
-└──────────────────┘
-       │
-       ▼
-┌──────────────────┐
-│ GPU Sorting      │ ← Compute Shader Dispatches
-│ (Multiple Passes)│
-└──────────────────┘
-       │
-       ▼
-┌──────────────────┐
-│ Download to CPU  │ ← mapAsync() + copyBufferToBuffer()
-│ (Staging Buffer) │
-└──────────────────┘
-       │
-       ▼
-Sorted Array (CPU)
-```
-
----
-
-## Code Style Guidelines
-
-### TypeScript/JavaScript
-
-- **Indentation**: 2 spaces (see `.editorconfig`)
-- **Quotes**: Single quotes
-- **Semicolons**: Required
-- **Line endings**: LF (Unix)
-- **Max line length**: 100 characters
-- **Trailing commas**: ES5 compatible (required)
-
-### ESLint Rules (Key)
-
-```javascript
-// From .eslintrc.cjs
-{
-  '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-  '@typescript-eslint/explicit-function-return-type': 'off',
-  '@typescript-eslint/no-explicit-any': 'warn',
-  '@typescript-eslint/no-non-null-assertion': 'warn',
-  'no-console': ['warn', { allow: ['warn', 'error'] }],
-  'prefer-const': 'error',
-  'no-var': 'error',
-}
-```
-
-### File Naming Conventions
-
-- TypeScript source files: `PascalCase.ts` for classes (e.g., `GPUContext.ts`)
-- Test files: `*.test.ts` (e.g., `GPUContext.test.ts`)
-- Shader files: `*.wgsl` (lowercase, e.g., `bitonic.wgsl`)
-
-### WGSL Shader Conventions
-
-- Use snake_case for variable/function names
-- Include sync comments with TypeScript constants:
-
-```wgsl
-// IMPORTANT: WORKGROUP_SIZE must match src/shared/constants.ts
-// @see src/shared/constants.ts - WORKGROUP_SIZE = 256
-const WORKGROUP_SIZE: u32 = 256u;
-```
-
----
-
-## Testing Strategy
-
-### Test Framework: Vitest
-
-- **Environment**: Node.js (browser APIs mocked where needed)
-- **Globals**: Enabled (`expect`, `describe`, `it`, etc.)
-- **Timeout**: 30 seconds per test (GPU operations can be slow)
-- **Coverage**: v8 provider with thresholds configured
-
-### Test Structure
-
-```
-test/
-├── core/              # Core module unit tests
-│   ├── GPUContext.test.ts
-│   ├── BufferManager.test.ts
-│   ├── Validator.test.ts
-│   └── errors.test.ts
-├── sorting/           # Sorting algorithm tests
-│   ├── BitonicSorter.test.ts
-│   └── RadixSorter.test.ts
-└── benchmark/         # Benchmark tests
-    └── Benchmark.test.ts
-```
-
-### Coverage Thresholds
-
-```typescript
-// From vitest.config.ts
-thresholds: {
-  lines: 25,
-  functions: 30,
-  branches: 20,
-  statements: 25,
-}
-```
-
-### Property-Based Testing
-
-Uses `fast-check` for generative testing. Property tests validate:
-
-1. Buffer round-trip consistency
-2. Buffer size alignment
-3. Bitonic padding to power of 2
-4. Sort correctness for both algorithms
-5. Speedup calculation correctness
-6. Average time calculation
-7. Validator correctness
-
-**Annotation Format for Property Tests**:
-
-```typescript
-// Feature: webgpu-sorting, Property 4: Bitonic Sort Correctness
-// Validates: Requirements 3.5
-```
-
----
-
-## Git Workflow & CI/CD
-
-### Git Hooks (Husky)
-
-Pre-commit hook runs `lint-staged`:
-
-- ESLint --fix on staged `*.ts,*.tsx` files
-- Prettier --write on staged files
-
-### CI/CD Pipelines (.github/workflows/)
-
-| Workflow        | Trigger            | Purpose                             |
-| --------------- | ------------------ | ----------------------------------- |
-| `ci.yml`        | PR, Push to master | Lint, test (Node 18.x, 20.x), build |
-| `pr-checks.yml` | PR                 | Additional PR validation            |
-| `docs.yml`      | Push to master     | Documentation generation            |
-| `pages.yml`     | Push to master     | Deploy demo to GitHub Pages         |
-| `release.yml`   | Tag push           | Release automation                  |
-| `codeql.yml`    | Scheduled          | Security analysis                   |
-
-### CI Pipeline Order
-
-```
-Lint & Format Check → Test (Node 18.x, 20.x) → Build
-         │                              │
-         └──── All must pass ───────────┘
+npm run dev
+npm run test:coverage
+npm run pages:build
 ```
 
----
-
-## Constants and Configuration
-
-### Shared Constants (src/shared/constants.ts)
-
-| Constant                  | Value                          | Description                         |
-| ------------------------- | ------------------------------ | ----------------------------------- |
-| `WORKGROUP_SIZE`          | 256                            | Compute shader workgroup size       |
-| `BITS_PER_PASS`           | 4                              | Bits processed per radix pass       |
-| `RADIX`                   | 16                             | Number of buckets (2^BITS_PER_PASS) |
-| `NUM_PASSES`              | 8                              | Passes for 32-bit integers          |
-| `DEFAULT_BENCHMARK_SIZES` | [1024, 10240, 102400, 1048576] | Default test sizes                  |
-| `MAX_VALIDATION_SIZE`     | 10000                          | Max size for validation             |
-
-> ⚠️ **CRITICAL**: These constants must stay in sync with WGSL shader values:
->
-> - `src/shaders/bitonic.wgsl`: `WORKGROUP_SIZE = 256u`
-> - `src/shaders/radix.wgsl`: `WORKGROUP_SIZE = 256u`, `RADIX = 16u`
+## Required workflow
 
----
+Use OpenSpec for any change that touches behavior, docs architecture, workflow, public positioning, or engineering policy.
 
-## Error Handling
-
-### Custom Error Classes (src/core/errors.ts)
-
-| Error                     | Description                     |
-| ------------------------- | ------------------------------- |
-| `WebGPUNotSupportedError` | Browser doesn't support WebGPU  |
-| `GPUAdapterError`         | Failed to get GPU adapter       |
-| `GPUDeviceError`          | Failed to get GPU device        |
-| `BufferAllocationError`   | GPU buffer allocation failed    |
-| `BufferMapError`          | Buffer mapping operation failed |
-| `ShaderCompilationError`  | WGSL shader compilation failed  |
-| `GPUTimeoutError`         | GPU operation timed out         |
-
----
-
-## Security Considerations
-
-### Browser Security Headers
-
-Vite dev server configured with COOP/COEP headers for WebGPU:
-
-```typescript
-// vite.config.ts
-server: {
-  headers: {
-    'Cross-Origin-Opener-Policy': 'same-origin',
-    'Cross-Origin-Embedder-Policy': 'require-corp',
-  },
-}
+```text
+/opsx:explore → /opsx:propose → /opsx:apply → /review → /opsx:archive
 ```
 
-### Security Reporting
-
-See `SECURITY.md` for vulnerability reporting procedures.
-
----
-
-## Documentation
+Workflow rules:
 
-### User Documentation (docs/)
+- Prefer **one active closeout change at a time** unless work is truly independent.
+- Prefer **small serial merges** over long-lived branches.
+- Run a **review pass** before declaring a meaningful slice complete.
+- Archive finished changes promptly so `openspec/changes/` stays clean.
 
-| Document                                              | Language | Description                 |
-| ----------------------------------------------------- | -------- | --------------------------- |
-| [Getting Started](./docs/setup/GETTING_STARTED.md)    | EN       | Installation, quick start   |
-| [入门指南](./docs/setup/GETTING_STARTED.zh.md)        | 中文     | 安装与快速开始              |
-| [API Reference](./docs/tutorials/API.md)              | EN       | Complete API documentation  |
-| [API 参考](./docs/tutorials/API.zh.md)                | 中文     | 完整 API 文档               |
-| [Technical Details](./docs/architecture/TECHNICAL.md) | EN       | Architecture and algorithms |
-| [技术文档](./docs/architecture/TECHNICAL.zh.md)       | 中文     | 架构与算法细节              |
+## Tool roles
 
-### API Documentation Generation
+| Tool / mode     | Preferred use in this repo                                                              |
+| --------------- | --------------------------------------------------------------------------------------- |
+| Copilot CLI     | Primary execution path for repo edits, validation, and `gh` integration                 |
+| `/opsx:explore` | Clarify cross-cutting cleanup before writing code                                       |
+| `/opsx:propose` | Create the change contract before non-trivial work                                      |
+| `/opsx:apply`   | Execute ordered tasks from the approved change                                          |
+| `/review`       | Review meaningful slices before merge/archive                                           |
+| Subagents       | Use for bounded parallel research or isolated validation, not for broad duplicated work |
+| `/fleet`        | Avoid by default; use only when work is clearly parallel and worth the extra cost       |
+| `gh` CLI        | Repository metadata, Actions inspection, release/repo hygiene                           |
 
-Generated via TypeDoc from JSDoc comments in source code:
+## Documentation policy
 
-```bash
-npm run docs:generate  # Output: docs/api/
-```
-
----
-
-## Common Development Tasks
-
-### Adding a New Sorting Algorithm
+- Shared docs default to **English**.
+- Chinese translations live in matching `.zh.md` files when maintained.
+- Delete, merge, or rewrite stale docs instead of layering on generic duplicates.
+- Keep README, docs hub, and Pages messaging aligned; they form one public narrative.
 
-1. Create spec update in `/specs/product/` and `/specs/rfc/`
-2. Create WGSL shader in `src/shaders/{algorithm}.wgsl`
-3. Implement sorter class in `src/sorting/{Algorithm}Sorter.ts`
-4. Add tests in `test/sorting/{Algorithm}Sorter.test.ts`
-5. Export from `src/index.ts`
-6. Update API documentation
+## AI instruction file policy
 
-### Modifying Shader Constants
+| File                              | Purpose                                                              |
+| --------------------------------- | -------------------------------------------------------------------- |
+| `AGENTS.md`                       | Project-wide operational rules and workflow constraints              |
+| `CLAUDE.md`                       | Assistant-focused project instructions                               |
+| `CLAUDE.local.md`                 | Personal local preferences; do not treat as shared project authority |
+| `.github/copilot-instructions.md` | Copilot-specific instructions for this repository                    |
 
-1. Update value in `src/shared/constants.ts`
-2. Update corresponding value in WGSL shader file
-3. Add/update cross-reference comments in both files
-4. Run tests to verify synchronization
-
-### Running Benchmarks Locally
-
-```bash
-npm run dev
-# Open browser to http://localhost:5173
-# Use the interactive UI to run benchmarks
-```
+Keep these files complementary. Do not duplicate long generic boilerplate across them.
 
----
+## Engineering policy
 
-## Standard Open Source Files
+- Keep automation **high-signal**. If a workflow only comments, duplicates stronger checks, or is routinely ignored, simplify or remove it.
+- Prefer repo-scoped committed config first; allow global tooling guidance only when the value is clear for this project.
+- MCP servers and plugins are **opt-in**, not defaults. Choose the lightest setup that meaningfully helps.
+- Pages is a first-class public surface, not an afterthought. Changes that affect project positioning should consider README + docs + site together.
 
-| File                               | Purpose                               | 说明                 |
-| ---------------------------------- | ------------------------------------- | -------------------- |
-| `README.md`                        | Project entry point (English)         | 项目入口（英文）     |
-| `README.zh.md`                     | Chinese version of README             | 中文版 README        |
-| `CONTRIBUTING.md`                  | Contribution guidelines               | 贡献指南             |
-| `CHANGELOG.md`                     | Version history and release notes     | 版本历史与发行说明   |
-| `LICENSE`                          | Open source license                   | 开源协议             |
-| `SECURITY.md`                      | Security policy                       | 安全策略             |
-| `CODE_OF_CONDUCT.md`               | Community behavior guidelines         | 社区行为准则         |
-| `.editorconfig`                    | Cross-editor code style configuration | 跨编辑器代码风格配置 |
-| `.nvmrc`                           | Node.js version specification         | Node.js 版本指定     |
-| `.github/ISSUE_TEMPLATE/`          | Issue templates                       | Issue 模板           |
-| `.github/PULL_REQUEST_TEMPLATE.md` | Pull request template                 | PR 模板              |
+## Code and config conventions
 
----
+- TypeScript: 2 spaces, single quotes, semicolons, strict typing
+- WGSL: keep shader constants synchronized with `src/shared/constants.ts`
+- Tests: update or add tests when behavior changes
+- Docs: prefer concise, project-specific wording over generic open-source filler
+- Public API changes: update OpenSpec first, then docs and exports
 
-## Code Generation Rules
+## Change design heuristics
 
-- Any external API changes **MUST** be proposed via `/opsx:propose` and documented in the corresponding spec.
-  - 任何对外部暴露的 API 变更，必须通过 `/opsx:propose` 提案并在相应规范中记录。
-- If uncertain about technical details, refer to the architectural conventions in `openspec/specs/_archived/`. **Do NOT invent design patterns on your own**.
-  - 如果遇到不确定的技术细节，请查阅 `openspec/specs/_archived/` 下的架构约定，不要自行捏造设计模式。
-- All documentation should be in English by default. Chinese translations should be linked or placed in corresponding `.zh.md` files.
-  - 所有文档默认使用英文。中文翻译应链接到对应的 `.zh.md` 文件。
-- README.md is in English with a link to README.zh.md at the top.
-  - README.md 使用英文，并在开头链接到中文版 README.zh.md。
+When making trade-offs:
 
----
+- choose coherence over feature count
+- choose maintainability over cleverness
+- choose fewer stronger workflows over many weak ones
+- choose purposeful documentation over exhaustive but stale documentation
 
-**Last Updated**: 2026-04-23
+If a change uncovers repository drift, fix the nearby source-of-truth layers instead of leaving the inconsistency behind.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e4e64fd
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+Read `AGENTS.md` first. This file adds Claude/Codex-style assistant guidance specific to this repository.
+
+## Operating stance
+
+- Treat this repo as a **closeout-quality** project: prioritize clarity, alignment, and maintainability.
+- Prefer finishing and simplifying existing surfaces over expanding scope.
+- Keep changes tightly connected to the active OpenSpec change.
+
+## What to optimize for
+
+1. OpenSpec alignment
+2. High-signal workflows and hooks
+3. Coherent public messaging across README, docs, Pages, and GitHub metadata
+4. Minimal-but-effective AI/tooling setup
+
+## Expected workflow
+
+- Explore before broad cleanup
+- Propose before non-trivial implementation
+- Apply tasks in order
+- Run a focused review before calling a slice done
+- Archive the change when tasks and specs are satisfied
+
+## Tooling preferences
+
+- Repo-scoped config is the default source of setup
+- Global LSP/MCP/plugin guidance is allowed only if it clearly helps this project
+- Avoid tool duplication; define distinct roles for Copilot, Claude/Codex, review, and subagents
+
+## Validation baseline
+
+Use the existing commands:
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
+
+## Editing guidance
+
+- Keep docs English-first unless a maintained `.zh.md` companion exists
+- Remove stale or generic documentation rather than preserving it for completeness
+- Treat `site/` as part of the product surface, not as disposable marketing copy

From 410b1eab3d6dcdc1411d4259eb77107f96456fc6 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 03:00:09 +0800
Subject: [PATCH 06/10] docs: streamline public documentation

- Rewrite README with clearer project positioning
- Update README.zh.md translation
- Simplify CHANGELOG to essential entries
- Streamline CONTRIBUTING guide
- Clarify PROJECT_OVERVIEW purpose
---
 CHANGELOG.md        |  93 ++------
 CONTRIBUTING.md     | 505 +++++---------------------------------------
 PROJECT_OVERVIEW.md | 453 ++++-----------------------------------
 README.md           | 336 +++++++----------------------
 README.zh.md        | 333 +++++++----------------------
 5 files changed, 276 insertions(+), 1444 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 59adb6b..72d68a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,91 +1,38 @@
-# Changelog | 更新日志
+# Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project are documented in this file.
 
-本项目所有重要变更都将记录在此文件中。
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),  
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-### Planned | 计划中
-
-- Support for descending sort | 支持降序排序
-- Support for Float32Array sorting | 支持 Float32Array 排序
-- Additional sorting algorithms (Merge Sort, Quick Sort) | 添加更多排序算法（归并排序、快速排序）
-- Custom comparison function support | 支持自定义比较函数
-- Web Worker support | 添加 Web Worker 支持
-- Performance profiling tools | 添加性能分析工具
+### Changed
 
----
+- Ongoing repository normalization for OpenSpec alignment, workflow cleanup, and public project positioning
 
 ## [1.0.1] - 2026-04-16
 
-### Fixed | 修复
-
-- Removed non-null assertions in favor of explicit null checks | 移除非空断言，使用显式空值检查
-- Fixed CI workflow branch names (`main` → `master`) | 修复 CI 工作流分支名称
-- Fixed Pages workflow branch names (`main` → `master`) | 修复 Pages 工作流分支名称
-
-### Optimized | 优化
+### Fixed
 
-- Separated CI jobs (lint, test, build) for better efficiency | 分离 CI 作业以提高效率
-- Added path filtering to Pages workflow | 为 Pages 工作流添加路径过滤
-- Updated ESLint config for examples directory | 更新 examples 目录的 ESLint 配置
+- Replaced non-null assertions with explicit null checks in touched areas
+- Corrected workflow branch references to `master`
 
-### Removed | 移除
+### Changed
 
-- Deleted unused `scan.wgsl` shader file | 删除未使用的 `scan.wgsl` 着色器文件
+- Split CI into clearer lint, test, and build stages
+- Improved Pages workflow path filtering
+- Cleaned up examples-related lint configuration
 
-### CI/CD
+### Removed
 
-- Added `.nojekyll` for GitHub Pages | 添加 `.nojekyll` 文件
-- Added artifact uploads (7 days retention) | 添加构建产物上传（保留 7 天）
-- Added coverage report uploads (30 days) | 添加覆盖率报告上传（保留 30 天）
-
-### Documentation | 文档
-
-- Fixed API documentation type definitions | 修复 API 文档类型定义
-- Updated all architecture diagrams | 更新所有架构图
-- Added bilingual documentation support | 添加双语文档支持
-
----
+- Unused `scan.wgsl` shader file
 
 ## [1.0.0] - 2026-01-02
 
-### Added | 新增
-
-- **Bitonic Sort** implementation with GPU optimization | 双调排序实现，GPU 优化
-- **Radix Sort** implementation with parallel histogram | 基数排序实现，并行直方图
-- **WebGPU Core Infrastructure**: GPUContext, BufferManager, Validator | WebGPU 核心基础设施
-- **Benchmark Utility** for performance testing | 基准测试工具
-- **Interactive Demo** with real-time results | 交互式演示
-- **Comprehensive Documentation** (5 documents) | 完整文档（5 个文档）
-- **61 Unit Tests** with property-based testing | 61 个单元测试，属性测试
-
-### Performance | 性能
-
-- Bitonic Sort: 20x speedup for 1M elements | 双调排序：100 万元素 20 倍加速
-- Radix Sort: 13x speedup for 1M elements | 基数排序：100 万元素 13 倍加速
-
----
-
-## Version History | 版本历史
-
-| Version | Date       | Changes                                         |
-| ------- | ---------- | ----------------------------------------------- |
-| 1.0.1   | 2026-04-16 | Code quality, CI/CD optimization, documentation |
-| 1.0.0   | 2026-01-02 | Initial release with two sorting algorithms     |
-
----
-
-## Links | 链接
-
-- [GitHub Releases](https://github.com/LessUp/webgpu-sorting/releases)
-
----
+### Added
 
-**Last Updated**: 2026-04-17
+- Bitonic sort implementation
+- Radix sort implementation
+- WebGPU runtime helpers (`GPUContext`, `BufferManager`, `Validator`)
+- Benchmark utility and browser demo
+- Initial documentation and automated test suite
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 11f6cb5..5350634 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,493 +1,92 @@
-# 贡献指南
+# Contributing
 
-感谢你对 WebGPU Sorting 项目的关注！我们欢迎各种形式的贡献。
+Thanks for your interest in WebGPU Sorting.
 
-## 目录
+## Before you change code
 
-1. [行为准则](#行为准则)
-2. [如何贡献](#如何贡献)
-3. [开发环境设置](#开发环境设置)
-4. [代码规范](#代码规范)
-5. [提交规范](#提交规范)
-6. [测试要求](#测试要求)
-7. [Pull Request 流程](#pull-request-流程)
+For any non-trivial change, use the project's OpenSpec workflow first:
 
----
-
-## 行为准则
-
-本项目遵循开源社区的基本准则：
-
-- 尊重所有贡献者
-- 接受建设性批评
-- 关注对项目最有利的事情
-- 对社区成员表现出同理心
-
----
-
-## 如何贡献
-
-### 报告 Bug
-
-如果你发现了 bug，请创建一个 Issue 并包含：
-
-1. **清晰的标题**: 简洁描述问题
-2. **复现步骤**: 详细的步骤说明
-3. **预期行为**: 你期望发生什么
-4. **实际行为**: 实际发生了什么
-5. **环境信息**:
-   - 浏览器版本
-   - 操作系统
-   - GPU 型号
-   - Node.js 版本
-
-**示例:**
-
-```markdown
-## Bug: 双调排序在大数组上失败
-
-### 复现步骤
-
-1. 创建 1M 元素的数组
-2. 调用 bitonicSorter.sort(data)
-3. 观察错误
-
-### 预期行为
-
-排序成功完成
-
-### 实际行为
-
-抛出 "Out of memory" 错误
-
-### 环境
-
-- Chrome 113.0.5672.126
-- Windows 11
-- NVIDIA RTX 3060
-- Node.js 18.16.0
+```text
+/opsx:explore → /opsx:propose → /opsx:apply → /review → /opsx:archive
 ```
 
-### 提出新功能
-
-如果你有新功能的想法，请先创建一个 Issue 讨论：
-
-1. **功能描述**: 详细说明功能
-2. **使用场景**: 为什么需要这个功能
-3. **实现建议**: 如何实现（可选）
-4. **替代方案**: 其他可能的解决方案
+Why this matters:
 
-### 改进文档
+- specs stay aligned with implementation
+- docs and workflow changes do not drift silently
+- cross-cutting cleanup can be executed in a controlled order
 
-文档改进总是受欢迎的：
+For the project-specific AI/tooling workflow, see [docs/setup/WORKFLOW.md](./docs/setup/WORKFLOW.md).
 
-- 修正拼写错误
-- 改进示例代码
-- 添加更多使用场景
-- 翻译文档
+## What kinds of contributions fit this repo
 
----
+Good contributions usually fall into one of these buckets:
 
-## 开发环境设置
+- bug fixes
+- documentation corrections or consolidation
+- workflow / tooling improvements with clear payoff
+- small maintainability improvements around the existing sorting implementations
 
-### 1. Fork 和克隆
-
-```bash
-# Fork 项目到你的 GitHub 账号
-# 然后克隆你的 fork
-
-git clone https://github.com/LessUp/webgpu-sorting.git
-cd webgpu-sorting
-```
+Large feature expansions should start with a clear OpenSpec proposal and a strong justification.
 
-### 2. 安装依赖
+## Local setup
 
 ```bash
 npm install
 ```
 
-### 3. 创建分支
+Useful commands:
 
 ```bash
-git checkout -b feature/your-feature-name
-# 或
-git checkout -b fix/your-bug-fix
-```
-
-### 4. 开发
-
-```bash
-# 启动开发服务器
-npm run dev
-
-# 运行测试（监听模式）
-npm run test:watch
-
-# 类型检查
 npm run lint
-```
-
----
-
-## 代码规范
-
-### TypeScript 风格
-
-```typescript
-// ✅ 好: 使用明确的类型
-function sort(data: Uint32Array): Promise<SortResult> {
-  // ...
-}
-
-// ❌ 差: 使用 any
-function sort(data: any): Promise<any> {
-  // ...
-}
-
-// ✅ 好: 使用接口定义复杂类型
-interface SortResult {
-  sortedData: Uint32Array;
-  gpuTimeMs: number;
-  totalTimeMs: number;
-}
-
-// ✅ 好: 使用 async/await
-async function initialize(): Promise<void> {
-  await this.requestAdapter();
-  await this.requestDevice();
-}
-
-// ❌ 差: 使用 Promise 链
-function initialize(): Promise<void> {
-  return this.requestAdapter().then(() => this.requestDevice());
-}
-```
-
-### WGSL 风格
-
-```wgsl
-// ✅ 好: 使用有意义的变量名
-fn compare_and_swap(index_a: u32, index_b: u32, ascending: bool) {
-  let value_a = data[index_a];
-  let value_b = data[index_b];
-  // ...
-}
-
-// ❌ 差: 使用单字母变量名
-fn compare_and_swap(i: u32, j: u32, a: bool) {
-  let x = data[i];
-  let y = data[j];
-  // ...
-}
-
-// ✅ 好: 添加注释说明同步点
-workgroupBarrier();  // 同步: 确保所有线程完成数据加载
-
-// ✅ 好: 使用常量
-const WORKGROUP_SIZE: u32 = 256u;
-const RADIX: u32 = 16u;
-```
-
-### 命名约定
-
-```typescript
-// 类名: PascalCase
-class BitonicSorter { }
-class GPUContext { }
-
-// 方法和变量: camelCase
-async sort(data: Uint32Array) { }
-const gpuTimeMs = 10.5;
-
-// 常量: UPPER_SNAKE_CASE
-const WORKGROUP_SIZE = 256;
-const MAX_BUFFER_SIZE = 1024 * 1024;
-
-// 私有成员: 前缀 _
-private _device: GPUDevice;
-private _pipeline: GPUComputePipeline;
-
-// 接口: PascalCase
-interface SortResult { }
-interface ValidationResult { }
-```
-
-### 注释规范
-
-````typescript
-/**
- * 对 Uint32Array 进行双调排序
- *
- * @param data - 要排序的数组
- * @returns 排序结果，包含排序后的数组和性能指标
- * @throws {Error} 如果数组为空或设备未初始化
- *
- * @example
- * ```typescript
- * const sorter = new BitonicSorter(context);
- * const result = await sorter.sort(new Uint32Array([5, 2, 8, 1]));
- * console.log(result.sortedData); // [1, 2, 5, 8]
- * ```
- */
-async sort(data: Uint32Array): Promise<SortResult> {
-  // 实现...
-}
-````
-
----
-
-## 提交规范
-
-使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-### Type 类型
-
-- `feat`: 新功能
-- `fix`: Bug 修复
-- `docs`: 文档更新
-- `style`: 代码格式（不影响功能）
-- `refactor`: 重构（不是新功能也不是 bug 修复）
-- `perf`: 性能优化
-- `test`: 添加或修改测试
-- `chore`: 构建过程或辅助工具的变动
-
-### 示例
-
-```bash
-# 新功能
-git commit -m "feat(radix): add 8-bit radix sort variant"
-
-# Bug 修复
-git commit -m "fix(bitonic): correct padding calculation for odd sizes"
-
-# 文档
-git commit -m "docs(api): add examples for Benchmark class"
-
-# 性能优化
-git commit -m "perf(radix): optimize histogram computation with shared memory"
-
-# 测试
-git commit -m "test(validator): add property tests for edge cases"
-```
-
----
-
-## 测试要求
-
-### 运行测试
-
-```bash
-# 运行所有测试
-npm test
-
-# 监听模式
-npm run test:watch
-
-# 覆盖率报告
-npm run test:coverage
-```
-
-### 测试类型
-
-#### 1. 单元测试
-
-测试单个函数或方法：
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { BufferManager } from '../src/core/BufferManager';
-
-describe('BufferManager', () => {
-  it('should align size correctly', () => {
-    expect(BufferManager.alignSize(100, 256)).toBe(256);
-    expect(BufferManager.alignSize(256, 256)).toBe(256);
-    expect(BufferManager.alignSize(257, 256)).toBe(512);
-  });
-});
-```
-
-#### 2. 属性测试
-
-使用 fast-check 测试通用属性：
-
-```typescript
-import { describe, it } from 'vitest';
-import fc from 'fast-check';
-import { Validator } from '../src/core/Validator';
-
-describe('Validator Properties', () => {
-  it('sorted array should pass isSorted check', () => {
-    fc.assert(
-      fc.property(fc.array(fc.nat(1000000), { minLength: 0, maxLength: 1000 }), (arr) => {
-        const sorted = new Uint32Array(arr.sort((a, b) => a - b));
-        expect(Validator.isSorted(sorted)).toBe(true);
-      }),
-      { numRuns: 100 }
-    );
-  });
-});
-```
-
-### 测试覆盖率要求
-
-- 核心功能: 90%+
-- 工具函数: 100%
-- 错误处理: 80%+
-
----
-
-## Pull Request 流程
-
-### 1. 准备工作
-
-```bash
-# 确保所有测试通过
-npm test
-
-# 确保类型检查通过
-npm run lint
-
-# 确保构建成功
+npm run typecheck
+npm run test
 npm run build
+npm run dev
 ```
 
-### 2. 创建 Pull Request
-
-1. 推送你的分支到 GitHub
-2. 在 GitHub 上创建 Pull Request
-3. 填写 PR 模板
-
-**PR 标题格式:**
-
-```
-<type>: <description>
-```
-
-**PR 描述模板:**
-
-```markdown
-## 变更类型
-
-- [ ] Bug 修复
-- [ ] 新功能
-- [ ] 性能优化
-- [ ] 文档更新
-- [ ] 代码重构
-
-## 变更说明
-
-简要描述你的变更...
-
-## 相关 Issue
-
-Closes #123
-
-## 测试
-
-- [ ] 添加了新测试
-- [ ] 所有测试通过
-- [ ] 手动测试通过
-
-## 检查清单
-
-- [ ] 代码遵循项目规范
-- [ ] 添加了必要的注释
-- [ ] 更新了相关文档
-- [ ] 没有引入新的警告
-```
-
-### 3. Code Review
-
-- 响应审查意见
-- 进行必要的修改
-- 保持讨论专业和建设性
+## Contributor expectations
 
-### 4. 合并
+### 1. Keep changes scoped
 
-PR 将在以下条件满足后合并：
+- prefer small serial changes over long-lived branches
+- avoid mixing unrelated cleanup into one PR or change
+- remove or rewrite stale material instead of stacking new generic docs on top
 
-- 至少一个维护者批准
-- 所有测试通过
-- 没有合并冲突
-- 遵循代码规范
+### 2. Keep source-of-truth layers aligned
 
----
+If your change affects behavior, workflow, or public positioning, update the matching authority files:
 
-## 开发技巧
-
-### 调试 WebGPU
-
-```typescript
-// 启用错误作用域
-device.pushErrorScope('validation');
-// ... GPU 操作 ...
-const error = await device.popErrorScope();
-if (error) console.error('GPU Error:', error.message);
-
-// 添加标签便于调试
-const buffer = device.createBuffer({
-  label: 'debug-my-buffer',
-  size: 1024,
-  usage: GPUBufferUsage.STORAGE,
-});
-```
+- `openspec/` for requirements and task flow
+- `README.md` / `docs/` for public explanation
+- `AGENTS.md`, `CLAUDE.md`, and Copilot instructions for AI workflow guidance
 
-### 性能分析
-
-```typescript
-// 使用 performance API
-const start = performance.now();
-await sorter.sort(data);
-const duration = performance.now() - start;
-console.log('Duration:', duration, 'ms');
-
-// 使用 Chrome DevTools
-// 1. 打开 Performance 面板
-// 2. 录制排序操作
-// 3. 分析 GPU 时间
-```
-
-### 测试 WGSL 着色器
-
-```typescript
-// 检查编译信息
-const shaderModule = device.createShaderModule({
-  code: wgslCode,
-});
-
-const compilationInfo = await shaderModule.getCompilationInfo();
-for (const message of compilationInfo.messages) {
-  console.log(`${message.type}: ${message.message}`);
-}
-```
+### 3. Use review intentionally
 
----
+Before considering a meaningful slice complete, run a review step such as `/review` or an equivalent focused code review pass.
 
-## 获取帮助
+### 4. Keep docs English-first
 
-如果你有任何问题：
+English is the default language for shared docs. Add a `.zh.md` companion only if you will keep it aligned.
 
-1. 查看 [文档](./docs/README.md)
-2. 搜索 [已有 Issues](https://github.com/LessUp/webgpu-sorting/issues)
-3. 创建新 Issue 提问
-4. 加入讨论区
+## Pull request guidance
 
----
+- explain the user-visible or maintainer-visible impact
+- call out spec/doc/workflow changes explicitly
+- mention any GitHub-side changes made through `gh`
+- avoid noisy “drive-by” edits outside the task scope
 
-## 许可证
+## Reporting bugs
 
-通过贡献代码，你同意你的贡献将在 MIT 许可证下发布。
+When filing a bug, include:
 
----
+- browser and version
+- OS
+- GPU model when relevant
+- WebGPU availability details
+- reproduction steps
+- expected vs actual behavior
 
-## 致谢
+## Code of conduct
 
-感谢所有贡献者的付出！你的贡献让这个项目变得更好。
+This project follows [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
diff --git a/PROJECT_OVERVIEW.md b/PROJECT_OVERVIEW.md
index e7a0e72..f39d581 100644
--- a/PROJECT_OVERVIEW.md
+++ b/PROJECT_OVERVIEW.md
@@ -1,431 +1,70 @@
-# WebGPU Sorting - Project Overview
+# Project Overview
 
-## Project Status
+## Purpose
 
-✅ **Complete** - All features implemented, tests passing, documentation complete
+WebGPU Sorting is a browser-focused GPU sorting project built around WebGPU compute shaders. The repository serves three roles at once:
 
-- **Version**: 1.0.1
-- **Tests**: 61/61 passing ✅
-- **Build**: Successful ✅
-- **Documentation**: Complete ✅
-- **CI/CD**: Configured ✅
+1. A small TypeScript library for GPU sorting experiments
+2. A benchmark/demo application
+3. A curated reference repo for WebGPU compute, project quality, and OpenSpec-driven maintenance
 
----
+## Current repository shape
 
-## Project Structure
-
-```
-webgpu-sorting/
-├── 📄 Core Documents
-│   ├── README.md                    # Project homepage, feature overview
-│   ├── CHANGELOG.md                 # Version history and release notes
-│   ├── CONTRIBUTING.md              # Contribution guidelines
-│   ├── LICENSE                      # MIT License
-│   ├── CODE_OF_CONDUCT.md           # Code of conduct
-│   ├── SECURITY.md                  # Security policy
-│   └── AGENTS.md                    # AI agent workflow (Spec-Driven Development)
-│
-├── 📚 Specifications (specs/)
-│   ├── product/                     # Product requirements (PRDs)
-│   │   ├── 0001-webgpu-sorting.md   # Core sorting algorithms spec
-│   │   └── 0002-project-quality-enhancement.md
-│   ├── rfc/                         # Technical design documents
-│   │   └── 0001-core-architecture.md
-│   ├── api/                         # API interface definitions
-│   ├── db/                          # Database/model specs
-│   └── testing/                     # BDD test specifications
-│
-├── 📖 User Documentation (docs/)
-│   ├── README.md                    # Documentation index
-│   ├── setup/                       # Installation & setup guides
-│   │   ├── GETTING_STARTED.md       # English getting started
-│   │   └── GETTING_STARTED.zh.md    # Chinese getting started
-│   ├── tutorials/                   # API tutorials
-│   │   ├── API.md                   # English API reference
-│   │   └── API.zh.md                # Chinese API reference
-│   ├── architecture/                # Technical deep-dives
-│   │   ├── TECHNICAL.md             # English technical docs
-│   │   └── TECHNICAL.zh.md          # Chinese technical docs
-│   └── changelog/                   # Version history
-│       ├── README.md                # Changelog index
-│       ├── en/                      # English changelogs
-│       └── zh/                      # Chinese changelogs
-│
-├── 💡 Example Code (examples/)
-│   ├── README.md                    # Example documentation
-│   ├── basic-usage.ts               # Basic usage
-│   ├── performance-comparison.ts    # Performance comparison
-│   ├── batch-processing.ts          # Batch processing
-│   └── error-handling.ts            # Error handling
-│
-├── 💻 Source Code (src/)
-│   ├── core/                        # WebGPU core infrastructure
-│   │   ├── GPUContext.ts            # GPU environment management
-│   │   ├── BufferManager.ts         # Buffer management
-│   │   ├── Validator.ts             # Result validation
-│   │   └── errors.ts                # Error type definitions
-│   │
-│   ├── sorting/                     # Sorting algorithm implementations
-│   │   ├── BitonicSorter.ts         # Bitonic sort
-│   │   └── RadixSorter.ts           # Radix sort
-│   │
-│   ├── shaders/                     # WGSL compute shaders
-│   │   ├── bitonic.wgsl             # Bitonic sort shader
-│   │   └── radix.wgsl               # Radix sort shader
-│   │
-│   ├── benchmark/                   # Performance benchmarking
-│   │   └── Benchmark.ts             # Benchmark utility
-│   │
-│   ├── index.ts                     # Library exports
-│   ├── main.ts                      # Demo interface logic
-│   └── types.ts                     # Type definitions
-│
-├── 🧪 Test Code (test/)
-│   ├── core/                        # Core module tests
-│   │   ├── GPUContext.test.ts       # 8 tests
-│   │   ├── BufferManager.test.ts    # 3 tests
-│   │   └── Validator.test.ts        # 10 tests
-│   │
-│   ├── sorting/                     # Sorting algorithm tests
-│   │   ├── BitonicSorter.test.ts    # 3 tests
-│   │   └── RadixSorter.test.ts      # 4 tests
-│   │
-│   └── benchmark/                   # Benchmark tests
-│       └── Benchmark.test.ts        # 10 tests
-│
-├── 🎨 Demo Interface
-│   └── index.html                   # Interactive demo page
-│
-├── ⚙️ GitHub Configuration (.github/)
-│   ├── workflows/
-│   │   ├── ci.yml                   # CI workflow
-│   │   └── pages.yml                # GitHub Pages deployment
-│   ├── ISSUE_TEMPLATE/
-│   │   ├── bug_report.md            # Bug report template
-│   │   └── feature_request.md       # Feature request template
-│   └── PULL_REQUEST_TEMPLATE.md     # PR template
-│
-└── ⚙️ Configuration Files
-    ├── package.json                 # Project configuration
-    ├── tsconfig.json                # TypeScript configuration
-    ├── vite.config.ts               # Vite configuration
-    ├── vitest.config.ts             # Vitest configuration
-    ├── .eslintrc.cjs                # ESLint configuration
-    ├── .prettierrc                  # Prettier configuration
-    ├── .editorconfig                # Editor configuration
-    ├── .nvmrc                       # Node.js version
-    └── .gitignore                   # Git ignore rules
+```text
+openspec/   Specs, active changes, templates, archive
+docs/       User-facing documentation
+site/       GitHub Pages site source
+src/        Library and demo implementation
+test/       Vitest suite
+examples/   Usage snippets
 ```
 
----
-
-## Core Features
-
-### 1. Bitonic Sort
-
-**Characteristics:**
-
-- Time Complexity: O(n log²n)
-- Space Complexity: O(1) in-place
-- Suitable for GPU parallelization
-
-**Technical Highlights:**
-
-- Uses `workgroupBarrier()` for thread synchronization
-- Shared memory optimization for intra-workgroup sorting
-- Supports arbitrary array sizes (automatic padding)
-
-**Files:**
-
-- `src/sorting/BitonicSorter.ts`
-- `src/shaders/bitonic.wgsl`
-- `test/sorting/BitonicSorter.test.ts`
-
-### 2. Radix Sort
-
-**Characteristics:**
-
-- Time Complexity: O(n × k), k = number of digits
-- Space Complexity: O(n) requires auxiliary array
-- Non-comparison sort, theoretically faster
-
-**Technical Highlights:**
-
-- 4-bit radix (16 buckets), 8 passes
-- Parallel histogram computation (Parallel Reduction)
-- CPU-side prefix sum computation (simplified)
-- Parallel data rearrangement (Scatter)
-
-**Files:**
-
-- `src/sorting/RadixSorter.ts`
-- `src/shaders/radix.wgsl`
-- `test/sorting/RadixSorter.test.ts`
-
-### 3. WebGPU Infrastructure
-
-**GPUContext:**
-
-- WebGPU environment initialization
-- Adapter and device management
-- Resource lifecycle management
-
-**BufferManager:**
-
-- GPU buffer creation
-- CPU-GPU data transfer
-- Buffer size alignment
-
-**Validator:**
-
-- Sorting result validation
-- Check if array is sorted
-- Check element preservation
-
-**Files:**
-
-- `src/core/GPUContext.ts`
-- `src/core/BufferManager.ts`
-- `src/core/Validator.ts`
-- `src/core/errors.ts`
-
-### 4. Performance Benchmarking
-
-**Features:**
-
-- Single test and full test suite
-- Automatic speedup calculation
-- GPU vs JS Array.sort() comparison
-- Multiple iterations for averaging
-
-**Files:**
-
-- `src/benchmark/Benchmark.ts`
-- `test/benchmark/Benchmark.test.ts`
-
-### 5. Demo Interface
-
-**Features:**
-
-- Algorithm selection (Bitonic/Radix/Both)
-- Array size selection (1K/10K/100K/1M)
-- Iteration count setting
-- Real-time progress display
-- Results visualization
-
-**Files:**
-
-- `index.html`
-- `src/main.ts`
-
----
-
-## Test Coverage
-
-### Test Statistics
-
-| Module        | Tests  | Status          |
-| ------------- | ------ | --------------- |
-| GPUContext    | 8      | ✅ Pass         |
-| BufferManager | 3      | ✅ Pass         |
-| Validator     | 10     | ✅ Pass         |
-| BitonicSorter | 3      | ✅ Pass         |
-| RadixSorter   | 4      | ✅ Pass         |
-| Benchmark     | 10     | ✅ Pass         |
-| **Total**     | **61** | **✅ All Pass** |
-
-### Test Types
-
-1. **Unit Tests**: Test individual functions and methods
-2. **Property-Based Tests**: Using fast-check for random testing (100+ iterations)
-3. **Integration Tests**: Test module interactions
-
-### Tested Properties
-
-- Property 1: Buffer Round-Trip Consistency
-- Property 2: Buffer Size Alignment
-- Property 3: Bitonic Padding to Power of 2
-- Property 4: Bitonic Sort Correctness
-- Property 5: Radix Sort Correctness
-- Property 6: Speedup Calculation Correctness
-- Property 7: Average Time Calculation
-- Property 8: isSorted Validator Correctness
-- Property 9: hasSameElements Validator Correctness
-
----
+## Source-of-truth order
 
-## CI/CD Configuration
+When these layers disagree, treat them in this order:
 
-### GitHub Actions Workflows
+1. `openspec/changes/<change-id>/` for active change intent and tasks
+2. `openspec/specs/` for stable requirements
+3. `src/` and `test/` for implementation reality
+4. README, docs, and Pages for public explanation
 
-#### CI Workflow (`.github/workflows/ci.yml`)
+## Main code areas
 
-- **Trigger**: Push to master branch, or Pull Request
-- **Jobs**:
-  1. **lint**: ESLint + Prettier + TypeScript check
-  2. **test**: Run on Node.js 18.x and 20.x
-  3. **build**: Production build
-- **Artifacts**: Coverage reports (30 days retention), build artifacts (7 days)
+| Area                         | Purpose                                     |
+| ---------------------------- | ------------------------------------------- |
+| `src/core/`                  | WebGPU context, buffers, validation, errors |
+| `src/sorting/`               | Bitonic and radix sorter implementations    |
+| `src/shaders/`               | WGSL compute shaders                        |
+| `src/benchmark/`             | Performance comparison utilities            |
+| `src/main.ts` + `index.html` | Browser demo entry                          |
 
-#### Pages Workflow (`.github/workflows/pages.yml`)
+## Main non-code areas
 
-- **Trigger**: Push to master branch (only relevant files)
-- **Target**: GitHub Pages
-- **Optimization**: Path filtering, `.nojekyll` support
+| Area                              | Purpose                                  |
+| --------------------------------- | ---------------------------------------- |
+| `AGENTS.md`                       | Project-wide AI and workflow conventions |
+| `CLAUDE.md`                       | Project-specific assistant instructions  |
+| `.github/copilot-instructions.md` | Copilot project instructions             |
+| `.github/workflows/`              | CI, Pages, release, security workflows   |
+| `.vscode/`                        | Workspace editor defaults                |
+| `.husky/`                         | Git hook entrypoints                     |
 
----
+## Validation baseline
 
-## Performance Metrics
-
-### Expected Performance
-
-| Array Size | JS Sort | Bitonic Sort | Radix Sort | Bitonic Speedup | Radix Speedup |
-| ---------- | ------- | ------------ | ---------- | --------------- | ------------- |
-| 1K         | ~0.1ms  | ~0.5ms       | ~0.8ms     | 0.2x            | 0.1x          |
-| 10K        | ~1ms    | ~0.8ms       | ~1ms       | 1.3x            | 1.0x          |
-| 100K       | ~15ms   | ~2ms         | ~3ms       | 7.5x            | 5.0x          |
-| 1M         | ~200ms  | ~10ms        | ~15ms      | 20x             | 13x           |
-
-### Performance Factors
-
-1. **GPU Hardware**: Discrete GPU > Integrated GPU
-2. **Data Transfer**: CPU ↔ GPU transfer is main overhead
-3. **Array Size**: Large arrays better showcase GPU advantage
-4. **Browser Implementation**: Varies across browsers
-
----
-
-## Browser Compatibility
-
-| Browser | Version | Status          |
-| ------- | ------- | --------------- |
-| Chrome  | 113+    | ✅ Full Support |
-| Edge    | 113+    | ✅ Full Support |
-| Firefox | Nightly | ⚠️ Experimental |
-| Safari  | 18+     | ⚠️ Partial      |
-| Opera   | 99+     | ✅ Supported    |
-
----
-
-## Tech Stack
-
-### Core Technologies
-
-- **WebGPU**: GPU compute API
-- **WGSL**: WebGPU Shading Language
-- **TypeScript**: Type-safe JavaScript
-- **Vite**: Fast dev server and build tool
-
-### Testing Tools
-
-- **Vitest**: Fast unit testing framework
-- **fast-check**: Property-based testing library
-
-### Development Tools
-
-- **Node.js**: JavaScript runtime
-- **npm**: Package manager
-- **ESLint**: Code linting
-- **Prettier**: Code formatting
-- **Husky**: Git hooks
-
----
-
-## Quick Commands
+The repository currently uses these validation commands:
 
 ```bash
-# Install dependencies
-npm install
-
-# Development server
-npm run dev
-
-# Run tests
-npm test
-
-# Watch tests
-npm run test:watch
-
-# Test coverage
-npm run test:coverage
-
-# Code linting
 npm run lint
-
-# Code formatting
-npm run format
-
-# Type checking
 npm run typecheck
-
-# Production build
+npm run test
 npm run build
-
-# Preview build
-npm run preview
 ```
 
----
-
-## Project Highlights
-
-### Resume-Worthy Skills
-
-1. **workgroupBarrier()**: Demonstrates understanding of GPU thread synchronization
-2. **Shared Memory**: Intra-workgroup shared memory optimization
-3. **Parallel Reduction**: GPU implementation of MapReduce's Reduce phase
-4. **Non-Graphics Task**: Pure data processing showcasing GPU general-purpose computing
-
-### Engineering Practices
-
-1. **Complete Testing**: 61 tests, 100% pass rate
-2. **Property Testing**: Random testing with fast-check
-3. **Type Safety**: Complete TypeScript type definitions
-4. **Error Handling**: Custom error types and complete error handling
-5. **Documentation**: Comprehensive documentation covering all aspects
-6. **Code Examples**: 4 practical examples covering common scenarios
-7. **CI/CD**: Complete automation workflow
-
----
-
-## Roadmap
-
-### Feature Extensions
-
-- [ ] Support descending sort
-- [ ] Support Float32Array sorting
-- [ ] Add more sorting algorithms (merge sort, quick sort)
-- [ ] Support custom comparators
-- [ ] Add Web Worker support
-
-### Performance Optimizations
-
-- [ ] Optimize small array performance
-- [ ] Reduce CPU-GPU data transfer
-- [ ] Support streaming processing
-- [ ] Add caching mechanism
-- [ ] Implement GPU-side prefix sum (Blelloch Scan)
-
-### Documentation Improvements
-
-- [ ] Add video tutorials
-- [ ] Add interactive demo
-- [ ] Add more examples
-
----
-
-## License
-
-MIT License - See [LICENSE](./LICENSE) file
-
----
-
-## Acknowledgments
-
-Thanks to all developers contributing to WebGPU and open source community!
+## Maintenance posture
 
----
+This repository should optimize for coherence and trust:
 
-**Last Updated**: 2026-04-17  
-**Version**: 1.0.1  
-**Status**: ✅ Complete
+- keep docs purposeful
+- keep workflows high-signal
+- keep OpenSpec current
+- prefer small serial improvements over sprawling branches
diff --git a/README.md b/README.md
index f318cb2..1a86a70 100644
--- a/README.md
+++ b/README.md
@@ -1,306 +1,130 @@
 # WebGPU Sorting
 
 <p align="center">
-  <strong>High-Performance GPU Sorting Algorithms Using WebGPU Compute Shaders</strong>
+  <strong>GPU-accelerated sorting for Uint32Array workloads using WebGPU compute shaders.</strong>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/webgpu-sorting"><img src="https://img.shields.io/npm/v/webgpu-sorting" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/webgpu-sorting"><img src="https://img.shields.io/npm/dw/webgpu-sorting" alt="npm downloads"></a>
-  <img src="https://img.shields.io/bundlephobia/minzip/webgpu-sorting" alt="bundle size">
-  <a href="https://github.com/LessUp/webgpu-sorting/actions"><img src="https://img.shields.io/badge/CI-passing-brightgreen" alt="CI Status"></a>
-  <img src="https://img.shields.io/badge/WebGPU-Compute-blue" alt="WebGPU">
-  <img src="https://img.shields.io/badge/TypeScript-5.3-blue" alt="TypeScript">
-  <img src="https://img.shields.io/badge/tests-61%20passed-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/license-MIT-yellow" alt="License">
+  <a href="https://lessup.github.io/webgpu-sorting/">Home</a> •
+  <a href="https://lessup.github.io/webgpu-sorting/demo/">Live Demo</a> •
+  <a href="./docs/README.md">Docs</a> •
+  <a href="./README.zh.md">中文</a>
 </p>
 
-<p align="center">
-  <a href="https://lessup.github.io/webgpu-sorting/">🚀 Live Demo</a> •
-  <a href="./README.zh.md">🇨🇳 中文版</a>
-</p>
-
----
-
-## Overview
-
-WebGPU Sorting is a high-performance sorting library that leverages the WebGPU API to execute sorting algorithms on the GPU. It provides significant performance improvements over JavaScript's native `Array.sort()` for large datasets.
-
-**Key Features:**
-
-- **10-100x performance** improvement for large arrays (100K+ elements)
-- Two optimized algorithms: **Bitonic Sort** and **Radix Sort**
-- Clean TypeScript API with full type safety
-- Zero dependencies, small bundle size (~10KB gzipped)
-- Comprehensive test coverage (61 tests)
-- Works in all WebGPU-enabled browsers
-
----
+## What this project is
 
-## Algorithms
+WebGPU Sorting is a TypeScript library and demo project that explores high-throughput GPU sorting in the browser. It ships two compute-shader implementations:
 
-| Algorithm        | Time Complexity | Space Complexity | Best For                       |
-| ---------------- | --------------- | ---------------- | ------------------------------ |
-| **Bitonic Sort** | O(n log²n)      | O(1) - in-place  | Medium arrays, general purpose |
-| **Radix Sort**   | O(n × k)        | O(n)             | Large arrays, 32-bit integers  |
+- **Bitonic Sort** for predictable sorting-network behavior
+- **Radix Sort** for large `Uint32Array` workloads
 
-**Algorithm Selection Guide:**
+The repository also includes a benchmark utility, an interactive demo, a custom GitHub Pages site, and an OpenSpec-driven workflow for maintaining the project coherently.
 
-| Array Size           | Recommendation        | Reason                       |
-| -------------------- | --------------------- | ---------------------------- |
-| < 10,000             | Native `Array.sort()` | GPU overhead not worth it    |
-| 10K - 100K           | Bitonic Sort          | Best overall performance     |
-| > 100K               | Radix Sort            | Linear time complexity wins  |
-| 32-bit integers only | Radix Sort            | Optimal for fixed-width data |
+## What you get
 
----
+- A small TypeScript API around WebGPU setup and sorting execution
+- WGSL shader implementations for bitonic and radix sorting
+- Browser benchmark helpers for comparing GPU and JS sorting
+- A live demo site for trying the project quickly
+- OpenSpec specs and tasks for structured maintenance
 
-## Quick Start
+## Quick start
 
-### Installation
-
-#### npm (Recommended)
+### Install
 
 ```bash
 npm install webgpu-sorting
 ```
 
-#### CDN / ES Module
-
-```html
-<script type="module">
-  import { BitonicSorter, GPUContext } from 'https://unpkg.com/webgpu-sorting@latest/dist/index.js';
-</script>
-```
-
-#### Development (Clone Repository)
-
-```bash
-# Clone the repository
-git clone https://github.com/LessUp/webgpu-sorting.git
-cd webgpu-sorting
-
-# Install dependencies
-npm install
-
-# Start development server
-npm run dev
-```
-
-### Basic Usage (npm)
-
-```typescript
-import { GPUContext, BitonicSorter, Validator } from 'webgpu-sorting';
+### Use in code
 
-async function main() {
-  // 1. Initialize WebGPU
-  const context = new GPUContext();
-  await context.initialize();
+```ts
+import { GPUContext, BitonicSorter } from 'webgpu-sorting';
 
-  // 2. Create sorter
-  const sorter = new BitonicSorter(context);
+const context = new GPUContext();
+await context.initialize();
 
-  // 3. Prepare data
-  const data = new Uint32Array([5, 2, 8, 1, 9, 3, 7, 4, 6, 0]);
+const sorter = new BitonicSorter(context);
+const input = new Uint32Array([5, 2, 8, 1, 9, 3]);
+const result = await sorter.sort(input);
 
-  // 4. Sort
-  const result = await sorter.sort(data);
-  console.log('Sorted:', result.sortedData); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+console.log(result.sortedData);
 
-  // 5. Validate
-  const validation = Validator.validate(data, result.sortedData);
-  console.log('Valid:', validation.isValid);
-
-  // 6. Cleanup
-  sorter.destroy();
-  context.destroy();
-}
-
-main();
+sorter.destroy();
+context.destroy();
 ```
 
-### Using Radix Sort (for 32-bit integers)
-
-```typescript
-import { GPUContext, RadixSorter } from 'webgpu-sorting';
-
-async function main() {
-  const context = new GPUContext();
-  await context.initialize();
+## Choosing an algorithm
 
-  // Use RadixSorter for better performance on 32-bit integers
-  const sorter = new RadixSorter(context);
-  const data = new Uint32Array([
-    /* 100K+ elements */
-  ]);
+| Use case                                    | Recommended sorter    | Why                                                          |
+| ------------------------------------------- | --------------------- | ------------------------------------------------------------ |
+| General browser demo or medium-sized arrays | `BitonicSorter`       | Simple parallel sorting network and stable project reference |
+| Large integer arrays (`Uint32Array`)        | `RadixSorter`         | Better scaling for fixed-width integer data                  |
+| Small arrays                                | Native `Array.sort()` | GPU setup and transfer overhead can dominate                 |
 
-  const result = await sorter.sort(data);
-  console.log('Sorted:', result.sortedData);
+## Browser support
 
-  sorter.destroy();
-  context.destroy();
-}
+| Browser            | Support                             |
+| ------------------ | ----------------------------------- |
+| Chrome / Edge 113+ | Recommended                         |
+| Firefox Nightly    | Experimental (`dom.webgpu.enabled`) |
+| Safari 18+         | Partial; requires recent macOS      |
 
-main();
-```
-
-### Benchmarking
-
-```typescript
-import { GPUContext, Benchmark } from 'webgpu-sorting';
-
-async function runBenchmark() {
-  const context = new GPUContext();
-  await context.initialize();
+WebGPU requires cross-origin isolation when running in the browser. The dev server is configured with the required COOP/COEP headers in `vite.config.ts`.
 
-  const benchmark = new Benchmark();
-  await benchmark.initialize(context);
+## Repository map
 
-  // Run benchmark for specific size
-  const results = await benchmark.runBitonicSort(102400);
-  console.log(`Speedup: ${results.speedup}x`);
-}
-
-runBenchmark();
+```text
+webgpu-sorting/
+├── openspec/            # Specs, change proposals, tasks, archive
+├── docs/                # User documentation
+├── site/                # Custom GitHub Pages site
+├── src/                 # Library and demo source
+├── test/                # Vitest suite
+├── examples/            # Usage examples
+├── AGENTS.md            # Project-wide AI and workflow guidance
+└── CLAUDE.md            # Project-specific assistant guidance
 ```
 
----
-
-## Performance
-
-### Benchmark Results
+## Development commands
 
-| Array Size | JS Array.sort() | Bitonic Sort | Radix Sort | Speedup (Bitonic) | Speedup (Radix) |
-| ---------- | --------------- | ------------ | ---------- | ----------------- | --------------- |
-| 1K         | ~0.1ms          | ~0.5ms       | ~0.8ms     | 0.2x              | 0.1x            |
-| 10K        | ~1ms            | ~0.8ms       | ~1ms       | 1.3x              | 1.0x            |
-| 100K       | ~15ms           | ~2ms         | ~3ms       | **7.5x**          | **5.0x**        |
-| 1M         | ~200ms          | ~10ms        | ~15ms      | **20x**           | **13x**         |
-
-_Note: Results from Chrome 120 on NVIDIA RTX 3060. Results may vary based on GPU hardware and browser implementation._
-
-**Key Takeaway:** GPU sorting shows clear advantages for arrays with 100K+ elements. For smaller arrays (<10K), the GPU overhead may outweigh the benefits.
-
----
-
-## Documentation
-
-| Category              | Link                                                          |
-| --------------------- | ------------------------------------------------------------- |
-| **Getting Started**   | [Setup Guide](./docs/setup/GETTING_STARTED.md)                |
-| **API Reference**     | [API Documentation](./docs/tutorials/API.md)                  |
-| **Technical Details** | [Architecture & Algorithms](./docs/architecture/TECHNICAL.md) |
-| **Examples**          | [Code Examples](./examples/)                                  |
-| **Project Specs**     | [Specifications](./specs/)                                    |
-| **Changelog**         | [Version History](./CHANGELOG.md)                             |
-
----
-
-## Browser Support
-
-| Browser | Version | Status             | Notes                       |
-| ------- | ------- | ------------------ | --------------------------- |
-| Chrome  | 113+    | ✅ Fully Supported | Recommended                 |
-| Edge    | 113+    | ✅ Fully Supported | Based on Chromium           |
-| Firefox | Nightly | ⚠️ Experimental    | Enable `dom.webgpu.enabled` |
-| Safari  | 18+     | ⚠️ Partial         | macOS 14+ required          |
-
-### WebGPU Configuration
-
-WebGPU requires specific security headers for cross-origin isolation. Ensure your server or HTML includes:
-
-**HTTP Headers:**
-
-```
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
 ```
 
-**Or in your HTML:**
+Other useful commands:
 
-```html
-<script>
-  if (crossOriginIsolated) {
-    // WebGPU is ready to use
-  }
-</script>
+```bash
+npm run dev
+npm run test:coverage
+npm run pages:build
 ```
 
----
+## Documentation and specs
 
-## Project Structure
+| Surface             | Link                                                                                             |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| Docs hub            | [docs/README.md](./docs/README.md)                                                               |
+| Getting started     | [docs/setup/GETTING_STARTED.md](./docs/setup/GETTING_STARTED.md)                                 |
+| API reference       | [docs/tutorials/API.md](./docs/tutorials/API.md)                                                 |
+| Technical notes     | [docs/architecture/TECHNICAL.md](./docs/architecture/TECHNICAL.md)                               |
+| Sorting spec        | [openspec/specs/sorting/webgpu-sorting.md](./openspec/specs/sorting/webgpu-sorting.md)           |
+| Quality spec        | [openspec/specs/quality/project-enhancement.md](./openspec/specs/quality/project-enhancement.md) |
+| Current change work | [openspec/changes/](./openspec/changes/)                                                         |
 
-```
-webgpu-sorting/
-├── specs/                    # Spec-Driven Development docs
-│   ├── product/              # Product requirements (PRDs)
-│   ├── rfc/                  # Technical design documents
-│   ├── api/                  # API definitions
-│   ├── db/                   # Database/model specs
-│   └── testing/              # BDD test specifications
-├── docs/                     # User documentation
-│   ├── setup/                # Installation & setup guides
-│   ├── tutorials/            # API tutorials & examples
-│   ├── architecture/         # Technical deep-dives
-│   └── assets/               # Images & static assets
-├── src/                      # Source code
-│   ├── core/                 # WebGPU core infrastructure
-│   ├── sorting/              # Sorting algorithm implementations
-│   ├── shaders/              # WGSL compute shaders
-│   ├── benchmark/            # Performance benchmarking
-│   └── types.ts              # Type definitions
-├── test/                     # Test suite (61 tests)
-├── examples/                 # Code examples
-├── index.html                # Interactive demo
-├── AGENTS.md                 # AI agent workflow instructions
-├── README.md                 # This file
-└── package.json
-```
-
----
+## Contributing
 
-## Available Scripts
+For non-trivial changes, start with OpenSpec instead of editing files directly:
 
-```bash
-# Development
-npm run dev              # Start development server
-
-# Testing
-npm test                 # Run all tests
-npm run test:watch       # Run tests in watch mode
-npm run test:coverage    # Generate coverage report
-
-# Linting
-npm run lint             # Run ESLint
-npm run lint:fix         # Fix ESLint issues
-npm run format           # Format code with Prettier
-
-# Building
-npm run build            # Build for production
-npm run preview          # Preview production build
+```text
+/opsx:explore → /opsx:propose → /opsx:apply → /review → /opsx:archive
 ```
 
----
-
-## Contributing
-
-We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
----
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the contributor workflow and [AGENTS.md](./AGENTS.md) for project-specific guidance.
 
 ## License
 
-[MIT License](./LICENSE)
-
----
-
-## Acknowledgments
-
-- [WebGPU Specification](https://www.w3.org/TR/webgpu/) by W3C
-- [WebGPU Fundamentals](https://webgpufundamentals.org/) for tutorials
-- All contributors to this project
-
----
-
-**Version**: 1.0.1  
-**Last Updated**: 2026-04-17
+[MIT](./LICENSE)
diff --git a/README.zh.md b/README.zh.md
index 27eb391..f0052ee 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -1,307 +1,130 @@
 # WebGPU Sorting
 
 <p align="center">
-  <strong>基于 WebGPU 计算着色器的高性能 GPU 排序算法</strong>
+  <strong>一个使用 WebGPU 计算着色器处理 Uint32Array 排序任务的 GPU 加速项目。</strong>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/webgpu-sorting"><img src="https://img.shields.io/npm/v/webgpu-sorting" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/webgpu-sorting"><img src="https://img.shields.io/npm/dw/webgpu-sorting" alt="npm downloads"></a>
-  <img src="https://img.shields.io/bundlephobia/minzip/webgpu-sorting" alt="bundle size">
-  <a href="https://github.com/LessUp/webgpu-sorting/actions"><img src="https://img.shields.io/badge/CI-passing-brightgreen" alt="CI Status"></a>
-  <img src="https://img.shields.io/badge/WebGPU-Compute-blue" alt="WebGPU">
-  <img src="https://img.shields.io/badge/TypeScript-5.3-blue" alt="TypeScript">
-  <img src="https://img.shields.io/badge/tests-61%20passed-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/license-MIT-yellow" alt="License">
+  <a href="https://lessup.github.io/webgpu-sorting/">主页</a> •
+  <a href="https://lessup.github.io/webgpu-sorting/demo/">在线 Demo</a> •
+  <a href="./docs/README.md">文档</a> •
+  <a href="./README.md">English</a>
 </p>
 
-<p align="center">
-  <a href="https://lessup.github.io/webgpu-sorting/">🚀 在线演示</a> •
-  <a href="./README.md">🇺🇸 English Version</a>
-</p>
-
----
-
-## 概述
-
-WebGPU Sorting 是一个高性能排序库，利用 WebGPU API 在 GPU 上执行排序算法。对于大型数据集，它比 JavaScript 原生的 `Array.sort()` 提供了显著的性能提升。
-
-**主要特性：**
-
-- **10-100 倍性能提升**，适用于大型数组（10万+ 元素）
-- 两种优化算法：**双调排序（Bitonic Sort）** 和 **基数排序（Radix Sort）**
-- 清晰的 TypeScript API，具有完整类型安全
-- 零依赖，体积小（gzip 后约 10KB）
-- 完整的测试覆盖（61 个测试）
-- 支持所有启用 WebGPU 的浏览器
-
----
+## 项目定位
 
-## 算法
+WebGPU Sorting 是一个 TypeScript 库 + 演示项目，用来展示浏览器中基于 WebGPU 的高性能排序。仓库当前包含两套核心实现：
 
-| 算法         | 时间复杂度 | 空间复杂度  | 适用场景           |
-| ------------ | ---------- | ----------- | ------------------ |
-| **双调排序** | O(n log²n) | O(1) - 原地 | 中等数组，通用场景 |
-| **基数排序** | O(n × k)   | O(n)        | 大型数组，32位整数 |
+- **Bitonic Sort**：适合并行排序网络示例与通用演示
+- **Radix Sort**：适合大规模 `Uint32Array` 整数排序
 
-**算法选择指南：**
+仓库还提供性能基准工具、交互式 Demo、自定义 GitHub Pages 站点，以及基于 OpenSpec 的维护流程。
 
-| 数组大小     | 推荐方案            | 原因           |
-| ------------ | ------------------- | -------------- |
-| < 1万        | 原生 `Array.sort()` | GPU 开销不值得 |
-| 1万 - 10万   | 双调排序（Bitonic） | 综合性能最佳   |
-| > 10万       | 基数排序（Radix）   | 线性时间复杂度 |
-| 仅 32 位整数 | 基数排序（Radix）   | 定长数据最优   |
+## 你可以得到什么
 
----
+- 面向 WebGPU 初始化与排序执行的简洁 TypeScript API
+- Bitonic / Radix 的 WGSL 着色器实现
+- GPU 与 JavaScript 排序的基准测试辅助工具
+- 一个可直接体验的在线 Demo
+- 一套用于规范维护流程的 OpenSpec 规格与任务
 
 ## 快速开始
 
 ### 安装
 
-#### npm（推荐）
-
 ```bash
 npm install webgpu-sorting
 ```
 
-#### CDN / ES 模块
-
-```html
-<script type="module">
-  import { BitonicSorter, GPUContext } from 'https://unpkg.com/webgpu-sorting@latest/dist/index.js';
-</script>
-```
-
-#### 开发环境（克隆仓库）
-
-```bash
-# 克隆仓库
-git clone https://github.com/LessUp/webgpu-sorting.git
-cd webgpu-sorting
-
-# 安装依赖
-npm install
-
-# 启动开发服务器
-npm run dev
-```
-
-### 基本用法（npm）
-
-```typescript
-import { GPUContext, BitonicSorter, Validator } from 'webgpu-sorting';
-
-async function main() {
-  // 1. 初始化 WebGPU
-  const context = new GPUContext();
-  await context.initialize();
-
-  // 2. 创建排序器
-  const sorter = new BitonicSorter(context);
-
-  // 3. 准备数据
-  const data = new Uint32Array([5, 2, 8, 1, 9, 3, 7, 4, 6, 0]);
-
-  // 4. 排序
-  const result = await sorter.sort(data);
-  console.log('排序结果:', result.sortedData); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-
-  // 5. 验证
-  const validation = Validator.validate(data, result.sortedData);
-  console.log('验证结果:', validation.isValid);
-
-  // 6. 清理
-  sorter.destroy();
-  context.destroy();
-}
-
-main();
-```
-
-### 使用基数排序（适合 32 位整数）
-
-```typescript
-import { GPUContext, RadixSorter } from 'webgpu-sorting';
+### 代码示例
 
-async function main() {
-  const context = new GPUContext();
-  await context.initialize();
+```ts
+import { GPUContext, BitonicSorter } from 'webgpu-sorting';
 
-  // 32 位整数排序使用 RadixSorter 性能更好
-  const sorter = new RadixSorter(context);
-  const data = new Uint32Array([
-    /* 10万+ 个元素 */
-  ]);
+const context = new GPUContext();
+await context.initialize();
 
-  const result = await sorter.sort(data);
-  console.log('排序结果:', result.sortedData);
+const sorter = new BitonicSorter(context);
+const input = new Uint32Array([5, 2, 8, 1, 9, 3]);
+const result = await sorter.sort(input);
 
-  sorter.destroy();
-  context.destroy();
-}
+console.log(result.sortedData);
 
-main();
+sorter.destroy();
+context.destroy();
 ```
 
-### 性能测试
-
-```typescript
-import { GPUContext, Benchmark } from 'webgpu-sorting';
-
-async function runBenchmark() {
-  const context = new GPUContext();
-  await context.initialize();
+## 如何选择算法
 
-  const benchmark = new Benchmark();
-  await benchmark.initialize(context);
-
-  // 对指定数据量进行测试
-  const results = await benchmark.runBitonicSort(102400);
-  console.log(`加速比: ${results.speedup}x`);
-}
-
-runBenchmark();
-```
-
----
-
-## 性能
-
-### 基准测试结果
-
-| 数组大小 | JS Array.sort() | 双调排序 | 基数排序 | 加速比 (双调) | 加速比 (基数) |
-| -------- | --------------- | -------- | -------- | ------------- | ------------- |
-| 1K       | ~0.1ms          | ~0.5ms   | ~0.8ms   | 0.2x          | 0.1x          |
-| 10K      | ~1ms            | ~0.8ms   | ~1ms     | 1.3x          | 1.0x          |
-| 100K     | ~15ms           | ~2ms     | ~3ms     | **7.5x**      | **5.0x**      |
-| 1M       | ~200ms          | ~10ms    | ~15ms    | **20x**       | **13x**       |
-
-_注：测试环境为 Chrome 120 + NVIDIA RTX 3060。实际结果可能因 GPU 硬件和浏览器实现而异。_
-
-**核心结论：** GPU 排序在 10万+ 元素的数组上优势明显。对于较小数组（<1万），GPU 开销可能抵消性能收益。
-
----
-
-## 文档
-
-| 分类         | 链接                                              |
-| ------------ | ------------------------------------------------- |
-| **入门指南** | [安装指南](./docs/setup/GETTING_STARTED.zh.md)    |
-| **API 参考** | [API 文档](./docs/tutorials/API.zh.md)            |
-| **技术细节** | [架构与算法](./docs/architecture/TECHNICAL.zh.md) |
-| **代码示例** | [示例代码](./examples/)                           |
-| **项目规范** | [规范文档](./specs/)                              |
-| **更新日志** | [版本历史](./CHANGELOG.md)                        |
-
----
+| 场景                            | 推荐算法            | 原因                               |
+| ------------------------------- | ------------------- | ---------------------------------- |
+| 通用浏览器演示或中等规模数组    | `BitonicSorter`     | 排序网络清晰，适合作为项目参考实现 |
+| 大规模整数数组（`Uint32Array`） | `RadixSorter`       | 对固定宽度整数数据扩展性更好       |
+| 小数组                          | 原生 `Array.sort()` | GPU 初始化与传输开销可能更高       |
 
 ## 浏览器支持
 
-| 浏览器  | 版本    | 状态        | 说明                      |
-| ------- | ------- | ----------- | ------------------------- |
-| Chrome  | 113+    | ✅ 完全支持 | 推荐                      |
-| Edge    | 113+    | ✅ 完全支持 | 基于 Chromium             |
-| Firefox | Nightly | ⚠️ 实验性   | 启用 `dom.webgpu.enabled` |
-| Safari  | 18+     | ⚠️ 部分支持 | 需要 macOS 14+            |
-
-### WebGPU 配置
+| 浏览器             | 支持情况                              |
+| ------------------ | ------------------------------------- |
+| Chrome / Edge 113+ | 推荐                                  |
+| Firefox Nightly    | 实验性（需开启 `dom.webgpu.enabled`） |
+| Safari 18+         | 部分支持，需要较新的 macOS            |
 
-WebGPU 需要特定的跨域隔离安全头。请确保你的服务器或 HTML 包含：
+如果在浏览器中运行 WebGPU，需要启用跨域隔离。开发服务器已在 `vite.config.ts` 中配置 COOP/COEP 头。
 
-**HTTP 响应头：**
+## 仓库结构
 
-```
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
-```
-
-**或在 HTML 中检查：**
-
-```html
-<script>
-  if (crossOriginIsolated) {
-    // WebGPU 可以正常使用
-  }
-</script>
-```
-
----
-
-## 项目结构
-
-```
+```text
 webgpu-sorting/
-├── specs/                    # Spec-Driven Development 规范文档
-│   ├── product/              # 产品需求 (PRD)
-│   ├── rfc/                  # 技术设计文档
-│   ├── api/                  # API 定义
-│   ├── db/                   # 数据库/模型规范
-│   └── testing/              # BDD 测试规范
-├── docs/                     # 用户文档
-│   ├── setup/                # 安装与配置指南
-│   ├── tutorials/            # API 教程与示例
-│   ├── architecture/         # 技术深入分析
-│   └── assets/               # 图片与静态资源
-├── src/                      # 源代码
-│   ├── core/                 # WebGPU 核心基础设施
-│   ├── sorting/              # 排序算法实现
-│   ├── shaders/              # WGSL 计算着色器
-│   ├── benchmark/            # 性能基准测试
-│   └── types.ts              # 类型定义
-├── test/                     # 测试套件 (61 个测试)
-├── examples/                 # 代码示例
-├── index.html                # 交互式演示
-├── AGENTS.md                 # AI 工作流指令
-├── README.md                 # 英文版 README
-├── README.zh.md              # 本文件
-└── package.json
+├── openspec/            # 规格、变更提案、任务、归档
+├── docs/                # 用户文档
+├── site/                # 自定义 GitHub Pages 站点
+├── src/                 # 库与 Demo 源码
+├── test/                # Vitest 测试
+├── examples/            # 使用示例
+├── AGENTS.md            # 项目级 AI / 工作流说明
+└── CLAUDE.md            # 项目级助手说明
 ```
 
----
-
-## 可用脚本
+## 常用命令
 
 ```bash
-# 开发
-npm run dev              # 启动开发服务器
-
-# 测试
-npm test                 # 运行所有测试
-npm run test:watch       # 监听模式运行测试
-npm run test:coverage    # 生成覆盖率报告
-
-# 代码检查
-npm run lint             # 运行 ESLint
-npm run lint:fix         # 修复 ESLint 问题
-npm run format           # 使用 Prettier 格式化代码
-
-# 构建
-npm run build            # 生产环境构建
-npm run preview          # 预览生产构建
+npm run lint
+npm run typecheck
+npm run test
+npm run build
 ```
 
----
+其他常用命令：
 
-## 贡献
+```bash
+npm run dev
+npm run test:coverage
+npm run pages:build
+```
 
-我们欢迎各种形式的贡献！请查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解详情。
+## 文档与规格
 
----
+| 内容     | 链接                                                                                             |
+| -------- | ------------------------------------------------------------------------------------------------ |
+| 文档入口 | [docs/README.md](./docs/README.md)                                                               |
+| 入门指南 | [docs/setup/GETTING_STARTED.zh.md](./docs/setup/GETTING_STARTED.zh.md)                           |
+| API 参考 | [docs/tutorials/API.zh.md](./docs/tutorials/API.zh.md)                                           |
+| 技术说明 | [docs/architecture/TECHNICAL.zh.md](./docs/architecture/TECHNICAL.zh.md)                         |
+| 排序规格 | [openspec/specs/sorting/webgpu-sorting.md](./openspec/specs/sorting/webgpu-sorting.md)           |
+| 质量规格 | [openspec/specs/quality/project-enhancement.md](./openspec/specs/quality/project-enhancement.md) |
+| 当前变更 | [openspec/changes/](./openspec/changes/)                                                         |
 
-## 许可证
+## 贡献方式
 
-[MIT License](./LICENSE)
+对非 trivial 的改动，请优先走 OpenSpec 流程，而不是直接改文件：
 
----
-
-## 致谢
+```text
+/opsx:explore → /opsx:propose → /opsx:apply → /review → /opsx:archive
+```
 
-- [WebGPU 规范](https://www.w3.org/TR/webgpu/) - W3C
-- [WebGPU Fundamentals](https://webgpufundamentals.org/) - 教程资源
-- 所有项目贡献者
+详细流程见 [CONTRIBUTING.md](./CONTRIBUTING.md) 与 [AGENTS.md](./AGENTS.md)。
 
----
+## 许可证
 
-**版本**: 1.0.1  
-**最后更新**: 2026-04-17
+[MIT](./LICENSE)

From 6c2a5dffb6af90289faf30ef1b29d941bf1dfeaa Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 03:00:22 +0800
Subject: [PATCH 07/10] docs(site): align docs hub and site with project
 positioning

- Simplify docs/README.md hub structure
- Add WORKFLOW.md for AI-assisted development guide
- Fix GitHub issues link in GETTING_STARTED.md
- Update site pages with clearer messaging
- Add docs link resolution in build-site.ts
- Update meta descriptions for better SEO
---
 docs/README.md                | 127 +++++++++-------------------------
 docs/setup/GETTING_STARTED.md |   2 +-
 docs/setup/WORKFLOW.md        |  87 +++++++++++++++++++++++
 site/pages/demo.html          |  16 ++---
 site/pages/index.html         | 116 ++++++++++++++++---------------
 site/scripts/build-site.ts    |  62 ++++++++++++++---
 6 files changed, 243 insertions(+), 167 deletions(-)
 create mode 100644 docs/setup/WORKFLOW.md

diff --git a/docs/README.md b/docs/README.md
index 19dd1de..c1c0850 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,95 +1,32 @@
-# WebGPU Sorting Documentation Hub
-
-<p align="center">
-  <strong>High-Performance GPU Sorting Algorithms Using WebGPU Compute Shaders</strong><br/>
-  <strong>基于 WebGPU 计算着色器的高性能 GPU 排序算法</strong>
-</p>
-
----
-
-## Documentation Structure | 文档结构
-
-This project follows the [Spec-Driven Development](../AGENTS.md) paradigm. All implementation details are governed by spec documents in `/specs`.
-
-> 本项目遵循 [Spec-Driven Development](../AGENTS.md) 范式。所有实现细节由 `/specs` 中的规范文档管理。
-
-```
-docs/
-├── setup/           # Installation & setup guides | 安装与配置指南
-├── tutorials/       # API tutorials & examples | API 教程与示例
-├── architecture/    # Technical deep-dives | 技术深入分析
-└── assets/          # Images & static resources | 图片与静态资源
-```
-
----
-
-## Quick Navigation | 快速导航
-
-### Setup Guides | 安装指南
-
-| Document                                      | Language   | Description                                |
-| --------------------------------------------- | ---------- | ------------------------------------------ |
-| [Getting Started](./setup/GETTING_STARTED.md) | 🇺🇸 English | Installation, quick start, troubleshooting |
-| [入门指南](./setup/GETTING_STARTED.zh.md)     | 🇨🇳 中文    | 安装、快速开始、常见问题                   |
-
-### Tutorials & API References | 教程与 API 参考
-
-| Document                            | Language   | Description                              |
-| ----------------------------------- | ---------- | ---------------------------------------- |
-| [API Reference](./tutorials/API.md) | 🇺🇸 English | Complete API documentation with examples |
-| [API 参考](./tutorials/API.zh.md)   | 🇨🇳 中文    | 完整的 API 文档和示例                    |
-
-### Architecture & Technical Details | 架构与技术细节
-
-| Document                                         | Language   | Description                            |
-| ------------------------------------------------ | ---------- | -------------------------------------- |
-| [Technical Details](./architecture/TECHNICAL.md) | 🇺🇸 English | Architecture, algorithms, optimization |
-| [技术文档](./architecture/TECHNICAL.zh.md)       | 🇨🇳 中文    | 架构、算法和优化                       |
-
-### Changelog | 更新日志
-
-See [CHANGELOG.md](../CHANGELOG.md) for version history.
-
-> 查看 [CHANGELOG.md](../CHANGELOG.md) 了解版本历史。
-
----
-
-## Specifications | 规范文档
-
-The `/specs` directory contains the authoritative specifications:
-
-| Spec                                                                        | Type    | Description                                  |
-| --------------------------------------------------------------------------- | ------- | -------------------------------------------- |
-| [WebGPU Sorting](../specs/product/0001-webgpu-sorting.md)                   | Product | Feature requirements and acceptance criteria |
-| [Quality Enhancement](../specs/product/0002-project-quality-enhancement.md) | Product | CI/CD, code quality, project metadata        |
-| [Core Architecture](../specs/rfc/0001-core-architecture.md)                 | RFC     | Technical design and architecture            |
-
----
-
-## Documentation Standards | 文档标准
-
-All documentation follows these principles:
-
-- Clear, professional language
-- Working code examples
-- Comprehensive troubleshooting
-- Cross-referenced links
-- Consistent formatting
-- Bilingual support (English + Chinese)
-
-> 所有文档遵循以下原则：清晰专业的语言、可运行的代码示例、全面的故障排除、交叉引用链接、一致的格式、双语支持（英文+中文）
-
----
-
-## For Contributors | 给贡献者
-
-Before contributing, please read:
-
-1. [AGENTS.md](../AGENTS.md) - Spec-Driven Development workflow
-2. [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
-3. [specs/](../specs/) - Project specifications
-
----
-
-**Last Updated**: 2026-04-17  
-**Version**: 1.0.1
+# Documentation Hub
+
+This directory contains the maintained user-facing documentation for WebGPU Sorting.
+
+## Start here
+
+| Topic                  | Link                                                           |
+| ---------------------- | -------------------------------------------------------------- |
+| Getting started        | [setup/GETTING_STARTED.md](./setup/GETTING_STARTED.md)         |
+| Getting started (中文) | [setup/GETTING_STARTED.zh.md](./setup/GETTING_STARTED.zh.md)   |
+| AI-assisted workflow   | [setup/WORKFLOW.md](./setup/WORKFLOW.md)                       |
+| API reference          | [tutorials/API.md](./tutorials/API.md)                         |
+| API reference (中文)   | [tutorials/API.zh.md](./tutorials/API.zh.md)                   |
+| Technical notes        | [architecture/TECHNICAL.md](./architecture/TECHNICAL.md)       |
+| Technical notes (中文) | [architecture/TECHNICAL.zh.md](./architecture/TECHNICAL.zh.md) |
+
+## Related project authority files
+
+| Surface                  | Link                                                                                                 |
+| ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Repository overview      | [../PROJECT_OVERVIEW.md](../PROJECT_OVERVIEW.md)                                                     |
+| Contributor workflow     | [../CONTRIBUTING.md](../CONTRIBUTING.md)                                                             |
+| AI and workflow guidance | [../AGENTS.md](../AGENTS.md)                                                                         |
+| Sorting spec             | [../openspec/specs/sorting/webgpu-sorting.md](../openspec/specs/sorting/webgpu-sorting.md)           |
+| Quality spec             | [../openspec/specs/quality/project-enhancement.md](../openspec/specs/quality/project-enhancement.md) |
+
+## Documentation principles
+
+- Keep public docs aligned with the actual repository structure.
+- Prefer rewriting or consolidating stale docs instead of layering on duplicates.
+- Default to English for shared docs; add `.zh.md` translations when they will be maintained.
+- Treat GitHub Pages, README, and this docs hub as one connected public narrative.
diff --git a/docs/setup/GETTING_STARTED.md b/docs/setup/GETTING_STARTED.md
index bc71854..598b239 100644
--- a/docs/setup/GETTING_STARTED.md
+++ b/docs/setup/GETTING_STARTED.md
@@ -421,7 +421,7 @@ Now that you're up and running:
 
 ### Get Help
 
-- 📋 [GitHub Issues](https://github.com/your-username/webgpu-sorting/issues)
+- 📋 [GitHub Issues](https://github.com/LessUp/webgpu-sorting/issues)
 - 📚 [WebGPU Specification](https://www.w3.org/TR/webgpu/)
 - 🎓 [WebGPU Fundamentals](https://webgpufundamentals.org/)
 
diff --git a/docs/setup/WORKFLOW.md b/docs/setup/WORKFLOW.md
new file mode 100644
index 0000000..12d2e25
--- /dev/null
+++ b/docs/setup/WORKFLOW.md
@@ -0,0 +1,87 @@
+# AI-Assisted Workflow
+
+This project uses OpenSpec to keep code, docs, and workflow changes aligned.
+
+## Default flow
+
+```text
+/opsx:explore → /opsx:propose → /opsx:apply → /review → /opsx:archive
+```
+
+Use it like this:
+
+1. **Explore** when the task is cross-cutting or the current state is unclear.
+2. **Propose** before any non-trivial implementation.
+3. **Apply** to execute the approved task list in order.
+4. **Review** after each meaningful slice.
+5. **Archive** as soon as the change is complete.
+
+## Execution modes
+
+| Mode        | Use it when                                                   | Avoid it when                                            |
+| ----------- | ------------------------------------------------------------- | -------------------------------------------------------- |
+| Interactive | The task needs steady judgment or frequent inspection         | The work is repetitive and fully specified               |
+| Autopilot   | The OpenSpec tasks are clear and the repo state is understood | The task still has design ambiguity                      |
+| Subagents   | Research threads are independent and bounded                  | The same context would be duplicated across agents       |
+| `/fleet`    | A large problem is truly parallel and worth the cost          | A single long-running session can finish it more cheaply |
+
+For this repository, prefer **one longer autopilot/apply run** over many `/fleet` bursts.
+
+## Tool roles
+
+| Tool                            | Primary role in this repo                                             |
+| ------------------------------- | --------------------------------------------------------------------- |
+| Copilot CLI                     | Main execution tool for repo work, validation, and `gh` operations    |
+| Claude / Codex style assistants | Deep reasoning on cross-cutting cleanup and design trade-offs         |
+| `/review`                       | Mandatory or strongly preferred before a slice is treated as complete |
+| `gh`                            | Repository metadata, Actions inspection, release hygiene              |
+| OpenSpec                        | Requirements, tasks, and change lifecycle                             |
+
+## Repo-level tooling
+
+These repo-scoped defaults should stay committed:
+
+- `.vscode/settings.json`
+- `.vscode/extensions.json`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.github/copilot-instructions.md`
+
+## Global tooling policy
+
+Global setup is allowed for this project, but only when it has a clear payoff.
+
+### Recommended global setup
+
+- GitHub CLI authenticated for `gh` usage
+- Copilot enabled in the editor/CLI you actually use
+- A WGSL-capable editor extension if your main IDE lacks one
+
+### Optional global setup
+
+- Personal shell aliases for validation commands
+- Personal Claude/Codex local preferences that do not override project rules
+
+### Usually not worth it
+
+- Context-heavy MCP servers by default
+- Multiple overlapping AI plugins that perform the same task
+- Tooling that requires constant manual reconciliation with repo-scoped instructions
+
+## LSP recommendations
+
+For editor support, keep the stack simple:
+
+- TypeScript: use the workspace TypeScript version from `node_modules/typescript/lib`
+- ESLint: surface diagnostics from the repo config
+- WGSL: use a WGSL-aware extension for syntax and shader authoring help
+- GitHub Actions: use workflow-aware editor support when editing `.github/workflows/`
+
+## Validation commands
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
diff --git a/site/pages/demo.html b/site/pages/demo.html
index 8519ab4..ddee458 100644
--- a/site/pages/demo.html
+++ b/site/pages/demo.html
@@ -3,20 +3,20 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta name="description" content="Interactive Demo - WebGPU Sorting. Run benchmarks comparing GPU Bitonic Sort and Radix Sort against JavaScript Array.sort()">
+  <meta name="description" content="Interactive benchmark for WebGPU Sorting. Compare Bitonic Sort and Radix Sort against JavaScript sorting on your own hardware.">
   <meta name="theme-color" content="#00d4ff">
   <link rel="canonical" href="https://lessup.github.io/webgpu-sorting/demo/">
 
   <!-- Open Graph -->
   <meta property="og:type" content="website">
   <meta property="og:title" content="Interactive Demo - WebGPU Sorting">
-  <meta property="og:description" content="Run GPU sorting benchmarks in your browser. Compare WebGPU performance vs JavaScript native sort.">
+  <meta property="og:description" content="Benchmark WebGPU sorting on your own browser and compare GPU timings with JavaScript sorting.">
   <meta property="og:url" content="https://lessup.github.io/webgpu-sorting/demo/">
 
   <!-- Twitter -->
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="Interactive Demo - WebGPU Sorting">
-  <meta name="twitter:description" content="Run GPU sorting benchmarks in your browser.">
+  <meta name="twitter:description" content="Benchmark Bitonic Sort and Radix Sort in your own browser.">
 
   <title>Interactive Demo - WebGPU Sorting</title>
   <link rel="stylesheet" href="/shared/styles.css">
@@ -50,7 +50,7 @@
     <div class="container">
       <div class="demo-header">
         <h1>⚡ Interactive Benchmark</h1>
-        <p class="subtitle">Compare GPU sorting performance against JavaScript native sort</p>
+        <p class="subtitle">Compare Bitonic Sort, Radix Sort, and JavaScript sorting on your own browser and hardware.</p>
       </div>
 
       <div id="unsupported" class="card unsupported" style="display: none;">
@@ -132,15 +132,15 @@ <h2>📈 Results</h2>
         </div>
 
         <div class="card info-card">
-          <h2>ℹ️ About the Algorithms</h2>
+          <h2>ℹ️ What you are measuring</h2>
           <div class="algorithm-info">
             <div class="algo">
               <h3>Bitonic Sort</h3>
-              <p>A comparison-based parallel sorting network with <code>O(n log²n)</code> complexity. Uses parallel compare-exchange operations across the GPU.</p>
+               <p>A comparison-based GPU sorting network. Useful as the easiest implementation path to inspect and reason about.</p>
             </div>
             <div class="algo">
               <h3>Radix Sort</h3>
-              <p>A non-comparison integer sorting algorithm with <code>O(n × k)</code> complexity. Uses parallel histogram and prefix sum operations for extreme speed.</p>
+               <p>A non-comparison integer sorter for <code>Uint32Array</code> workloads. It uses histogram-style passes and tends to shine on larger arrays.</p>
             </div>
           </div>
           <div class="tech-badges">
@@ -160,7 +160,7 @@ <h3>Radix Sort</h3>
     <div class="footer-content">
       <div class="footer-section">
         <h4>WebGPU Sorting</h4>
-        <p>High-performance GPU sorting algorithms using WebGPU compute shaders.</p>
+         <p>Benchmark GPU sorting in the browser and inspect the underlying project if you want the implementation details.</p>
       </div>
       <div class="footer-section">
         <h4>Links</h4>
diff --git a/site/pages/index.html b/site/pages/index.html
index abd2c1c..c060f62 100644
--- a/site/pages/index.html
+++ b/site/pages/index.html
@@ -3,23 +3,23 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta name="description" content="WebGPU Sorting - High-performance GPU sorting algorithms using WebGPU compute shaders. Achieve 10-100x speedup over JavaScript Array.sort() with Bitonic Sort and Radix Sort.">
+  <meta name="description" content="WebGPU Sorting is a TypeScript + WGSL reference project for GPU sorting in the browser, with live demo, documentation, and OpenSpec-driven project maintenance.">
   <meta name="keywords" content="WebGPU, GPU sorting, Bitonic Sort, Radix Sort, compute shaders, parallel computing, TypeScript">
   <meta name="theme-color" content="#00d4ff">
   <link rel="canonical" href="https://lessup.github.io/webgpu-sorting/">
 
   <!-- Open Graph -->
   <meta property="og:type" content="website">
-  <meta property="og:title" content="WebGPU Sorting - High-Performance GPU Sorting">
-  <meta property="og:description" content="GPU-accelerated sorting algorithms using WebGPU compute shaders. 10-100x faster than JavaScript native sort.">
+  <meta property="og:title" content="WebGPU Sorting - WebGPU Sorting Reference Project">
+  <meta property="og:description" content="TypeScript and WGSL implementations of GPU sorting with a live demo, docs, and project-quality guidance.">
   <meta property="og:url" content="https://lessup.github.io/webgpu-sorting/">
 
   <!-- Twitter -->
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="WebGPU Sorting - High-Performance GPU Sorting">
-  <meta name="twitter:description" content="GPU-accelerated sorting algorithms using WebGPU compute shaders.">
+  <meta name="twitter:title" content="WebGPU Sorting - WebGPU Sorting Reference Project">
+  <meta name="twitter:description" content="Explore GPU sorting in the browser with Bitonic Sort, Radix Sort, docs, and a live benchmark demo.">
 
-  <title>WebGPU Sorting - High-Performance GPU Sorting</title>
+  <title>WebGPU Sorting - WebGPU Sorting Reference Project</title>
   <link rel="stylesheet" href="/shared/styles.css">
   <link rel="stylesheet" href="/shared/home.css">
   <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚡</text></svg>">
@@ -52,35 +52,38 @@
     <section class="hero">
       <div class="hero-content">
         <div class="hero-badge">
-          <span class="badge">WebGPU Compute Shaders</span>
+          <span class="badge">WebGPU + WGSL Reference Project</span>
         </div>
         <h1 class="hero-title">
-          High-Performance<br>
-          <span class="gradient-text">GPU Sorting</span>
+          GPU Sorting for<br>
+          <span class="gradient-text">Real Browser Workloads</span>
         </h1>
         <p class="hero-subtitle">
-          Sorting algorithms that harness the power of your GPU. Achieve <strong>10-100x speedup</strong> over JavaScript's native <code>Array.sort()</code> using WebGPU compute shaders.
+          WebGPU Sorting combines a small TypeScript API, WGSL shader implementations, benchmark tooling, and a live demo so you can evaluate when GPU sorting is worth using for large <code>Uint32Array</code> workloads.
         </p>
         <div class="hero-actions">
           <a href="/demo/" class="btn btn-primary btn-lg">
-            <span>⚡ Try Interactive Demo</span>
+            <span>⚡ Run the Demo</span>
           </a>
           <a href="/docs/getting-started/" class="btn btn-secondary btn-lg">
-            <span>📖 Read Documentation</span>
+            <span>📖 Read the Docs</span>
+          </a>
+          <a href="https://github.com/LessUp/webgpu-sorting" class="btn btn-secondary btn-lg" target="_blank" rel="noopener">
+            <span>↗ View Source</span>
           </a>
         </div>
         <div class="hero-stats">
           <div class="stat">
-            <span class="stat-value">100x</span>
-            <span class="stat-label">Speedup vs JS</span>
+            <span class="stat-value">2</span>
+            <span class="stat-label">GPU sorters</span>
           </div>
           <div class="stat">
-            <span class="stat-value">2</span>
-            <span class="stat-label">Algorithms</span>
+            <span class="stat-value">61</span>
+            <span class="stat-label">Automated tests</span>
           </div>
           <div class="stat">
-            <span class="stat-value">MIT</span>
-            <span class="stat-label">License</span>
+            <span class="stat-value">Spec</span>
+            <span class="stat-label">Driven workflow</span>
           </div>
         </div>
       </div>
@@ -105,7 +108,7 @@ <h1 class="hero-title">
 <span class="code-keyword">const</span> data = <span class="code-keyword">new</span> <span class="code-function">Uint32Array</span>([<span class="code-number">5</span>, <span class="code-number">2</span>, <span class="code-number">8</span>, <span class="code-number">1</span>, <span class="code-number">9</span>]);
 <span class="code-keyword">const</span> { sortedData } = <span class="code-keyword">await</span> sorter.<span class="code-function">sort</span>(data);
 
-<span class="code-comment">// 10-100x faster than Array.sort()!</span></code></pre>
+<span class="code-comment">// Benchmark on your own hardware</span></code></pre>
         </div>
       </div>
     </section>
@@ -113,37 +116,37 @@ <h1 class="hero-title">
     <!-- Features Section -->
     <section class="features">
       <div class="container">
-        <h2 class="section-title">Key Features</h2>
+        <h2 class="section-title">Why this repo is useful</h2>
         <div class="features-grid">
           <div class="feature-card">
             <div class="feature-icon">⚡</div>
-            <h3>High Performance</h3>
-            <p>Leverage GPU parallelism to sort millions of elements in milliseconds. Perfect for data visualization, game engines, and scientific computing.</p>
+            <h3>WebGPU sorting reference</h3>
+            <p>Use the repo to study practical Bitonic Sort and Radix Sort implementations in TypeScript + WGSL without wading through a large framework.</p>
           </div>
           <div class="feature-card">
             <div class="feature-icon">🔧</div>
-            <h3>Two Algorithms</h3>
-            <p><strong>Bitonic Sort</strong> for comparison-based sorting and <strong>Radix Sort</strong> for integer sorting. Choose the right tool for your data.</p>
+            <h3>Two algorithm paths</h3>
+            <p><strong>Bitonic Sort</strong> is the clean sorting-network baseline, while <strong>Radix Sort</strong> is the better fit for large integer-heavy workloads.</p>
           </div>
           <div class="feature-card">
             <div class="feature-icon">🚀</div>
-            <h3>WebGPU Native</h3>
-            <p>Built on modern WebGPU API with WGSL compute shaders. Hardware-accelerated on all major browsers supporting WebGPU.</p>
+            <h3>Live benchmark demo</h3>
+            <p>Run the interactive demo in your browser to compare GPU timings, total timings, and speedup versus native JavaScript sorting.</p>
           </div>
           <div class="feature-card">
             <div class="feature-icon">📦</div>
-            <h3>TypeScript First</h3>
-            <p>Full TypeScript support with comprehensive type definitions. Easy integration into modern web applications.</p>
+            <h3>TypeScript-first API</h3>
+            <p>The public surface stays small: initialize WebGPU, choose a sorter, run the benchmark, and inspect results without extra dependencies.</p>
           </div>
           <div class="feature-card">
             <div class="feature-icon">🛡️</div>
-            <h3>Validated & Tested</h3>
-            <p>Extensive test suite with property-based testing. Results validated against JavaScript native sort.</p>
+            <h3>Trust signals included</h3>
+            <p>Specs, tests, docs, and GitHub Pages are all part of the same repo so you can inspect implementation, expectations, and project hygiene together.</p>
           </div>
           <div class="feature-card">
             <div class="feature-icon">🔬</div>
-            <h3>Benchmark Tools</h3>
-            <p>Built-in benchmarking utilities to measure performance against native JavaScript sorting on your hardware.</p>
+            <h3>OpenSpec-maintained</h3>
+            <p>Non-trivial changes go through an explicit propose/apply/review/archive flow, which keeps code, docs, and workflow guidance from drifting apart.</p>
           </div>
         </div>
       </div>
@@ -152,18 +155,18 @@ <h3>Benchmark Tools</h3>
     <!-- Algorithms Section -->
     <section class="algorithms">
       <div class="container">
-        <h2 class="section-title">Sorting Algorithms</h2>
+        <h2 class="section-title">What is implemented</h2>
         <div class="algorithm-cards">
           <div class="algorithm-card">
             <div class="algorithm-header">
               <h3>Bitonic Sort</h3>
               <span class="complexity">O(n log²n)</span>
             </div>
-            <p>A comparison-based parallel sorting network. Excellent for general-purpose sorting with predictable performance characteristics.</p>
+            <p>A comparison-based parallel sorting network that makes the GPU execution pattern easy to inspect and reason about.</p>
             <ul class="algorithm-specs">
-              <li>Works with any comparable data type</li>
-              <li>Stable sorting network</li>
-              <li>Best for: General-purpose sorting</li>
+              <li>Good baseline for browser-side GPU sorting experiments</li>
+              <li>Handles padding to power-of-two sizes</li>
+              <li>Best fit: general-purpose reference implementation</li>
             </ul>
           </div>
           <div class="algorithm-card">
@@ -171,11 +174,11 @@ <h3>Bitonic Sort</h3>
               <h3>Radix Sort</h3>
               <span class="complexity">O(n × k)</span>
             </div>
-            <p>A non-comparison integer sorting algorithm using parallel histogram and prefix sum operations. Extremely fast for 32-bit integers.</p>
+            <p>A non-comparison integer sorter built around histogram and prefix-sum style passes for large fixed-width integer arrays.</p>
             <ul class="algorithm-specs">
-              <li>Specialized for integer sorting</li>
-              <li>Parallel histogram computation</li>
-              <li>Best for: Large integer arrays</li>
+              <li>Specialized for <code>Uint32Array</code> workloads</li>
+              <li>Includes GPU/CPU cooperation for simplified prefix sums</li>
+              <li>Best fit: large integer-heavy datasets</li>
             </ul>
           </div>
         </div>
@@ -185,8 +188,8 @@ <h3>Radix Sort</h3>
     <!-- Performance Section -->
     <section class="performance">
       <div class="container">
-        <h2 class="section-title">Benchmark Results</h2>
-        <p class="section-subtitle">Typical performance on mid-range GPU vs JavaScript Array.sort()</p>
+        <h2 class="section-title">Where GPU sorting starts to matter</h2>
+        <p class="section-subtitle">Use the live demo to verify these trends on your own hardware.</p>
         <div class="performance-chart">
           <div class="chart-bars">
             <div class="chart-bar-group">
@@ -196,7 +199,7 @@ <h2 class="section-title">Benchmark Results</h2>
                   <span class="bar-value">JS</span>
                 </div>
                 <div class="bar gpu" style="--height: 100%">
-                  <span class="bar-value">5-10x</span>
+                  <span class="bar-value">Overhead</span>
                 </div>
               </div>
             </div>
@@ -207,7 +210,7 @@ <h2 class="section-title">Benchmark Results</h2>
                   <span class="bar-value">JS</span>
                 </div>
                 <div class="bar gpu" style="--height: 100%">
-                  <span class="bar-value">20-50x</span>
+                  <span class="bar-value">Often wins</span>
                 </div>
               </div>
             </div>
@@ -218,14 +221,14 @@ <h2 class="section-title">Benchmark Results</h2>
                   <span class="bar-value">JS</span>
                 </div>
                 <div class="bar gpu" style="--height: 100%">
-                  <span class="bar-value">50-100x</span>
+                  <span class="bar-value">Best case</span>
                 </div>
               </div>
             </div>
           </div>
         </div>
         <div class="performance-cta">
-          <a href="/demo/" class="btn btn-primary">Run Your Own Benchmark</a>
+          <a href="/demo/" class="btn btn-primary">Run your own benchmark</a>
         </div>
       </div>
     </section>
@@ -233,7 +236,7 @@ <h2 class="section-title">Benchmark Results</h2>
     <!-- Quick Start Section -->
     <section class="quick-start">
       <div class="container">
-        <h2 class="section-title">Quick Start</h2>
+        <h2 class="section-title">Get to the useful parts fast</h2>
         <div class="quick-start-steps">
           <div class="step">
             <span class="step-number">1</span>
@@ -245,14 +248,15 @@ <h3>Install</h3>
           <div class="step">
             <span class="step-number">2</span>
             <div class="step-content">
-              <h3>Import</h3>
-              <pre class="step-code"><code>import { GPUContext, BitonicSorter } from 'webgpu-sorting';</code></pre>
+              <h3>Read or run</h3>
+              <pre class="step-code"><code>Open /docs/ for the API
+or /demo/ to benchmark in-browser</code></pre>
             </div>
           </div>
           <div class="step">
             <span class="step-number">3</span>
             <div class="step-content">
-              <h3>Sort</h3>
+              <h3>Benchmark or integrate</h3>
               <pre class="step-code"><code>const gpu = new GPUContext();
 await gpu.initialize();
 const sorter = new BitonicSorter(gpu);
@@ -261,7 +265,7 @@ <h3>Sort</h3>
           </div>
         </div>
         <div class="quick-start-actions">
-          <a href="/docs/getting-started/" class="btn btn-secondary">View Full Documentation</a>
+          <a href="/docs/getting-started/" class="btn btn-secondary">Open getting started guide</a>
         </div>
       </div>
     </section>
@@ -269,7 +273,7 @@ <h3>Sort</h3>
     <!-- Browser Support Section -->
     <section class="browser-support">
       <div class="container">
-        <h2 class="section-title">Browser Support</h2>
+        <h2 class="section-title">Browser support</h2>
         <div class="browser-grid">
           <div class="browser-item supported">
             <div class="browser-icon">🌐</div>
@@ -300,7 +304,7 @@ <h2 class="section-title">Browser Support</h2>
     <div class="footer-content">
       <div class="footer-section">
         <h4>WebGPU Sorting</h4>
-        <p>High-performance GPU sorting algorithms using WebGPU compute shaders.</p>
+        <p>A WebGPU sorting reference project with demo, docs, and implementation details in one place.</p>
       </div>
       <div class="footer-section">
         <h4>Links</h4>
@@ -311,8 +315,10 @@ <h4>Links</h4>
         </ul>
       </div>
       <div class="footer-section">
-        <h4>Resources</h4>
+        <h4>Inspect further</h4>
         <ul>
+          <li><a href="https://github.com/LessUp/webgpu-sorting/tree/master/openspec/specs" target="_blank">OpenSpec specs</a></li>
+          <li><a href="https://github.com/LessUp/webgpu-sorting/tree/master/test" target="_blank">Test suite</a></li>
           <li><a href="https://www.w3.org/TR/webgpu/" target="_blank">WebGPU Spec</a></li>
           <li><a href="https://www.w3.org/TR/WGSL/" target="_blank">WGSL Spec</a></li>
         </ul>
diff --git a/site/scripts/build-site.ts b/site/scripts/build-site.ts
index e6c47ec..4059897 100644
--- a/site/scripts/build-site.ts
+++ b/site/scripts/build-site.ts
@@ -40,8 +40,48 @@ const NAVIGATION: NavItem[] = [
   },
 ];
 
+const DOC_ROUTE_MAP: Record<string, string> = {
+  'docs/README.md': '/docs/',
+  'docs/setup/GETTING_STARTED.md': '/docs/getting-started/',
+  'docs/setup/WORKFLOW.md': '/docs/workflow/',
+  'docs/tutorials/API.md': '/docs/api/',
+  'docs/architecture/TECHNICAL.md': '/docs/architecture/',
+};
+
+function resolveContentLink(sourcePath: string, url: string): string {
+  if (
+    url.startsWith('http') ||
+    url.startsWith('#') ||
+    url.startsWith('mailto:') ||
+    url.startsWith('javascript:') ||
+    url.startsWith('/')
+  ) {
+    return url;
+  }
+
+  const [rawPath, hash = ''] = url.split('#');
+  const sourceRelativePath = path.relative(ROOT_DIR, sourcePath).split(path.sep).join('/');
+  const normalizedPath = path.posix.normalize(
+    path.posix.join(path.posix.dirname(sourceRelativePath), rawPath)
+  );
+  const resolvedPath = DOC_ROUTE_MAP[normalizedPath];
+  const hashSuffix = hash ? `#${hash}` : '';
+
+  if (resolvedPath) {
+    return `${resolvedPath}${hashSuffix}`;
+  }
+
+  if (normalizedPath.endsWith('.md')) {
+    return `https://github.com/LessUp/webgpu-sorting/blob/master/${normalizedPath}${hashSuffix}`;
+  }
+
+  const isDirectoryLike = rawPath.endsWith('/') || path.posix.extname(normalizedPath) === '';
+  const githubPathType = isDirectoryLike ? 'tree' : 'blob';
+  return `https://github.com/LessUp/webgpu-sorting/${githubPathType}/master/${normalizedPath}${hashSuffix}`;
+}
+
 // Simple markdown parser
-function parseMarkdown(content: string): { html: string; title: string } {
+function parseMarkdown(content: string, sourcePath: string): { html: string; title: string } {
   let html = content;
   let title = 'Documentation';
 
@@ -76,12 +116,10 @@ function parseMarkdown(content: string): { html: string; title: string } {
 
   // Convert links
   html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match, text, url) => {
-    if (url.startsWith('./') || url.startsWith('../')) {
-      url = url.replace(/\.md$/, '.html');
-    }
-    const isExternal = url.startsWith('http');
+    const resolvedUrl = resolveContentLink(sourcePath, url);
+    const isExternal = resolvedUrl.startsWith('http');
     const target = isExternal ? ' target="_blank" rel="noopener noreferrer"' : '';
-    return `<a href="${url}"${target}>${text}</a>`;
+    return `<a href="${resolvedUrl}"${target}>${text}</a>`;
   });
 
   // Convert tables
@@ -278,7 +316,8 @@ function copySharedAssets() {
 
 function processMarkdownFile(inputPath: string, outputPath: string, urlPath: string) {
   const content = fs.readFileSync(inputPath, 'utf-8');
-  const { html, title } = parseMarkdown(content);
+  const { html, title } = parseMarkdown(content, inputPath);
+  const relativeInputPath = path.relative(ROOT_DIR, inputPath).split(path.sep).join('/');
 
   const pageContent = `<main class="docs-page">
   <div class="docs-container">
@@ -288,7 +327,7 @@ function processMarkdownFile(inputPath: string, outputPath: string, urlPath: str
     <article class="docs-content">
       ${html}
       <footer class="page-footer">
-        <a href="https://github.com/LessUp/webgpu-sorting/edit/master/docs/${path.basename(inputPath)}" target="_blank" rel="noopener">
+        <a href="https://github.com/LessUp/webgpu-sorting/edit/master/${relativeInputPath}" target="_blank" rel="noopener">
           Edit this page on GitHub
         </a>
       </footer>
@@ -312,6 +351,7 @@ function processMarkdownFile(inputPath: string, outputPath: string, urlPath: str
 function generateDocsSidebar(currentPath: string): string {
   const docsNav = [
     { title: 'Getting Started', path: '/docs/getting-started/' },
+    { title: 'Workflow', path: '/docs/workflow/' },
     { title: 'API Reference', path: '/docs/api/' },
     { title: 'Architecture', path: '/docs/architecture/' },
   ];
@@ -331,6 +371,7 @@ function generateSitemap(baseUrl: string): string {
     { path: '/demo/', priority: '0.9' },
     { path: '/docs/', priority: '0.9' },
     { path: '/docs/getting-started/', priority: '0.8' },
+    { path: '/docs/workflow/', priority: '0.8' },
     { path: '/docs/api/', priority: '0.8' },
     { path: '/docs/architecture/', priority: '0.7' },
   ];
@@ -368,6 +409,11 @@ function main() {
       output: 'docs/getting-started/index.html',
       path: '/docs/getting-started/',
     },
+    {
+      input: 'docs/setup/WORKFLOW.md',
+      output: 'docs/workflow/index.html',
+      path: '/docs/workflow/',
+    },
     { input: 'docs/tutorials/API.md', output: 'docs/api/index.html', path: '/docs/api/' },
     {
       input: 'docs/architecture/TECHNICAL.md',

From a875af1c636de612b64c92ea2f48f217092c3c1b Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 03:00:39 +0800
Subject: [PATCH 08/10] chore(openspec): update config and add
 closeout-foundation-reset change

- Update openspec/config.yaml with correct repo URL and version
- Remove archived specs entry from config
- Add closeout-foundation-reset change proposal for repo alignment
---
 .../closeout-foundation-reset/.openspec.yaml  |  2 +
 .../closeout-foundation-reset/design.md       | 92 +++++++++++++++++++
 .../closeout-foundation-reset/proposal.md     | 28 ++++++
 .../specs/project-workflow-governance/spec.md | 58 ++++++++++++
 .../specs/quality/spec.md                     | 53 +++++++++++
 .../closeout-foundation-reset/tasks.md        | 36 ++++++++
 openspec/config.yaml                          |  8 +-
 7 files changed, 271 insertions(+), 6 deletions(-)
 create mode 100644 openspec/changes/closeout-foundation-reset/.openspec.yaml
 create mode 100644 openspec/changes/closeout-foundation-reset/design.md
 create mode 100644 openspec/changes/closeout-foundation-reset/proposal.md
 create mode 100644 openspec/changes/closeout-foundation-reset/specs/project-workflow-governance/spec.md
 create mode 100644 openspec/changes/closeout-foundation-reset/specs/quality/spec.md
 create mode 100644 openspec/changes/closeout-foundation-reset/tasks.md

diff --git a/openspec/changes/closeout-foundation-reset/.openspec.yaml b/openspec/changes/closeout-foundation-reset/.openspec.yaml
new file mode 100644
index 0000000..8b394c6
--- /dev/null
+++ b/openspec/changes/closeout-foundation-reset/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-23
diff --git a/openspec/changes/closeout-foundation-reset/design.md b/openspec/changes/closeout-foundation-reset/design.md
new file mode 100644
index 0000000..a10c6fd
--- /dev/null
+++ b/openspec/changes/closeout-foundation-reset/design.md
@@ -0,0 +1,92 @@
+## Context
+
+The repository already passes its core quality gates, but the project is not yet operating from a single trustworthy source of truth. OpenSpec exists, yet several repo documents still reference the legacy `specs/` layout, `openspec/config.yaml` contains placeholder repository metadata, AI/tooling guidance is fragmented, and the current automation mix favors breadth over signal. The user wants a deliberate closeout phase: aggressively normalize the repo, finish the important work, and leave behind a coherent project that can be maintained lightly.
+
+This change is cross-cutting because it touches specifications, docs, AI instruction files, engineering config, GitHub workflows, Pages, and repository metadata. It also explicitly allows selected machine-level global tooling setup when that meaningfully improves the project's finish-line workflow.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Re-establish OpenSpec as the authoritative workflow and requirements layer.
+- Make documentation, instruction files, and repository metadata accurately reflect the real repo structure and project value.
+- Reduce automation noise so CI/hooks/Pages support closeout instead of creating churn.
+- Define a project-specific AI-assisted workflow for OpenSpec, review checkpoints, subagents, LSP, and selective MCP/plugin usage.
+- Keep the public project presentation polished and trustworthy without expanding the runtime API surface unnecessarily.
+
+**Non-Goals:**
+
+- Adding new sorting algorithms or broadening the public runtime API.
+- Introducing heavyweight infrastructure that increases maintenance burden without clear closeout value.
+- Preserving every existing doc/workflow/config file if it no longer serves a concrete purpose.
+- Treating all possible global tooling as mandatory; only high-value global setup is in scope.
+
+## Decisions
+
+### 1. Use one umbrella closeout change instead of many overlapping changes
+
+The work will be organized under a single OpenSpec change, `closeout-foundation-reset`, with ordered tasks.
+
+- **Why:** The repo needs coordinated normalization across many surfaces. A single umbrella change reduces drift between docs/specs/config and fits the desired “one longer autopilot run, minimal fleet usage” workflow.
+- **Alternative considered:** Multiple small changes. Rejected because the repo is already suffering from fragmentation and this would increase sequencing overhead.
+
+### 2. Treat repository governance and project presentation as first-class requirements
+
+The change will add a dedicated capability, `project-workflow-governance`, and extend the existing `quality` capability with new requirements around source-of-truth alignment, automation signal quality, and public presentation consistency.
+
+- **Why:** AGENTS/CLAUDE/Copilot/process guidance should not live only as informal prose. The closeout workflow needs a durable normative layer that later implementation can follow.
+- **Alternative considered:** Keep everything in docs only. Rejected because it would recreate the same “advice without contract” drift.
+
+### 3. Keep runtime behavior stable unless a closeout defect forces change
+
+The default implementation posture will be to normalize architecture, docs, workflows, and tooling without intentionally expanding the library API.
+
+- **Why:** The user wants a high-quality finish, not a new feature wave. Stability is more valuable than surface-area growth at this stage.
+- **Alternative considered:** Fold feature additions into the same pass. Rejected because it would blur the scope and delay closeout.
+
+### 4. Prefer repo-scoped defaults plus a minimal global-tooling layer
+
+Committed repository settings and docs remain the primary source of setup, but the implementation may also add carefully selected global guidance/configuration for Copilot, Claude/Codex, LSP, MCP, or shell workflows.
+
+- **Why:** The user explicitly wants global tooling included, but only where it materially improves execution. A minimal layered policy keeps the environment usable without overfitting it.
+- **Alternative considered:** Repo-only setup. Rejected because it would ignore the confirmed scope.
+- **Alternative considered:** Broad global tooling rollout. Rejected because it would create unnecessary context and maintenance cost.
+
+### 5. Simplify automation toward high-signal gates
+
+Hooks and workflows will be evaluated against one standard: they must materially protect the repo or improve release/public-site quality.
+
+- **Why:** Current automation includes low-signal PR commenting and non-enforcing audit behavior. Closeout work benefits from fewer, clearer gates.
+- **Alternative considered:** Preserve all existing workflows and just patch them. Rejected because the repo specifically needs normalization, not incremental accretion.
+
+### 6. Reframe GitHub Pages as the project front door
+
+Pages will be treated as a product/showcase surface that aligns with README and GitHub metadata, not as a detached brochure or a passive README mirror.
+
+- **Why:** A polished landing page can explain trust, value, and demo flow faster than README alone, especially for a project entering low-maintenance mode.
+- **Alternative considered:** Leave Pages mostly as-is. Rejected because the public narrative is one of the user’s core concerns.
+
+## Risks / Trade-offs
+
+- **[Broad scope may cause mixed concerns]** → Mitigation: keep a strict ordered task list and validate each phase against the OpenSpec artifacts.
+- **[Global tooling changes may be environment-specific]** → Mitigation: favor minimal, reversible setup and document clear rationale for every global recommendation.
+- **[Workflow simplification could remove something useful]** → Mitigation: preserve only checks with measurable protective value and verify remaining gates cover lint, type safety, tests, build, and Pages.
+- **[Pages redesign may over-promise performance or support claims]** → Mitigation: align public copy with validated repo evidence and current benchmark/support statements.
+- **[OpenSpec schema and current repo layout are slightly misaligned]** → Mitigation: use this change to move toward canonical, easier-to-automate spec organization instead of reinforcing the drift.
+
+## Migration Plan
+
+1. Normalize OpenSpec/config/spec references first.
+2. Rewrite project authority docs and instruction files.
+3. Rationalize workflows/hooks/config.
+4. Update Pages and public GitHub positioning.
+5. Apply GitHub-side metadata changes with `gh`.
+6. Finish by codifying the closeout workflow and archiving the change.
+
+Rollback is straightforward because the work is mostly file/config/docs based: individual commits can be reverted by phase if a simplification choice proves harmful.
+
+## Open Questions
+
+- Which global-tooling files can be safely standardized in this environment versus documented as optional local setup?
+- How aggressively should legacy/low-value docs be removed versus retained with redirects or brief stubs?
+- Should the final workflow keep a dedicated PR-check workflow at all, or collapse everything into CI + Pages + release/security only?
diff --git a/openspec/changes/closeout-foundation-reset/proposal.md b/openspec/changes/closeout-foundation-reset/proposal.md
new file mode 100644
index 0000000..fa601ba
--- /dev/null
+++ b/openspec/changes/closeout-foundation-reset/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+The repository works, but its source-of-truth layers have drifted apart: OpenSpec adoption is incomplete, key documents still describe obsolete structures, AI/tooling guidance is fragmented, and several engineering workflows create noise instead of confidence. This change is needed now to aggressively normalize the project into a coherent, closeout-ready state so the remaining work can be finished with less ambiguity and less maintenance burden.
+
+## What Changes
+
+- Normalize the repository around OpenSpec as the single authoritative workflow and repair stale structural references, config drift, and spec wording gaps.
+- Redesign top-level documentation, project instruction files, and closeout workflow guidance so they are specific to this project and useful for final-stage maintenance.
+- Rationalize hooks, CI/workflows, Pages build flow, and related engineering configuration to keep only high-signal automation.
+- Reposition GitHub Pages and repository metadata so the public project presentation clearly explains the library, its demo, and its quality signals.
+- Define a pragmatic AI-assisted development workflow for OpenSpec + Copilot + Claude/Codex, including review checkpoints, LSP guidance, and a minimal policy for MCP/plugin usage.
+- Fix repository issues uncovered during this normalization work when they materially block the closeout path.
+
+## Capabilities
+
+### New Capabilities
+
+- `project-workflow-governance`: Defines the repo-specific closeout workflow, AI tool collaboration model, review checkpoints, and repo/global tooling policy for finishing the project cleanly.
+
+### Modified Capabilities
+
+- `quality`: Tightens project quality requirements to cover OpenSpec alignment, documentation authority, workflow signal quality, Pages positioning, hooks, repository metadata, and engineering configuration consistency.
+
+## Impact
+
+- Affected areas include `openspec/`, top-level project docs, `.github/workflows/`, `.husky/`, `.vscode/`, Pages/site assets, AI instruction files, and selected build/tooling config files.
+- GitHub-side repository metadata will be updated via `gh` during implementation after local wording and positioning are finalized.
+- No intentional public runtime API expansion is planned; the main impact is repository structure, process clarity, engineering reliability, and public presentation quality.
diff --git a/openspec/changes/closeout-foundation-reset/specs/project-workflow-governance/spec.md b/openspec/changes/closeout-foundation-reset/specs/project-workflow-governance/spec.md
new file mode 100644
index 0000000..9f40a9c
--- /dev/null
+++ b/openspec/changes/closeout-foundation-reset/specs/project-workflow-governance/spec.md
@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: OpenSpec closeout workflow
+
+The repository SHALL define a lightweight OpenSpec-driven workflow for finish-line development so contributors can complete cross-cutting changes without branch drift or ambiguous process.
+
+#### Scenario: Starting a closeout change
+
+- **WHEN** a contributor begins a non-trivial repository change
+- **THEN** the documented workflow SHALL require creating or selecting an OpenSpec change before implementation begins
+
+#### Scenario: Implementing a closeout change
+
+- **WHEN** a contributor executes work from an approved OpenSpec change
+- **THEN** the documented workflow SHALL define a clear sequence for `/opsx:explore`, `/opsx:propose`, `/opsx:apply`, `/review`, and `/opsx:archive`
+
+#### Scenario: Minimizing branch drift
+
+- **WHEN** contributors work through a closeout task list
+- **THEN** the workflow SHALL prefer small serial merges and SHALL discourage long-lived or fragmented parallel branches by default
+
+### Requirement: AI tool collaboration model
+
+The repository SHALL document project-specific roles for AI tools and review steps so Copilot, Claude/Codex-style agents, subagents, and review passes are used intentionally rather than interchangeably.
+
+#### Scenario: Choosing an execution mode
+
+- **WHEN** a contributor decides between interactive work, autopilot, subagents, or review
+- **THEN** the repository guidance SHALL explain which mode is appropriate for this project and what checkpoints are required
+
+#### Scenario: Using review before merge
+
+- **WHEN** a contributor completes a meaningful implementation slice
+- **THEN** the workflow SHALL require or strongly prescribe a `/review` step before the slice is considered ready
+
+#### Scenario: Avoiding tool duplication
+
+- **WHEN** multiple AI tools can perform overlapping work
+- **THEN** the project guidance SHALL define preferred tool roles so contributors avoid redundant instructions, duplicated context, and unnecessary cost
+
+### Requirement: Tooling policy for local and global setup
+
+The repository SHALL provide a minimal, justified policy for repo-level and global tooling setup, including LSP, MCP, plugins, and instruction files, so contributors can assemble a consistent development environment without excessive complexity.
+
+#### Scenario: Defining required repo-level tooling
+
+- **WHEN** a tool or setting is necessary for reliable work on this repository
+- **THEN** it SHALL be represented in committed project files or project docs
+
+#### Scenario: Recommending global tooling
+
+- **WHEN** a global tool configuration is recommended
+- **THEN** the guidance SHALL explain why it is useful for this project and whether it is required, recommended, or optional
+
+#### Scenario: Evaluating context-heavy integrations
+
+- **WHEN** MCP servers, plugins, or similar integrations are considered
+- **THEN** the repository guidance SHALL prefer the lowest-complexity option that still delivers clear value for this project
diff --git a/openspec/changes/closeout-foundation-reset/specs/quality/spec.md b/openspec/changes/closeout-foundation-reset/specs/quality/spec.md
new file mode 100644
index 0000000..4df8528
--- /dev/null
+++ b/openspec/changes/closeout-foundation-reset/specs/quality/spec.md
@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: Repository source-of-truth alignment
+
+The project SHALL keep its OpenSpec configuration, repository metadata references, and core documentation aligned with the actual repository structure so contributors do not encounter conflicting authority layers.
+
+#### Scenario: Referencing specifications
+
+- **WHEN** top-level docs or contributor guidance reference project specifications
+- **THEN** they SHALL point to the canonical `openspec/` structure used by the repository
+
+#### Scenario: Declaring repository identity
+
+- **WHEN** project configuration or governance files declare repository metadata
+- **THEN** they SHALL use the real repository URL, branch expectations, and authoritative project locations instead of placeholders or stale paths
+
+### Requirement: High-signal engineering automation
+
+The project SHALL maintain a small set of high-value hooks and GitHub workflows that protect code quality, build health, release flow, and public-site integrity without relying on noisy or low-trust automation.
+
+#### Scenario: Validating pull requests and pushes
+
+- **WHEN** contributors open pull requests or push protected branch updates
+- **THEN** the automation SHALL cover linting, type checking, tests, and build verification through clearly scoped workflows
+
+#### Scenario: Handling low-signal checks
+
+- **WHEN** an automated check only comments, warns without enforcement, or duplicates stronger protections
+- **THEN** the project SHALL remove it or replace it with a more actionable safeguard
+
+#### Scenario: Maintaining Pages and release flows
+
+- **WHEN** Pages or release automation is kept
+- **THEN** its responsibilities SHALL be explicit, deterministic, and consistent with the repository's closeout-ready maintenance posture
+
+### Requirement: Consistent public project positioning
+
+The project SHALL present a consistent narrative across README, documentation entrypoints, GitHub Pages, and GitHub repository metadata so users can quickly understand the library, demo, and trust signals.
+
+#### Scenario: Presenting the project to new users
+
+- **WHEN** a user lands on README, GitHub Pages, or the repository About section
+- **THEN** the messaging SHALL consistently describe what the project does, why it is useful, and where to try the demo or read docs
+
+#### Scenario: Linking public entrypoints
+
+- **WHEN** public-facing docs or metadata link to project resources
+- **THEN** those links SHALL resolve to maintained documentation, demo, spec, or repository locations
+
+#### Scenario: Curating documentation for closeout readiness
+
+- **WHEN** low-value, redundant, stale, or generic documents are identified
+- **THEN** the project SHALL remove, consolidate, or rewrite them so the remaining document set stays purposeful and specific
diff --git a/openspec/changes/closeout-foundation-reset/tasks.md b/openspec/changes/closeout-foundation-reset/tasks.md
new file mode 100644
index 0000000..04ba373
--- /dev/null
+++ b/openspec/changes/closeout-foundation-reset/tasks.md
@@ -0,0 +1,36 @@
+## 1. Repository truth reset
+
+- [x] 1.1 Audit and fix stale references to legacy `specs/` paths, placeholder repository metadata, and obsolete structure descriptions across OpenSpec config and authority docs
+- [x] 1.2 Normalize the canonical spec/doc layout so `openspec/` is the unambiguous source of truth for future changes
+- [x] 1.3 Tighten the quality and workflow-governance source docs so later implementation work has clear project-specific guidance
+
+## 2. Core documentation redesign
+
+- [x] 2.1 Rewrite `README.md` and `README.zh.md` to align project positioning, public links, and actual repository structure
+- [x] 2.2 Rewrite `PROJECT_OVERVIEW.md`, `docs/README.md`, and related entrypoint docs to remove stale, redundant, or generic content
+- [x] 2.3 Consolidate `CONTRIBUTING.md`, `CHANGELOG.md`, and other closeout-facing docs into a lower-noise, project-specific document set
+
+## 3. AI guidance and tooling workflow
+
+- [x] 3.1 Redesign `AGENTS.md` around this repository's actual architecture, OpenSpec workflow, and closeout-oriented contribution model
+- [x] 3.2 Add a project `CLAUDE.md` and generate/refine `copilot-instructions.md` so AI instructions are complementary and non-duplicative
+- [x] 3.3 Document the preferred usage model for Copilot, Claude/Codex-style agents, `/review`, subagents, autopilot, and minimal `/fleet` usage
+- [x] 3.4 Define repo-level and global-tooling guidance for LSP, MCP, plugins, and optional local setup with explicit value/cost trade-offs
+
+## 4. Engineering surface rationalization
+
+- [x] 4.1 Simplify Husky hooks and workspace/editor settings so they enforce only the protections this repo actually needs
+- [x] 4.2 Rationalize GitHub workflows for CI, PR checks, Pages, release, and security into a smaller high-signal automation set
+- [x] 4.3 Fix concrete engineering issues uncovered during normalization, including current lint warnings and configuration inconsistencies in touched areas
+
+## 5. Public presentation and repository metadata
+
+- [x] 5.1 Redesign the GitHub Pages content and supporting build flow so the site acts as a polished project showcase and demo funnel
+- [x] 5.2 Align README, docs entrypoints, and Pages messaging so public claims, trust signals, and navigation stay consistent
+- [x] 5.3 Update GitHub repository description, homepage/about, and topic curation with `gh` after the local messaging and Pages direction are finalized
+
+## 6. Closeout workflow finalization
+
+- [x] 6.1 Codify a lightweight finish-line workflow for OpenSpec propose/apply/review/archive cycles with small serial merges
+- [x] 6.2 Validate the final repo setup with the existing lint, typecheck, test, and build commands plus any remaining closeout-specific checks
+- [x] 6.3 Review the completed change against its specs, capture any follow-up gaps, and prepare it for archive
diff --git a/openspec/config.yaml b/openspec/config.yaml
index 6e16ae4..a0a1182 100644
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -3,12 +3,12 @@
 
 project:
   name: webgpu-sorting
-  version: 1.0.0
+  version: 1.0.1
   description: High-performance GPU-accelerated sorting library using WebGPU compute shaders
 
   repository:
     type: git
-    url: https://github.com/user/webgpu-sorting
+    url: https://github.com/LessUp/webgpu-sorting
     branch: master
 
   tech_stack:
@@ -37,10 +37,6 @@ specs:
       description: CI/CD, code quality, and project metadata
       owners: []
 
-    - name: _archived
-      description: Historical design documents and superseded specs
-      owners: []
-
   naming:
     spec_files: kebab-case.md
     change_dirs: kebab-case

From e572814f89f28416a8d1fbc1d895941c2c4ab2f3 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 03:00:49 +0800
Subject: [PATCH 09/10] chore(ci): remove redundant pr-checks workflow

PR checks duplicate functionality already covered by ci.yml.
Simplify CI by relying on the main ci.yml workflow.
---
 .github/workflows/pr-checks.yml | 95 ---------------------------------
 1 file changed, 95 deletions(-)
 delete mode 100644 .github/workflows/pr-checks.yml

diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
deleted file mode 100644
index f162873..0000000
--- a/.github/workflows/pr-checks.yml
+++ /dev/null
@@ -1,95 +0,0 @@
-name: PR Quality Checks
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  # Check PR size to encourage small, focused PRs
-  pr-size-check:
-    name: PR Size Check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Check PR size
-        id: pr_size
-        run: |
-          # Get the number of changed lines
-          git fetch origin ${{ github.base_ref }}:base
-          CHANGED_LINES=$(git diff --numstat base ${{ github.head_ref }} | awk '{sum+=$1+$2} END {print sum}')
-          echo "changed_lines=$CHANGED_LINES" >> $GITHUB_OUTPUT
-
-          if [ "$CHANGED_LINES" -gt 500 ]; then
-            echo "::warning::PR is quite large ($CHANGED_LINES lines changed). Consider breaking it into smaller PRs."
-            echo "large_pr=true" >> $GITHUB_OUTPUT
-          else
-            echo "large_pr=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Comment on large PR
-        if: steps.pr_size.outputs.large_pr == 'true'
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const changedLines = '${{ steps.pr_size.outputs.changed_lines }}';
-            const message = `⚠️ **Large PR Warning**\n\nThis PR contains ${changedLines} lines of changes. Consider breaking it down into smaller, more focused PRs for easier review.\n\n[Best practices for PR size](https://github.com/google/eng-practices/blob/master/review/developer/small-cls.md)`;
-
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: message
-            });
-
-  # Check for common issues in PR
-  pr-content-check:
-    name: PR Content Check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Check PR title format
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const title = context.payload.pull_request.title;
-            const validPrefixes = ['feat:', 'fix:', 'docs:', 'style:', 'refactor:', 'test:', 'chore:', 'perf:', 'ci:'];
-            const hasValidPrefix = validPrefixes.some(prefix => title.toLowerCase().startsWith(prefix));
-
-            if (!hasValidPrefix) {
-              const message = `⚠️ **PR Title Format**\n\nConsider using a conventional commit prefix in your PR title:\n- feat: new feature\n- fix: bug fix\n- docs: documentation\n- style: formatting\n- refactor: code restructuring\n- test: tests\n- chore: maintenance\n- perf: performance\n- ci: CI/CD changes`;
-              
-              github.rest.issues.createComment({
-                issue_number: context.issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                body: message
-              });
-            }
-
-  # Run npm audit to check for vulnerabilities
-  security-audit:
-    name: npm audit
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'npm'
-
-      - name: Run npm audit
-        run: |
-          npm audit --audit-level=high || true

From 58ab63fae0e7ebad766412414902a3acd35d859c Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 03:00:56 +0800
Subject: [PATCH 10/10] chore: add Claude Code local configuration

- Add settings.local.json for project-specific permissions
- Add verify skill for change verification workflow
---
 .claude/settings.local.json    | 20 ++++++++++++++++++++
 .claude/skills/verify/SKILL.md | 18 ++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 .claude/settings.local.json
 create mode 100644 .claude/skills/verify/SKILL.md

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000..e775aca
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": ["Skill(update-config)"]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path // .tool_response.filePath' | { read -r f; [ -n \"$f\" ] && npx prettier --write --ignore-unknown \"$f\" 2>/dev/null || true; }",
+            "timeout": 30,
+            "statusMessage": "Formatting..."
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md
new file mode 100644
index 0000000..0169c2f
--- /dev/null
+++ b/.claude/skills/verify/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: verify
+description: Run typecheck, lint, and tests to verify changes are correct
+---
+
+Run full verification suite:
+
+```bash
+npm run typecheck && npm run lint && npm run test
+```
+
+This checks:
+
+1. TypeScript types are correct
+2. ESLint passes with no errors
+3. All Vitest tests pass
+
+Run this before marking work complete or creating a PR.