@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

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

@@ -1,80 +1,80 @@
-# Refactor Clean
-
-Safely identify and remove dead code with test verification at every step.
-
-## Step 1: Detect Dead Code
-
-Run analysis tools based on project type:
-
-| Tool | What It Finds | Command |
-|------|--------------|---------|
-| knip | Unused exports, files, dependencies | `npx knip` |
-| depcheck | Unused npm dependencies | `npx depcheck` |
-| ts-prune | Unused TypeScript exports | `npx ts-prune` |
-| vulture | Unused Python code | `vulture src/` |
-| deadcode | Unused Go code | `deadcode ./...` |
-| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
-
-If no tool is available, use Grep to find exports with zero imports:
-```
-# Find exports, then check if they're imported anywhere
-```
-
-## Step 2: Categorize Findings
-
-Sort findings into safety tiers:
-
-| Tier | Examples | Action |
-|------|----------|--------|
-| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
-| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
-| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
-
-## Step 3: Safe Deletion Loop
-
-For each SAFE item:
-
-1. **Run full test suite** — Establish baseline (all green)
-2. **Delete the dead code** — Use Edit tool for surgical removal
-3. **Re-run test suite** — Verify nothing broke
-4. **If tests fail** — Immediately revert with `git checkout -- <file>` and skip this item
-5. **If tests pass** — Move to next item
-
-## Step 4: Handle CAUTION Items
-
-Before deleting CAUTION items:
-- Search for dynamic imports: `import()`, `require()`, `__import__`
-- Search for string references: route names, component names in configs
-- Check if exported from a public package API
-- Verify no external consumers (check dependents if published)
-
-## Step 5: Consolidate Duplicates
-
-After removing dead code, look for:
-- Near-duplicate functions (>80% similar) — merge into one
-- Redundant type definitions — consolidate
-- Wrapper functions that add no value — inline them
-- Re-exports that serve no purpose — remove indirection
-
-## Step 6: Summary
-
-Report results:
-
-```
-Dead Code Cleanup
-──────────────────────────────
-Deleted:   12 unused functions
-           3 unused files
-           5 unused dependencies
-Skipped:   2 items (tests failed)
-Saved:     ~450 lines removed
-──────────────────────────────
-All tests passing ✅
-```
-
-## Rules
-
-- **Never delete without running tests first**
-- **One deletion at a time** — Atomic changes make rollback easy
-- **Skip if uncertain** — Better to keep dead code than break production
-- **Don't refactor while cleaning** — Separate concerns (clean first, refactor later)
+# Refactor Clean
+
+Safely identify and remove dead code with test verification at every step.
+
+## Step 1: Detect Dead Code
+
+Run analysis tools based on project type:
+
+| Tool | What It Finds | Command |
+|------|--------------|---------|
+| knip | Unused exports, files, dependencies | `npx knip` |
+| depcheck | Unused npm dependencies | `npx depcheck` |
+| ts-prune | Unused TypeScript exports | `npx ts-prune` |
+| vulture | Unused Python code | `vulture src/` |
+| deadcode | Unused Go code | `deadcode ./...` |
+| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
+
+If no tool is available, use Grep to find exports with zero imports:
+```
+# Find exports, then check if they're imported anywhere
+```
+
+## Step 2: Categorize Findings
+
+Sort findings into safety tiers:
+
+| Tier | Examples | Action |
+|------|----------|--------|
+| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
+| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
+| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
+
+## Step 3: Safe Deletion Loop
+
+For each SAFE item:
+
+1. **Run full test suite** — Establish baseline (all green)
+2. **Delete the dead code** — Use Edit tool for surgical removal
+3. **Re-run test suite** — Verify nothing broke
+4. **If tests fail** — Immediately revert with `git checkout -- <file>` and skip this item
+5. **If tests pass** — Move to next item
+
+## Step 4: Handle CAUTION Items
+
+Before deleting CAUTION items:
+- Search for dynamic imports: `import()`, `require()`, `__import__`
+- Search for string references: route names, component names in configs
+- Check if exported from a public package API
+- Verify no external consumers (check dependents if published)
+
+## Step 5: Consolidate Duplicates
+
+After removing dead code, look for:
+- Near-duplicate functions (>80% similar) — merge into one
+- Redundant type definitions — consolidate
+- Wrapper functions that add no value — inline them
+- Re-exports that serve no purpose — remove indirection
+
+## Step 6: Summary
+
+Report results:
+
+```
+Dead Code Cleanup
+──────────────────────────────
+Deleted:   12 unused functions
+           3 unused files
+           5 unused dependencies
+Skipped:   2 items (tests failed)
+Saved:     ~450 lines removed
+──────────────────────────────
+All tests passing PASS:
+```
+
+## Rules
+
+- **Never delete without running tests first**
+- **One deletion at a time** — Atomic changes make rollback easy
+- **Skip if uncertain** — Better to keep dead code than break production
+- **Don't refactor while cleaning** — Separate concerns (clean first, refactor later)

