kido-workspace 0.1.0

package/.agents/skills/kido-writing-specs/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: kido-writing-specs
+description: Use for requested KIDO product-document work or to establish requirements before a full-flow implementation; do not invoke routinely during implementation.
+---
+
+# KIDO Writing Specs
+
+Follow [kido-workflow](../kido-workflow/SKILL.md). Read document rules, the glossary, templates, and the relevant domain sources. For a code change, inspect the current implementation read-only and use the clarified requirements.
+
+Establish coverage during design/planning. Bounded work may use approved in-chat acceptance checks without creating product documents. During implementation and review fixes, keep established Spec/AC content fixed and record pending changes in the existing plan or chat; do not rerun this audit on each code iteration. Perform one consolidated synchronization after code acceptance, or handle an explicitly requested document correction in its own scope.
+
+## Audit before creating documents
+
+Compare actors, needs, outcomes, scope, and observed behavior with existing Epics and Stories. Check consistency among AC, Specs, contracts, ADRs, and implementation. Compare contract changes against the declared canonical source, its imports, and generated or legacy artifacts. For UI, consult the relevant design system.
+
+| Finding | Smallest suitable action |
+| --- | --- |
+| Existing Story, AC, and Spec still cover the request | Reuse them. |
+| Related Story is incomplete or incorrect | Update the Story, AC, and affected Spec. |
+| Epic outcome or scope changed | Update the Epic and related Story or Spec. |
+| No suitable Story exists | Add a linked Story and Spec under the relevant Epic. |
+| A distinct outcome has no Epic | Create the minimum Epic, Story, and Spec set. |
+
+Do not duplicate documents merely because wording differs. Require Story/AC/Spec coverage for full-flow changes; reuse suitable documents. For bounded changes, the approved request and observable checks in chat provide coverage.
+
+## Content and readiness
+
+- **Epic:** problem, observable or measurable outcome, in/out scope, and Definition of Done.
+- **Story:** actor, need, value, context, and stable AC IDs. Each AC states the condition, action, and observable result, including relevant errors and boundaries.
+- **Spec:** current versus required behavior, business rules, flows and states, contract or data changes, validation and errors, and applicable security or observability changes. Link the Story and specified AC.
+
+Keep code, hooks, CSS, source-file lists, framework choices, and infrastructure out of `epics/`. A contract delta may name observable endpoints, fields, and errors; HOW belongs in a plan. Describe what a user or external system observes, not a component render.
+
+Example AC: “When connectivity fails while saving a profile, the user sees an unsynced state and the entered content remains available.” The actual persistence policy must come from confirmed requirements, not this example.
+
+## Sources and approval state
+
+Record each requirement's source. Documents prepared during design/planning remain Draft or Pending PO/BA review until the owner signs off. A complete draft can be presented for design approval; that approval does not imply PO/BA sign-off. Keep assumptions, decision owners, and impact visible. Apply the implementation freeze rather than updating documents just to keep pace with code.
+
+## Review and links
+
+1. Map the request to each AC. The AC and Spec must agree on outcomes, conditions, and errors.
+2. Remove implementation detail, placeholders, and contradictions. Do not guess missing product requirements.
+3. Link each Story to its Spec. Link a plan only after it exists. Use relative Markdown links and verify targets.
+4. During design/planning, describe planned endpoint/schema deltas in the Spec and plan. During implementation, retain that baseline and accumulate pending deltas in the plan or chat. After user code acceptance, update affected Specs, the canonical contract, and required ADR/glossary material in one batch under the workflow. Code-generation exceptions follow the explicitly approved build-input strategy; they do not authorize continuous Spec or canonical-contract edits.
+5. Report paths, AC, approval state, and open decisions. Writing a document does not complete an AC.
+
+For documentation-only work, hand off here. For full-flow implementation, provide the established requirements and approval evidence through [kido-brainstorming](../kido-brainstorming/SKILL.md) and [kido-writing-plans](../kido-writing-plans/SKILL.md). Bounded implementation stays with its approved chat baseline and goes to execution without mandatory product documents or a plan. After code acceptance, perform the authorized synchronization and return to handoff without restarting design/planning. This skill does not create a technical plan.

