@musashishao/agent-kit 1.7.0 → 1.8.1

package/.agent/skills/react-patterns/rerender-patterns.md

@@ -0,0 +1,163 @@
+# Re-render Patterns (MEDIUM)
+
+> Optimize re-renders for smoother UX. Profile first, optimize second.
+
+---
+
+## rerender-memo
+
+**Extract expensive work into memoized components.**
+
+```tsx
+// ✅ Wrap expensive components
+const ExpensiveList = memo(function ExpensiveList({ items }) {
+  return items.map(item => <Item key={item.id} {...item} />);
+});
+
+// Use when:
+// - Component re-renders often
+// - Props rarely change
+// - Rendering is expensive
+```
+
+---
+
+## rerender-functional-setstate
+
+**Use functional setState for stable callbacks.**
+
+```tsx
+// ❌ BAD: Needs count in dependencies
+const increment = useCallback(() => {
+  setCount(count + 1);
+}, [count]);
+
+// ✅ GOOD: No dependencies needed
+const increment = useCallback(() => {
+  setCount(c => c + 1);
+}, []);
+```
+
+---
+
+## rerender-lazy-state-init
+
+**Pass function to useState for expensive initial values.**
+
+```tsx
+// ❌ BAD: Runs on every render
+const [data] = useState(expensiveCalc());
+
+// ✅ GOOD: Runs only on mount
+const [data] = useState(() => expensiveCalc());
+```
+
+---
+
+## rerender-derived-state
+
+**Subscribe to derived booleans, not raw values.**
+
+```tsx
+// ❌ BAD: Re-renders on every items change
+const items = useStore(state => state.items);
+const hasItems = items.length > 0;
+
+// ✅ GOOD: Only re-renders when boolean changes
+const hasItems = useStore(state => state.items.length > 0);
+```
+
+---
+
+## rerender-derived-state-no-effect
+
+**Derive state during render, not in effects.**
+
+```tsx
+// ❌ BAD: Extra render cycle
+const [filtered, setFiltered] = useState([]);
+useEffect(() => {
+  setFiltered(items.filter(filterFn));
+}, [items]);
+
+// ✅ GOOD: Computed during render
+const filtered = useMemo(
+  () => items.filter(filterFn),
+  [items]
+);
+```
+
+---
+
+## rerender-transitions
+
+**Use startTransition for non-urgent updates.**
+
+```tsx
+// ✅ Keep UI responsive during heavy updates
+const [isPending, startTransition] = useTransition();
+
+const handleSearch = (query: string) => {
+  setQuery(query); // Urgent: update input
+  
+  startTransition(() => {
+    setResults(search(query)); // Non-urgent: update list
+  });
+};
+```
+
+---
+
+## rerender-use-ref-transient-values
+
+**Use refs for transient frequent values.**
+
+```tsx
+// ❌ BAD: Re-renders on every mouse move
+const [position, setPosition] = useState({ x: 0, y: 0 });
+
+// ✅ GOOD: No re-renders, update DOM directly
+const positionRef = useRef({ x: 0, y: 0 });
+
+useEffect(() => {
+  const handle = (e) => {
+    positionRef.current = { x: e.clientX, y: e.clientY };
+    // Update DOM directly if needed
+  };
+  window.addEventListener('mousemove', handle);
+  return () => window.removeEventListener('mousemove', handle);
+}, []);
+```
+
+---
+
+## rerender-move-effect-to-event
+
+**Put interaction logic in event handlers, not effects.**
+
+```tsx
+// ❌ BAD: Effect for user action
+useEffect(() => {
+  if (shouldSubmit) {
+    submit();
+    setShouldSubmit(false);
+  }
+}, [shouldSubmit]);
+
+// ✅ GOOD: Direct in handler
+const handleClick = () => {
+  submit();
+};
+```
+
+---
+
+## Quick Detection
+
+| Signal | Pattern to Apply |
+|--------|-----------------|
+| Renders on typing | `startTransition` or debounce |
+| Child re-renders when parent does | `memo` the child |
+| Effect sets state from props | Derive during render |
+| High-frequency updates | Use refs |
+| Complex filtering | `useMemo` |

package/.agent/skills/react-patterns/server-patterns.md

