Tạo lộ trình implementation với ak:plan

Dùng ak:plan để biến outcome đã được chấp nhận thành implementation roadmap mà workflow khác có thể thực thi. Skill kiểm tra project hiện tại, thách thức scope không cần thiết, ghi dependency cùng ownership tệp và xác minh plan trước khi đề nghị implementation.

Chọn ak:plan khi delivery cần roadmap

Dùng ak:plan khi

• Feature, refactor, bug repair hoặc thay đổi kiến trúc cần nhiều phase.
• Implementation phải điều phối tệp, interface, test hoặc dependency.
• Công nghệ lạ hoặc codebase chưa quen cần research trước design.
• Bạn muốn plan bền vững để validate, red-team hoặc chuyển cho ak:cook.

Chọn workflow khác khi

• Outcome hoặc approach vẫn chưa rõ. Dùng ak:brainstorm trước.
• Bạn chỉ cần bản đồ codebase có giới hạn. Dùng ak:scout.
• Task là chỉnh sửa trực tiếp, ít rủi ro với requirement đã duyệt. Dùng ak:cook nếu plan riêng không tạo thêm giá trị.
• Bạn muốn implementation thay vì planning. ak:plan không thay đổi product code.

Chạy workflow delivery một feature

Dùng ak:plan làm ranh giới quyết định trong một chuỗi dài hơn, không xem đây là lệnh tự động bắt đầu implementation. Một workflow feature đáng tin cậy có bảy stage riêng biệt và có thể review:

Chuyển một contract ngắn gọn sang mỗi stage tiếp theo:

Mục tiêu:
Scope và non-goal đã duyệt:
Bằng chứng và quyết định:
Artifact đã tạo:
Acceptance criteria:
Rủi ro hoặc blocker còn mở:
Thẩm quyền được cấp cho stage này:

Nếu một stage thất bại, tiếp tục từ chính stage đó với bằng chứng mới. Không chạy lại toàn bộ chuỗi trừ khi hướng đã chọn hoặc acceptance criteria thay đổi. Dùng ak:handoff trước khi đổi session, runtime hoặc Kit.

Chuẩn bị project và runtime

Trước khi bắt đầu:

• Hoàn thành Làm quen, xác nhận Engineer Kit đã được cài và ak CLI khả dụng cho plan scaffolding cùng phase-state operation.
• Mở project cần lập plan. Project scope ghi dưới <project>/<plans-dir>/<timestamp>-<slug>/. Giá trị paths.plans tương đối theo project trong .agentkit/config.yaml chọn <plans-dir>; nếu không có, mặc định là plans/.
• Cung cấp outcome, constraint, non-goal và acceptance criteria đã được chấp nhận.
• Giữ nguyên plan chưa hoàn tất và nêu công việc chồng lấn đã biết.
• Bảo đảm projection GitHub hoặc AgentWiki tùy chọn có client, authentication, repository visibility và publication authority cần thiết.

Chạy Skill

/ak:plan "Add offline draft recovery to the editor. Preserve the current document format, avoid a new service, and cover crash plus reload recovery." --hard --tdd

/ak:plan "Add offline draft recovery to the editor. Preserve the current document format, avoid a new service, and cover crash plus reload recovery." --hard --tdd

$ak:plan "Add offline draft recovery to the editor. Preserve the current document format, avoid a new service, and cover crash plus reload recovery." --hard --tdd

Khi không có task rõ ràng, Skill hỏi bạn muốn tạo plan hay chạy một maintenance operation:

Chọn độ sâu planning có chủ đích

Mặc định là --auto, tự chọn mode theo scope và mức bất định.

Các tùy chọn có thể kết hợp làm thay đổi artifact hoặc handoff:

Chỉ dùng --global khi bạn chủ động muốn global plans root đã cấu hình hoặc không có project context. Xác nhận cú pháp plan CLI chính xác từ ak plan --help; Skill không dùng subcommand ghi nhớ làm authority.

Ranh giới CLI V1 chỉ chấp nhận giá trị paths.plans tương đối theo project và an toàn. Nếu giá trị bị thiếu, malformed, là absolute path, trỏ ra ngoài project hay vào .agentkit, hoặc không thể follow an toàn, ak plan, journal và dashboard fallback về <project>/plans/. Absolute path vẫn có thể hiển thị cho Skill, vì vậy hãy xác nhận location do CLI resolve trước scaffolding thay vì giả định mọi plan surface đều dùng external directory đó.

Mô tả plan rõ ràng

Yêu cầu tốt nêu:

• Delivery contract: outcome, constraint, non-goal và acceptance criteria.
• Affected surface: module, public contract, data, runtime và deployment boundary có thể bị ảnh hưởng.
• Known risks: compatibility, security, performance, migration hoặc rollback.
• Load-bearing assumptions: premise mà nếu thiếu thì design thất bại, phần nào evidence hiện tại giải quyết được và phần nào có thể hỏng trong delivery.
• Evidence: research, scout report, incident hoặc plan hiện có.
• Authority: có cho phép external research, tạo GitHub issue, private share hoặc public publication không.

Với ví dụ draft recovery, hãy nêu state phải tồn tại, compatibility format hiện tại, giới hạn storage, thời điểm recovery, kỳ vọng test và không có service hay deployment mới trong scope.

Hiểu điều gì xảy ra trong một lần chạy