package/.agents/templates/context/current-state.md

@@ -0,0 +1,22 @@
+# <Project Name> — Current State
+
+> Context template. Save the project document at `context/current-state.md`. Record the scope and date of evidence. Existing code or passing checks do not establish deployment or acceptance.
+
+**Updated:** <Date>
+**Survey scope:** <Components, sources, and limits>
+
+## Delivery State
+
+| Component / Story | Implementation | Verification / evidence | Deployment | Review / acceptance |
+| --- | --- | --- | --- | --- |
+| <Component> | <State> | <Evidence or not verified> | <Evidence or not confirmed> | <Actual feedback or pending> |
+
+## Known Gaps & Tech Debt
+
+| Gap | Observed source | Impact | Decision / next step |
+| --- | --- | --- | --- |
+| <Gap> | <Evidence> | <Impact> | <Confirmed decision or proposal> |
+
+## Roadmap & Open Decisions
+
+<Distinguish approved plans from proposals. Link existing Stories, Specs, and plans.>

package/.agents/templates/context/glossary.md

@@ -0,0 +1,11 @@
+# <Project Name> — Glossary
+
+> Context template. Save the project document at `context/glossary.md`. Keep one canonical definition per concept. Confirm terms inferred from code before treating them as requirements.
+
+| Canonical term | Definition | Aliases | Source / confirmation status |
+| --- | --- | --- | --- |
+| <Term> | <Meaning in this project> | <Other names> | <Source or not confirmed> |
+
+## Open Definitions
+
+<Conflicting or unclear concepts, related sources, and the person who must decide.>

package/.agents/templates/context/overview.md

@@ -0,0 +1,28 @@
+# <Project Name> — Overview
+
+> Context template. Save the project document at `context/overview.md`. Source every factual claim; mark inferences separately for confirmation. Current code does not establish an approved business objective.
+
+**Document status:** Draft
+**Sources / survey scope:** <Actual sources and limits>
+
+## Problem & Purpose
+
+<Problem, confirmed goals, and decisions still needed from the owner.>
+
+## Actors & Outcomes
+
+| Actor | Need | Confirmed outcome / assumption |
+| --- | --- | --- |
+| <Actor> | <Need> | <Outcome and source> |
+
+## System Boundaries
+
+<Owned components, external integrations, data sources, and ownership.>
+
+## Constraints & Sources
+
+<Relative links to existing architecture, invariants, canonical contracts, and design system.>
+
+## Open Questions
+
+<Unclear points, decision owner, and impact.>

package/.agents/templates/epics/EPIC-001-template/US-template-slug/spec.md

