@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/workflows/claw.md

@@ -1,51 +1,23 @@
----
-description: Start NanoClaw v2 — ECC's persistent, zero-dependency REPL with model routing, skill hot-load, branching, compaction, export, and metrics.
----
-
-# Claw Command
-
-Start an interactive AI agent session with persistent markdown history and operational controls.
-
-## Usage
-
-```bash
-node scripts/claw.js
-```
-
-Or via npm:
-
-```bash
-npm run claw
-```
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLAW_SESSION` | `default` | Session name (alphanumeric + hyphens) |
-| `CLAW_SKILLS` | *(empty)* | Comma-separated skills loaded at startup |
-| `CLAW_MODEL` | `sonnet` | Default model for the session |
-
-## REPL Commands
-
-```text
-/help                          Show help
-/clear                         Clear current session history
-/history                       Print full conversation history
-/sessions                      List saved sessions
-/model [name]                  Show/set model
-/load <skill-name>             Hot-load a skill into context
-/branch <session-name>         Branch current session
-/search <query>                Search query across sessions
-/compact                       Compact old turns, keep recent context
-/export <md|json|txt> [path]   Export session
-/metrics                       Show session metrics
-exit                           Quit
-```
-
-## Notes
-
-- NanoClaw remains zero-dependency.
-- Sessions are stored at `~/.claude/claw/<session>.md`.
-- Compaction keeps the most recent turns and writes a compaction header.
-- Export supports markdown, JSON turns, and plain text.
+---
+description: Legacy slash-entry shim for the nanoclaw-repl skill. Prefer the skill directly.
+---
+
+# Claw Command (Legacy Shim)
+
+Use this only if you still reach for `/claw` from muscle memory. The maintained implementation lives in `skills/nanoclaw-repl/SKILL.md`.
+
+## Canonical Surface
+
+- Prefer the `nanoclaw-repl` skill directly.
+- Keep this file only as a compatibility entry point while command-first usage is retired.
+
+## Arguments
+
+`$ARGUMENTS`
+
+## Delegation
+
+Apply the `nanoclaw-repl` skill and keep the response focused on operating or extending `scripts/claw.js`.
+- If the user wants to run it, use `node scripts/claw.js` or `npm run claw`.
+- If the user wants to extend it, preserve the zero-dependency and markdown-backed session model.
+- If the request is really about long-running orchestration rather than NanoClaw itself, redirect to `dmux-workflows` or `autonomous-agent-harness`.

package/.agent/workflows/clean-memory.md

@@ -0,0 +1,34 @@
+---
+description: Chiến lược Quản trị Tri thức & Dọn dẹp Ngữ cảnh toàn diện cho AI Agent.
+---
+
+# 🧠 Knowledge Distillation & Memory Hygiene Protocol
+
+Quy mô dự án càng lớn, AI càng dễ bị "nhiễu" bởi các log cũ và các bước thực thi rườm rà. Workflow này không chỉ xóa dữ liệu, mà là quá trình **TỔNG HỢP** tri thức để giữ cho AI luôn thực tế và nhạy bén.
+
+## 1. Giai đoạn Quét tri thức (Knowledge Sweep)
+Agent phải rà soát toàn bộ các nguồn dữ liệu đang "phình to":
+- **Tasks**: Toàn bộ file trong `.agent/tasks/` (Tìm các task đã `DONE` nhưng chưa được tổng hợp kết quả).
+- **Session Memory**: Tệp `session_memory.md` hoặc các tệp ghi chép nháp.
+- **Workflow Logs**: Các kết quả thực thi lệnh slash trước đó.
+
+## 2. Giai đoạn Chắt lọc tinh hoa (Synthesis & Extraction)
+Thay vì xóa bỏ, Agent phải **TRÍCH XUẤT** các giá trị vĩnh viễn:
+- **ADRs**: Các quyết định kiến trúc quan trọng phải được chuyển vào `PROJECT_MAP.md`.
+- **Instincts**: Các quy tắc làm việc mới "học" được từ lỗi sai phải được chuyển vào `PILO_MASTER.md` hoặc `.agent/rules/`.
+- **State Compression**: Tóm lược 10 bước làm việc thành 1 dòng trạng thái duy nhất ("Ví dụ: Đã hoàn thành refactor module X, cấu trúc hiện tại là Y").
+
+## 3. Giai đoạn Thực thi Làm sạch (Atomic Pruning)
+Sau khi đã cất giữ tinh hoa vào các file "não bộ" (`PROJECT_MAP.md`, `PILO_MASTER.md`), Agent mới được phép:
+- Lưu trữ (Archive) hoặc xóa bỏ các task cũ đã hoàn thành.
+- Làm sạch các log thừa trong terminal hoặc file tạm.
+- Cắt tỉa các tệp memory để chỉ giữ lại **Ngữ cảnh hiện tại (Current Status)** và **Mục tiêu tiếp theo (Next Goal)**.
+
+## 4. Xác nhận & Báo cáo
+Agent báo cáo lại:
+- `Synthesized`: Những tri thức mới nào đã được đưa vào bản đồ dự án?
+- `Pruned`: Đã xóa bỏ bao nhiêu KB/Dòng dữ liệu dư thừa?
+- `Ready`: Xác nhận ngữ cảnh hiện tại đã "sạch" và tập trung vào mục tiêu mới.
+
+---
+> **Triết lý**: Đừng chỉ xóa đi quá khứ, hãy biến nó thành kinh nghiệm để tối ưu tương lai.

package/.agent/workflows/code-review.md

@@ -1,40 +1,289 @@
-# Code Review
-
-Comprehensive security and quality review of uncommitted changes:
-
-1. Get changed files: git diff --name-only HEAD
-
-2. For each changed file, check for:
-
-**Security Issues (CRITICAL):**
-- Hardcoded credentials, API keys, tokens
-- SQL injection vulnerabilities
-- XSS vulnerabilities  
-- Missing input validation
-- Insecure dependencies
-- Path traversal risks
-
-**Code Quality (HIGH):**
-- Functions > 50 lines
-- Files > 800 lines
-- Nesting depth > 4 levels
-- Missing error handling
-- console.log statements
-- TODO/FIXME comments
-- Missing JSDoc for public APIs
-
-**Best Practices (MEDIUM):**
-- Mutation patterns (use immutable instead)
-- Emoji usage in code/comments
-- Missing tests for new code
-- Accessibility issues (a11y)
-
-3. Generate report with:
-   - Severity: CRITICAL, HIGH, MEDIUM, LOW
-   - File location and line numbers
-   - Issue description
-   - Suggested fix
-
-4. Block commit if CRITICAL or HIGH issues found
-
-Never approve code with security vulnerabilities!
+---
+description: Code review — local uncommitted changes or GitHub PR (pass PR number/URL for PR mode)
+argument-hint: [pr-number | pr-url | blank for local review]
+---
+
+# Code Review
+
+> PR review mode adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+**Input**: $ARGUMENTS
+
+---
+
+## Mode Selection
+
+If `$ARGUMENTS` contains a PR number, PR URL, or `--pr`:
+→ Jump to **PR Review Mode** below.
+
+Otherwise:
+→ Use **Local Review Mode**.
+
+---
+
+## Local Review Mode
+
+Comprehensive security and quality review of uncommitted changes.
+
+### Phase 1 — GATHER
+
+```bash
+git diff --name-only HEAD
+```
+
+If no changed files, stop: "Nothing to review."
+
+### Phase 2 — REVIEW
+
+Read each changed file in full. Check for:
+
+**Security Issues (CRITICAL):**
+- Hardcoded credentials, API keys, tokens
+- SQL injection vulnerabilities
+- XSS vulnerabilities
+- Missing input validation
+- Insecure dependencies
+- Path traversal risks
+
+**Code Quality (HIGH):**
+- Functions > 50 lines
+- Files > 800 lines
+- Nesting depth > 4 levels
+- Missing error handling
+- console.log statements
+- TODO/FIXME comments
+- Missing JSDoc for public APIs
+
+**Best Practices (MEDIUM):**
+- Mutation patterns (use immutable instead)
+- Emoji usage in code/comments
+- Missing tests for new code
+- Accessibility issues (a11y)
+
+### Phase 3 — REPORT
+
+Generate report with:
+- Severity: CRITICAL, HIGH, MEDIUM, LOW
+- File location and line numbers
+- Issue description
+- Suggested fix
+
+Block commit if CRITICAL or HIGH issues found.
+Never approve code with security vulnerabilities.
+
+---
+
+## PR Review Mode
+
+Comprehensive GitHub PR review — fetches diff, reads full files, runs validation, posts review.
+
+### Phase 1 — FETCH
+
+Parse input to determine PR:
+
+| Input | Action |
+|---|---|
+| Number (e.g. `42`) | Use as PR number |
+| URL (`github.com/.../pull/42`) | Extract PR number |
+| Branch name | Find PR via `gh pr list --head <branch>` |
+
+```bash
+gh pr view <NUMBER> --json number,title,body,author,baseRefName,headRefName,changedFiles,additions,deletions
+gh pr diff <NUMBER>
+```
+
+If PR not found, stop with error. Store PR metadata for later phases.
+
+### Phase 2 — CONTEXT
+
+Build review context:
+
+1. **Project rules** — Read `CLAUDE.md`, `.claude/docs/`, and any contributing guidelines
+2. **PRP artifacts** — Check `.claude/PRPs/reports/` and `.claude/PRPs/plans/` for implementation context related to this PR
+3. **PR intent** — Parse PR description for goals, linked issues, test plans
+4. **Changed files** — List all modified files and categorize by type (source, test, config, docs)
+
+### Phase 3 — REVIEW
+
+Read each changed file **in full** (not just the diff hunks — you need surrounding context).
+
+For PR reviews, fetch the full file contents at the PR head revision:
+```bash
+gh pr diff <NUMBER> --name-only | while IFS= read -r file; do
+  gh api "repos/{owner}/{repo}/contents/$file?ref=<head-branch>" --jq '.content' | base64 -d
+done
+```
+
+Apply the review checklist across 7 categories:
+
+| Category | What to Check |
+|---|---|
+| **Correctness** | Logic errors, off-by-ones, null handling, edge cases, race conditions |
+| **Type Safety** | Type mismatches, unsafe casts, `any` usage, missing generics |
+| **Pattern Compliance** | Matches project conventions (naming, file structure, error handling, imports) |
+| **Security** | Injection, auth gaps, secret exposure, SSRF, path traversal, XSS |
+| **Performance** | N+1 queries, missing indexes, unbounded loops, memory leaks, large payloads |
+| **Completeness** | Missing tests, missing error handling, incomplete migrations, missing docs |
+| **Maintainability** | Dead code, magic numbers, deep nesting, unclear naming, missing types |
+
+Assign severity to each finding:
+
+| Severity | Meaning | Action |
+|---|---|---|
+| **CRITICAL** | Security vulnerability or data loss risk | Must fix before merge |
+| **HIGH** | Bug or logic error likely to cause issues | Should fix before merge |
+| **MEDIUM** | Code quality issue or missing best practice | Fix recommended |
+| **LOW** | Style nit or minor suggestion | Optional |
+
+### Phase 4 — VALIDATE
+
+Run available validation commands:
+
+Detect the project type from config files (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.), then run the appropriate commands:
+
+**Node.js / TypeScript** (has `package.json`):
+```bash
+npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null  # Type check
+npm run lint                                                    # Lint
+npm test                                                        # Tests
+npm run build                                                   # Build
+```
+
+**Rust** (has `Cargo.toml`):
+```bash
+cargo clippy -- -D warnings  # Lint
+cargo test                   # Tests
+cargo build                  # Build
+```
+
+**Go** (has `go.mod`):
+```bash
+go vet ./...    # Lint
+go test ./...   # Tests
+go build ./...  # Build
+```
+
+**Python** (has `pyproject.toml` / `setup.py`):
+```bash
+pytest  # Tests
+```
+
+Run only the commands that apply to the detected project type. Record pass/fail for each.
+
+### Phase 5 — DECIDE
+
+Form recommendation based on findings:
+
+| Condition | Decision |
+|---|---|
+| Zero CRITICAL/HIGH issues, validation passes | **APPROVE** |
+| Only MEDIUM/LOW issues, validation passes | **APPROVE** with comments |
+| Any HIGH issues or validation failures | **REQUEST CHANGES** |
+| Any CRITICAL issues | **BLOCK** — must fix before merge |
+
+Special cases:
+- Draft PR → Always use **COMMENT** (not approve/block)
+- Only docs/config changes → Lighter review, focus on correctness
+- Explicit `--approve` or `--request-changes` flag → Override decision (but still report all findings)
+
+### Phase 6 — REPORT
+
+Create review artifact at `.claude/PRPs/reviews/pr-<NUMBER>-review.md`:
+
+```markdown
+# PR Review: #<NUMBER> — <TITLE>
+
+**Reviewed**: <date>
+**Author**: <author>
+**Branch**: <head> → <base>
+**Decision**: APPROVE | REQUEST CHANGES | BLOCK
+
+## Summary
+<1-2 sentence overall assessment>
+
+## Findings
+
+### CRITICAL
+<findings or "None">
+
+### HIGH
+<findings or "None">
+
+### MEDIUM
+<findings or "None">
+
+### LOW
+<findings or "None">
+
+## Validation Results
+
+| Check | Result |
+|---|---|
+| Type check | Pass / Fail / Skipped |
+| Lint | Pass / Fail / Skipped |
+| Tests | Pass / Fail / Skipped |
+| Build | Pass / Fail / Skipped |
+
+## Files Reviewed
+<list of files with change type: Added/Modified/Deleted>
+```
+
+### Phase 7 — PUBLISH
+
+Post the review to GitHub:
+
+```bash
+# If APPROVE
+gh pr review <NUMBER> --approve --body "<summary of review>"
+
+# If REQUEST CHANGES
+gh pr review <NUMBER> --request-changes --body "<summary with required fixes>"
+
+# If COMMENT only (draft PR or informational)
+gh pr review <NUMBER> --comment --body "<summary>"
+```
+
+For inline comments on specific lines, use the GitHub review comments API:
+```bash
+gh api "repos/{owner}/{repo}/pulls/<NUMBER>/comments" \
+  -f body="<comment>" \
+  -f path="<file>" \
+  -F line=<line-number> \
+  -f side="RIGHT" \
+  -f commit_id="$(gh pr view <NUMBER> --json headRefOid --jq .headRefOid)"
+```
+
+Alternatively, post a single review with multiple inline comments at once:
+```bash
+gh api "repos/{owner}/{repo}/pulls/<NUMBER>/reviews" \
+  -f event="COMMENT" \
+  -f body="<overall summary>" \
+  --input comments.json  # [{"path": "file", "line": N, "body": "comment"}, ...]
+```
+
+### Phase 8 — OUTPUT
+
+Report to user:
+
+```
+PR #<NUMBER>: <TITLE>
+Decision: <APPROVE|REQUEST_CHANGES|BLOCK>
+
+Issues: <critical_count> critical, <high_count> high, <medium_count> medium, <low_count> low
+Validation: <pass_count>/<total_count> checks passed
+
+Artifacts:
+  Review: .claude/PRPs/reviews/pr-<NUMBER>-review.md
+  GitHub: <PR URL>
+
+Next steps:
+  - <contextual suggestions based on decision>
+```
+
+---
+
+## Edge Cases
+
+- **No `gh` CLI**: Fall back to local-only review (read the diff, skip GitHub publish). Warn user.
+- **Diverged branches**: Suggest `git fetch origin && git rebase origin/<base>` before review.
+- **Large PRs (>50 files)**: Warn about review scope. Focus on source changes first, then tests, then config/docs.

package/.agent/workflows/context-budget.md

@@ -1,29 +1,23 @@
----
-description: Analyze context window usage across agents, skills, MCP servers, and rules to find optimization opportunities. Helps reduce token overhead and avoid performance warnings.
----
-
-# Context Budget Optimizer
-
-Analyze your Claude Code setup's context window consumption and produce actionable recommendations to reduce token overhead.
-
-## Usage
-
-```
-/context-budget [--verbose]
-```
-
-- Default: summary with top recommendations
-- `--verbose`: full breakdown per component
-
-$ARGUMENTS
-
-## What to Do
-
-Run the **context-budget** skill (`skills/context-budget/SKILL.md`) with the following inputs:
-
-1. Pass `--verbose` flag if present in `$ARGUMENTS`
-2. Assume a 200K context window (Claude Sonnet default) unless the user specifies otherwise
-3. Follow the skill's four phases: Inventory → Classify → Detect Issues → Report
-4. Output the formatted Context Budget Report to the user
-
-The skill handles all scanning logic, token estimation, issue detection, and report formatting.
+---
+description: Legacy slash-entry shim for the context-budget skill. Prefer the skill directly.
+---
+
+# Context Budget Optimizer (Legacy Shim)
+
+Use this only if you still invoke `/context-budget`. The maintained workflow lives in `skills/context-budget/SKILL.md`.
+
+## Canonical Surface
+
+- Prefer the `context-budget` skill directly.
+- Keep this file only as a compatibility entry point.
+
+## Arguments
+
+$ARGUMENTS
+
+## Delegation
+
+Apply the `context-budget` skill.
+- Pass through `--verbose` if the user supplied it.
+- Assume a 200K context window unless the user specified otherwise.
+- Return the skill's inventory, issue detection, and prioritized savings report without re-implementing the scan here.