From c8ff5e108bc61da0814410313aa6a53589028d78 Mon Sep 17 00:00:00 2001 From: pqhuy1987 Date: Fri, 29 May 2026 18:20:20 +0700 Subject: [PATCH] [CLAUDE] Docs: S40 adopt /session-start + /session-end slash commands (bulletin MUC 3) - .claude/commands/session-start.md (3 phase READ/AUDIT/REPORT) + session-end.md (6 phase FLUSH/WRITE/VERIFY/REPORT/COMMIT/EVAL) - Adapted: 7-agent topology (not 4 default) + charter v2 (RAG eval/re-index = AI_INFRA op) + SendMessage N/A harness caveat - Placeholders filled: MD core + 6 skill + dotnet test SolutionErp.slnx + commit scope + proj_solution_erp + cron 2026-06-01 - 0 leftover {{placeholder}}/comment. Activate: anh main restart CLI (slash KHONG hot-reload) Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/commands/session-end.md | 112 ++++++++++++++++++++++++++++++ .claude/commands/session-start.md | 105 ++++++++++++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 .claude/commands/session-end.md create mode 100644 .claude/commands/session-start.md diff --git a/.claude/commands/session-end.md b/.claude/commands/session-end.md new file mode 100644 index 0000000..6da5719 --- /dev/null +++ b/.claude/commands/session-end.md @@ -0,0 +1,112 @@ +--- +description: Đóng session SOLUTION_ERP — flush 7-agent memory, sync MD/RAG, commit + push, eval. Run cuối mỗi session. +--- + +# /session-end — Session closeout (FLUSH + WRITE + VERIFY + REPORT + COMMIT + EVAL) + +> Trigger cuối session. Em main chủ trì, gọi lại sub-agent đã spawn. +> ⚠️ **Harness note:** SendMessage KHÔNG khả dụng → "flush con đã spawn" = agent đã tự update MEMORY khi return (BẮT BUỘC trong agent frontmatter). Em main đọc lại MEMORY on-disk để synthesize, KHÔNG cần re-spawn chỉ để flush. + +## 📋 BƯỚC 0 — Show command body (visibility, no wait) + +Em main PHẢI echo **TOÀN BỘ nội dung command body này** (đầy đủ Phase 1-6 + sub-section + guard rule) trong response đầu tiên ĐỂ ANH USER ĐỌC LẠI. + +**Quy trình (KHÔNG wait confirm):** +1. Em echo full content command (raw markdown, KHÔNG tóm tắt, KHÔNG cắt) +2. Em proceed execute Phase 1 → 6 sequential ngay +3. Anh user điều chỉnh **cuối session** nếu cần thay đổi nội dung command (KHÔNG mid-flow interrupt) + +## Phase 1 — FLUSH (sub-agent memory) + +**Điều kiện:** Chỉ xử lý con đã spawn trong session. KHÔNG spawn mới chỉ để flush (agent đã update MEMORY khi return). + +1. Đọc MEMORY.md update của sub-agent đã spawn (Tiered L1 HOT): + - 🟦 **investigator-codebase** — research findings + audit results + schema/count grounding + - 🟦 **investigator-api** — external docs/CVE/lib eval + cross-project port + RAG fleet + - 🟨 **implementer-backend** — BE patterns applied + scope refusals (ACCEPT vs REFUSE) + - 🟧 **implementer-frontend** — FE mirror SHA256 + Pattern 16-bis 4-place + KIND_CONFIG + - 🟪 **test-specialist** — test bundle added + coverage gap + spec drift detected + - 🟥 **reviewer** — anti-patterns observed + Smart Friend catches + claim verification + - 🟢 **cicd-monitor** — Run verdict + bundle hash rotate + Mig prod + corpus drift + +2. Synthesize cross-agent learnings → integrate vào: + - User auto-memory `MEMORY.md` (index — append entry mới, KHÔNG rewrite) + - `docs/rules.md`, `docs/architecture.md`, `docs/gotchas.md`, `docs/database/`, `docs/flows/` + - rules, architecture, gotcha, skill, daily, hand-off (`docs/HANDOFF.md`), DB, luồng DB, session log (`docs/changelog/sessions/`) + +## Phase 2 — WRITE (update MD/RAG) + +### 2.1 UPDATE/Re-rank MD/RAG đã thay đổi +- `docs/STATUS.md` (In Progress → Recently Done) + `docs/HANDOFF.md` (tiering: giữ current+2-3 session, archive cũ → session logs per `feedback_status_handoff_tiering`) +- rules, architecture, gotcha, skill, hand-off, DB, luồng DB, session log + +### 2.2 Skill registry +- Liệt kê 6 skill. Dùng skill khi task khớp (KHÔNG tự suy luận lại) +- Skill staleness audit chỉ chạy theo lịch định kỳ (cron 2026-06-01) +- Phân bổ skill mới phù hợp per agent (README matrix) + +### 2.3 Memory entry mới +- Add memory entry NẾU phát hiện rule/gotcha/decision quan trọng chưa có (vd `feedback_*`) +- **KHÔNG rewrite toàn bộ memory** — chỉ append entry mới + update MEMORY.md index 1 dòng + +### 2.4 Quy tắc consolidate MD/RAG (CRITICAL — đọc kỹ) [GENERIC — GIỮ NGUYÊN] + +- **Thứ 1:** Rất quan trọng, đọc kỹ lại quy tắc consolidate đúng cách, những thứ quan trọng KHÔNG đc cắt, chỉ phân tầng cho gọn lại, và xóa double. Phân tầng để các session sau đọc lại đúng chính xác context, không bị over context, rất quan trọng đấy. +- **Thứ 2:** Nếu MD/RAG không có gì cần điều chỉnh thì KHÔNG cần phải cố gắng điều chỉnh, điều này cũng rất quan trọng. + +## Phase 3 — VERIFY (test + state) + +### 3.1 Unit test verify +- `dotnet test SolutionErp.slnx --nologo --verbosity minimal` — verify count tăng đúng (vd 130 → 132 nếu thêm 2 test). Update STATUS Recently Done. +- Phase 9 UAT mode: feature test-after (có thể skip per chunk), vẫn `npm run build` × 2 app. Nếu chỉ docs/infra → ghi "N/A". + +### 3.2 Sub-agent state +- Kiểm tra trạng thái spawn sub-agent (7-agent) +- Task bất kỳ phải phân việc đầy đủ đúng vai trò split boundary (BE→backend, FE→frontend, test→test-specialist) + +### 3.3 RAG + MCP state +- RAG corpus health (chunk count delta, `last_indexed_at`). Re-index full = AI_INFRA op (charter v2). +- MCP `rag-unified` stdio launch verify (5 tool) +- Re-rank coverage: prompts đã store + đánh dấu re-rank đầy đủ chưa + +## Phase 4 — REPORT (plan status) + +Đặt tên + tô màu cho Plan hiện tại, tiến độ + agent assignment: + +``` +Plan cha: [tên] + Plan con: [tên] + Task: [tên] — STATUS: 🟢 done | 🟡 in-progress | ⚪ pending + - 🟦 investigator-codebase — [a] - 🟦 investigator-api — [b] + - 🟨 implementer-backend — [c] - 🟧 implementer-frontend — [d] + - 🟪 test-specialist — [e] - 🟥 reviewer — [f] + - 🟩 cicd-monitor — [g] - 👤 chủ trì — [h] +``` + +### SOLUTION_ERP report (per-session) +- Tóm tắt việc done + commit SHA + CI Run verdict + bundle hash rotate + plan progress +- (SE KHÔNG copy phần "6 sister report" của AI_INFRA host) + +## Phase 5 — COMMIT (release) + +### 5.1 Release + commit +- Kiểm tra release, commit task vừa hoàn thành. ⚠️ Update `SolutionErp.slnx` nếu có `.cs/.csproj` mới. +- Format: `[CLAUDE] : ` + `Co-Authored-By: Claude Opus 4.8 (1M context) ` +- Scope: `Contract · PurchaseEvaluation · Budget · Form · Workflow · Supplier · Auth · Admin · Api · App · Domain · Infra · FE-Admin · FE-User · Tests · Docs · CICD · Scripts · Skill` + +### 5.2 Push remote +- `git push origin main` → `git.baocaogiaoduc.vn/vietreport-admin/solution-erp` +- Docs-only commit → CI skip per gotcha #41 (paths-ignore `docs/**` + `**/*.md` + `.claude/skills/**`). Code commit → spawn 🟩 cicd-monitor verify deploy. + +## Phase 6 — EVAL (chunk + RAG) + +### 6.1 Chunk MD/RAG update +- Cập nhật chunk MD/RAG content mới (Proposal/WorkflowApps/Phase 11...). SE-side: `mcp__rag-unified__store_memory` key facts (stopgap content-gap). + +### 6.2 RAG eval +- ⚠️ **Charter v2:** RAG eval + full re-index (`bootstrap.py`, golden set, recall@5) = **AI_INFRA op** (cần VOYAGE_API_KEY). SE KHÔNG tự chạy. +- SE-side closeout: (a) verify `store_memory` chunk retrievable (1 `search_memory` rerank check); (b) flag drift/staleness lên AI_INFRA nếu `last_indexed` lag nhiều; (c) báo cáo broadcast nếu adopt infra change. + +--- + +**Trigger sau Phase 6:** Session đóng. Working memory có thể `/clear` an toàn (persistent memory đã flush + commit + push). diff --git a/.claude/commands/session-start.md b/.claude/commands/session-start.md new file mode 100644 index 0000000..7a5c0ee --- /dev/null +++ b/.claude/commands/session-start.md @@ -0,0 +1,105 @@ +--- +description: Bootstrap session SOLUTION_ERP — load context, audit state (7-agent + RAG + tests), report plan. Run đầu mỗi session. +--- + +# /session-start — Session bootstrap (READ + AUDIT + REPORT) + +> Trigger đầu session. Em main chủ trì, spawn sub-agent khi task match delegate criteria. +> ⚠️ **Harness note:** SendMessage KHÔNG khả dụng harness hiện tại → "reuse agent" = **fresh spawn** (MEMORY on-disk auto-inject giữ context). agentId chỉ valid trong-session. + +## 📋 BƯỚC 0 — Show command body (visibility, no wait) + +Em main PHẢI echo **TOÀN BỘ nội dung command body này** (đầy đủ Phase 1-3 + sub-section + guard rule) trong response đầu tiên ĐỂ ANH USER ĐỌC LẠI. + +**Quy trình (KHÔNG wait confirm):** +1. Em echo full content command (raw markdown, KHÔNG tóm tắt, KHÔNG cắt) +2. Em proceed execute Phase 1 → 3 sequential ngay +3. Anh user điều chỉnh **cuối session** nếu cần thay đổi nội dung command (KHÔNG mid-flow interrupt) + +## Phase 1 — READ (load context) + +Đọc theo thứ tự, KHÔNG skip: + +1. **`CLAUDE.md`** (root) — AI agent context + quick rules (BE Clean Arch + FE 2 app + DB conventions + commit scope) +2. **`docs/STATUS.md`** — snapshot HIỆN TẠI (current state verified + recently done 3 session) +3. **`docs/HANDOFF.md`** — brief 5 phút: session trước làm gì + next tasks +4. **`docs/PROJECT-MAP.md`** — bản đồ tổng quan module +5. **`docs/changelog/migration-todos.md`** — atomic tasks theo phase (Phase 11 polish hiện tại) +6. **`docs/workflow-contract.md`** — state machine 9 phase HĐ (base pattern cho PE/Proposal workflow V2) +7. **`.claude/agents/README.md`** — 7-agent decision tree + skill matrix + split boundary +8. **`.claude/agent-memory/{spawned-agent}/MEMORY.md`** — L1 HOT auto-inject (Tiered Memory v1 ~30KB) + L2 `archive/` Read-on-demand + L3 RAG `search_memory` just-in-time +9. **User auto-memory `MEMORY.md`** — auto-loaded bởi harness (index feedback_* entries) +10. **Liên quan task hiện tại:** `docs/rules.md`, `docs/architecture.md`, `docs/gotchas.md` (55), `docs/database/schema-diagram.md`, `docs/flows/` + +## Phase 2 — AUDIT (state check) + +### 2.1 Sub-agent state (7-agent topology) +- Check 7 sub-agent đã spawn chưa: + - 🟦 **investigator-codebase** — internal SQL/EF/grep/reference mirror audit + - 🟦 **investigator-api** — external docs/CVE/lib/cross-project reference + - 🟨 **implementer-backend** — .NET Domain+App+Infra+Api scaffold + - 🟧 **implementer-frontend** — FE 2 app cookie-cutter SHA256 mirror + - 🟪 **test-specialist** — tests/ xUnit dedicated + - 🟥 **reviewer** — adversarial pre-commit + live curl prod + - 🟩 **cicd-monitor** — post-deploy Gitea + bundle hash + smoke +- Task match delegate criteria (ACCEPT) → BẮT BUỘC delegate (xem `.claude/agents/README.md` decision tree) +- KHÔNG spawn mới khi con cũ rảnh → fresh spawn re-inject MEMORY (SendMessage N/A harness này) +- Nạp full context project cho sub-agent spawn, giữ context sống đến cuối session +- Em main solo CHỈ khi: schema/UX/architecture decision · cross-stack tight · bug reasoning chain · gotcha #53/#54/#55 fallback (truncate/529) + +### 2.2 Skill registry (6 skill) +- Liệt kê: `contract-workflow` · `form-engine` · `permission-matrix` · `dependency-audit-erp` · `ef-core-migration` · `iis-deploy-runbook` +- Dùng skill khi task khớp (KHÔNG tự suy luận lại). Phân bổ per agent: xem README skill matrix. +- Skill staleness audit: chỉ chạy theo lịch định kỳ (xem 2.4) + +### 2.3 RAG + MCP health +- `mcp__rag-unified__list_projects` — verify collection `proj_solution_erp` còn sống (baseline ~3076 chunks) +- Chunk count + `last_indexed_at` delta (drift > 20% → flag AI_INFRA). ⚠️ Re-index = **AI_INFRA op** (charter v2, cần VOYAGE_API_KEY) — KHÔNG tự chạy `bootstrap.py`; SE stopgap = `store_memory` key facts. +- Voyage rerank quota OK (verify 1 query có rerank_score) +- Kiểm tra RAG chủ trì + sub: prompts đã store + đánh dấu re-rank đầy đủ chưa + +### 2.4 Audit cadence +- **Monthly (ngày 1):** skill + doc drift audit — cron `solution-erp-skill-audit-monthly`. Next: **2026-06-01**. +- KHÔNG tự chạy audit ngoài cadence, trừ khi user yêu cầu hoặc drift nghiêm trọng +- Check trạng thái audit định kỳ (đã audit chưa? kết quả ra sao) + +### 2.5 Quy tắc consolidate MD/RAG (CRITICAL — đọc kỹ) [GENERIC — GIỮ NGUYÊN] + +- **Thứ 1:** Rất quan trọng, đọc kỹ lại quy tắc consolidate đúng cách, những thứ quan trọng KHÔNG đc cắt, chỉ phân tầng cho gọn lại, và xóa double. Phân tầng để các session sau đọc lại đúng chính xác context, không bị over context, rất quan trọng đấy. +- **Thứ 2:** Nếu MD không có gì cần điều chỉnh thì KHÔNG cần phải cố gắng điều chỉnh, điều này cũng rất quan trọng. + +### 2.6 Unit test check +- `dotnet test SolutionErp.slnx --nologo --verbosity minimal` — verify count cho tính năng mới + bug fix gần đây. +- Baseline **130 PASS** (58 Domain + 72 Infra). Phase 9 UAT mode: test-after feature (skip per chunk per `feedback_uat_skip_verify`), test-before BẮT BUỘC cho bug fix + critical algo. test-specialist owns; coverage gap backlog xem STATUS. + +### 2.7 Cross-agent synthesis (post-audit) [GENERIC — GIỮ NGUYÊN] +- Audit MD/RAG của sub-agent đã spawn, synthesize cross-agent learnings +- Integrate vào: rules, architecture, gotcha, skill, daily, hand-off, DB, luồng DB, session log + +## Phase 3 — REPORT (plan status) + +Đặt tên + tô màu cho Plan hiện tại đang chạy, kèm tiến độ + agent assignment: + +``` +Plan cha: [tên] + Plan con 1: [tên] + Task 1.1 — STATUS: 🟢 done | 🟡 in-progress | ⚪ pending + - 🟦 investigator-codebase — phụ trách [a] + - 🟦 investigator-api — phụ trách [b] + - 🟨 implementer-backend — phụ trách [c] + - 🟧 implementer-frontend — phụ trách [d] + - 🟪 test-specialist — phụ trách [e] + - 🟥 reviewer — phụ trách [f] + - 🟩 cicd-monitor — phụ trách [g] + - 👤 chủ trì — phụ trách [h] +``` + +### SOLUTION_ERP report +- Trạng thái spawn 7 sub-agent (idle/working) + agentId reuse-able trong session +- Plan progress: ✅ Phase 10 COMPLETE 11/11 · ⬜ Phase 11 polish (wire ApproveV2 skeleton) · 🚫 Phase 9 Ops (anh main coordinate) +- Critical signal: state counts (mig/table/endpoint/page/menu/test/gotcha) + bundle hash prod + RAG health +- (SE KHÔNG copy phần "6 sister report" của AI_INFRA — đó là vai trò host) + +--- + +**Trigger sau Phase 3:** Em main đợi user input task cụ thể. Sub-agent spawn theo decision tree khi ACCEPT criteria match.