@@ -0,0 +1,51 @@
+# US-xxx: <Tên thay đổi> — Change Specification
+
+> Template chung cho WHAT & BOUNDARIES. Không chứa mã triển khai, hooks, CSS, lựa chọn framework/hạ tầng hoặc danh sách file source. HOW thuộc plan của package. Thay nội dung mẫu; phần không áp dụng ghi lý do.
+
+**Story:** [story.md](./story.md)
+**AC được đặc tả:** <ID AC từ Story>
+**Trạng thái yêu cầu:** Draft
+
+## 1. Current Behavior
+
+<Hành vi hiện tại, điều kiện và nguồn quan sát. Phân biệt chưa có hành vi với chưa đủ evidence.>
+
+## 2. Required Behavior
+
+| AC | Điều kiện / trạng thái | Hành vi cần đạt |
+| --- | --- | --- |
+| AC-01 | <Điều kiện> | <Kết quả nhất quán với Story> |
+| AC-02 | <Lỗi/boundary> | <Kết quả đã chốt> |
+
+## 3. Rules & Boundaries
+
+- <Quy tắc áp dụng và liên kết tương đối tới nguồn chuẩn>
+- <Hành vi cần bảo toàn và ranh giới không thuộc thay đổi>
+
+## 4. Flow & States
+
+<Luồng chính, chuyển trạng thái, điều kiện kết thúc và nhánh lỗi. Dùng sequence diagram khi giúp làm rõ tương tác; không mặc định actor hay subsystem từ một dự án khác.>
+
+## 5. Contract / Data Delta
+
+**Nguồn canonical:** <Liên kết tương đối tới contract hiện có hoặc lý do không áp dụng>
+
+| Thành phần hợp đồng | Hiện tại | Yêu cầu | AC |
+| --- | --- | --- | --- |
+| <Endpoint/trường/quyền/lỗi quan sát được> | <Hiện trạng> | <Delta> | <ID AC> |
+
+<Nêu tác động tương thích và bên sử dụng bị ảnh hưởng; không chọn cách triển khai.>
+
+## 6. Validation & Errors
+
+| Điều kiện | Kết quả quan sát được | AC | Evidence cần có |
+| --- | --- | --- | --- |
+| <Invalid input/lỗi/boundary liên quan> | <Kết quả đã chốt> | <ID AC> | <Quan sát xác nhận hành vi> |
+
+## 7. Security & Observability Delta
+
+<Thay đổi quyền, dữ liệu nhạy cảm hoặc sự kiện cần quan sát ở mức yêu cầu; không có thay đổi thì ghi rõ cùng lý do.>
+
+## 8. Open Decisions
+
+<Giả định chưa được xác nhận, nguồn cần bổ sung và AC bị phụ thuộc. Không biến gap thành yêu cầu đã duyệt.>

package/.agents/templates/epics/EPIC-001-template/US-template-slug/story.md

@@ -0,0 +1,47 @@
+# US-xxx: <Tên Story>
+
+> Template chung. Thay ID/slug và nội dung mẫu. AC mô tả điều actor hoặc hệ thống bên ngoài quan sát được; không đưa cách triển khai vào yêu cầu. ID AC phải ổn định để truy vết tới Spec, plan và evidence.
+
+**Trạng thái yêu cầu:** Draft
+**Nguồn yêu cầu:** <Nguồn và quyết định đã xác nhận>
+
+## 1. User Story
+
+- **As a:** <Actor>
+- **I want:** <Nhu cầu>
+- **So that:** <Giá trị/kết quả cần đạt>
+
+## 2. Context & Triggers
+
+<Điều kiện đầu vào, sự kiện kích hoạt, quyền của actor và phụ thuộc liên quan.>
+
+## 3. Acceptance Criteria
+
+| ID | Điều kiện | Thao tác / sự kiện | Kết quả quan sát được |
+| --- | --- | --- | --- |
+| AC-01 | <Điều kiện> | <Thao tác> | <Kết quả> |
+| AC-02 | <Lỗi hoặc boundary thuộc phạm vi> | <Sự kiện> | <Kết quả đã chốt> |
+
+> Thêm/bớt AC theo yêu cầu thật; không mặc định mất mạng, fallback hoặc một trạng thái giao diện cụ thể. Chưa có evidence thì không đánh dấu AC đạt.
+
+## 4. Open Decisions
+
+| Giả định / quyết định | Người cần xác nhận | Ảnh hưởng |
+| --- | --- | --- |
+| <Điểm chưa rõ hoặc không có> | <Người phụ trách> | <AC/phạm vi phụ thuộc> |
+
+## 5. Traceability
+
+- **Epic:** [epic.md](../epic.md)
+- **Spec:** [spec.md](./spec.md)
+
+> Chỉ thêm liên kết tới các plan thực tế đã tồn tại khi có; không liên kết template như plan của Story. Chi tiết kỹ thuật vẫn nằm trong plan.
+
+## 6. Acceptance Evidence
+
+| AC | Evidence / giới hạn | Trạng thái kiểm chứng |
+| --- | --- | --- |
+| AC-01 | <Nguồn evidence hoặc chưa có> | Chưa kiểm chứng |
+| AC-02 | <Nguồn evidence hoặc chưa có> | Chưa kiểm chứng |
+
+**Nghiệm thu:** Chưa có xác nhận. Ghi nguồn, phạm vi và thời điểm khi có phản hồi thực tế.

