@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/x-api/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: x-api
+description: X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.
+origin: ECC
+---
+
+# X API
+
+Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics.
+
+## When to Activate
+
+- User wants to post tweets or threads programmatically
+- Reading timeline, mentions, or user data from X
+- Searching X for content, trends, or conversations
+- Building X integrations or bots
+- Analytics and engagement tracking
+- User says "post to X", "tweet", "X API", or "Twitter API"
+
+## Authentication
+
+### OAuth 2.0 Bearer Token (App-Only)
+
+Best for: read-heavy operations, search, public data.
+
+```bash
+# Environment setup
+export X_BEARER_TOKEN="your-bearer-token"
+```
+
+```python
+import os
+import requests
+
+bearer = os.environ["X_BEARER_TOKEN"]
+headers = {"Authorization": f"Bearer {bearer}"}
+
+# Search recent tweets
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={"query": "claude code", "max_results": 10}
+)
+tweets = resp.json()
+```
+
+### OAuth 1.0a (User Context)
+
+Required for: posting tweets, managing account, DMs, and any write flow.
+
+```bash
+# Environment setup — source before use
+export X_CONSUMER_KEY="your-consumer-key"
+export X_CONSUMER_SECRET="your-consumer-secret"
+export X_ACCESS_TOKEN="your-access-token"
+export X_ACCESS_TOKEN_SECRET="your-access-token-secret"
+```
+
+Legacy aliases such as `X_API_KEY`, `X_API_SECRET`, and `X_ACCESS_SECRET` may exist in older setups. Prefer the `X_CONSUMER_*` and `X_ACCESS_TOKEN_SECRET` names when documenting or wiring new flows.
+
+```python
+import os
+from requests_oauthlib import OAuth1Session
+
+oauth = OAuth1Session(
+    os.environ["X_CONSUMER_KEY"],
+    client_secret=os.environ["X_CONSUMER_SECRET"],
+    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
+    resource_owner_secret=os.environ["X_ACCESS_TOKEN_SECRET"],
+)
+```
+
+## Core Operations
+
+### Post a Tweet
+
+```python
+resp = oauth.post(
+    "https://api.x.com/2/tweets",
+    json={"text": "Hello from Claude Code"}
+)
+resp.raise_for_status()
+tweet_id = resp.json()["data"]["id"]
+```
+
+### Post a Thread
+
+```python
+def post_thread(oauth, tweets: list[str]) -> list[str]:
+    ids = []
+    reply_to = None
+    for text in tweets:
+        payload = {"text": text}
+        if reply_to:
+            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
+        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
+        tweet_id = resp.json()["data"]["id"]
+        ids.append(tweet_id)
+        reply_to = tweet_id
+    return ids
+```
+
+### Read User Timeline
+
+```python
+resp = requests.get(
+    f"https://api.x.com/2/users/{user_id}/tweets",
+    headers=headers,
+    params={
+        "max_results": 10,
+        "tweet.fields": "created_at,public_metrics",
+    }
+)
+```
+
+### Search Tweets
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={
+        "query": "from:affaanmustafa -is:retweet",
+        "max_results": 10,
+        "tweet.fields": "public_metrics,created_at",
+    }
+)
+```
+
+### Pull Recent Original Posts for Voice Modeling
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={
+        "query": "from:affaanmustafa -is:retweet -is:reply",
+        "max_results": 25,
+        "tweet.fields": "created_at,public_metrics",
+    }
+)
+voice_samples = resp.json()
+```
+
+### Get User by Username
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/users/by/username/affaanmustafa",
+    headers=headers,
+    params={"user.fields": "public_metrics,description,created_at"}
+)
+```
+
+### Upload Media and Post
+
+```python
+# Media upload uses v1.1 endpoint
+
+# Step 1: Upload media
+media_resp = oauth.post(
+    "https://upload.twitter.com/1.1/media/upload.json",
+    files={"media": open("image.png", "rb")}
+)
+media_id = media_resp.json()["media_id_string"]
+
+# Step 2: Post with media
+resp = oauth.post(
+    "https://api.x.com/2/tweets",
+    json={"text": "Check this out", "media": {"media_ids": [media_id]}}
+)
+```
+
+## Rate Limits
+
+X API rate limits vary by endpoint, auth method, and account tier, and they change over time. Always:
+- Check the current X developer docs before hardcoding assumptions
+- Read `x-rate-limit-remaining` and `x-rate-limit-reset` headers at runtime
+- Back off automatically instead of relying on static tables in code
+
+```python
+import time
+
+remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
+if remaining < 5:
+    reset = int(resp.headers.get("x-rate-limit-reset", 0))
+    wait = max(0, reset - int(time.time()))
+    print(f"Rate limit approaching. Resets in {wait}s")
+```
+
+## Error Handling
+
+```python
+resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
+if resp.status_code == 201:
+    return resp.json()["data"]["id"]
+elif resp.status_code == 429:
+    reset = int(resp.headers["x-rate-limit-reset"])
+    raise Exception(f"Rate limited. Resets at {reset}")
+elif resp.status_code == 403:
+    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
+else:
+    raise Exception(f"X API error {resp.status_code}: {resp.text}")
+```
+
+## Security
+
+- **Never hardcode tokens.** Use environment variables or `.env` files.
+- **Never commit `.env` files.** Add to `.gitignore`.
+- **Rotate tokens** if exposed. Regenerate at developer.x.com.
+- **Use read-only tokens** when write access is not needed.
+- **Store OAuth secrets securely** — not in source code or logs.
+
+## Integration with Content Engine
+
+Use `brand-voice` plus `content-engine` to generate platform-native content, then post via X API:
+1. Pull recent original posts when voice matching matters
+2. Build or reuse a `VOICE PROFILE`
+3. Generate content with `content-engine` in X-native format
+4. Validate length and thread structure
+5. Return the draft for approval unless the user explicitly asked to post now
+6. Post via X API only after approval
+7. Track engagement via public_metrics
+
+## Related Skills
+
+- `brand-voice` — Build a reusable voice profile from real X and site/source material
+- `content-engine` — Generate platform-native content for X
+- `crosspost` — Distribute content across X, LinkedIn, and other platforms
+- `connections-optimizer` — Reorganize the X graph before drafting network-driven outreach

package/.agent/tasks/lessons.md

@@ -1,40 +1,40 @@
-# 💡 Lessons Learned / Nhật ký Học tập
-
-> **Dự án**: Pilo Masterkit
-> **Vai trò**: Lưu trữ tri thức, quyết định quan trọng và bài học rút ra giữa các phiên làm việc.
-
----
-
-## 📅 [2026-03-29] - Khởi tạo Pilo Masterkit (Refactor v1.0.0)
-
-### 🎯 Mục tiêu
-- **Thay đổi thương hiệu**: Đổi tên từ `heyai-ruleset` sang `pilo-masterkit` để chuyên nghiệp hơn.
-- **Mô-đun hóa cực hạn**: Áp dụng cấu trúc `.agent/` chuẩn (Agents, Skills, Workflows, Rules, Scripts).
-- **Hợp nhất tri thức**: Tích hợp các quy tắc tinh hoa từ Antigravity, UI/UX Pro và Claude ECC.
-
-### ✅ Quyết định Cốt lõi
-- **Chỉ định Nhân dạng**: `PILO_MASTER.md` trở thành nhân dạng trung tâm điều phối.
-- **Quy tắc Ưu tiên**: Thiết lập `CORE_RULES.md` (P0) làm hiến chương bất biến (PDCA, Socratic Gate).
-- **Copy-Paste Thông minh**: Tận dụng trực tiếp các bộ kỹ năng (Skills) và kịch bản (Scripts) chuẩn của thế giới thay vì tự tạo lại.
-
-### 💡 Bài học kinh nghiệm
-- **Markdown Linting**: Sử dụng cách tiếp cận "Clean Rewrite" (dùng `write_to_file`) cho các file rule quan trọng để đảm bảo tính nhất quán cao nhất.
-- **Tên thư mục ẩn**: Việc sử dụng `.agent/` giúp AI dễ dàng nhận diện và tự động nạp tri thức mà không cần người dùng chỉ định thủ công.
-
-### 🚀 Nhiệm vụ Chờ thực hiện (Pending)
-- Cần chạy hậu kiểm tất cả các kỹ năng vừa copy để đảm bảo đường dẫn tài sản (`assets/`) và tham chiếu chéo (`references/`) không bị hỏng.
-- Nâng cấp `SYSTEM_DESIGN.md` theo mô hình "Master + Overrides" của UI/UX Pro.
-
----
-
-## 📅 [2026-03-18] - Standardizing AI Identity & Operations (Từ bộ tài liệu cũ)
-
-### ✅ Quyết định quan trọng
-- **Standardized Navigation**: Di chuyển các file lẻ tẻ vào `documentation/` (tại thời điểm đó).
-- **Identity Enforcement**: Hợp nhất danh tính và triết lý vận hành vào `IDENTITY_SOUL.md`.
-
-### 💡 Bài học kinh nghiệm
-- Việc sử dụng `multi_replace_file_content` đôi khi gây ra sự trùng lặp nếu phạm vi không chuẩn.
-
----
-> *"Memory is the bridge between instructions and execution."*
+# 💡 Lessons Learned / Nhật ký Học tập
+
+> **Dự án**: Pilo Masterkit
+> **Vai trò**: Lưu trữ tri thức, quyết định quan trọng và bài học rút ra giữa các phiên làm việc.
+
+---
+
+## 📅 [2026-03-29] - Khởi tạo Pilo Masterkit (Refactor v1.0.0)
+
+### 🎯 Mục tiêu
+- **Thay đổi thương hiệu**: Đổi tên từ `heyai-ruleset` sang `pilo-masterkit` để chuyên nghiệp hơn.
+- **Mô-đun hóa cực hạn**: Áp dụng cấu trúc `.agent/` chuẩn (Agents, Skills, Workflows, Rules, Scripts).
+- **Hợp nhất tri thức**: Tích hợp các quy tắc tinh hoa từ Antigravity, UI/UX Pro và Claude ECC.
+
+### ✅ Quyết định Cốt lõi
+- **Chỉ định Nhân dạng**: `PILO_MASTER.md` trở thành nhân dạng trung tâm điều phối.
+- **Quy tắc Ưu tiên**: Thiết lập `CORE_RULES.md` (P0) làm hiến chương bất biến (PDCA, Socratic Gate).
+- **Copy-Paste Thông minh**: Tận dụng trực tiếp các bộ kỹ năng (Skills) và kịch bản (Scripts) chuẩn của thế giới thay vì tự tạo lại.
+
+### 💡 Bài học kinh nghiệm
+- **Markdown Linting**: Sử dụng cách tiếp cận "Clean Rewrite" (dùng `write_to_file`) cho các file rule quan trọng để đảm bảo tính nhất quán cao nhất.
+- **Tên thư mục ẩn**: Việc sử dụng `.agent/` giúp AI dễ dàng nhận diện và tự động nạp tri thức mà không cần người dùng chỉ định thủ công.
+
+### 🚀 Nhiệm vụ Chờ thực hiện (Pending)
+- Cần chạy hậu kiểm tất cả các kỹ năng vừa copy để đảm bảo đường dẫn tài sản (`assets/`) và tham chiếu chéo (`references/`) không bị hỏng.
+- Nâng cấp `SYSTEM_DESIGN.md` theo mô hình "Master + Overrides" của UI/UX Pro.
+
+---
+
+## 📅 [2026-03-18] - Standardizing AI Identity & Operations (Từ bộ tài liệu cũ)
+
+### ✅ Quyết định quan trọng
+- **Standardized Navigation**: Di chuyển các file lẻ tẻ vào `documentation/` (tại thời điểm đó).
+- **Identity Enforcement**: Hợp nhất danh tính và triết lý vận hành vào `IDENTITY_SOUL.md`.
+
+### 💡 Bài học kinh nghiệm
+- Việc sử dụng `multi_replace_file_content` đôi khi gây ra sự trùng lặp nếu phạm vi không chuẩn.
+
+---
+> *"Memory is the bridge between instructions and execution."*

package/.agent/tasks/todo.md

@@ -1,33 +1,33 @@
-# 📋 Task List / Danh sách Nhiệm vụ
-
-> **Dự án**: Pilo Masterkit
-> **Trạng thái**: Đang thực hiện Refactor tổng thể v1.0.0
-
----
-
-## 🏃 Nhiệm vụ hiện tại: Project Refactor
-
-- [x] Đổi tên dự án trong `package.json` thành `pilo-masterkit`.
-- [x] Khởi tạo cấu trúc thư mục `.agent/`.
-- [x] Di chuyển 125+ kỹ năng tinh hoa (Antigravity & UI/UX Pro).
-- [x] Di chuyển 20+ nhân dạng Agent chuyên gia (Antigravity & ECC).
-- [x] Di chuyển 60+ quy trình lệnh Slash Command.
-- [x] Di chuyển 4 kịch bản Master Audit (`checklist.py`, `verify_all.py`).
-- [x] Refactor `IDENTITY_SOUL.md` -> `.agent/agents/PILO_MASTER.md`.
-- [x] Refactor `PROTOCOLS.md` & `RULES.md` -> `.agent/rules/CORE_RULES.md`.
-- [x] Refactor `MAP.md` -> `.agent/rules/PROJECT_MAP.md`.
-- [x] Refactor `SECURITY.md` -> `.agent/rules/SECURITY_ARMOR.md`.
-- [/] Refactor `MEMORIES.md` -> `.agent/tasks/lessons.md`.
-- [ ] Refactor `SYSTEM_DESIGN.md`, `CODE_STANDARDS.md`, `TESTING_POLICY.md`, `GIT_WORKFLOW.md`.
-- [ ] Dọn dẹp thư mục `products/` (Xóa các file đã refactor xong).
-
----
-
-## 🚀 Nhiệm vụ tiếp theo
-
-1.  **Hoàn thiện bộ tiêu chuẩn kỹ thuật**: Nâng cấp các file tiêu chuẩn (Code, Design, Test, Git) lên chuẩn chuyên nghiệp.
-2.  **Xác minh hệ thống**: Chạy thử các Agent và Kỹ năng mới nạp.
-3.  **Cập nhật README.md**: Phản ánh đầy đủ cấu trúc và tên mới của dự án.
-
----
-> *"Plan before you execute. Measure before you commit."*
+# 📋 Task List / Danh sách Nhiệm vụ
+
+> **Dự án**: Pilo Masterkit
+> **Trạng thái**: Đang thực hiện Refactor tổng thể v1.0.0
+
+---
+
+## 🏃 Nhiệm vụ hiện tại: Project Refactor
+
+- [x] Đổi tên dự án trong `package.json` thành `pilo-masterkit`.
+- [x] Khởi tạo cấu trúc thư mục `.agent/`.
+- [x] Di chuyển 125+ kỹ năng tinh hoa (Antigravity & UI/UX Pro).
+- [x] Di chuyển 20+ nhân dạng Agent chuyên gia (Antigravity & ECC).
+- [x] Di chuyển 60+ quy trình lệnh Slash Command.
+- [x] Di chuyển 4 kịch bản Master Audit (`checklist.py`, `verify_all.py`).
+- [x] Refactor `IDENTITY_SOUL.md` -> `.agent/agents/PILO_MASTER.md`.
+- [x] Refactor `PROTOCOLS.md` & `RULES.md` -> `.agent/rules/CORE_RULES.md`.
+- [x] Refactor `MAP.md` -> `.agent/rules/PROJECT_MAP.md`.
+- [x] Refactor `SECURITY.md` -> `.agent/rules/SECURITY_ARMOR.md`.
+- [/] Refactor `MEMORIES.md` -> `.agent/tasks/lessons.md`.
+- [ ] Refactor `SYSTEM_DESIGN.md`, `CODE_STANDARDS.md`, `TESTING_POLICY.md`, `GIT_WORKFLOW.md`.
+- [ ] Dọn dẹp thư mục `products/` (Xóa các file đã refactor xong).
+
+---
+
+## 🚀 Nhiệm vụ tiếp theo
+
+1.  **Hoàn thiện bộ tiêu chuẩn kỹ thuật**: Nâng cấp các file tiêu chuẩn (Code, Design, Test, Git) lên chuẩn chuyên nghiệp.
+2.  **Xác minh hệ thống**: Chạy thử các Agent và Kỹ năng mới nạp.
+3.  **Cập nhật README.md**: Phản ánh đầy đủ cấu trúc và tên mới của dự án.
+
+---
+> *"Plan before you execute. Measure before you commit."*

package/.agent/tasks/two-track-merge-contract.md

@@ -0,0 +1,29 @@
+# Two-Track Merge Contract (Canonical + Alias)
+
+Date: 2026-04-04
+
+## Workflow Compatibility Contract
+- Canonical workflow entries remain stable for: `plan`, `code-review`, `verify`, `clean-memory`, `ui-ux-pro-max`.
+- Specialized workflows remain available and are treated as scoped aliases, not replacements.
+- No workflow path removal until alias map and broken-link checks pass.
+
+## Skill Compatibility Contract
+- Legacy skill packs are retained while new packs are integrated.
+- Overlapping skills are mapped by purpose before archive.
+- Critical skills (`clean-code`, `frontend-design`, `ui-ux-pro-max`) are locked from deletion.
+
+## Rule Compatibility Contract
+- Legacy core rule files remain active baseline.
+- Modular `rules/common/*` and language rules are additive during transition.
+- If conflict exists, stricter security/testing requirement wins.
+
+## Persona Safety Contract
+- Current persona profiles and Trigger On behavior are preserved.
+- Selective read maps are updated only if canonical paths change.
+- No persona folder renaming during merge transition.
+
+## Definition of Done for Cleanup Phase
+- No critical file missing.
+- No duplicate cluster without canonical+alias mapping.
+- No broken internal references in `.agent` docs/workflows/profiles.
+- UTF-8 readability validated on touched files.

package/.agent/workflows/aside.md

@@ -78,7 +78,7 @@ Flag it clearly before resuming:
 ```
 ASIDE: [answer]
 
-⚠️ Note: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
+WARNING: Note: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
 ```
 Wait for the user's decision before resuming.
 
@@ -119,7 +119,7 @@ Note the change needed but do not make it during the aside:
 ```
 ASIDE: [answer]
 
-📝 Worth fixing: [what should be changed]. I'll flag this after the current task unless you want to address it now.
+ Worth fixing: [what should be changed]. I'll flag this after the current task unless you want to address it now.
 ```
 
 **Question is ambiguous or too vague:**
@@ -150,7 +150,7 @@ No — the shared cache object in src/cache/store.ts:34 is mutated without locki
 Under concurrent requests this is a race condition. It's low risk in a single-process
 Node.js server but would be a real problem with worker threads or clustering.
 
-⚠️ Note: This could affect the feature we're building. Want to address this now or continue and fix it in a follow-up?
+WARNING: Note: This could affect the feature we're building. Want to address this now or continue and fix it in a follow-up?
 ```
 
 ---

package/.agent/workflows/brainstorm.md

@@ -1,113 +1,113 @@
----
-description: Structured brainstorming for projects and features. Explores multiple options before implementation.
----
-
-# /brainstorm - Structured Idea Exploration
-
-$ARGUMENTS
-
----
-
-## Purpose
-
-This command activates BRAINSTORM mode for structured idea exploration. Use when you need to explore options before committing to an implementation.
-
----
-
-## Behavior
-
-When `/brainstorm` is triggered:
-
-1. **Understand the goal**
-   - What problem are we solving?
-   - Who is the user?
-   - What constraints exist?
-
-2. **Generate options**
-   - Provide at least 3 different approaches
-   - Each with pros and cons
-   - Consider unconventional solutions
-
-3. **Compare and recommend**
-   - Summarize tradeoffs
-   - Give a recommendation with reasoning
-
----
-
-## Output Format
-
-```markdown
-## 🧠 Brainstorm: [Topic]
-
-### Context
-[Brief problem statement]
-
----
-
-### Option A: [Name]
-[Description]
-
-✅ **Pros:**
-- [benefit 1]
-- [benefit 2]
-
-❌ **Cons:**
-- [drawback 1]
-
-📊 **Effort:** Low | Medium | High
-
----
-
-### Option B: [Name]
-[Description]
-
-✅ **Pros:**
-- [benefit 1]
-
-❌ **Cons:**
-- [drawback 1]
-- [drawback 2]
-
-📊 **Effort:** Low | Medium | High
-
----
-
-### Option C: [Name]
-[Description]
-
-✅ **Pros:**
-- [benefit 1]
-
-❌ **Cons:**
-- [drawback 1]
-
-📊 **Effort:** Low | Medium | High
-
----
-
-## 💡 Recommendation
-
-**Option [X]** because [reasoning].
-
-What direction would you like to explore?
-```
-
----
-
-## Examples
-
-```
-/brainstorm authentication system
-/brainstorm state management for complex form
-/brainstorm database schema for social app
-/brainstorm caching strategy
-```
-
----
-
-## Key Principles
-
-- **No code** - this is about ideas, not implementation
-- **Visual when helpful** - use diagrams for architecture
-- **Honest tradeoffs** - don't hide complexity
-- **Defer to user** - present options, let them decide
+---
+description: Structured brainstorming for projects and features. Explores multiple options before implementation.
+---
+
+# /brainstorm - Structured Idea Exploration
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command activates BRAINSTORM mode for structured idea exploration. Use when you need to explore options before committing to an implementation.
+
+---
+
+## Behavior
+
+When `/brainstorm` is triggered:
+
+1. **Understand the goal**
+   - What problem are we solving?
+   - Who is the user?
+   - What constraints exist?
+
+2. **Generate options**
+   - Provide at least 3 different approaches
+   - Each with pros and cons
+   - Consider unconventional solutions
+
+3. **Compare and recommend**
+   - Summarize tradeoffs
+   - Give a recommendation with reasoning
+
+---
+
+## Output Format
+
+```markdown
+## 🧠 Brainstorm: [Topic]
+
+### Context
+[Brief problem statement]
+
+---
+
+### Option A: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+- [benefit 2]
+
+❌ **Cons:**
+- [drawback 1]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+### Option B: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+
+❌ **Cons:**
+- [drawback 1]
+- [drawback 2]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+### Option C: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+
+❌ **Cons:**
+- [drawback 1]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+## 💡 Recommendation
+
+**Option [X]** because [reasoning].
+
+What direction would you like to explore?
+```
+
+---
+
+## Examples
+
+```
+/brainstorm authentication system
+/brainstorm state management for complex form
+/brainstorm database schema for social app
+/brainstorm caching strategy
+```
+
+---
+
+## Key Principles
+
+- **No code** - this is about ideas, not implementation
+- **Visual when helpful** - use diagrams for architecture
+- **Honest tradeoffs** - don't hide complexity
+- **Defer to user** - present options, let them decide