@@ -0,0 +1,146 @@
+# Server Patterns (HIGH)
+
+> Server Components and caching patterns for optimal performance.
+
+---
+
+## server-cache-react
+
+**Use React.cache() for per-request deduplication.**
+
+```tsx
+// ✅ Dedupe within same request
+import { cache } from 'react';
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+
+// Called multiple times in component tree = 1 DB query
+```
+
+| Caching Method | Scope | Use Case |
+|----------------|-------|----------|
+| `React.cache()` | Per-request | Same data in multiple components |
+| `unstable_cache()` | Cross-request | Data shared between users |
+| Data Cache | Persistent | fetch() with revalidate |
+
+---
+
+## server-dedup-props
+
+**Avoid duplicate serialization in RSC props.**
+
+```tsx
+// ❌ BAD: Passes full object to multiple children
+<ChildA user={user} />
+<ChildB user={user} />
+<ChildC user={user} /> // user serialized 3x
+
+// ✅ GOOD: Pass minimal data or use context
+<UserProvider user={user}>
+  <ChildA />
+  <ChildB />
+  <ChildC />
+</UserProvider>
+```
+
+---
+
+## server-parallel-fetching
+
+**Restructure components to parallelize fetches.**
+
+```tsx
+// ❌ BAD: Sequential in parent
+async function Page() {
+  const user = await getUser();
+  const posts = await getPosts(user.id); // Waits for user
+  return <Content user={user} posts={posts} />;
+}
+
+// ✅ GOOD: Parallel with child components
+async function Page() {
+  return (
+    <>
+      <Suspense><UserSection /></Suspense>
+      <Suspense><PostsSection /></Suspense>
+    </>
+  );
+}
+```
+
+---
+
+## server-after-nonblocking
+
+**Use after() for non-blocking operations.**
+
+```tsx
+import { after } from 'next/server';
+
+export async function POST(request: Request) {
+  const data = await request.json();
+  
+  // Return response immediately
+  const result = await saveData(data);
+  
+  // Log after response is sent
+  after(async () => {
+    await logAnalytics(data);
+    await sendNotification(data);
+  });
+  
+  return Response.json(result);
+}
+```
+
+---
+
+## server-auth-actions
+
+**Authenticate Server Actions like API routes.**
+
+```tsx
+'use server'
+
+export async function updateProfile(formData: FormData) {
+  // ✅ Always verify auth in server actions
+  const session = await getSession();
+  if (!session) {
+    throw new Error('Unauthorized');
+  }
+  
+  // ✅ Validate input
+  const data = schema.parse(Object.fromEntries(formData));
+  
+  return db.user.update({
+    where: { id: session.userId },
+    data
+  });
+}
+```
+
+---
+
+## server-serialization
+
+**Minimize data passed to client components.**
+
+```tsx
+// ❌ BAD: Passes entire object
+<ClientComponent user={user} /> // Serializes all fields
+
+// ✅ GOOD: Pass only needed fields
+<ClientComponent 
+  name={user.name}
+  avatar={user.avatar}
+/>
+```
+
+| Rule | Why |
+|------|-----|
+| Only pass primitives | Smaller payload |
+| No functions | Can't serialize |
+| No Date objects | Use ISO strings |
+| No circular refs | JSON.stringify fails |

package/.agent/skills/react-patterns/waterfall-patterns.md

