tidy
Dọn + validate kho nháp và render (wiki/sources/draft/*.md + llmwiki/html/*.html) khi phình to — ex docs-curate (đổi tên 2026-09-09 vì tên cũ không ai gọi). Ba tầng — PROMOTE bản chất quý lên wiki ADR/concept, ARCHIVE nháp đã xong (status done/implemented hoặc task done) vào archive/<nhóm>/ bằng git mv (TRACKED, không xoá, không giết draft còn proposed), KEEP canonical — rồi RE-INDEX. Gọi tay bất cứ lúc nào, hoặc khi đầu phiên báo "[tidy] draft/ có N file (> 10)". Trigger — "tidy", "dọn nháp", "dọn docs", "draft quá nhiều", "archive draft", "quét nháp lỗi thời", "/tidy".
How do I install this agent skill?
npx skills add https://github.com/rheinmir/setup --skill tidyIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The tidy skill is a utility designed to manage and organize documentation drafts and wiki entries. It automates the process of checking, planning, and applying changes to draft files using git and local Python scripts. The primary security consideration is the potential for indirect prompt injection, as the agent is tasked with reading user-generated drafts to determine if their content should be promoted to a permanent wiki, which could allow instructions within those drafts to affect the agent's judgment or output.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Skill: tidy
WHAT
Purpose và context
- Purpose: dọn + validate kho nháp và render (
wiki/sources/draft/*.md+llmwiki/html/*.html) khi phình to: PROMOTE bản chất quý lên wiki, ARCHIVE nháp đã xong (tracked, không xoá), KEEP canonical, rồi RE-INDEX. - Trigger (when to use):
- Đầu phiên thấy
🧹 [tidy] draft/ có N file .md tầng gốc (> ngưỡng 10)— hooksession_start.pyhỏi user; user ĐỒNG Ý → chạy skill này. User TỪ CHỐI → bỏ qua, không hỏi lại trong phiên. - User tự gọi
/tidykhi thấydraft/hoặcllmwiki/html/lộn xộn, khó tìm, sợ mất bản chất quý. /lintbước 8c (docs-sprawl pulse) hoặcmedicprobetidybáo warn.
- Đầu phiên thấy
- Non-goals: không xoá nháp, không archive draft còn sống chỉ vì cũ, không "sửa cho đúng chuẩn" file đã nằm trong
archive/.
Mental model
Vì sao 3 tầng (không chỉ "merge"): Cái QUÝ trong nháp là quyết định / bài học / pattern — nó phải lên wiki (concept/ADR, travel + được commit + được index). Còn nháp đã thi hành xong và render html là lịch sử → archive (giữ, không xoá). Tool tất định lo đếm + phân loại + dời + index; phần đọc-hiểu để promote là việc của agent.
draft/ + html/ → check (đếm) → plan (KEEP · ARCHIVE · PROMOTE?) → agent promote → apply (git mv vào archive/<nhóm>/) → re-index → verify + commit.
Input và output contract
| Field | Required? | Ý nghĩa | |
|---|---|---|---|
| In | --threshold N / env OVERSTACK_DRAFT_THRESHOLD | không (mặc định 10) | ngưỡng số file .md tầng gốc |
| In | --keep-dates N | không (mặc định 2) | số mốc ngày html report giữ lại |
| In | --root . | không | dùng khi downstream không có harness/ |
| Out | bảng plan | có | KEEP / ARCHIVE / PROMOTE? kèm lý do từng file |
| Out | ADR/concept mới trong wiki | theo nội dung | bản chất quý đã promote, có ## Origin |
| Out | rename vào archive/<proposals/superseded/analysis/reports>/ + index | có (khi apply) | git thấy rename, không delete |
Rules và capabilities
- RULE-01 (MUST): PROMOTE trước APPLY. Archive giờ TRACKED nên promote-sau vẫn làm được, nhưng đừng để bản chất chôn dưới
archive/mà không ai biết. - RULE-02 (MUST): Archive = DỜI, KHÔNG XOÁ. Không bao giờ
rmnháp;git mvgiữ history (git log --follow). - RULE-03 (MUST): Tuổi không phải lý do archive một draft còn
status: proposed/open/implementing. Chỉ status/task đã xong (hoặc PLAN/seq đi theo SPEC đã archive) mới archive. Muốn dọn draft treo → người quyết, đổi status, chạy lại. - RULE-04 (MUST): Canonical (
overstack.html,index.html,wiki-graph.html,*-cheatsheet,*-health-dashboard,problem-tree,line-status) không bao giờ archive. Html report có ngày: giữ 2 mốc ngày gần nhất (--keep-dates N), cũ hơn archive — html là render, không áp cho.md. - RULE-05 (MUST): Vai rõ: tool = đếm/phân loại/dời/re-index (tất định, 0 token); agent = promote (đọc-hiểu). Không lẫn.
- RULE-06 (MUST): Wiki entry mới phải có
## Origin+ frontmattertype(R2/R9); cập nhậtwiki/index.md+wiki/log.md(R3). - RULE-07 (MUST): Validator R7/R9/R18 và
wiki-health/index_syncbỏ quaarchive/(nháp đông cứng) — đừng "sửa cho đúng chuẩn" file trong archive, chúng là lịch sử. - Capabilities: đọc draft/html + frontmatter; dời file bằng git (tracked rename); ghi wiki (ADR/concept/index/log); chạy kiểm wiki-health/index_sync cục bộ.
Failure boundaries
checkexit 3 = vượt ngưỡng → đi tiếp plan; dưới ngưỡng và user không tự gọi → dừng, không có gì dọn.- Draft treo (
status: proposed/open…) → clarify: hỏi user làm-tiếp hay reject, không tự archive. - Đích archive bị
.gitignore→ tool từ chối dời (chủ ý), in dòng gitignore cần bỏ → blocked cho file đó. wiki-health --fail-on brokenhoặcindex_syncđỏ → failed, sửa trước khi commit.
HOW
Main workflow
| Step | Type | Inputs | Action | Outputs/exit | Failure/next |
|---|---|---|---|---|---|
| W01 | deterministic | draft/ | Check (0 token, không đụng file): tidy.py check | exit 3 = vượt ngưỡng | dưới ngưỡng → dừng trừ khi user tự gọi |
| W02 | deterministic | draft + html | Plan (dry-run): tidy.py plan, đọc kỹ cột lý do | bảng KEEP/ARCHIVE/PROMOTE? | draft treo → B01; cờ outdated → B02 |
| W03 | judgment | mục PROMOTE? + ARCHIVE có quyết định | PROMOTE bản chất quý vào wiki TRƯỚC khi apply | ADR/concept + index + log | đã có trong wiki → chỉ archive |
| W04 | effect | plan | Apply: tidy.py apply — git mv vào archive + re-index | rename + index | đích gitignored → B03 |
| W05 | deterministic | worktree | Verify + commit: git status, wiki-health, index_sync | commit + log | đỏ → sửa, lặp W05 |
Chi tiết từng bước (nguồn chân lý cho W01–W05, bước 0–4):
- Check (0 token, không đụng file):
Exit 3 = vượt ngưỡng (mặc định 10 filepython3 harness/scripts/tidy.py check # downstream không có harness/: python3 ~/.claude/harness/harness/scripts/tidy.py check --root ..mdtầng gốc, thư mục con không tính; đổi bằng--threshold Nhoặc envOVERSTACK_DRAFT_THRESHOLD). - Plan (dry-run):
python3 harness/scripts/tidy.py plan→ bảng KEEP / ARCHIVE / PROMOTE? kèm lý do từng file. Đọc kỹ cột lý do:OUTDATED — status done|implemented|…hoặctask T-… đã done→ nháp đã xong → ARCHIVE.⏱ TREO — status proposed/open…→ còn sống, tuổi không phải lý do archive; muốn dọn thì hỏi user quyết làm-tiếp hay reject (đổistatus:trong frontmatter rồi chạy lại).PROMOTE?= draft không status, không task → agent đọc rồi quyết.↳ ⚠ nội dung có thể outdateddưới một draft GIỮ = file nó trích dẫn đã chết (claim-receipts) hoặc code nó nói tới đã đổi sau khi viết (cờcode-drifttrongstale.json). Status còn sống không có nghĩa là nội dung còn đúng: đối chiếu với code, rồi (a) đã làm xong → đổi status và archive, (b) còn làm → sửa đúng câu sai, (c) bỏ →rejectedhoặc dờineed-review/. Có dương tính giả (đường dẫn ví dụ), nên phải đọc trước khi kết luận.
- PROMOTE bản chất QUÝ vào wiki — làm TRƯỚC khi apply (phán đoán của agent): với mỗi mục
PROMOTE?và mỗi mục ARCHIVE có vẻ chứa quyết định/bài học chưa có trong wiki → viếtllmwiki/wiki/sources/adr/ADR-NNN-<slug>.md(quyết định) hoặcllmwiki/wiki/concepts/<slug>.md(khái niệm), đúng frontmattertype:+## Origintrỏ draft; cập nhậtwiki/index.md+wiki/log.md. Đã có trong wiki → chỉ archive. Không promote thứ tầm thường (report tiến độ, render trùng). - Apply:
python3 harness/scripts/tidy.py apply— dời nhóm ARCHIVE vàoarchive/<proposals|superseded|analysis|reports>/(file tracked →git mv, git thấy rename không delete), sắp xếp cả file đã archive từ trước, rồi re-index (build-docs-indexnếu có,index_sync --fix,html/archive/INDEX.md).- Tool từ chối dời file tracked khi đích bị
.gitignore(dời = xoá khỏi repo) và in dòng gitignore cần bỏ. Đây là chủ ý, không phải lỗi.
- Tool từ chối dời file tracked khi đích bị
- Verify + commit:
git statuschỉ thấy rename/archive/INDEX.md;python3 harness/scripts/wiki-health.py --wiki-dir llmwiki/wiki --fail-on brokensạch (wikilink trỏ stem trong archive/ = resolved-frozen, không broken);index_syncxanh. Commit gồm ADR/concept mới promote + các rename. Appendwiki/log.md.
Branches
| ID | Kind | Guard | Hành vi | Skip / failure | Rejoin |
|---|---|---|---|---|---|
| B01 | conditional_required | plan báo ⏱ TREO — status proposed/open… | giữ; muốn dọn thì hỏi user làm-tiếp hay reject, đổi status: rồi chạy lại plan | user không quyết → KEEP | W02 |
| B02 | conditional_required | dòng ↳ ⚠ nội dung có thể outdated dưới draft GIỮ | đối chiếu code: (a) xong → đổi status + archive, (b) còn làm → sửa đúng câu sai, (c) bỏ → rejected hoặc dời need-review/ | dương tính giả (đường dẫn ví dụ) → giữ nguyên | W03 |
| B03 | recovery | tool từ chối dời vì đích bị .gitignore | báo user dòng gitignore cần bỏ; không lách bằng xoá | user không bỏ → file đó ở yên | W04 |
Validation và stopping
Tất định: bash harness/tests/tidy-test.sh (mục Test tất định dưới), wiki-health --fail-on broken sạch, index_sync xanh, git status chỉ thấy rename/archive/INDEX.md. Cần review: quyết định PROMOTE (agent đọc-hiểu). Dừng sau W05 commit; không lặp apply nhiều lần trong một phiên nếu plan không đổi.
Examples
- Positive: đầu phiên báo
[tidy] draft/ có 57 file, user đồng ý → plan: 40 ARCHIVE (status done), 4 PROMOTE?, 13 KEEP → agent viết 1 ADR cho quyết định chưa có trong wiki →tidy.py apply→git statuschỉ thấy rename →wiki-healthsạch → commit. - Boundary/failure: draft
status: proposed3 tháng tuổi → plan đánh⏱ TREO, KHÔNG archive; hỏi user làm-tiếp hay reject. Đícharchive/reports/bị gitignore → apply từ chối dời file tracked đó và in dòng gitignore cần bỏ.
Test tất định
bash harness/tests/tidy-test.sh — 11 assertion: ngưỡng >10 (thư mục con không tính), status done → archive, proposed cũ → keep, đích gitignored → không dời, đích tracked → git rename, vòng khép về exit 0.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/rheinmir/setup/tidy">View tidy on skillZs</a>