1. Skill kiểm tra plan context. Skill quét plan chưa hoàn tất, xác định overlap và ghi blocking relationship vào cả hai plan khi được xác nhận.
2. Skill xác lập scope baseline. Ngoại trừ việc nhỏ, Skill nhắc lại đầy đủ scope được yêu cầu, xác định behavior có thể tái sử dụng và loại complexity ngoài yêu cầu trước research. --fast chỉ thay đổi planning depth; flag này không cấp quyền cắt scope. Khi có --yagni, Skill cũng challenge và cắt phần scope được yêu cầu nhưng không cần thiết cho outcome đã nêu.
3. Skill chọn mode. Skill tôn trọng flag rõ ràng hoặc chọn độ sâu theo mức bất định, blast radius và workstream độc lập.
4. Skill thu thập bằng chứng. Skill đọc repository instruction, code, test, contract và documentation hiện tại. Chỉ thêm research hoặc scouting khi mode hay bằng chứng còn thiếu yêu cầu.
5. Skill design và scaffold plan. Skill so sánh worst plausible case và khi load-bearing assumption chưa xử lý, ưu tiên design có chi phí rời bỏ thấp nhất. Skill ghi điều kiện khiến design không còn đạt success criteria, switching cost cùng lock-in. Sau đó Skill dùng help trực tiếp của ak plan và CLI-managed scaffolding, đọc mọi generated stub rồi ghi plan.md cùng các tệp phase-*.md chi tiết.
6. Skill review plan. Mode phù hợp chạy red team và validation dựa trên bằng chứng. Red-team review nhắm vào assumption vừa thiết yếu vừa có thể hỏng trong vòng đời plan. Mỗi thay đổi được chấp nhận kích hoạt consistency sweep toàn plan.
7. Skill tạo projection tùy chọn. Skill có thể hydrate live task view, tạo plan.html, GitHub issue hoặc chia sẻ qua AgentWiki theo tùy chọn đã yêu cầu cùng authentication khả dụng.
8. Skill chuẩn bị handoff. Skill báo artifact có authority, câu hỏi chưa giải quyết, trạng thái validation và lựa chọn rõ ràng để validate, red-team, thực thi hoặc dừng.

Hiểu các plan artifact

Nguồn bền vững là file-first:

• Trong project scope, plan folder canonical là <project>/<plans-dir>/<timestamp>-<slug>/, dùng resolved directory boundary ở trên.
• plan.md tóm tắt contract, status, dependency và link phase.
• phase-NN-*.md ghi architecture, tệp bị ảnh hưởng, bước thực hiện, success criteria, test, risk và dependency cho từng phase. Với breakable assumption chưa xử lý, risk entry gồm observable failure signal cùng response đã chốt: điều chỉnh trong plan hoặc dừng và lập lại plan.
• Local plan index có thể rebuild từ các tệp đó. Nếu index và file lệch nhau, dùng reindex operation hiển thị bởi ak plan --help.
• Live task view là projection tiện ích. Plan file thắng khi state không khớp.
• Với --html, plan.html là authority và chứa outline phase, detail view, implementation flow, risk và UI mockup khi liên quan.
• GitHub issue hoặc AgentWiki document là visibility projection, không phải plan canonical.

Giữ quyền phê duyệt và an toàn ở bạn

Skill hỏi trước khi xử lý cross-plan dependency còn mơ hồ, chấp nhận red-team finding quan trọng hoặc thay đổi assumption lớn. Skill không nên đề xuất implementation khi verification failure hoặc contradiction toàn plan chưa xử lý.

External effect phụ thuộc tùy chọn:

• --github có thể tạo label, issue hoặc comment qua GitHub. Skill quét secret trong nội dung và báo authentication hay publication failure mà không coi local plan đã thất bại.
• --wiki mặc định chia sẻ private hoặc workspace. Public document và hosted HTML site cần quyền rõ ràng và có thể dùng external provider.
• --html ghi portable local artifact và có thể tạo local image asset. Image provider có thể có giới hạn availability hoặc cost riêng.
• archive đổi visibility trong plan index; operation không xóa, di chuyển hoặc erase Markdown file.

Mọi commit, push, implementation, deployment, destructive removal hoặc chấp nhận verification thất bại vẫn là quyết định riêng của người dùng.

Xác minh kết quả

Plan hoàn tất nên cung cấp:

• Overview có giới hạn với requirement, non-goal và acceptance criteria.
• Phase, dependency, priority và tệp bị ảnh hưởng rõ ràng.
• Architecture cùng implementation step bám bằng chứng project hiện tại.
• Cân nhắc test, security, performance, migration và rollback khi liên quan.
• Load-bearing assumption, stop condition của design, switching cost và observable signal cùng response điều chỉnh-hoặc-lập-lại-plan.
• Verification result với failure hoặc claim chưa xác minh vẫn hiển thị.
• Consistency sweep không còn contradiction chưa xử lý trước execution.
• Đường dẫn artifact có authority cùng trạng thái projection GitHub, AgentWiki, HTML hoặc task tùy chọn.
• Câu hỏi chưa giải quyết được liệt kê cuối cùng.

Chỉ coi plan sẵn sàng cho ak:cook sau khi bạn duyệt, codebase verification không có blocking failure và whole-plan consistency sweep không còn contradiction chưa xử lý.

Xử lý sự cố hoặc tiếp tục

Tiếp tục bằng ak:plan validate <plan-path> hoặc ak:plan red-team <plan-path> khi cần gate khác. Sau khi duyệt, chuyển plan path đã báo cho ak:cook. Xem Project, artifact và checkpoint để hiểu recovery cùng ownership.

Biết các giới hạn hiện tại

• Chất lượng research phụ thuộc bằng chứng project, provider, network access và authentication khả dụng.
• Runtime task hydration là tùy chọn và được phát hiện theo capability; không bảo đảm trong mọi client.
• Cách gọi Cursor bằng slash là bằng chứng do người dùng xác minh, không chứng minh runtime parity đầy đủ.