@@ -0,0 +1,102 @@
+# Waterfall Patterns (CRITICAL)
+
+> Eliminating request waterfalls is the highest-impact React optimization.
+
+---
+
+## async-defer-await
+
+**Move `await` into branches where actually used.**
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| Fetch data before checking if needed | Fetch only when condition is true |
+
+```tsx
+// ❌ BAD: Always waits even when not needed
+const data = await getData();
+if (condition) {
+  use(data);
+}
+
+// ✅ GOOD: Only fetches when needed
+if (condition) {
+  const data = await getData();
+  use(data);
+}
+```
+
+---
+
+## async-parallel
+
+**Use Promise.all() for independent operations.**
+
+```tsx
+// ❌ BAD: Sequential (2 round trips)
+const user = await getUser();
+const posts = await getPosts();
+
+// ✅ GOOD: Parallel (1 round trip)
+const [user, posts] = await Promise.all([
+  getUser(),
+  getPosts()
+]);
+```
+
+---
+
+## async-suspense-boundaries
+
+**Use Suspense to stream content progressively.**
+
+```tsx
+// ✅ Stream slow components independently
+<Suspense fallback={<Skeleton />}>
+  <SlowComponent /> {/* Streams when ready */}
+</Suspense>
+<FastComponent /> {/* Shows immediately */}
+```
+
+| Pattern | Use When |
+|---------|----------|
+| Single Suspense | One slow data source |
+| Nested Suspense | Multiple independent slow sources |
+| Suspense + loading.tsx | Page-level loading |
+
+---
+
+## async-api-routes
+
+**Start promises early, await late in API routes.**
+
+```tsx
+// ✅ Start all promises immediately
+export async function GET() {
+  const userPromise = getUser();
+  const postsPromise = getPosts();
+  
+  // Do other sync work here...
+  
+  // Await at the end
+  const [user, posts] = await Promise.all([
+    userPromise,
+    postsPromise
+  ]);
+  
+  return Response.json({ user, posts });
+}
+```
+
+---
+
+## Quick Detection
+
+| Signal | Likely Waterfall |
+|--------|------------------|
+| Sequential `await` | Use `Promise.all()` |
+| `await` before `if` | Move into branch |
+| No `<Suspense>` with RSC | Add streaming |
+| Nested data fetching | Restructure components |
+
+> **Remember:** Profile first with React DevTools and Network tab.

package/.agent/skills/reader-testing/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: reader-testing
+description: Validate documents and code by testing with a fresh AI instance (no context). Use when finalizing docs, specs, READMEs, or any content that others will read. Catches blind spots, assumptions, and gaps before publishing.
+---
+
+# Reader Testing
+
+> **Core Idea:** Test your document with a "fresh reader" (no context) to catch blind spots before others read it.
+> **Inspired by:** Anthropic's Doc Co-Authoring workflow
+
+---
+
+## 🎯 When to Use
+
+| Trigger | Example |
+|---------|---------|
+| Finalizing docs | "Review my README", "Check this spec" |
+| Before publishing | "Is this doc clear?", "Test this guide" |
+| Knowledge transfer | "Will others understand this?" |
+| API docs | "Test my API documentation" |
+
+---
+
+## 🔄 3-Phase Workflow
+
+```
+Phase 1: Context Gathering
+    └── Understand what the doc is about
+
+Phase 2: Question Prediction
+    └── Generate questions readers will ask
+
+Phase 3: Fresh Reader Test
+    └── Test with zero-context AI
+    └── Fix gaps found
+```
+
+---
+
+## Phase 1: Context Gathering
+
+Before testing, understand:
+
+| Question | Why |
+|----------|-----|
+| Who is the audience? | Technical vs non-technical affects clarity needs |
+| What's the goal? | Reference doc vs tutorial vs decision doc |
+| What context do readers have? | What can you assume they know? |
+
+---
+
+## Phase 2: Question Prediction
+
+Generate 5-10 questions that readers would realistically ask:
+
+### Question Types
+
+| Type | Example |
+|------|---------|
+| **Discovery** | "How do I do X?" |
+| **Clarification** | "What does Y mean?" |
+| **Edge cases** | "What happens if Z?" |
+| **Prerequisites** | "What do I need first?" |
+| **Troubleshooting** | "Why isn't this working?" |
+
+### Example Predictions
+
+```markdown
+For a README:
+1. "How do I install this?"
+2. "What are the requirements?"
+3. "How do I run it?"
+4. "Where do I configure X?"
+5. "What does error Y mean?"
+```
+
+---
+
+## Phase 3: Fresh Reader Test
+
+### Option A: Sub-Agent Test (Automated)
+
+Use a sub-agent with ONLY the document content:
+
+```
+Instructions to sub-agent:
+1. Read ONLY the provided document
+2. Answer the predicted questions
+3. Report what was unclear or missing
+4. Identify assumed knowledge
+```
+
+### Option B: Manual Test
+
+1. Open a new AI conversation (fresh context)
+2. Paste the document
+3. Ask the predicted questions
+4. Note what the AI gets wrong
+
+### Test Checklist
+
+For each question, check:
+
+| Check | Pass | Fail |
+|-------|------|------|
+| Answer found in doc? | ✅ | ❌ Add it |
+| Answer is clear? | ✅ | ❌ Rewrite |
+| No wrong assumptions? | ✅ | ❌ Add context |
+
+---
+
+## 🛠️ Additional Checks
+
+Ask the fresh reader:
+
+```markdown
+1. "What in this doc might be ambiguous?"
+2. "What knowledge does this assume readers have?"
+3. "Are there contradictions or inconsistencies?"
+4. "What's missing that you'd expect to find?"
+```
+
+---
+
+## 📋 Output Format
+
+After testing, report:
+
+```markdown
+## Reader Test Results
+
+### Questions Tested
+| # | Question | Result | Action |
+|---|----------|--------|--------|
+| 1 | How to install? | ✅ Clear | None |
+| 2 | How to configure? | ❌ Missing | Add config section |
+| 3 | What are prereqs? | ⚠️ Unclear | Clarify Node version |
+
+### Gaps Found
+- [ ] Missing: Configuration guide
+- [ ] Unclear: Error handling section
+- [ ] Assumed: Reader knows Docker
+
+### Recommended Fixes
+1. Add "Prerequisites" section
+2. Expand "Configuration" with examples
+3. Add "Troubleshooting" FAQ
+```
+
+---
+
+## 🔁 Iteration
+
+**Exit Condition:** When fresh reader:
+- Answers all questions correctly
+- Finds no new gaps
+- Reports no ambiguities
+
+Then the doc is ready! ✅
+
+---
+
+## Integration with Other Skills
+
+| Combine With | For |
+|--------------|-----|
+| `documentation-templates` | Generate initial doc structure |
+| `spec-writing` | Validate specs before implementation |
+| `plan-writing` | Test project plans for clarity |
+
+---
+
+## Quick Reference
+
+```
+1. LIST predicted reader questions (5-10)
+2. TEST with fresh AI (no context)
+3. RECORD what failed
+4. FIX gaps
+5. REPEAT until clean
+```
+
+> **Remember:** If YOU wrote it, you have context bias. Fresh readers don't.

