🤖 Agent Workflow (@nguyen-worker/agent-workflow)

Zero-Config AI Agent Portal Gateway & Multi-Stack Bootstrapper Nâng cấp và tiêu chuẩn hóa quy trình làm việc (Pair Programming) giữa Developer và AI Coding Agents (Cursor, Windsurf, Claude Code, GitHub Copilot, Antigravity).

🚀 Hướng Dẫn Khởi Đầu Nhanh (Quick Start)

Mở terminal tại thư mục gốc của bất kỳ dự án nào (Next.js, React, Node.js, Go, Ruby, Python, Java, PHP, Flutter...) và chạy 1 câu lệnh duy nhất:

npx @nguyen-worker/agent-workflow init

Lệnh trên sẽ tự động:

1. 📦 Sao chép bộ khung .agent/ (14 Skills tiêu chuẩn, Presets, Context Templates) vào dự án.
2. 🔗 Tạo hoặc tiêm khối Gateway Header lên đầu tệp AGENTS.md (giữ nguyên 100% quy tắc cũ của dự án).
3. ⚡ Quét tự động Tech Stack và khởi tạo file cấu hình trung tâm .agent/project.md.

✨ Các Tính Năng Trọng Tâm

1. ⚡ Tự Động Thích Nghi Dự Án (auto-adapt — Zero Config)

Agent tự động quét dự án để nhận diện các công nghệ (Node/TS, Python, Go, Ruby, Rust, Java, PHP...), tự cấu hình đường dẫn mã nguồn, thư mục module, lệnh test/lint và sơ đồ kiến trúc phù hợp.

2. 🛑 Các Cổng Phê Duyệt Bắt Buộc (Mandatory Approval Gates & Jira Sync Gate)

Bắt buộc tất cả các AI Model tuân thủ kỷ luật nghiêm ngặt, luôn dừng lại xin phép Developer trước khi chuyển pha:

• Cổng 1 — Phân Tích & QA (Phase 1 & 2): Xin ý kiến duyệt phân tích & câu hỏi QA.
• Cổng 2 — Kế Hoạch (<KEY>-plan.md): Xin duyệt danh sách task con và ước lượng thời gian.
• Cổng 3 — Jira Sync Gate (4 Tùy Chọn Upload/Comment Jira): Dừng lại hỏi User lựa chọn ghi dữ liệu giải pháp lên Jira (Upload file + Comment, Chỉ comment, Chỉ upload file, Bỏ qua).
• Cổng 4 — Thiết Kế Kỹ Thuật (Implementation Brief): Xin duyệt spec (approved) trước khi sinh code.
• Cổng 5 — Kiểm Thử & Auto-Fix: Xin phép trước khi tự động sửa đổi code khi test bị lỗi.

3. 🛠️ 3 Cấp Độ Thích Nghi Tech Stack (Dynamic Tech Adaptation)

• Cấp độ 1 — Built-in Presets: Có sẵn bộ mẫu chuẩn (nestjs-typeorm, react-query-mui, nextjs-tailwind, express-prisma, fastapi-sqlalchemy).
• Cấp độ 2 — Auto Preset Generation (create-skill): Tự sinh bộ preset mẫu mới cho công nghệ chưa có sẵn (Django, Spring Boot, Go Fiber, Laravel, Vue 3, Flutter...).
• Cấp độ 3 — Few-Shot Code Scan (preset: custom): Quét tự động 2-3 tệp code thực tế của dự án để nhại theo 100% style code nội bộ.

4. 📋 Quy Trình Xử Lý Task Jira 7 Pha (task-workflow)

Chỉ cần nhập mã task Jira (ví dụ: UNI-6868), Agent sẽ tự động kiểm tra trạng thái và dẫn dắt bạn qua 7 Pha tiêu chuẩn với kỷ luật kiểm soát nghiêm ngặt:

