mx — MedX AI Workflow CLI

CLI tích hợp AI vào quy trình phát triển MedX. Giúp Claude Code hiểu context ticket, đúng lifecycle, đúng role, và đúng skill — tự động mỗi lần mở session. Hỗ trợ cả Claude Code (SessionStart hook) và Codex (AGENTS.md adapter).

Cài đặt

Global (khuyến nghị):

npm install -g medx-workflow-cli

Cài vào project (devDependencies):

npm install --save-dev medx-workflow-cli

Sau đó thêm vào package.json để dùng qua npx:

{
  "scripts": {
    "mx": "mx"
  }
}

Dùng bằng npx mx use SCRUM-xxxx hoặc npm run mx -- use SCRUM-xxxx.

Bản dev từ GitHub:

npm install --save-dev github:johnavu/mxai

Setup (một lần)

cd medx/           # vào project root
mx init            # tạo .medxflow/, cài hook, cấu hình Jira
mx who --set       # khai báo bạn là ai (FE / BE / BA / Tester / Teamlead)

Nếu project dùng song song Claude Code và Codex:

mx init --all      # bật Claude SessionStart hook + Codex AGENTS.md adapter

Chỉ bật Codex cho project hiện có:

mx init --codex
mx codex sync

Nếu muốn tách biệt setup trong medx-fe/ nhưng vẫn đọc được BE và sửa automation:

cd medx-fe
mx init --all --workspace-root .. --primary-repo medx-fe --be-readonly --automation-write

Workflow hàng ngày

# 1. Load ticket
mx use SCRUM-3699

# 2. Mở Claude Code — AI tự inject context + skill đúng lifecycle
claude

# 3. Sau khi xong một phase, chuyển lifecycle
mx advance         # In Dev → In Review

# 4. Làm nhiều ticket song song
mx task pause -n "chờ review BE"
mx use SCRUM-3700
mx task resume SCRUM-3699

# 5. Nếu dùng Codex, sync context sau khi đổi ticket
mx codex sync

Commands

| Lệnh | Mô tả | |---|---| | mx use SCRUM-xxxx | Load ticket từ Jira vào context | | mx use SCRUM-xxxx -c | Load kèm tất cả comments | | mx use SCRUM-xxxx --clast 5 | Load 5 comment gần nhất | | mx use --manual | Nhập context thủ công | | mx use --file task.md | Load từ file local | | mx who | Xem operator identity | | mx who --set | Cập nhật identity | | mx task status | Task đang active + pending | | mx task list | Tất cả tasks | | mx task pause | Tạm dừng task hiện tại | | mx task resume SCRUM-xxxx | Tiếp tục task đã pause | | mx task switch SCRUM-xxxx | Pause rồi switch | | mx task remove SCRUM-xxxx | Xóa task | | mx advance | Chuyển lifecycle state | | mx advance --to "In Review" | Chuyển trực tiếp sang state chỉ định | | mx codex sync | Đồng bộ MedX context vào AGENTS.md cho Codex | | mx doctor | Kiểm tra setup | | mx init | Khởi tạo project (Claude adapter) | | mx init --codex | Khởi tạo chỉ adapter Codex | | mx init --claude | Khởi tạo chỉ adapter Claude | | mx init --all | Khởi tạo cả Claude và Codex | | mx init --workspace-root .. --primary-repo medx-fe | Tạo overlay riêng trong repo con | | mx init --be-readonly | medx-be chỉ đọc trong overlay | | mx init --automation-write | Cho phép sửa medx-automation trong overlay |

Lifecycle MedX

Draft → Ready for Dev → In Dev → In Review → Testing → Rework Needed → Build → Done

SessionStart hook tự động inject instruction phù hợp với lifecycle + role hiện tại.

Với Codex, mx codex sync ghi một block có marker vào AGENTS.md. Block này đọc cùng state trong .medxflow/, nên Claude và Codex có thể dùng chung một project mà không tách workflow.

Cơ chế hoạt động

mx use SCRUM-3699
    │
    ├─ Fetch Jira REST API
    ├─ Detect type / repos / approval areas
    ├─ Map Jira status → MedX lifecycle
    └─ Lưu .medxflow/context/current.json
           .medxflow/tasks/SCRUM-3699/task-state.json

    ↓ mở `claude`

SessionStart hook (.medxflow/hooks/session-start.js)
    │
    ├─ Đọc CURRENT_OPERATOR.local.md  → [OPERATOR]
    ├─ Đọc current.json + task-state  → [ACTIVE_TASK]
    ├─ Chạy git status FE + BE        → [REPO STATE]
    ├─ Detect lifecycle + role        → inject đúng skill
    └─ Inject toàn bộ vào system prompt của AI

    ↓ AI nhận đủ context → làm việc đúng lifecycle ngay

    ↓ hoặc mở Codex

mx codex sync → ghi block vào AGENTS.md
    │
    ├─ Đọc cùng .medxflow/ state
    ├─ Build lifecycle instruction theo role
    └─ List skill paths relevant với lifecycle hiện tại

File structure sau mx init

project/
├── .medxflow/
│   ├── context/
│   │   ├── current.json       ← task đang active
│   │   └── history/           ← lịch sử
│   ├── tasks/
│   │   └── SCRUM-xxxx/
│   │       ├── task-state.json
│   │       └── context.json   ← snapshot khi pause
│   ├── hooks/
│   │   └── session-start.js   ← hook inject context cho Claude
│   ├── skills/
│   │   └── skills-bundle.json ← skills inject theo role + lifecycle
│   ├── workflow/              ← workflow docs
│   ├── config.json            ← cấu hình adapter (Claude/Codex)
│   └── state.json             ← current task pointer
├── .claude/
│   └── settings.json          ← hook registration (mx init tạo)
├── AGENTS.md                  ← Codex context block (khi bật adapter Codex)
└── agents/
    ├── templates/             ← templates (handoff, status, verify...)
    └── CURRENT_OPERATOR.local.md  ← KHÔNG commit

Các file không được commit (đã có trong .gitignore sau mx init):

• .medxflow/context/ — context cá nhân, thay đổi liên tục
• .medxflow/tasks/ — task state cá nhân
• .medxflow/credentials.json — credentials backup local
• agents/CURRENT_OPERATOR.local.md — identity cá nhân

Approval-sensitive areas

Khi mx use detect các pattern sau trong description, sẽ hiển thị cảnh báo và inject warning vào AI:

• Database / Migration
• API Contract
• Permission / Auth / Tenant
• Shared Component / Hook
• Architecture