package/.agent/workflows/resume-session.md

@@ -1,156 +1,156 @@
----
-description: Load the most recent session file from ~/.claude/session-data/ and resume work with full context from where the last session ended.
----
-
-# Resume Session Command
-
-Load the last saved session state and orient fully before doing any work.
-This command is the counterpart to `/save-session`.
-
-## When to Use
-
-- Starting a new session to continue work from a previous day
-- After starting a fresh session due to context limits
-- When handing off a session file from another source (just provide the file path)
-- Any time you have a session file and want Claude to fully absorb it before proceeding
-
-## Usage
-
-```
-/resume-session                                                      # loads most recent file in ~/.claude/session-data/
-/resume-session 2024-01-15                                           # loads most recent session for that date
-/resume-session ~/.claude/session-data/2024-01-15-abc123de-session.tmp  # loads a current short-id session file
-/resume-session ~/.claude/sessions/2024-01-15-session.tmp               # loads a specific legacy-format file
-```
-
-## Process
-
-### Step 1: Find the session file
-
-If no argument provided:
-
-1. Check `~/.claude/session-data/`
-2. Pick the most recently modified `*-session.tmp` file
-3. If the folder does not exist or has no matching files, tell the user:
-   ```
-   No session files found in ~/.claude/session-data/
-   Run /save-session at the end of a session to create one.
-   ```
-   Then stop.
-
-If an argument is provided:
-
-- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/session-data/` first, then the legacy
-  `~/.claude/sessions/`, for files matching `YYYY-MM-DD-session.tmp` (legacy format) or
-  `YYYY-MM-DD-<shortid>-session.tmp` (current format)
-  and load the most recently modified variant for that date
-- If it looks like a file path, read that file directly
-- If not found, report clearly and stop
-
-### Step 2: Read the entire session file
-
-Read the complete file. Do not summarize yet.
-
-### Step 3: Confirm understanding
-
-Respond with a structured briefing in this exact format:
-
-```
-SESSION LOADED: [actual resolved path to the file]
-════════════════════════════════════════════════
-
-PROJECT: [project name / topic from file]
-
-WHAT WE'RE BUILDING:
-[2-3 sentence summary in your own words]
-
-CURRENT STATE:
-✅ Working: [count] items confirmed
-🔄 In Progress: [list files that are in progress]
-🗒️ Not Started: [list planned but untouched]
-
-WHAT NOT TO RETRY:
-[list every failed approach with its reason — this is critical]
-
-OPEN QUESTIONS / BLOCKERS:
-[list any blockers or unanswered questions]
-
-NEXT STEP:
-[exact next step if defined in the file]
-[if not defined: "No next step defined — recommend reviewing 'What Has NOT Been Tried Yet' together before starting"]
-
-════════════════════════════════════════════════
-Ready to continue. What would you like to do?
-```
-
-### Step 4: Wait for the user
-
-Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
-
-If the next step is clearly defined in the session file and the user says "continue" or "yes" or similar — proceed with that exact next step.
-
-If no next step is defined — ask the user where to start, and optionally suggest an approach from the "What Has NOT Been Tried Yet" section.
-
----
-
-## Edge Cases
-
-**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`):
-Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
-
-**Session file references files that no longer exist:**
-Note this during the briefing — "⚠️ `path/to/file.ts` referenced in session but not found on disk."
-
-**Session file is from more than 7 days ago:**
-Note the gap — "⚠️ This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
-
-**User provides a file path directly (e.g., forwarded from a teammate):**
-Read it and follow the same briefing process — the format is the same regardless of source.
-
-**Session file is empty or malformed:**
-Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
-
----
-
-## Example Output
-
-```
-SESSION LOADED: /Users/you/.claude/session-data/2024-01-15-abc123de-session.tmp
-════════════════════════════════════════════════
-
-PROJECT: my-app — JWT Authentication
-
-WHAT WE'RE BUILDING:
-User authentication with JWT tokens stored in httpOnly cookies.
-Register and login endpoints are partially done. Route protection
-via middleware hasn't been started yet.
-
-CURRENT STATE:
-✅ Working: 3 items (register endpoint, JWT generation, password hashing)
-🔄 In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
-🗒️ Not Started: middleware.ts, app/login/page.tsx
-
-WHAT NOT TO RETRY:
-❌ Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
-❌ localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
-
-OPEN QUESTIONS / BLOCKERS:
-- Does cookies().set() work inside a Route Handler or only Server Actions?
-
-NEXT STEP:
-In app/api/auth/login/route.ts — set the JWT as an httpOnly cookie using
-cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
-then test with Postman for a Set-Cookie header in the response.
-
-════════════════════════════════════════════════
-Ready to continue. What would you like to do?
-```
-
----
-
-## Notes
-
-- Never modify the session file when loading it — it's a read-only historical record
-- The briefing format is fixed — do not skip sections even if they are empty
-- "What Not To Retry" must always be shown, even if it just says "None" — it's too important to miss
-- After resuming, the user may want to run `/save-session` again at the end of the new session to create a new dated file
+---
+description: Load the most recent session file from ~/.claude/session-data/ and resume work with full context from where the last session ended.
+---
+
+# Resume Session Command
+
+Load the last saved session state and orient fully before doing any work.
+This command is the counterpart to `/save-session`.
+
+## When to Use
+
+- Starting a new session to continue work from a previous day
+- After starting a fresh session due to context limits
+- When handing off a session file from another source (just provide the file path)
+- Any time you have a session file and want Claude to fully absorb it before proceeding
+
+## Usage
+
+```
+/resume-session                                                      # loads most recent file in ~/.claude/session-data/
+/resume-session 2024-01-15                                           # loads most recent session for that date
+/resume-session ~/.claude/session-data/2024-01-15-abc123de-session.tmp  # loads a current short-id session file
+/resume-session ~/.claude/sessions/2024-01-15-session.tmp               # loads a specific legacy-format file
+```
+
+## Process
+
+### Step 1: Find the session file
+
+If no argument provided:
+
+1. Check `~/.claude/session-data/`
+2. Pick the most recently modified `*-session.tmp` file
+3. If the folder does not exist or has no matching files, tell the user:
+   ```
+   No session files found in ~/.claude/session-data/
+   Run /save-session at the end of a session to create one.
+   ```
+   Then stop.
+
+If an argument is provided:
+
+- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/session-data/` first, then the legacy
+  `~/.claude/sessions/`, for files matching `YYYY-MM-DD-session.tmp` (legacy format) or
+  `YYYY-MM-DD-<shortid>-session.tmp` (current format)
+  and load the most recently modified variant for that date
+- If it looks like a file path, read that file directly
+- If not found, report clearly and stop
+
+### Step 2: Read the entire session file
+
+Read the complete file. Do not summarize yet.
+
+### Step 3: Confirm understanding
+
+Respond with a structured briefing in this exact format:
+
+```
+SESSION LOADED: [actual resolved path to the file]
+════════════════════════════════════════════════
+
+PROJECT: [project name / topic from file]
+
+WHAT WE'RE BUILDING:
+[2-3 sentence summary in your own words]
+
+CURRENT STATE:
+PASS: Working: [count] items confirmed
+ In Progress: [list files that are in progress]
+ Not Started: [list planned but untouched]
+
+WHAT NOT TO RETRY:
+[list every failed approach with its reason — this is critical]
+
+OPEN QUESTIONS / BLOCKERS:
+[list any blockers or unanswered questions]
+
+NEXT STEP:
+[exact next step if defined in the file]
+[if not defined: "No next step defined — recommend reviewing 'What Has NOT Been Tried Yet' together before starting"]
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+### Step 4: Wait for the user
+
+Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
+
+If the next step is clearly defined in the session file and the user says "continue" or "yes" or similar — proceed with that exact next step.
+
+If no next step is defined — ask the user where to start, and optionally suggest an approach from the "What Has NOT Been Tried Yet" section.
+
+---
+
+## Edge Cases
+
+**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`):
+Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
+
+**Session file references files that no longer exist:**
+Note this during the briefing — "WARNING: `path/to/file.ts` referenced in session but not found on disk."
+
+**Session file is from more than 7 days ago:**
+Note the gap — "WARNING: This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
+
+**User provides a file path directly (e.g., forwarded from a teammate):**
+Read it and follow the same briefing process — the format is the same regardless of source.
+
+**Session file is empty or malformed:**
+Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
+
+---
+
+## Example Output
+
+```
+SESSION LOADED: /Users/you/.claude/session-data/2024-01-15-abc123de-session.tmp
+════════════════════════════════════════════════
+
+PROJECT: my-app — JWT Authentication
+
+WHAT WE'RE BUILDING:
+User authentication with JWT tokens stored in httpOnly cookies.
+Register and login endpoints are partially done. Route protection
+via middleware hasn't been started yet.
+
+CURRENT STATE:
+PASS: Working: 3 items (register endpoint, JWT generation, password hashing)
+ In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
+ Not Started: middleware.ts, app/login/page.tsx
+
+WHAT NOT TO RETRY:
+FAIL: Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
+FAIL: localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
+
+OPEN QUESTIONS / BLOCKERS:
+- Does cookies().set() work inside a Route Handler or only Server Actions?
+
+NEXT STEP:
+In app/api/auth/login/route.ts — set the JWT as an httpOnly cookie using
+cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
+then test with Postman for a Set-Cookie header in the response.
+
+════════════════════════════════════════════════
+Ready to continue. What would you like to do?
+```
+
+---
+
+## Notes
+
+- Never modify the session file when loading it — it's a read-only historical record
+- The briefing format is fixed — do not skip sections even if they are empty
+- "What Not To Retry" must always be shown, even if it just says "None" — it's too important to miss
+- After resuming, the user may want to run `/save-session` again at the end of the new session to create a new dated file

package/.agent/workflows/rules-distill.md

@@ -1,11 +1,20 @@
----
-description: "Scan skills to extract cross-cutting principles and distill them into rules"
----
-
-# /rules-distill — Distill Principles from Skills into Rules
-
-Scan installed skills, extract cross-cutting principles, and distill them into rules.
-
-## Process
-
-Follow the full workflow defined in the `rules-distill` skill.
+---
+description: Legacy slash-entry shim for the rules-distill skill. Prefer the skill directly.
+---
+
+# Rules Distill (Legacy Shim)
+
+Use this only if you still invoke `/rules-distill`. The maintained workflow lives in `skills/rules-distill/SKILL.md`.
+
+## Canonical Surface
+
+- Prefer the `rules-distill` skill directly.
+- Keep this file only as a compatibility entry point.
+
+## Arguments
+
+`$ARGUMENTS`
+
+## Delegation
+
+Apply the `rules-distill` skill and follow its inventory, cross-read, and verdict workflow instead of duplicating that logic here.