[Nhập mã Jira: UNI-6868]
  │
  ├── 🔹 Phase 1: Intake & Analysis (Phân tích & Tự động tải tệp đính kèm)
  │       └── 🛑 STOP & Xin duyệt kết quả phân tích
  │
  ├── 🔹 Phase 2: Clarification (Làm rõ yêu cầu — Chỉ chạy nếu có [BLOCKER])
  │       └── 🛑 STOP & Xin duyệt nội dung QA trước khi gửi Jira comment
  │
  ├── 🔹 Phase 3: Planning & Mandatory Jira Sync Gate (Lập kế hoạch chi tiết)
  │       └── 🛑 JIRA SYNC GATE: Chọn 1 trong 4 tùy chọn ghi dữ liệu Jira
  │       └── 🛑 STOP & Xin duyệt Kế hoạch (<KEY>-plan.md)
  │
  ├── 🔹 Phase 4: Implementation Brief & Mandatory Jira Sync Gate (Thiết kế kỹ thuật)
  │       └── 🛑 JIRA SYNC GATE: Chọn 1 trong 4 tùy chọn ghi dữ liệu Jira
  │       └── 🛑 STOP & Xin duyệt Spec kỹ thuật (Brief approved)
  │
  ├── 🔹 Phase 5: Coding (Thực thi viết mã nguồn)
  │       └── 🛑 STOP & Báo cáo danh sách các tệp code đã sửa/tạo mới
  │
  ├── 🔹 Phase 6: Review & PR (Tự đánh giá code 9 bước & Tạo PR description)
  │       └── 🛑 STOP & Hỏi chuyển sang chạy test ở Phase 7
  │
  └── 🔹 Phase 7: Testing & Test Report (Kiểm thử hệ thống & Báo cáo pass/fail)
          └── 🛑 CỔNG DUYỆT AUTO-FIX: Dừng lại báo lỗi & chỉ tự sửa khi được duyệt

🔍 Chi Tiết 7 Pha Xử Lý Task:

• Phase 1 — Intake & Analysis (Phân Tích & Thu Thập Thông Tin):

  • Hành động: Đọc Jira issue, tự động tải tất cả file/ảnh đính kèm về jira-attachments/<KEY>/, phân tích yêu cầu thành 3 nhóm: Fact (Sự thật), Inference (Suy luận) và Unknowns (Chưa rõ). Gắn nhãn [BLOCKER] hoặc [NON-BLOCKER].
  • Artifact: docs/issue-analysis/<KEY>/<KEY>.md.
  • Gate: 🛑 Dừng lại xin duyệt kết quả phân tích.

• Phase 2 — Clarification (Làm Rõ Yêu Cầu):

  • Hành động: Chỉ chạy khi có item [BLOCKER]. Soạn thảo comment QA bằng Jira Wiki Markup để hỏi lại PM/BA/Tech Lead.
  • Gate: 🛑 Dừng lại hiển thị bản nháp và bắt buộc xin phép User trước khi đăng comment lên Jira. Sau khi đăng, lưu link comment + timestamp vào artifact.

• Phase 3 — Planning & Mandatory Jira Sync Gate (Lập Kế Hoạch Chi Tiết):

  • Hành động: Phân tích ảnh hưởng toàn diện (DB, API, Web UI), chia nhỏ công việc thành các task con kèm ước lượng thời gian, xác định rủi ro và định nghĩa Definition of Done (DoD).
  • Artifact: docs/issue-analysis/<KEY>/<KEY>-plan.md.
  • Jira Sync Gate (Bắt buộc): 🛑 Dừng lại hỏi User lựa chọn 1 trong 4 phương án ghi thông tin Kế hoạch lên Jira (1. Upload file + Comment, 2. Chỉ comment, 3. Chỉ upload file, 4. Bỏ qua).
  • Gate: 🛑 Dừng lại xin duyệt Kế hoạch trước khi sang Phase 4.

• Phase 4 — Implementation Brief & Mandatory Jira Sync Gate (Thiết Kế Kỹ Thuật):

  • Hành động: Lập thiết kế kỹ thuật chi tiết: danh sách tệp sẽ tạo/sửa, API contract, DB migration, test plan và rollout notes.
  • Artifact: Cập nhật phần Implementation Brief trong docs/issue-analysis/<KEY>/<KEY>.md.
  • Jira Sync Gate (Bắt buộc): 🛑 Dừng lại hỏi User chọn 1 trong 4 phương án ghi thông tin giải pháp lên Jira.
  • Gate: 🛑 Dừng lại xin duyệt Implementation Brief (approved) trước khi viết code.

• Phase 5 — Coding (Thực Thi Viết Mã Nguồn):

  • Hành động: Áp dụng checklist từ .agent/tasks/feature.md hoặc bugfix.md kết hợp với kỹ năng code-be (Entity → Migration → DTO → Repo → Service → Controller) và code-fe (Interface → Service → Hook → Page → Route).
  • Gate: 🛑 Dừng lại báo cáo danh sách tệp đã thay đổi sau khi viết code xong.

