shipfast-mcp 0.1.0__tar.gz

shipfast_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuocTang
+
+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.

shipfast_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: shipfast-mcp
+Version: 0.1.0
+Summary: MCP server phân phối quy trình làm việc theo đợt giữa PO và AI (Điều hành, agent con), dùng được cho mọi stack.
+Keywords: mcp,model-context-protocol,ai-agent,workflow,claude-code,skills
+Author: QuocTang
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Requires-Dist: fastmcp>=4.1,<5
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/QuocTang/shipfast-mcp
+Project-URL: Issues, https://github.com/QuocTang/shipfast-mcp/issues
+Description-Content-Type: text/markdown
+
+# 🚢 shipfast-mcp
+
+<!-- mcp-name: io.github.QuocTang/shipfast-mcp -->
+
+**Quy trình làm việc theo đợt giữa người và AI, cài bằng một dòng MCP.** AI làm Điều hành: đề xuất, phản biện, giữ hồ sơ, điều phối agent con. Người làm PO: chốt và nghiệm thu. Dùng được cho mọi stack.
+
+[![CI](https://github.com/QuocTang/shipfast-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/QuocTang/shipfast-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/shipfast-mcp.svg)](https://pypi.org/project/shipfast-mcp/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![MCP](https://img.shields.io/badge/MCP-2026--07--28-8A2BE2.svg)](https://modelcontextprotocol.io/specification/2026-07-28)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> A Model Context Protocol server that ships a wave-based PO ↔ AI working process (propose, critique, decide, build, verify) to any stack, with three-way-merge upgrades so projects never diff against a template repo by hand.
+
+## Table of Contents
+
+- [🚀 Quick Start](#quick-start)
+- [🛠️ Installation](#installation)
+- [📦 Features](#features)
+- [🤝 How to Contribute](#how-to-contribute)
+- [💬 Community & Support](#community--support)
+- [👥 Repo Contributors](#repo-contributors)
+- [⚖️ License](#license)
+- [🌟 Star History](#star-history)
+
+---
+
+## Quick Start
+
+Cần [uv](https://docs.astral.sh/uv/). Trong Claude Code:
+
+```text
+/plugin install shipfast --marketplace QuocTang/shipfast-mcp
+```
+
+Mở repo cần làm, gọi điểm vào phù hợp:
+
+| Tình huống | Gọi | Kết quả |
+|---|---|---|
+| Repo mới, chưa có code | `/mcp__shipfast__init` | Đợt W01: AI hỏi về sản phẩm, đề xuất và phản biện 2–3 phương án stack, PO chốt; dựng khung tài liệu, khung code chạy được, nghiệm thu |
+| Dự án đang chạy | `/mcp__shipfast__adopt` | AI khảo sát cái đang có, lập bảng đối chiếu; khung được thêm mà không phá tài liệu, quyết định sẵn có |
+| Đã dùng shipfast | Hỏi "đang tới đâu" | Skill trong dự án tự kích hoạt, AI gọi `status` và làm tiếp |
+
+Sau đó làm việc như với một trưởng nhóm: nêu yêu cầu, trả lời theo mã ("W02-03: A"), nói **"chốt"** khi đồng ý phạm vi.
+
+## Installation
+
+| Công cụ | Cách cài |
+|---|---|
+| Claude Code (plugin) | `/plugin install shipfast --marketplace QuocTang/shipfast-mcp` |
+| Claude Code (MCP) | `claude mcp add shipfast -- uvx shipfast-mcp` |
+| Cursor, VS Code, Codex và client MCP khác | Server stdio, lệnh `uvx`, tham số `shipfast-mcp` |
+
+Cấu hình dạng JSON cho client đọc `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "shipfast": { "command": "uvx", "args": ["shipfast-mcp"] }
+  }
+}
+```
+
+Ghim phiên bản: `uvx shipfast-mcp@0.1.0`.
+
+## Features
+
+### Vấn đề và cách giải
+
+| Khi làm việc với AI không có quy trình | shipfast |
+|---|---|
+| AI viết code khi chưa hiểu đúng yêu cầu | 🛑 Không code trước khi PO chốt phạm vi |
+| AI chiều theo mọi yêu cầu | 🥊 Điều hành phản biện cả đề xuất của mình; 7 vai phản biện tranh luận độc lập rồi phản biện chéo |
+| Quyết định rải rác trong chat và comment | 📒 Sổ quyết định một chỗ (`SP`, `KT`, `QT`), code chỉ trỏ mã |
+| Phiên mới quên bối cảnh | 💾 Trạng thái nằm trong file; tool `status` cho biết đang tới đâu |
+| Phạm vi phình dần | 📥 Việc mới vào backlog, đổi phạm vi qua CR |
+| "Xong" nhưng chưa chạy thật | ✅ Cổng kiểm chứng phải chạy thật; QA độc lập nghiệm thu |
+| Chép template rồi lệch dần, cập nhật phải so tay với repo gốc | 🔀 Nâng cấp gộp ba phía tự động, không cần repo gốc |
+
+### Vòng đời một đợt
+
+```text
+📥 Gom việc → 🗣️ Thảo luận → ✅ Chốt → 🔨 Thi công → 🧹 Dọn dẹp → 🧪 Nghiệm thu → 🚀 Phát hành, rút kinh nghiệm, đóng
+```
+
+| Chế độ chốt | Khi nào |
+|---|---|
+| PO chốt | Mặc định |
+| Chốt thẳng | Đợt nhỏ, yêu cầu đã rõ |
+| Uỷ quyền | Đã có từ hai bộ phận; Chủ toạ phán quyết theo tiêu chí PO đặt |
+
+### Thành phần MCP
+
+| Loại | Tên | Việc |
+|---|---|---|
+| 🔧 Tool | `scaffold_project` | Dựng `CLAUDE.md`, `docs/` (đợt, backlog, sổ quyết định, tổ chức) và skill `.claude/skills/shipfast-*`; chạy thử trước, không ghi đè |
+| 🔧 Tool | `upgrade` | Nâng khung lên phiên bản mới bằng gộp ba phía |
+| 🔧 Tool | `status`, `check` | Đợt nào đang chạy, chờ PO điều gì; hồ sơ có lệch không |
+| 🔧 Tool | `open_wave`, `new_decision`, `next_code` | Mở đợt, ghi quyết định, cấp mã không trùng |
+| 🔧 Tool | `read_guide` | Tài liệu hướng dẫn cho người |
+| 💬 Prompt | `init`, `adopt`, `upgrade` | Điểm vào |
+| 📚 Resource | `skill://shipfast-*/SKILL.md` | 6 skill: luật nền, khởi tạo, áp dụng, chạy đợt, tranh luận, nâng cấp |
+| 📚 Resource | `shipfast://guide/*` | Bắt đầu, tổ chức, ý nghĩa, phát triển và nâng cấp |
+
+### Nâng cấp không cần repo gốc
+
+Dự án giữ `.shipfast/manifest.json` và `.shipfast/base/` (bản khung lần trước). `upgrade` so ba bản: bản gốc, bản dự án, bản mới.
+
+| Trường hợp | Kết quả |
+|---|---|
+| Dự án chưa sửa file | Thay bằng bản mới |
+| Hai bên sửa khác chỗ | Gộp tự động |
+| Hai bên sửa cùng chỗ | File thật giữ nguyên; bản gộp có dấu xung đột ở `.shipfast/pending/` để duyệt |
+| Bảng đợt, backlog, sổ quyết định | Không bao giờ bị đụng |
+
+### Hướng dẫn
+
+| Bài | File |
+|---|---|
+| Bắt đầu từ đâu | [`start.md`](src/shipfast_mcp/knowledge/guide/start.md) |
+| Tổ chức ra sao | [`organization.md`](src/shipfast_mcp/knowledge/guide/organization.md) |
+| Ý nghĩa và mục đích | [`purpose.md`](src/shipfast_mcp/knowledge/guide/purpose.md) |
+| Phát triển tiếp và nâng cấp | [`evolve.md`](src/shipfast_mcp/knowledge/guide/evolve.md) |
+
+## How to Contribute
+
+Đóng góp được hoan nghênh, nhất là cách làm đã chạy thật ở dự án của bạn và dùng được cho mọi stack.
+
+1. **Fork** repository.
+2. **Tạo nhánh mới** cho thay đổi.
+3. **Gửi Pull Request**: mô tả vấn đề gặp phải, cách làm, bằng chứng từ dự án thật.
+
+Phát triển tại máy:
+
+```bash
+uv sync
+uv run pytest
+uv run shipfast-mcp
+```
+
+Kho tri thức nằm ở `src/shipfast_mcp/knowledge/`: `project/` (khung dựng vào dự án), `skills/`, `guide/`. Quyết định thiết kế: [`docs/decisions/README.md`](docs/decisions/README.md).
+
+## Community & Support
+
+- Báo lỗi, đề xuất: [GitHub Issues](https://github.com/QuocTang/shipfast-mcp/issues).
+- Nếu repository giúp bạn tiết kiệm thời gian, hãy để lại một ⭐.
+
+## Repo Contributors
+
+<a href="https://github.com/QuocTang/shipfast-mcp/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=QuocTang/shipfast-mcp" alt="Repository contributors" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=QuocTang/shipfast-mcp&type=Date)](https://star-history.com/#QuocTang/shipfast-mcp&Date)

shipfast_mcp-0.1.0/README.md

@@ -0,0 +1,162 @@
+# 🚢 shipfast-mcp
+
+<!-- mcp-name: io.github.QuocTang/shipfast-mcp -->
+
+**Quy trình làm việc theo đợt giữa người và AI, cài bằng một dòng MCP.** AI làm Điều hành: đề xuất, phản biện, giữ hồ sơ, điều phối agent con. Người làm PO: chốt và nghiệm thu. Dùng được cho mọi stack.
+
+[![CI](https://github.com/QuocTang/shipfast-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/QuocTang/shipfast-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/shipfast-mcp.svg)](https://pypi.org/project/shipfast-mcp/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![MCP](https://img.shields.io/badge/MCP-2026--07--28-8A2BE2.svg)](https://modelcontextprotocol.io/specification/2026-07-28)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> A Model Context Protocol server that ships a wave-based PO ↔ AI working process (propose, critique, decide, build, verify) to any stack, with three-way-merge upgrades so projects never diff against a template repo by hand.
+
+## Table of Contents
+
+- [🚀 Quick Start](#quick-start)
+- [🛠️ Installation](#installation)
+- [📦 Features](#features)
+- [🤝 How to Contribute](#how-to-contribute)
+- [💬 Community & Support](#community--support)
+- [👥 Repo Contributors](#repo-contributors)
+- [⚖️ License](#license)
+- [🌟 Star History](#star-history)
+
+---
+
+## Quick Start
+
+Cần [uv](https://docs.astral.sh/uv/). Trong Claude Code:
+
+```text
+/plugin install shipfast --marketplace QuocTang/shipfast-mcp
+```
+
+Mở repo cần làm, gọi điểm vào phù hợp:
+
+| Tình huống | Gọi | Kết quả |
+|---|---|---|
+| Repo mới, chưa có code | `/mcp__shipfast__init` | Đợt W01: AI hỏi về sản phẩm, đề xuất và phản biện 2–3 phương án stack, PO chốt; dựng khung tài liệu, khung code chạy được, nghiệm thu |
+| Dự án đang chạy | `/mcp__shipfast__adopt` | AI khảo sát cái đang có, lập bảng đối chiếu; khung được thêm mà không phá tài liệu, quyết định sẵn có |
+| Đã dùng shipfast | Hỏi "đang tới đâu" | Skill trong dự án tự kích hoạt, AI gọi `status` và làm tiếp |
+
+Sau đó làm việc như với một trưởng nhóm: nêu yêu cầu, trả lời theo mã ("W02-03: A"), nói **"chốt"** khi đồng ý phạm vi.
+
+## Installation
+
+| Công cụ | Cách cài |
+|---|---|
+| Claude Code (plugin) | `/plugin install shipfast --marketplace QuocTang/shipfast-mcp` |
+| Claude Code (MCP) | `claude mcp add shipfast -- uvx shipfast-mcp` |
+| Cursor, VS Code, Codex và client MCP khác | Server stdio, lệnh `uvx`, tham số `shipfast-mcp` |
+
+Cấu hình dạng JSON cho client đọc `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "shipfast": { "command": "uvx", "args": ["shipfast-mcp"] }
+  }
+}
+```
+
+Ghim phiên bản: `uvx shipfast-mcp@0.1.0`.
+
+## Features
+
+### Vấn đề và cách giải
+
+| Khi làm việc với AI không có quy trình | shipfast |
+|---|---|
+| AI viết code khi chưa hiểu đúng yêu cầu | 🛑 Không code trước khi PO chốt phạm vi |
+| AI chiều theo mọi yêu cầu | 🥊 Điều hành phản biện cả đề xuất của mình; 7 vai phản biện tranh luận độc lập rồi phản biện chéo |
+| Quyết định rải rác trong chat và comment | 📒 Sổ quyết định một chỗ (`SP`, `KT`, `QT`), code chỉ trỏ mã |
+| Phiên mới quên bối cảnh | 💾 Trạng thái nằm trong file; tool `status` cho biết đang tới đâu |
+| Phạm vi phình dần | 📥 Việc mới vào backlog, đổi phạm vi qua CR |
+| "Xong" nhưng chưa chạy thật | ✅ Cổng kiểm chứng phải chạy thật; QA độc lập nghiệm thu |
+| Chép template rồi lệch dần, cập nhật phải so tay với repo gốc | 🔀 Nâng cấp gộp ba phía tự động, không cần repo gốc |
+
+### Vòng đời một đợt
+
+```text
+📥 Gom việc → 🗣️ Thảo luận → ✅ Chốt → 🔨 Thi công → 🧹 Dọn dẹp → 🧪 Nghiệm thu → 🚀 Phát hành, rút kinh nghiệm, đóng
+```
+
+| Chế độ chốt | Khi nào |
+|---|---|
+| PO chốt | Mặc định |
+| Chốt thẳng | Đợt nhỏ, yêu cầu đã rõ |
+| Uỷ quyền | Đã có từ hai bộ phận; Chủ toạ phán quyết theo tiêu chí PO đặt |
+
+### Thành phần MCP
+
+| Loại | Tên | Việc |
+|---|---|---|
+| 🔧 Tool | `scaffold_project` | Dựng `CLAUDE.md`, `docs/` (đợt, backlog, sổ quyết định, tổ chức) và skill `.claude/skills/shipfast-*`; chạy thử trước, không ghi đè |
+| 🔧 Tool | `upgrade` | Nâng khung lên phiên bản mới bằng gộp ba phía |
+| 🔧 Tool | `status`, `check` | Đợt nào đang chạy, chờ PO điều gì; hồ sơ có lệch không |
+| 🔧 Tool | `open_wave`, `new_decision`, `next_code` | Mở đợt, ghi quyết định, cấp mã không trùng |
+| 🔧 Tool | `read_guide` | Tài liệu hướng dẫn cho người |
+| 💬 Prompt | `init`, `adopt`, `upgrade` | Điểm vào |
+| 📚 Resource | `skill://shipfast-*/SKILL.md` | 6 skill: luật nền, khởi tạo, áp dụng, chạy đợt, tranh luận, nâng cấp |
+| 📚 Resource | `shipfast://guide/*` | Bắt đầu, tổ chức, ý nghĩa, phát triển và nâng cấp |
+
+### Nâng cấp không cần repo gốc
+
+Dự án giữ `.shipfast/manifest.json` và `.shipfast/base/` (bản khung lần trước). `upgrade` so ba bản: bản gốc, bản dự án, bản mới.
+
+| Trường hợp | Kết quả |
+|---|---|
+| Dự án chưa sửa file | Thay bằng bản mới |
+| Hai bên sửa khác chỗ | Gộp tự động |
+| Hai bên sửa cùng chỗ | File thật giữ nguyên; bản gộp có dấu xung đột ở `.shipfast/pending/` để duyệt |
+| Bảng đợt, backlog, sổ quyết định | Không bao giờ bị đụng |
+
+### Hướng dẫn
+
+| Bài | File |
+|---|---|
+| Bắt đầu từ đâu | [`start.md`](src/shipfast_mcp/knowledge/guide/start.md) |
+| Tổ chức ra sao | [`organization.md`](src/shipfast_mcp/knowledge/guide/organization.md) |
+| Ý nghĩa và mục đích | [`purpose.md`](src/shipfast_mcp/knowledge/guide/purpose.md) |
+| Phát triển tiếp và nâng cấp | [`evolve.md`](src/shipfast_mcp/knowledge/guide/evolve.md) |
+
+## How to Contribute
+
+Đóng góp được hoan nghênh, nhất là cách làm đã chạy thật ở dự án của bạn và dùng được cho mọi stack.
+
+1. **Fork** repository.
+2. **Tạo nhánh mới** cho thay đổi.
+3. **Gửi Pull Request**: mô tả vấn đề gặp phải, cách làm, bằng chứng từ dự án thật.
+
+Phát triển tại máy:
+
+```bash
+uv sync
+uv run pytest
+uv run shipfast-mcp
+```
+
+Kho tri thức nằm ở `src/shipfast_mcp/knowledge/`: `project/` (khung dựng vào dự án), `skills/`, `guide/`. Quyết định thiết kế: [`docs/decisions/README.md`](docs/decisions/README.md).
+
+## Community & Support
+
+- Báo lỗi, đề xuất: [GitHub Issues](https://github.com/QuocTang/shipfast-mcp/issues).
+- Nếu repository giúp bạn tiết kiệm thời gian, hãy để lại một ⭐.
+
+## Repo Contributors
+
+<a href="https://github.com/QuocTang/shipfast-mcp/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=QuocTang/shipfast-mcp" alt="Repository contributors" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=QuocTang/shipfast-mcp&type=Date)](https://star-history.com/#QuocTang/shipfast-mcp&Date)

shipfast_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "shipfast-mcp"
+version = "0.1.0"
+description = "MCP server phân phối quy trình làm việc theo đợt giữa PO và AI (Điều hành, agent con), dùng được cho mọi stack."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "workflow",
+    "claude-code",
+    "skills",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+]
+dependencies = ["fastmcp>=4.1,<5"]
+
+[[project.authors]]
+name = "QuocTang"
+
+[project.urls]
+Repository = "https://github.com/QuocTang/shipfast-mcp"
+Issues = "https://github.com/QuocTang/shipfast-mcp/issues"
+
+[project.scripts]
+shipfast-mcp = "shipfast_mcp.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shipfast_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[project]
+name = "shipfast-mcp"
+version = "0.1.0"
+description = "MCP server phân phối quy trình làm việc theo đợt giữa PO và AI (Điều hành, agent con), dùng được cho mọi stack."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "QuocTang" }]
+requires-python = ">=3.12"
+keywords = ["mcp", "model-context-protocol", "ai-agent", "workflow", "claude-code", "skills"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "fastmcp>=4.1,<5",
+]
+
+[project.urls]
+Repository = "https://github.com/QuocTang/shipfast-mcp"
+Issues = "https://github.com/QuocTang/shipfast-mcp/issues"
+
+[project.scripts]
+shipfast-mcp = "shipfast_mcp.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shipfast_mcp-0.1.0/src/shipfast_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""shipfast-mcp: quy trình làm việc PO, Điều hành, agent con, phân phối qua MCP."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("shipfast-mcp")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

shipfast_mcp-0.1.0/src/shipfast_mcp/knowledge/guide/evolve.md

@@ -0,0 +1,29 @@
+# Phát triển tiếp và nâng cấp
+
+## Trong một dự án
+
+| Muốn | Làm |
+|---|---|
+| Đổi cách làm việc của dự án | Ghi `QT-nnn` (tool `new_decision`), sửa tài liệu tương ứng; PO chốt |
+| Thêm quy chuẩn kỹ thuật | Thêm file vào `docs/technical/`, ghi vào mục lục của thư mục |
+| Lập bộ phận | Theo `docs/ORGANIZATION.md` §6 khi một lĩnh vực có dòng việc riêng qua nhiều đợt |
+| Chạy song song nhiều agent | Chia team theo vùng thư mục (`docs/ORGANIZATION.md` §4.1) trong `2-scope.md` |
+| Giảm số lần phải chốt | Uỷ quyền (`docs/ORGANIZATION.md` §7) khi đã có từ hai bộ phận |
+| Thêm vai phản biện riêng | Thêm dòng vào `docs/ORGANIZATION.md` §7.4 |
+
+Sửa thoải mái các file khung trong dự án; khi nâng cấp, phần đã sửa được giữ và gộp với thay đổi mới.
+
+## Nâng cấp khung lên phiên bản shipfast mới
+
+1. `uvx` tự lấy bản mới nhất khi khởi động MCP (ghim phiên bản bằng `uvx shipfast-mcp@0.1.0` nếu cần).
+2. Tool `status` báo có bản mới. Gọi prompt `upgrade` hoặc nói "nâng cấp quy trình".
+3. Tool `upgrade` chạy thử trước, phân loại từng file:
+   - dự án chưa sửa → thay bằng bản mới;
+   - cả hai cùng sửa, không đụng nhau → gộp tự động;
+   - sửa cùng chỗ → bản gộp có đánh dấu xung đột ở `.shipfast/pending/`, file thật giữ nguyên, AI đề xuất cách hợp nhất để bạn duyệt;
+   - file dữ liệu của dự án (bảng đợt, backlog, sổ quyết định, thiết kế) không bao giờ bị đụng.
+4. Commit cả `.shipfast/` để người khác trong nhóm nâng cấp từ cùng một bản gốc.
+
+## Góp lại cho shipfast
+
+Cách làm nào chạy tốt ở dự án của bạn và dùng được cho mọi stack thì mở issue hoặc pull request ở repo shipfast-mcp: mô tả vấn đề gặp phải, cách làm, bằng chứng từ dự án thật. Bản phát hành mới đến với mọi dự án qua `upgrade`.

shipfast_mcp-0.1.0/src/shipfast_mcp/knowledge/guide/organization.md

@@ -0,0 +1,52 @@
+# Tổ chức ra sao
+
+## Vai trò
+
+| Vai | Ai | Làm gì | Không làm gì |
+|---|---|---|---|
+| PO | Người (bạn) | Quyết định, chốt phạm vi, duyệt, nghiệm thu | Không phải viết tài liệu quy trình |
+| Điều hành | Phiên AI chính | Đề xuất, phản biện, giữ hồ sơ, điều phối agent, tích hợp, commit khi được phép | Không tự quyết thay PO ngoài phạm vi uỷ quyền |
+| Agent con | AI do Điều hành giao việc | Thi công, khảo sát, dọn dẹp, QA trong vùng được giao | Không commit, không đụng trạng thái git chung |
+| Bộ phận | Nhóm agent theo lĩnh vực, lập khi có việc | Giữ chuẩn và sổ sách của lĩnh vực, tranh luận khi uỷ quyền | Không lập trước khi có đợt do nó chủ trì |
+| Team thi công | Nhóm agent theo vùng code trong một đợt | Thi công song song không chồng vùng | Giải tán khi đợt đóng |
+| Vai phản biện | Góc nhìn AI đóng khi tranh luận | Người dùng, sản phẩm, kiến trúc, an toàn, vận hành, QA, phản biện tự do | Chỉ tham vấn, không quyết |
+
+## Đợt (wave)
+
+Mọi việc có code đi qua một đợt 7 bước: 📥 gom việc → 🗣️ thảo luận → ✅ chốt → 🔨 thi công → 🧹 dọn dẹp → 🧪 nghiệm thu → 🚀 phát hành và đóng. Trừ hai ngoại lệ: hotfix (lỗi chặn người dùng) và việc PO giao trực tiếp (`PO-nn`, ghi lại trước khi làm).
+
+Ba chế độ chốt: PO chốt từng vấn đề (mặc định), chốt thẳng cho đợt nhỏ đã rõ, uỷ quyền cho tranh luận giữa các bộ phận.
+
+## Thư mục
+
+```text
+CLAUDE.md             luật cho AI
+docs/
+  ORGANIZATION.md     vai trò, bộ phận, team, uỷ quyền, ranh giới an toàn
+  GLOSSARY.md         từ vựng chuẩn
+  00_analysis/        phân tích hệ cũ, dự án nguồn
+  01_design/          thiết kế sản phẩm
+  02_build/           thành phần, lệnh chuẩn, hợp đồng (CONTRACTS.md)
+  03_release/         phát hành, vận hành
+  04_waves/           quy trình đợt, bảng đợt, backlog, hồ sơ Wxx/
+  05_decisions/       sổ quyết định SP/KT/QT
+  technical/          quy chuẩn kỹ thuật của stack
+.claude/skills/       skill shipfast-* (quản lý bởi shipfast, nâng cấp được)
+.shipfast/            phiên bản và bản gốc của khung (commit, không sửa tay)
+reports/              trang HTML cho PO xem offline
+tmp/                  file tạm (gitignored)
+```
+
+## Hệ mã
+
+| Mã | Là gì |
+|---|---|
+| `BL-012` | Việc trong backlog |
+| `W03` | Đợt thứ 3 |
+| `W03-04` | Vấn đề thứ 4 cần chốt trong đợt 3 |
+| `W03-P02` | Hạng mục thi công thứ 2 của đợt 3 |
+| `CR-W03-01` | Yêu cầu đổi phạm vi khi đang thi công |
+| `SP-002` / `KT-005` / `QT-003` | Quyết định sản phẩm / kỹ thuật / quy trình |
+| `PO-04`, `OPS-02`, `HOTFIX-01` | Việc ngoài đợt |
+
+Mỗi thông tin chỉ sống ở một chỗ; nơi khác trỏ mã.

shipfast_mcp-0.1.0/src/shipfast_mcp/knowledge/guide/purpose.md

@@ -0,0 +1,27 @@
+# Ý nghĩa và mục đích
+
+## Vấn đề shipfast giải quyết
+
+| Khi làm việc với AI không có quy trình | shipfast làm gì |
+|---|---|
+| AI viết code ngay khi chưa hiểu đúng yêu cầu | Không code trước khi PO chốt phạm vi |
+| AI chiều theo mọi yêu cầu, không ai chỉ ra rủi ro | Điều hành bắt buộc phản biện cả đề xuất của mình; vai phản biện cho nhiều góc nhìn |
+| Quyết định nằm rải rác trong chat, comment, tin nhắn | Sổ quyết định một chỗ, code chỉ trỏ mã |
+| Phiên mới quên hết bối cảnh | Trạng thái nằm trong file; `status` cho biết đang tới đâu |
+| Phạm vi phình dần trong lúc làm | Việc mới vào backlog, đổi phạm vi qua CR |
+| "Xong" nhưng chưa chạy thật | Cổng kiểm chứng phải chạy thật; QA độc lập nghiệm thu |
+| Rác tích tụ sau mỗi đợt | Bước dọn dẹp có ranh giới an toàn |
+| Mỗi dự án chép mẫu rồi lệch dần, cập nhật phải so tay với repo gốc | Khung phân phối qua MCP, nâng cấp gộp ba phía tự động |
+
+## Nguyên lý
+
+1. **Người quyết, AI đề xuất và phản biện.** AI được sáng tạo trong phương án, không được tự quyết điều thuộc về PO.
+2. **Trạng thái nằm trong file.** Không phụ thuộc trí nhớ của phiên hay của agent.
+3. **Mỗi thông tin một chỗ.** Chép lại là bắt đầu lệch.
+4. **Cổng phải chạy thật.** Tiêu chí đo được, bằng chứng ghi lại.
+5. **Lập tổ chức khi có việc.** Bộ phận, team, uỷ quyền chỉ dùng khi dự án thật sự cần.
+6. **Không giới hạn stack.** Quy trình không gắn công nghệ; stack là một quyết định của từng dự án.
+
+## Nguồn gốc
+
+Quy trình rút từ các dự án thật làm việc với AI theo đợt. Những cách làm tốt (chốt thẳng cho đợt nhỏ, tách team khỏi bộ phận, rút kinh nghiệm bắt buộc, cấm agent đụng trạng thái git chung) được đưa vào khung chung sau khi đã chạy thật.

shipfast_mcp-0.1.0/src/shipfast_mcp/knowledge/guide/start.md

@@ -0,0 +1,50 @@
+# Bắt đầu từ đâu
+
+shipfast là một quy trình làm việc giữa người (PO) và AI, đóng gói thành một MCP server. Cài MCP vào công cụ AI đang dùng là có quy trình; không cần clone repo mẫu, không cần so sánh tay.
+
+## 1. Cài
+
+Cần [uv](https://docs.astral.sh/uv/) (để có lệnh `uvx`).
+
+| Công cụ | Cách cài |
+|---|---|
+| Claude Code (plugin) | `/plugin install shipfast --marketplace QuocTang/shipfast-mcp` |
+| Claude Code (MCP) | `claude mcp add shipfast -- uvx shipfast-mcp` |
+| Cursor, VS Code, Codex và client MCP khác | Khai server stdio: lệnh `uvx`, tham số `["shipfast-mcp"]` |
+
+Ví dụ `.mcp.json` hoặc cấu hình tương đương:
+
+```json
+{
+  "mcpServers": {
+    "shipfast": { "command": "uvx", "args": ["shipfast-mcp"] }
+  }
+}
+```
+
+## 2. Chọn điểm vào
+
+| Tình huống | Gọi | Kết quả |
+|---|---|---|
+| Repo mới, chưa có code | Prompt `init` | Đợt W01: AI hỏi về sản phẩm, đề xuất và phản biện stack, bạn chốt; dựng khung tài liệu, khung code, chạy được, nghiệm thu |
+| Dự án đang chạy | Prompt `adopt` | AI khảo sát cái đang có, lập bảng đối chiếu, bạn duyệt; khung được thêm mà không phá tài liệu cũ |
+| Dự án đã dùng shipfast | Không cần gọi gì | Skill trong `.claude/skills/` tự kích hoạt; hỏi "đang tới đâu" để AI gọi `status` |
+
+Trong Claude Code, prompt MCP hiện dưới dạng lệnh `/mcp__shipfast__init`, `/mcp__shipfast__adopt`.
+
+## 3. Đọc gì trong ngày đầu
+
+| Thứ tự | File | Vì sao |
+|---|---|---|
+| 1 | `CLAUDE.md` | Luật cho AI, cũng là tóm tắt cho người |
+| 2 | `docs/04_waves/README.md` | Vòng đời đợt, hệ mã, luật khi thảo luận và thi công |
+| 3 | `docs/04_waves/WAVES.md` | Đợt nào đang chạy |
+| 4 | `docs/05_decisions/README.md` | Đã quyết những gì |
+| 5 | `docs/ORGANIZATION.md` | Ai làm gì, khi nào lập bộ phận, team, vai phản biện |
+
+## 4. Làm việc hằng ngày
+
+- Muốn làm gì thì nói với AI như với một trưởng nhóm: AI ghi thành vấn đề, đề xuất, phản biện, rồi hỏi bạn chốt.
+- Trả lời theo mã cho nhanh: "W02-03: A", "đồng ý trừ W02-05".
+- Nói **"chốt"** khi đồng ý phạm vi; từ đó AI thi công liên tục tới nghiệm thu.
+- Hỏi "đang tới đâu" bất cứ lúc nào; phiên mới vẫn làm tiếp được vì mọi trạng thái nằm trong file.