package/.agents/templates/epics/EPIC-001-template/epic.md

@@ -0,0 +1,56 @@
+# EPIC-xxx: <Tên Epic>
+
+> Template chung. Thay ID/slug và nội dung mẫu trước khi bàn giao. Giữ problem, outcome và scope ở tầng yêu cầu; cách triển khai thuộc plan. Mục không áp dụng ghi lý do, không tự bổ sung yêu cầu để điền mẫu.
+
+**Trạng thái yêu cầu:** Draft
+**Nguồn yêu cầu:** <Nguồn, người phụ trách và quyết định đã xác nhận>
+
+## 1. Problem
+
+<Actor gặp vấn đề gì, trong điều kiện nào, tác động và bằng chứng hiện có.>
+
+## 2. Outcome
+
+<Kết quả quan sát được sau thay đổi và giá trị cần đạt.>
+
+## 3. Scope
+
+### In scope
+
+- <Kết quả/hành vi thuộc phạm vi>
+
+### Out of scope
+
+- <Kết quả/hành vi nằm ngoài phạm vi>
+
+## 4. Constraints & Invariants
+
+| Nguồn chuẩn / ID | Ràng buộc áp dụng | Kết quả cần bảo toàn |
+| --- | --- | --- |
+| <Liên kết tương đối tới nguồn hiện có> | <Ràng buộc của dự án> | <Kết quả quan sát được> |
+
+## 5. Success Metrics
+
+| Chỉ số | Baseline / chưa có số liệu | Mục tiêu | Cách đo |
+| --- | --- | --- | --- |
+| <Metric> | <Evidence hoặc gap> | <Mục tiêu đã chốt> | <Phương thức đo> |
+
+## 6. Stories
+
+- [US-xxx-slug](./US-xxx-slug/story.md)
+
+> Khi dùng template, chỉ liên kết Story đã tồn tại và thay đường dẫn theo slug thực tế.
+
+## 7. Definition of Done
+
+- [ ] AC của các Story trong phạm vi có evidence phù hợp; phần chưa đạt được ghi rõ.
+- [ ] Constraints/invariants liên quan được đối chiếu với evidence.
+- [ ] Contract và tài liệu bị ảnh hưởng đã được đồng bộ hoặc ghi lý do không cần đổi.
+- [ ] Kiểm chứng cần thiết theo policy dự án đã được thực hiện và ghi nhận giới hạn.
+- [ ] Trạng thái triển khai, kiểm chứng, deploy và nghiệm thu được ghi riêng theo thực tế.
+
+## 8. Open Decisions
+
+| Quyết định / giả định | Người cần xác nhận | Ảnh hưởng khi chưa chốt |
+| --- | --- | --- |
+| <Điểm chưa rõ hoặc không có> | <Người phụ trách> | <Phần bị phụ thuộc> |

package/.agents/templates/implementation-plan.md