• Phase 6 — Review & PR (Tự Đánh Giá Code & Tạo PR):

  • Hành động: Áp dụng kỹ năng review để tự động kiểm tra code qua 9 khía cạnh (Security, Architecture, TypeScript, BE, FE, Testing, Code Quality, Performance) và soạn bản nháp PR Description chuẩn mực.
  • Gate: 🛑 Dừng lại xin ý kiến User để chuyển sang Phase 7.

• Phase 7 — Testing & Test Report (Kiểm Thử & Tạo Báo Cáo):

  • Hành động: Đọc câu lệnh thực thi từ .agent/project.md để chạy tsc, lint và unit test. Lưu toàn bộ log kiểm thử vào thư mục docs/test-report/<KEY>/ (summary.md, typecheck.log, lint.log, unit-test.log).
  • Cổng Duyệt Auto-Fix (Bắt buộc): 🛑 Nếu phát hiện lỗi test/lint/typecheck, Agent không tự ý sửa code, mà dừng lại báo cáo số lượng và danh sách lỗi, xin phép User (ví dụ: "fix đi") trước khi tiến hành Auto-Fix.

🎯 Chạy Trực Tiếp Pha Mong Muốn (Intent Commands):

Bạn có thể nhảy thẳng tới từng pha bằng cách thêm từ khóa chỉ định sau mã Jira task:

• UNI-6868 qa → Chuyển đến Phase 2 (Làm rõ yêu cầu).
• UNI-6868 plan → Chuyển đến Phase 3 (Lập kế hoạch).
• UNI-6868 brief → Chuyển đến Phase 4 (Thiết kế kỹ thuật).
• UNI-6868 implement → Chuyển đến Phase 5 (Viết code).
• UNI-6868 review → Chuyển đến Phase 6 (Tự review code).
• UNI-6868 test → Chuyển đến Phase 7 (Kiểm thử hệ thống).

💻 Các Câu Lệnh CLI

# Khởi tạo & tự động thích nghi vào dự án hiện tại
npx @nguyen-worker/agent-workflow init

# Kiểm tra sức khỏe cấu hình hệ khung .agent/
npx @nguyen-worker/agent-workflow health

# Cập nhật các skills và templates mới nhất
npx @nguyen-worker/agent-workflow update

🔌 Cấu Hình Jira MCP Server (@cuongph.dev/jira-mcp)

Để kết nối và tự động đọc task, tải tệp đính kèm và ghi comment lên Jira, hãy thêm đoạn cấu hình sau vào IDE của bạn (Cursor / Windsurf / Claude Code / VSCode):

Hướng dẫn và tài liệu cài đặt chi tiết có tại: @cuongph.dev/jira-mcp (NPM)

{
  "mcpServers": {
    "jira-mcp": {
      "command": "npx",
      "args": ["-y", "@cuongph.dev/jira-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.your-domain.com",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_PASSWORD": "your-jira-password"
      }
    }
  }
}

📂 Cấu Trúc Thư Mục Hệ Khung .agent/

.agent/
├── README.md               ← Tài liệu hướng dẫn sử dụng chi tiết
├── project.md              ← ⚙️ File cấu hình trung tâm của dự án
├── context/                ← Ngữ cảnh nghiệp vụ (architecture.md, decisions.md, domain.md)
├── rules/                  ← Bộ quy chuẩn viết code (api.md, database.md, web.md)
├── tasks/                  ← Checklists mẫu cho feature.md và bugfix.md
└── skills/                 ← 14 Module kỹ năng thực thi
    ├── task-workflow/      ← Master Workflow điều phối quy trình 7 pha
    ├── auto-adapt/         ← Động cơ tự động quét & thích nghi dự án mới
    ├── agent-health/       ← Kiểm tra sức khỏe cấu hình project.md
    ├── plan-task/          ← Lập kế hoạch chi tiết trước khi code
    ├── code-be/            ← Kỹ năng viết code Backend
    ├── code-fe/            ← Kỹ năng viết code Frontend
    ├── review/             ← Quy trình Code Review 8 pha
    ├── test/               ← Kỹ năng chạy test, lint và tự sửa lỗi
    └── tech-stacks/        ← Các bộ presets code mẫu

📄 License

MIT ©nguyen-worker