package/.agent/skills/verification-gate/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: verification-gate
+description: Evidence-based verification before any completion claims. Use ALWAYS before claiming work is done, tests pass, builds succeed, or bugs are fixed. NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+allowed-tools: Read, Bash, Grep
+---
+
+# Verification Before Completion
+
+> **Iron Law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+---
+
+## 🔴 The Gate Function (MANDATORY)
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+---
+
+## 📋 Verification Matrix
+
+| Claim | Command Required | Evidence Needed | Not Sufficient |
+|-------|------------------|-----------------|----------------|
+| **Tests pass** | `npm test` / `pytest` | 0 failures, exit 0 | "should pass", previous run |
+| **Linter clean** | `npm run lint` / `eslint` | 0 errors | partial check |
+| **Build succeeds** | `npm run build` | exit 0 | linter passing |
+| **Bug fixed** | Test original symptom | passes now | "code changed" |
+| **Types correct** | `tsc --noEmit` | 0 errors | "looks correct" |
+| **Agent completed** | Check VCS diff | changes visible | agent reports "success" |
+| **Requirements met** | Line-by-line checklist | each verified | tests passing |
+
+---
+
+## 🚩 Red Flags - STOP IMMEDIATELY
+
+**Language Red Flags:**
+- Using "should", "probably", "seems to"
+- Expressing satisfaction ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- ANY wording implying success without evidence
+
+**Behavior Red Flags:**
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+
+---
+
+## ❌ Rationalization Prevention
+
+| Excuse | Correct Response |
+|--------|------------------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+
+---
+
+## ✅ Correct Patterns
+
+### Tests
+```
+✅ [Run: npm test] [Output: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+### TDD Red-Green (Regression Tests)
+```
+✅ Write test → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+### Build
+```
+✅ [Run: npm run build] [Output: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+### Requirements
+```
+✅ Re-read plan → Create checklist → Verify EACH → Report gaps OR completion
+❌ "Tests pass, phase complete"
+```
+
+### Agent Delegation
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report without verification
+```
+
+---
+
+## ⏱️ When to Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+---
+
+## 📊 The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is **non-negotiable**.