@@ -0,0 +1,71 @@
+# <Change Name> — Implementation Plan
+
+> Shared template for full-flow changes or an explicitly requested plan, not an approved plan. Bounded work may retain design and acceptance checks in chat without creating this file. Save at `packages/<pkg>/plans/<plan-name>.md`; replace placeholders and explain sections that do not apply.
+
+**Goal:** <Technical outcome serving the requirement>
+**Package / scope:** <Responsible package and path limits; reference services are read-only>
+**Story / Spec or request:** <Existing document links; supplied requirements/chat baseline for an explicitly requested plan when product documents do not apply>
+**Acceptance checks:** <AC IDs or request checks with implementation/verification coverage>
+**Status:** Pending plan approval
+
+## 1. Approval & Permissions
+
+| Item | Content / version / scope | Evidence and status |
+| --- | --- | --- |
+| Design | <Design scope> | <Actual feedback or pending> |
+| Plan | <Plan version> | Pending approval |
+| Commands | <Command, working directory, and execution scope> | <Authorized or permission needed> |
+
+> Apply the action boundaries in `kido-workflow`: distinguish edit, command, and Git/data permissions and reuse matching session authorization. Record only actual approval.
+
+## 2. Architecture & Reuse
+
+<Boundaries, data flow, state owner, interfaces/types, dependencies, and side effects.>
+
+**Reuse:** <Implementations and callers inspected; abstraction to reuse or extend, or reason to add one>
+**Constraints:** <Canonical contract, design system, invariants, and coding conventions>
+**Dependencies:** <Required changes or confirmation that none are needed>
+
+## 3. Tasks
+
+### Task <N>: <Deliverable>
+
+**Acceptance checks:** <Applicable AC IDs or supplied request checks>
+**Files:** <Actual paths marked [NEW] or [MODIFY]>
+**Interfaces / behavior:** <Signatures, inputs/outputs, state, errors, and boundaries>
+**Dependencies:** <Prior tasks or required sources>
+
+- [ ] RED: <Test case, command, and expected failure for the correct reason before production code>
+- [ ] GREEN: <Minimum change and command showing the outcome>
+- [ ] REFACTOR: <Only if needed; what to recheck>
+- [ ] Match acceptance checks, approved contract delta, and evidence without rewriting upstream documents.
+
+> Use RED/GREEN for behavior changes with a meaningful test under project policy. Verify mechanical or document changes appropriately. Record the reason, alternative check, and required approval for a TDD exception before code; setup failures are not valid RED evidence.
+
+## 4. Verification Matrix
+
+| AC / requirement | Case / boundary | Check or command + working directory | Expected result | Permission | Evidence / status |
+| --- | --- | --- | --- | --- | --- |
+| <ID> | <Case> | <Confirmed command or direct check> | <Result> | <Evidence or missing> | Not run |
+
+## 5. SSOT Delta
+
+Keep requirements, Specs, and canonical contracts fixed during implementation and review fixes. Record pending deltas here; do not update upstream documents after every task. After explicit code acceptance, synchronize affected sources once and verify against accepted code. Preserve their authority and approval states.
+
+| Source | Update needed / reason no update is needed |
+| --- | --- |
+| Story / Spec | <Impact> |
+| Canonical contract | <Impact> |
+| ADR / glossary / design system | <Impact> |
+| Current state | <Changed state, gap, debt, or roadmap> |
+
+**Code-generation strategy:** <Not applicable, or explicitly authorized temporary build-input/artifact paths, approved delta, and command permissions. No automatic canonical-contract edits or duplicate SSOT.>
+
+## 6. Handoff
+
+<Diff, AC → change → evidence, observed RED/GREEN or approved exception, checks not run, and limits.>
+
+**Implementation:** <Actual state>
+**Verification:** <Actual state>
+**Deployment:** <Actual state>
+**Review / acceptance:** <Pending or actual feedback evidence>

package/.agents/templates/workspace-instructions.md

