AgentSkillsCN

openspec-ff-change

快速推进 OpenSpec 工件的创建。当用户希望迅速生成所有必要的工件以完成部署，而无需逐一执行时，可使用此技能。

SKILL.md
--- frontmatter
name: openspec-ff-change
description: Fast-forward through OpenSpec artifact creation. Sử dụng khi người dùng muốn nhanh chóng tạo tất cả các artifact cần thiết để triển khai mà không cần thực hiện từng cái một.
license: MIT
compatibility: Yêu cầu openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.0.2"

Bỏ qua các bước tạo artifact thủ công - tạo ra tất cả mọi thứ cần thiết để bắt đầu triển khai ngay lập tức.

Đầu vào: Yêu cầu của người dùng nên bao gồm tên thay đổi (định dạng kebab-case) HOẶC bản mô tả những gì họ muốn xây dựng.

Các bước

  1. •

    Nếu không có đầu vào rõ ràng, hãy hỏi họ muốn xây dựng điều gì

    Sử dụng công cụ AskUserQuestion (dạng câu hỏi mở, không có lựa chọn sẵn) để hỏi:

    "Bạn muốn thực hiện thay đổi nào? Hãy mô tả những gì bạn muốn xây dựng hoặc sửa chữa."

    Từ bản mô tả của họ, suy ra một cái tên định dạng kebab-case (ví dụ: "add user authentication" → add-user-auth).

    QUAN TRỌNG: KHÔNG được tiếp tục nếu chưa hiểu rõ người dùng muốn xây dựng điều gì.

  2. •

    Tạo thư mục thay đổi

    bash
    openspec new change "<name>"

    Lệnh này tạo ra một khung thay đổi tại openspec/changes/<name>/.

  3. •

    Lấy thứ tự xây dựng artifact

    bash
    openspec status --change "<name>" --json

    Phân tích JSON để lấy:

    • •applyRequires: mảng các ID artifact cần thiết trước khi triển khai (ví dụ: ["tasks"]).
    • •artifacts: danh sách tất cả các artifact kèm theo trạng thái và các phụ thuộc (dependencies).
  4. •

    Tạo các artifact theo trình tự cho đến khi sẵn sàng triển khai (apply-ready)

    Sử dụng công cụ TodoWrite để theo dõi tiến độ tạo các artifact.

    Lặp qua các artifact theo thứ tự phụ thuộc (các artifact không còn phụ thuộc chưa hoàn thành sẽ được làm trước):

    a. Với mỗi artifact ở trạng thái ready (các artifact phụ thuộc đã hoàn tất):

    • •Lấy hướng dẫn:
      bash
      openspec instructions <artifact-id> --change "<name>" --json
    • •JSON hướng dẫn bao gồm:
      • •context: Bối cảnh dự án (ràng buộc cho bạn - KHÔNG đưa vào đầu ra).
      • •rules: Các quy tắc riêng của artifact (ràng buộc cho bạn - KHÔNG đưa vào đầu ra).
      • •template: Cấu trúc cần sử dụng cho file đầu ra của bạn.
      • •instruction: Hướng dẫn cụ thể theo schema cho loại artifact này.
      • •outputPath: Nơi ghi artifact.
      • •dependencies: Các artifact đã hoàn thành cần đọc để lấy ngữ cảnh.
    • •Đọc bất kỳ file dependency nào đã hoàn thành để lấy ngữ cảnh.
    • •Tạo file artifact sử dụng template làm cấu trúc.
    • •Áp dụng context và rules làm các ràng buộc - nhưng KHÔNG sao chép chúng vào file.
    • •Hiển thị tiến độ ngắn gọn: "✓ Đã tạo <artifact-id>".

    b. Tiếp tục cho đến khi tất cả các artifact trong applyRequires hoàn thành

    • •Sau khi tạo mỗi artifact, chạy lại lệnh openspec status --change "<name>" --json.
    • •Kiểm tra xem mọi ID artifact trong applyRequires đã có status: "done" trong mảng artifacts chưa.
    • •Dừng lại khi tất cả các artifact trong applyRequires đã xong.

    c. Nếu một artifact yêu cầu người dùng nhập thông tin (ngữ cảnh chưa rõ):

    • •Sử dụng công cụ AskUserQuestion để làm rõ.
    • •Sau đó tiếp tục việc tạo artifact.
  5. •

    Hiển thị trạng thái cuối cùng

    bash
    openspec status --change "<name>"

Đầu ra

Sau khi hoàn thành tất cả các artifact, hãy tóm tắt:

  • •Tên thay đổi và vị trí lưu trữ.
  • •Danh sách các artifact đã được tạo kèm theo mô tả ngắn gọn.
  • •Những gì đã sẵn sàng: "Tất cả các artifact đã được tạo! Sẵn sàng để triển khai."
  • •Gợi ý: "Hãy chạy lệnh /opsx:apply hoặc yêu cầu tôi bắt đầu thực hiện các task."

Hướng dẫn tạo Artifact

  • •Làm theo trường instruction từ lệnh openspec instructions cho mỗi loại artifact.
  • •Schema xác định nội dung mỗi artifact nên chứa những gì - hãy tuân theo.
  • •Đọc các artifact phụ thuộc để lấy ngữ cảnh trước khi tạo cái mới.
  • •Sử dụng template làm cấu trúc cho file đầu ra của bạn - điền vào các phần của nó.
  • •QUAN TRỌNG: context và rules là các ràng buộc dành cho BẠN, không phải là nội dung của file.
    • •KHÔNG sao chép các khối <context>, <rules>, <project_context> vào artifact.
    • •Những nội dung này hướng dẫn những gì bạn viết, nhưng không bao giờ xuất hiện trong đầu ra.

Nguyên tắc an toàn (Guardrails)

  • •Tạo TẤT CẢ các artifact cần thiết để triển khai (theo định nghĩa trong apply.requires của schema).
  • •Luôn đọc các artifact phụ thuộc trước khi tạo cái mới.
  • •Nếu ngữ cảnh cực kỳ không rõ ràng, hãy hỏi người dùng - nhưng nên ưu tiên đưa ra các quyết định hợp lý để giữ đà tiến độ.
  • •Nếu một thay đổi cùng tên đã tồn tại, hãy đề xuất tiếp tục thay đổi đó.
  • •Xác minh mỗi file artifact tồn tại sau khi ghi trước khi chuyển sang bước tiếp theo.