Mọi skill OpenSpec: đối số, những gì nó tạo ra và những gì nó phản hồi.
Các skill có hai bộ:
- Core: được cài đặt theo mặc định, vòng lặp lập kế hoạch chính.
- Optional: chỉ được cài đặt khi bạn thêm chúng, thông qua Profiles.
Mỗi skill đều kỳ vọng một dự án đã sử dụng OpenSpec. Trước bước đầu tiên có ghi bất kỳ nội dung nào, skill sẽ kiểm tra xem đã có root được phân giải chưa. Điều gì xảy ra khi không có root phụ thuộc vào cách skill được gọi tới:
- Được tự động chọn: agent của bạn tự chọn skill mà không cần bạn nêu tên OpenSpec. Nó bỏ qua OpenSpec và trả lời yêu cầu của bạn một cách bình thường, giống như khi OpenSpec chưa được cài đặt.
- Yêu cầu OpenSpec rõ ràng: bạn đã nêu tên OpenSpec, nêu tên skill hoặc chạy lệnh của skill. Nó dừng trước khi ghi và hỏi cách tiếp tục: chạy
openspec inittại đây, nhắm tới một store bằng--store <id>, hoặc tiếp tục mà không có OpenSpec. Nó chờ câu trả lời của bạn.
Các lệnh luôn thuộc trường hợp thứ hai. Một dự án mà openspec/config.yaml nêu tên một store mà máy này không thể phân giải (chưa được đăng ký hoặc dòng store: không đúng định dạng) không bị coi là chưa khởi tạo: skill dừng lại và hiển thị lỗi store kèm cách khắc phục. Không skill nào tự tạo thư mục openspec/ trong cả hai trường hợp. Các mục bên dưới mô tả điều mỗi skill làm khi đã có root.
| Skill | Công việc | Loại |
|---|---|---|
| openspec-explore | Suy nghĩ thấu đáo về một ý tưởng trước khi nó trở thành đề xuất thay đổi | Core |
| openspec-propose | Tạo một đề xuất thay đổi cùng toàn bộ artifact lập kế hoạch của nó trong một bước | Core |
| openspec-apply-change | Triển khai các tác vụ của đề xuất thay đổi | Core |
| openspec-update-change | Chỉnh sửa kế hoạch của đề xuất thay đổi | Core |
| openspec-sync-specs | Hợp nhất các cập nhật spec của đề xuất thay đổi vào specs/ | Core |
| openspec-archive-change | Chuyển một đề xuất thay đổi đã hoàn tất vào kho lưu trữ | Core |
| openspec-new-change | Bắt đầu một đề xuất thay đổi dưới dạng bộ khung trống | Optional |
| openspec-continue-change | Tạo artifact lập kế hoạch tiếp theo, từng cái một | Optional |
| openspec-ff-change | Tạo một đề xuất thay đổi với mọi artifact mà quá trình triển khai cần, trong một lượt | Optional |
| openspec-verify-change | Kiểm tra xem phần triển khai có khớp với kế hoạch không | Optional |
| openspec-bulk-archive-change | Lưu trữ nhiều đề xuất thay đổi cùng lúc | Optional |
| openspec-onboard | Học quy trình làm việc bằng cách thực hiện trọn vẹn một đề xuất thay đổi thực tế từ đầu đến cuối | Optional |
Mỗi mục bên dưới nêu tên skill sở hữu bước tiếp theo. Khi profile của bạn không bao gồm skill đó, các tệp được cài đặt sẽ không bao giờ nêu tên nó: bước bàn giao trở thành lệnh openspec tương đương, hoặc một yêu cầu đơn giản gửi đến bạn, và một dòng chỉ tồn tại để trỏ tới skill bị thiếu sẽ không được ghi lại chút nào. Vì vậy, các skill bạn có luôn bàn giao cho những skill bạn có. Bộ bạn nhận được do Profiles quyết định.## openspec-explore
Suy nghĩ kỹ về một ý tưởng trước khi nó trở thành một đề xuất thay đổi.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Một chủ đề: một ý tưởng, một vấn đề, một so sánh, hoặc tên của một đề xuất thay đổi hiện có để khám phá trong ngữ cảnh. Nếu không được cung cấp gì, nó sẽ chuyển vào chế độ khám phá. |
| Tạo ra | Không tạo gì theo mặc định. Nó chỉ đọc và tìm hiểu. Khi được yêu cầu, nó ghi lại các nhận định: một đề xuất thay đổi mới dưới openspec/changes/<name>/, hoặc các cập nhật cho proposal, design, specs hoặc tasks của một đề xuất hiện có. Không bao giờ tạo code. |
| Phản hồi | Một cuộc hội thoại mở, không yêu cầu đầu ra cụ thể. Khi suy nghĩ đã rõ ràng, nó tóm tắt vấn đề, cách tiếp cận, các câu hỏi còn bỏ ngỏ và các bước tiếp theo, đồng thời đề nghị ghi lại những điều đó. Bạn quyết định. Việc triển khai không bao giờ bắt đầu từ đây. |
openspec-propose
Tạo một đề xuất thay đổi và sinh toàn bộ artifact lập kế hoạch của nó trong một bước.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Một tên dạng kebab-case (add-dark-mode) hoặc một mô tả đơn giản. Nếu bạn không cung cấp gì cả, nó sẽ hỏi lại. |
| Tạo ra | openspec/changes/<name>/ với đầy đủ các artifact mà schema định nghĩa, theo thứ tự phụ thuộc (spec-driven: proposal, spec deltas, design, tasks). Không bao giờ tạo code. |
| Phản hồi | Các artifact vừa được tạo, sẵn sàng để bạn xem xét, cùng bước tiếp theo. Dừng lại ở đó; việc triển khai chờ openspec-apply-change. |
openspec-apply-change
Triển khai các task của một đề xuất thay đổi, làm lần lượt qua danh sách cho đến khi hoàn tất hoặc bị chặn.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Tên của một đề xuất thay đổi (add-auth), tùy chọn. Nếu mục tiêu chưa rõ ràng, nó liệt kê các đề xuất thay đổi đang hoạt động và yêu cầu bạn chọn. |
| Tạo ra | Code: những thay đổi tối thiểu mà từng task yêu cầu, ngay trong các tệp dự án của bạn. Trong đề xuất thay đổi, nó đánh dấu hoàn thành từng task đã xong (- [ ] thành - [x]) trong tệp được theo dõi, được xác định bởi sourcePath và line (đánh số bắt đầu từ 1). Một schema có thể theo dõi tasks trên nhiều tệp. |
| Phản hồi | Tiến độ cho từng task, sau đó là con số tổng thể (N/M task hoàn thành). Hoàn thành tất cả: gợi ý dùng openspec-archive-change. Bị chặn vì thiếu artifact: chỉ đến openspec-continue-change, hoặc đến openspec status và openspec instructions nếu skill đó chưa được cài đặt (profile core không bao gồm nó). Task chưa rõ ràng hoặc gặp lỗi: tạm dừng và hỏi. |
openspec-update-change
Sửa đổi các artifact lập kế hoạch hiện có của một đề xuất thay đổi và giữ cho chúng nhất quán với nhau.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Tên của một đề xuất thay đổi, tùy chọn, kèm theo nội dung sửa đổi bạn muốn. Nếu không nêu rõ nội dung sửa đổi, nó sẽ chạy một đợt rà soát tính nhất quán: các artifact được đối chiếu lẫn nhau để tìm mâu thuẫn, thiếu sót và trùng lặp. |
| Tạo ra | Chỉnh sửa các tệp artifact đã tồn tại. Một ngoại lệ: đối với artifact được khai báo dưới dạng glob, ví dụ specs/**/*.md, mà đã có ít nhất một tệp, nó có thể thêm tệp đi kèm còn thiếu sau khi bạn xác nhận đường dẫn. Artifact chưa có tệp nào là việc của openspec-continue-change. Nếu thiếu skill đó (profile core không bao gồm nó), nó sẽ chỉ đến openspec status và openspec instructions thay thế. Không bao giờ tạo code. |
| Phản hồi | Hiển thị từng nội dung sửa đổi đề xuất và chỉ ghi sau khi bạn xác nhận, mỗi lần một artifact. Kết thúc bằng những gì đã được sửa và bước tiếp theo; việc triển khai chờ openspec-apply-change. |
openspec-sync-specs
Hợp nhất các cập nhật spec của một đề xuất thay đổi vào specs/ mà không lưu trữ nó.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Tên của một đề xuất thay đổi, tùy chọn. Bạn cũng có thể nêu tên một tập con các delta specs của nó, và chỉ những spec đó được đồng bộ. |
| Tạo ra | Chỉnh sửa hoặc tạo openspec/specs/<capability-path>/spec.md cho từng delta spec, hợp nhất các yêu cầu được thêm, sửa, xóa và đổi tên vào spec chính. Không bao giờ tạo code. |
| Phản hồi | Tóm tắt theo từng capability về các yêu cầu được thêm, sửa, xóa hoặc đổi tên, sau khi các spec đã cập nhật vượt qua kiểm tra hợp lệ. Đề xuất thay đổi vẫn ở trạng thái hoạt động; việc lưu trữ chờ openspec-archive-change. |
openspec-archive-change
Chuyển một đề xuất thay đổi đã hoàn thành vào khu lưu trữ.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Tên của một đề xuất thay đổi, tùy chọn. |
| Tạo ra | Di chuyển thư mục của đề xuất thay đổi đến openspec/changes/archive/YYYY-MM-DD-<name>/ (không thêm ngày nếu tên đã bắt đầu bằng ngày). Với sự chấp thuận của bạn, nó đồng bộ các delta specs còn tồn đọng trước. Khi openspec-sync-specs đã được cài đặt, nó chạy quy trình đó. Nếu không, nó tự hợp nhất các delta specs vào specs chính. Không bao giờ tạo code. |
| Phản hồi | Cảnh báo và hỏi trước khi lưu trữ nếu còn artifact hoặc task chưa hoàn thành, và hỏi có đồng bộ hay không khi còn delta specs. Kết thúc bằng một bản tóm tắt: tên, schema, vị trí lưu trữ, trạng thái đồng bộ spec, và các cảnh báo (nếu có). |
openspec-new-change
Khởi tạo một đề xuất thay đổi dưới dạng khung sườn trống.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Một tên dạng kebab-case (add-user-auth) hoặc một mô tả đơn giản, cộng thêm tên schema chỉ khi dùng quy trình không mặc định. Nếu bạn không cung cấp gì cả, nó sẽ hỏi bạn muốn xây dựng gì. |
| Tạo ra | openspec/changes/<name>/ dưới dạng khung sườn trống: chưa có artifact nào, không bao giờ tạo code. |
| Phản hồi | Tên và vị trí của khung sườn, chuỗi artifact của quy trình, trạng thái (0/N hoàn thành), và template của artifact đầu tiên. Việc soạn thảo artifact chờ openspec-continue-change. |
openspec-continue-change
Tạo artifact lập kế hoạch tiếp theo trong một đề xuất thay đổi, mỗi lần một artifact.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Tên của một đề xuất thay đổi, tùy chọn. Nếu vẫn còn mơ hồ, nó yêu cầu bạn chọn trong số các đề xuất được sửa đổi gần đây nhất. |
| Tạo ra | Artifact kế tiếp duy nhất đang sẵn sàng trong chuỗi của schema, được ghi vào thư mục của đề xuất thay đổi. Mỗi lần chạy một artifact, không bao giờ tạo code. |
| Phản hồi | Artifact vừa được tạo, tiến độ (N trên M hoàn thành), và những artifact nào được mở khóa nhờ đó. Khi lập kế hoạch hoàn tất, nó thông báo điều đó; việc triển khai chuyển sang openspec-apply-change. |
openspec-ff-change
Tạo một đề xuất thay đổi cùng mọi artifact lập kế hoạch mà việc triển khai cần, trong một lượt duy nhất.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Một tên dạng kebab-case hoặc một mô tả đơn giản. Nếu bạn không cung cấp gì cả, nó sẽ hỏi lại. Nếu đề xuất thay đổi mang tên đó đã tồn tại, nó đề xuất tiếp tục đề xuất đó thay vì tạo mới. |
| Tạo ra | openspec/changes/<name>/ cùng mọi artifact lập kế hoạch mà việc triển khai yêu cầu, theo thứ tự phụ thuộc (spec-driven: proposal, specs, design, tasks), chỉ bỏ qua những artifact được đánh dấu skipped hoặc conditional. Không bao giờ tạo code. |
| Phản hồi | Tên và vị trí của đề xuất thay đổi, từng artifact đã tạo, cùng các artifact conditional bị bỏ qua (nếu có) và lý do. Dừng lại ở đó; việc triển khai chờ openspec-apply-change. |
openspec-verify-change
Kiểm tra xem phần triển khai có khớp với các artifact của đề xuất thay đổi hay không.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Tên của một đề xuất thay đổi, tùy chọn. Khi chưa rõ ràng, nó hỏi lại, liệt kê các đề xuất thay đổi có artifact tasks. |
| Tạo ra | Không tạo gì cả. Nó đọc các artifact của đề xuất thay đổi và codebase. Việc xác minh chỉ dừng ở báo cáo. |
| Phản hồi | Một báo cáo: bảng đánh giá cho Tính đầy đủ, Tính đúng đắn và Tính nhất quán, sau đó là các vấn đề CRITICAL, WARNING và SUGGESTION kèm khuyến nghị, và đánh giá cuối cùng về mức độ sẵn sàng lưu trữ. Nó không thay đổi gì và không thực hiện lưu trữ. |
openspec-bulk-archive-change
Lưu trữ nhiều đề xuất thay đổi cùng một lúc.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Không có. Nó liệt kê các đề xuất thay đổi đang hoạt động và yêu cầu bạn chọn số lượng tùy ý, có tùy chọn chọn tất cả. Nếu không có đề xuất nào đang hoạt động, nó thông báo vậy và dừng lại. |
| Tạo ra | openspec/changes/archive/YYYY-MM-DD-<name>/ cho từng đề xuất thay đổi được lưu trữ (tên đã có sẵn ngày sẽ giữ nguyên tiền tố). Delta specs của từng đề xuất được đồng bộ trước thông qua openspec-sync-specs. Không bao giờ tạo code. |
| Phản hồi | Bảng trạng thái cho từng đề xuất thay đổi và một lần xác nhận cho cả lô, sau đó là tóm tắt các đề xuất đã lưu trữ, bị bỏ qua và thất bại, cùng kết quả đồng bộ spec. Khi hai đề xuất thay đổi cùng tác động đến một spec, nó kiểm tra codebase và đồng bộ các delta đã triển khai theo thứ tự cũ nhất trước. |
openspec-onboard
Học quy trình bằng cách thực hiện trọn vẹn một đề xuất thay đổi thực tế từ đầu đến cuối.
| Hợp đồng | Mô tả |
|---|---|
| Đối số | Không có. Nó quét codebase của bạn để tìm các task khởi đầu nhỏ và yêu cầu bạn chọn một hoặc mô tả task của riêng bạn. |
| Tạo ra | Một đề xuất thay đổi thực tế cho task đã chọn, từng artifact một, sau đó là code thật khi bạn xác nhận triển khai. Lưu trữ đề xuất thay đổi ở bước cuối. |
| Phản hồi | Một buổi dẫn dắt qua toàn bộ chu trình có bình giải, với các điểm dừng chờ bạn nhập liệu: khám phá, tạo, xây dựng từng artifact, triển khai, lưu trữ. Kết thúc bằng phần tổng kết và gợi ý chuyển sang openspec-propose. Mất khoảng 15 đến 20 phút. |