@@ -0,0 +1,50 @@
+# <Workspace Name> — Project Instructions
+
+> Template for project instructions at the workspace root. Do not copy it verbatim as approved policy. Review existing instructions first, keep unconfirmed facts and permissions in Draft status, and recalculate relative links from the actual file location.
+
+## 1. Project Snapshot
+
+<Purpose, actors, components, and links to canonical context.>
+
+## 2. Workspace Layout & Ownership
+
+<Selected project/workspace root and supporting evidence; distinguish it from component Git roots. Resolve shared context and entrypoint paths from this root, and record any component outside authorized scope.>
+
+| Component | Path | Ownership | Authorized read/write scope |
+| --- | --- | --- | --- |
+| <Component> | <Relative path> | <Owned / Reference / External writable> | <Exact scope; a symlink does not grant access> |
+
+## 3. Context Routing
+
+| Task domain | Required sources | Canonical contract / design system / invariants |
+| --- | --- | --- |
+| <Domain> | <Relative links to existing sources> | <Authority and generated or legacy material to distinguish> |
+
+## 4. Document Boundaries
+
+`context/` holds system knowledge. `epics/` holds problems, outcomes, Stories, Acceptance Criteria (AC), and behavior Specs. `packages/<pkg>/plans/` holds files, interfaces, and implementation details. Link Stories, Specs, and plans to existing documents, using stable AC IDs.
+
+When TypeSpec is used for contracts, default to `context/contracts/`. Record its `main.tsp` entrypoint, domain modules, and generated artifacts in the routing table. For a domain task, read that module and relevant dependencies; do not load the entire contract without a reason. A scaffold awaiting migration does not replace an existing canonical contract. Mark `.tsp` as the SSOT only after its authority is confirmed.
+
+## 5. Workflow & Approval
+
+<Bounded in-chat design/checks versus full Story/AC/Spec/design/plan flow; approval evidence, TDD exceptions, and applicable project policy. Honor explicit user instructions and reuse matching authorization. Questions, reviews, and documentation tasks stay in their scope.>
+
+<Implementation uses a fixed approved baseline. Accumulate pending Spec/contract deltas in the plan/chat; synchronize affected SSOT sources once after explicit code acceptance. Record any explicitly approved temporary code-generation strategy before implementation.>
+
+## 6. Commands & State Permissions
+
+| Action | Command / shell / working directory, if applicable | Policy and required permission |
+| --- | --- | --- |
+| <Scripts/tests/format/build> | <Command confirmed to exist> | <Not granted or exact authorization> |
+| <Git/data/deploy/cleanup> | <Action> | <Not granted or exact authorization> |
+
+Apply `kido-workflow` action boundaries and record this project's actual permissions: file edits, commands, and Git/data/runtime actions are distinct; reuse matching authorization and ask only for missing or materially changed scope. Never read environment files or infer execution permission from documented scripts or plan approval alone.
+
+## 7. Verification & Handoff
+
+<Required checks by domain, AC-to-evidence mapping, evidence location, and current state. Distinguish implementation, verification, deployment, and acceptance.>
+
+## 8. Agent Entry Points
+
+<Skill and rule locations, and entrypoints supported by each tool. Response conventions if required. Do not assume every agent loads the same rule format or has read these instructions.>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KIDO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# kido-workspace-template
+
+Bộ skills, rules và templates của KIDO dành cho AI agent làm việc trên các project.
+
+## Cấu trúc workspace được khởi tạo
+
+Workspace sau khi khởi tạo có cấu trúc mục tiêu:
+
+| Thư mục | Nội dung |
+| --- | --- |
+| `context/` | Context dùng chung: overview, glossary, current-state và API contract TypeSpec tại `contracts/` (được điền sau khi onboarding khảo sát API) |
+| `.agents/skills/` | Bộ KIDO skills dùng trong workspace |
+| `.agents/rules/` | Rules và hướng dẫn agent dùng trong workspace |
+| `epics/` | Epics, Stories, Acceptance Criteria và Specs của workspace |
+| `packages/` | Các component/codebase FE, BE và package khác |
+
+`context/`, `.agents/` và `epics/` thuộc workspace root. Mỗi package trong `packages/` có thể là repo riêng. Khi gọi onboarding từ workspace cha, agent hỏi một lần cho các component FE/BE ngoài `packages/`: move vào `packages/<tên-component>/` hay giữ source tại chỗ và tạo symlink từ package tương ứng. Quy tắc này cũng áp dụng khi gọi từ repo con, sau khi xác định workspace root. Không tự move hoặc tạo symlink trước khi người dùng chọn; dùng lại lựa chọn đã có khi onboard lại.
+
+## CLI init và upgrade
+
+CLI yêu cầu Node.js 22 trở lên, dùng tài nguyên đi kèm package đang chạy và không truy cập Git công ty. CLI không tự chạy onboarding, build, Git hoặc di chuyển FE/BE.
+
+Sau khi package được phát hành lên npm, chạy tại thư mục workspace cần khởi tạo:
+
+```sh
+npx kido-workspace@latest init --dry-run
+npx kido-workspace@latest init
+```
+
+`init` chép skills, rules và templates vào `.agents/`, tạo `context/contracts/`, `epics/`, `packages/` nếu chưa có, cùng metadata `.agents/kido-install.json`. `.agents/` là thư mục thật duy nhất chứa tài nguyên agent; không tạo `agents/`. `.claude/skills/<skill>` trỏ tới từng skill dùng chung và `.claude/templates` trỏ tới `.agents/templates/`. Các symlink dùng đường dẫn tương đối trên macOS/Linux; Windows dùng directory junction.
+
+`AGENTS.md` và `CLAUDE.md` chỉ được tạo bootstrap khi chưa tồn tại. Các entrypoint, context và component đã có được giữ nguyên. Nếu resource directory, metadata hoặc adapter trùng với nội dung đang có, CLI dừng trước khi ghi. Không tự hợp nhất hay di chuyển một cây `.agents/` đã có; workspace đã khởi tạo bằng CLI này dùng `upgrade`.
+
+Nâng tài nguyên lên bản package mới nhất:
+
+```sh
+npx kido-workspace@latest upgrade --dry-run
+npx kido-workspace@latest upgrade
+```
+
+`upgrade` chỉ quản lý các file tài nguyên được ghi trong metadata và tài nguyên mới từ package. Checksum lưu trong metadata giúp đối chiếu bản đã cài, bản local và bản đi kèm package:
+
+- File chưa chỉnh local được cập nhật; file mới không trùng được thêm vào.
+- File chỉ đổi local, còn upstream không đổi, được giữ nguyên.
+- Nếu cả local và upstream thay đổi khác nhau, file local được giữ lại và báo conflict. Các file không có xung đột vẫn được cập nhật; CLI trả exit code `2` và lưu danh sách conflict trong metadata.
+- File bị upstream loại bỏ chỉ được xóa khi chưa chỉnh local. File riêng của project, context, entrypoint và source ứng dụng không thuộc phạm vi upgrade.
+
+Đối chiếu file conflict với bản trong `.agents/` của package đã tải và hợp nhất thủ công. Nếu file local đã giống upstream, chạy lại `upgrade` để ghi nhận. Nếu muốn giữ nội dung khác upstream sau khi review, chỉ định từng file:
+
+```sh
+npx kido-workspace@latest upgrade --keep-local .agents/skills/kido-workflow/SKILL.md
+```
+
+`--keep-local` giữ nguyên file local và ghi nhận checksum upstream làm baseline mới; lần sau upstream đổi vẫn phát hiện xung đột. Có thể lặp tùy chọn cho nhiều file hoặc kết hợp `--dry-run`. Với file đã bị upstream loại bỏ, tùy chọn này giữ file như tài nguyên riêng của project. `templateVersion` ghi version package đã đối chiếu; trường `conflicts` cho biết upgrade còn phần chưa hoàn tất.
+
+`--dry-run` thực hiện cùng kiểm tra nhưng không ghi file. Để chọn version cụ thể, thay `@latest` bằng version đó. Workspace đã init bằng CLI cũ với `.agents → agents` và metadata checksum hợp lệ được chuyển layout khi chạy `upgrade`: thư mục thật `agents/` đổi thành `.agents/`, cập nhật adapter Claude, đường dẫn metadata và các tham chiếu tài nguyên ở root trong `AGENTS.md`/`CLAUDE.md` nếu là file thường, giữ nguyên các policy khác. `--dry-run` không thực hiện việc chuyển này. Installation metadata từ shell script cũ chưa có checksum không được tự tiếp nhận; cần đối chiếu layout và tùy chỉnh trước khi chuyển sang CLI mới.
+
+Trong source repo, chạy `node bin/kido-workspace.cjs --help` để xem cú pháp. Các ví dụ npm ở trên chỉ dùng được sau khi package được publish.
+
+## Gọi onboarding
+
+Khi tài nguyên KIDO đã có trong workspace, mở thư mục gốc của toàn project trong agent và gửi:
+
+```text
+Onboard project này.
+```
+
+Agent nhận diện workspace và các component. Với FE/BE ngoài `packages/`, agent hỏi một lần: move vào `packages/<tên-component>/` hay giữ source tại chỗ và tạo symlink từ package tương ứng.
+
+Câu hỏi thực tế phải nêu source và destination của từng component. Sau khi bạn chọn, agent thực hiện placement đã chọn, khảo sát API của BE để viết `context/contracts/`, rồi khảo sát FE/BE và tài liệu dự án để viết glossary, current-state, overview, architecture và chỉ dẫn agent. Các repo đã nằm trong `packages/` hoặc đã có lựa chọn được ghi nhận không cần hỏi lại.
+
+Nếu công cụ chưa nhận diện skill, chỉ đường dẫn trực tiếp:
+
+```text
+Đọc .agents/skills/kido-onboarding/SKILL.md và thực hiện onboarding
+repository này theo hướng dẫn đó.
+
+Tạo hoặc bổ sung context, chỉ dẫn agent và contract TypeSpec từ API/schema thực tế của project; đối chiếu với contract hiện có nếu có.
+Giữ policy và tài liệu hiện có; ghi riêng những điểm cần xác nhận.
+```
+
+Nếu chỉ cần khảo sát trước, thêm: "Chỉ đọc và báo đề xuất, chưa sửa file." Nếu skill đã được công cụ nhận diện, có thể yêu cầu "Dùng kido-onboarding để onboard repository này vào KIDO."
+
+Với project gồm nhiều repo con, mở agent tại thư mục cha của toàn project. Không cần nhắc lại root/component nếu metadata và cấu trúc đã rõ. Ví dụ layout trước khi chọn placement:
+
+```text
+project-root/
+├── .agents/                   ← Skills và rules dùng chung
+├── context/                  ← Context chung, gồm contracts/
+├── epics/                    ← Epics, Stories và Specs
+├── AGENTS.md hoặc CLAUDE.md   ← Entrypoint theo agent đang dùng
+├── packages/                 ← Đích move hoặc symlink sau khi chọn
+├── web-app/                  ← Repo frontend đang có
+└── api-service/              ← Repo backend đang có
+```
+
+```text
+Onboard project này.
+```
+
+Git root của `api-service/` không phải root của toàn project; thư mục cha không cần có `.git`. Nếu agent đang mở trong repo con, nó phải xác định root từ yêu cầu và cấu trúc trong phạm vi được phép trước khi ghi file; hỏi lại khi chưa rõ. Chỉ onboarding riêng trong repo con khi yêu cầu hoặc ranh giới project đã xác định phạm vi đó. Context/chỉ dẫn sẵn có trong repo con được giữ lại và ghi nhận để đối chiếu, không tự xóa hoặc di chuyển.
+
+Agent tạo hoặc bổ sung overview, glossary, current-state, architecture, báo cáo khảo sát và entrypoint. Onboarding khảo sát API/schema trong source cùng contract hiện có, rồi viết TypeSpec model/operation cho phần có evidence. Mặc định TypeSpec nằm tại `context/contracts/`: `main.tsp` chỉ import các module theo miền; mỗi miền có thư mục và các file model/operation riêng. Repo không cần có OpenAPI/Proto trước. Nếu code và tài liệu API mâu thuẫn, agent ghi điểm lệch và giữ contract mới ở trạng thái Draft cho review; không tự tuyên bố SSOT đã được phê duyệt. Nếu chưa xác minh được API/schema, scaffold được ghi rõ là chưa có contract nghiệp vụ. Scaffold KIDO cũ ở root `contracts/` cần được chuyển vào `context/contracts/` khi onboarding chạy lại, không giữ hai nguồn chuẩn. Policy riêng của project chọn chuẩn khác hoặc cấm tạo `.tsp` được ưu tiên. Không tự sinh lịch sử Epic/Story, implementation plan hoặc approval.
+
+Onboarding là công việc của agent khi tài nguyên đã có trong workspace; phạm vi viết TypeSpec ở trên không cấp quyền chạy scripts/build, sửa source ứng dụng, dependencies, deploy hay commit/push. Policy của project đích vẫn được áp dụng.

package/bin/kido-workspace.cjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../lib/workspace.cjs');
+
+try {
+  process.exitCode = run(process.argv.slice(2));
+} catch (error) {
+  console.error(`kido-workspace: ${error.message}`);
+  process.exitCode = 1;
+}