@psnext/slingcli 3.0.20260827-1 → 3.3.20260911-1

package/skills/context-management/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: context-management
+description: Strategies for efficient context management using context_log, context_tag, and context_checkout. Learn when to tag, how to visualize the graph, and safe ways to squash history. Use for complex refactoring, debugging, and long conversations.
+---
+
+# Context Management
+
+**CRITICAL: THIS SKILL MANAGES YOUR MEMORY. WITHOUT IT, YOU WILL FORGET.**
+
+Your context window is limited. As conversations grow, "pollution" (noise, failed attempts) degrades your reasoning.
+
+**YOU MUST PROACTIVELY MANAGE YOUR HISTORY.**
+Do not wait for the user to tell you.
+
+## The Core Philosophy: Build, Perceive, Navigate
+
+```
+Context Window = RAM (Expensive, volatile, limited)
+Context Graph  = Disk (Cheap, persistent, unlimited)
+
+→ Move finished tasks from RAM to the Graph.
+```
+
+Manage your context window like a Git repository. You are the maintainer.
+
+1.  **BUILD the Skeleton (`context_tag`)**:
+    *   Raw conversation is a flat list. **Tags create structure.**
+    *   Without tags, `context_log` is just a list of IDs. With tags, it is a **Map**.
+2.  **PERCEIVE the State (`context_log`)**:
+    *   Check the HUD: Is "Segment Size" too big? You are drifting.
+    *   Check the Graph: Where are you? Are you in a deep branch?
+3.  **NAVIGATE & MERGE (`context_checkout`)**:
+    *   **Squash:** Convert a messy "feature branch" (thinking process) into a single "merge commit" (summary).
+    *   **Jump:** Move between tasks or retry paths without carrying baggage.
+
+## Quick Start: The Loop
+
+Follow this cycle for every major task:
+
+1.  **CHECK:** Verify state.
+    `context_log`
+2.  **START:** Tag the beginning with a semantic name.
+    `context_tag({ name: "<task-slug>-start" })`  // e.g., `auth-login-start`
+3.  **WORK:** Execute steps.
+4.  **MILESTONE:** Tag intermediate stable states.
+    `context_tag({ name: "<task-slug>-plan" })`  // e.g., `auth-login-plan`
+5.  **SQUASH (Autonomous):** If history becomes noisy or low-density, **Squash with Backup**.
+    *   *Action:* `context_checkout({ target: "<task-slug>-start", message: "...", backupTag: "<task-slug>-raw-history" })`
+    *   *Action (Optional):* `context_tag({ name: "<task-slug>-done" })`
+    *   *Safety:* If you need the details later, checkout the backup tag.
+
+## Tool Reference
+
+| Tool | Analog | Purpose | When to Use |
+| :--- | :--- | :--- | :--- |
+| `context_tag` | `git tag` | Bookmark a stable state. | Before risky changes. Before starting a new task. |
+| `context_log` | `git log` | See where you are. | When you feel lost. To find IDs for checkout. |
+| `context_checkout`| `git reset --soft` | **Time Travel / Squash.** | To undo mistakes. To compress history. |
+
+## Critical Rules
+
+### Tag Wisely (Build The Skeleton)
+
+Tags are the "Table of Contents". Name them so you can understand the history at a glance.
+
+**Naming Formula:** `<task-slug>-<phase>`
+
+*   **task-slug**: Short, kebab-case identifier for the task (e.g., `auth-login`, `db-migration`)
+*   **phase**: The stage of work (`start`, `plan`, `impl`, `done`, `fail`, `backup`)
+
+| Bad (Generic) | Good (Semantic) | Why |
+| :--- | :--- | :--- |
+| `task-start` | `auth-oauth-start` | Describes WHAT task |
+| `pre-research` | `error-log-analysis-start` | Future-you knows the topic |
+| `phase-1-done` | `db-schema-plan-done` | Know which phase of which task |
+| `debug-retry` | `null-pointer-fix-retry` | What bug? |
+
+**Tag Categories:**
+
+| Category | Pattern | Examples |
+| :--- | :--- | :--- |
+| **Start** | `<task>-start` | `auth-jwt-start`, `docker-setup-start` |
+| **Plan** | `<task>-plan` | `api-v2-plan`, `migration-plan` |
+| **Milestone** | `<task>-<milestone>` | `auth-jwt-impl-done`, `tests-passed` |
+| **Backup** | `<task>-raw-history` | `auth-jwt-raw-history` |
+| **Failure** | `<task>-fail-<reason>` | `auth-jwt-fail-timeout` |
+
+**How to generate:** Ask yourself "What is the task?" → Extract 1-3 keywords (e.g., "fix login timeout" → `login-timeout-fix-start`)
+
+### Squash Noise, Keep Signal, Focus on Goal (Context Hygiene)
+Think of your conversation as a "Feature Branch" full of messy thoughts.
+**You must distinguish Signal from Noise.**
+
+*   **Signal (High Value):** Design decisions, user constraints, final working code. -> **KEEP.**
+*   **Noise (Low Value):** Failed attempts, long tool outputs, "thinking" steps. -> **SQUASH.**
+*   **Focus on Goal:** Ask yourself: "Does this message help me achieve the current goal?" -> **KEEP.**
+
+**When to Squash:**
+1.  **Task Done:** Convert the messy process into one clean summary.
+2.  **Low Density:** You read 2000 lines but only found 1 error.
+
+**Safety:** Squashing is **LOSSLESS**.
+By using `backupTag`, you save the "Messy Branch" forever. You can always checkout the backup tag if the summary isn't enough.
+*   **Main Trunk:** Jump back to the summary.
+*   **Backup Tag:** Jump back to the raw details.
+
+### Fail Fast, Revert Faster
+If you fail 3 times:
+1.  **STOP.** Don't try a 4th time.
+2.  `context_checkout` back to the last safe tag.
+3.  Summarize the failure in the checkout message ("Tried X, failed because Y").
+4.  Try a new approach from the clean state.
+
+### After Checkout: Execute Next Step
+
+When `context_checkout` completes and injects a summary, you are in a **new context**.
+
+1. **READ** the injected summary carefully
+2. **EXECUTE** the `Next Step` from the summary - this is your new task.
+
+## Decision Matrix: When to Act
+
+| Situation | Action | Reason |
+| :--- | :--- | :--- |
+| **Starting Task** | `context_tag({ name: "<task-slug>-start" })` | Create a rollback point. |
+| **Research / Logs** | `context_checkout` (Squash) | **Process is Noise.** Read 2000 lines -> Keep result. |
+| **Messy Debugging** | **Squash w/ Backup** | **Cleanup.** The error logs are noise once fixed. |
+| **Task Done (Candidate)**| **Squash w/ Backup** | **Assume Success.** Summary is usually enough. Backup exists if not. |
+| **Goal Shift** | `context_checkout` (Squash) | Old context is irrelevant. |
+| **Drift (some steps w/o tag)** | **Tag (Milestone)** | Maintain the skeleton. Don't fly blind. |
+
+## The "Context Health" Check
+
+If you cannot answer these, run `context_log`:
+
+| Question | Answer Source |
+| :--- | :--- |
+| **Where is the skeleton?** | The sequence of `tag`s in the log. |
+| **Is this history useful?** | If "No" -> **SQUASH IT.** |
+| **Am I in a loop?** | Repeated entries in the graph. |
+
+## Good Checkout Messages
+
+The `message` is your lifeline to your past self.
+A good message preserves critical context that would otherwise be lost.
+
+Structure: `[Key Finding/Status] + [Reason] + [Important Changes] + [Next Step]`
+
+*   **Key Finding/Status**: What did you discover or complete? Include specific numbers, errors, or outcomes.
+*   **Reason**: Why are you branching/moving? (e.g., "Task complete", "Approach failed", "Need raw logs")
+*   **Important Changes**: What files or logic have been modified? (This checkout only resets *conversation history*, NOT disk files, so you must remember what changed.)
+*   **Next Step**: What should you do immediately after this squash? Be specific. (e.g., "Wait for user feedback", "Implement the recommended fix", "Revert file X and try approach Y")
+
+Examples:
+
+*   *Good (Resetting after failure)*: "Recursive parser hit stack overflow at depth 8000. Switching to iterative. **Reason**: Stack limit reached. **Important Changes**: Modified `utils/recursion.ts`. **Next Step**: Inform user of the failure and propose iterative approach."
+*   *Good (Cleaning up)*: "Auth module complete: JWT + OAuth2 + RBAC. 23 tests passing. **Reason**: Task done, cleaning context. **Important Changes**: Created `auth/`, modified `routes.ts` and `middleware.ts`. **Next Step**: Report completion to user, ask if they want to review or test."
+*   *Bad*: "Switching context." (Too vague - you will forget why)
+*   *Bad*: "Done." (What is done? What should you do next?)
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+| :--- | :--- |
+| **Blind Tagging** (Tagging without looking) | **Check** (`context_log`) to avoid duplicates or tagging noise. |
+| **Over-Tagging** (Tagging every step) | **Tag** only major phase changes (`start`, `milestone`). |
+| **Hoard** (Keep all history "just in case") | **Squash** low-density history (research, logs). |
+| **Panic** (Apologize repeatedly for errors) | **Revert** (`context_checkout`) to before the error. |
+| **Blind Checkout** (Guessing IDs) | **Look** (`context_log`) first to get valid IDs. |
+| **Vague Summaries** ("Done", "Fixed") | **Detailed Summaries** ("Found bug in line 40. Fixed with patch X.") |
+| **Generic Tag Names** (`task-start`, `phase-1`) | **Semantic Names** (`auth-jwt-start`, `db-schema-plan`) |
+| **Missing Next Step** in checkout message | **Always specify** what to do after squash (e.g., "Wait for user", "Implement fix X") |
+
+## Recipes (Copy-Paste)
+
+### 1. The "Miner" (Immediate Squash)
+**Goal:** Pure information gathering (Reading files, Searching web).
+**Why:** The *process* of searching is irrelevant. Only the *result* matters.
+
+**Example Task:** Analyzing error logs to find root cause of timeout
+
+```javascript
+// 1. Tag BEFORE starting the noisy work (use descriptive name)
+context_tag({ name: "timeout-analysis-start" });
+
+// ... (Read 5 log files, search 3 docs, find DB connection pool exhaustion) ...
+
+// 2. Squash IMMEDIATELY. Do not wait for user.
+context_checkout({
+  target: "timeout-analysis-start",
+  message: "Found DB connection pool exhaustion as root cause (pool size: 10, peak load: 1000 req/s). Recommended fix: increase to 50. **Reason**: Context cleanup after research. **Important Changes**: None (read-only). **Next Step**: Report findings to user and await approval to implement fix.",
+  backupTag: "timeout-analysis-raw-history" // Safety backup
+});
+context_tag({ name: "timeout-analysis-done" });
+```
+
+### 2. The "Candidate" (Wait for Confirmation)
+**Goal:** You finished a complex task.
+**Why:** The history is noisy. The result is clean.
+**Safety:** We create a backup tag automatically.
+
+**Example Task:** Implementing OAuth login flow
+
+```javascript
+// Squash to Summary (Optimistic Cleanup)
+context_checkout({
+  target: "oauth-impl-start", // Squash range: Start -> Now
+  message: "OAuth2 flow implemented with PKCE, Google + GitHub providers. All 12 tests passing. **Reason**: Task complete, cleaning up. **Important Changes**: Created `auth/oauth.ts`, modified `routes.ts`, `config.ts`. **Next Step**: Report completion to user, summarize what was implemented.",
+  backupTag: "oauth-impl-raw-history"
+});
+context_tag({ name: "oauth-impl-candidate" });
+```
+
+### 3. The "Undo" (Revert Squash)
+**Goal:** User asks about a detail you squashed away.
+**Action:** Jump back to the backup tag.
+
+**Example Task:** Reviewing OAuth implementation details
+
+```javascript
+// Jump back to the raw history
+context_checkout({
+  target: "oauth-impl-raw-history",
+  message: "Reviewing token refresh logic - user reports 401 after 15 min idle. Suspect refresh token not firing. **Reason**: Need raw logs to trace the bug. **Important Changes**: None. **Next Step**: Re-read token refresh implementation and identify the bug."
+});
+context_tag({ name: "oauth-review-start" });
+```
+
+### 4. Branching (Alternative Approach)
+**Scenario:** Method A failed (and was squashed). You want to try Method B from the clean state.
+**Action:** Checkout the start point.
+
+**Example Task:** Fixing memory leak - trying different approaches
+
+```javascript
+// Method A (weak references) failed, trying Method B (object pooling)
+context_checkout({
+  target: "memory-leak-fix-start", 
+  message: "WeakRef approach failed: objects GC'd within 30s (expected: 5min). Cache hit rate dropped from 95% to 12%. **Reason**: Switching to object pooling approach. **Important Changes**: `CacheManager.ts` modified (will revert). **Next Step**: Revert `CacheManager.ts` changes and implement object pooling strategy."
+});
+context_tag({ name: "memory-leak-pool-approach-start" });
+```
+
+### 5. The "Undo" (Failed Attempt)
+You tried to fix a bug but broke everything.
+**Goal:** Clean up a failed path.
+
+**Example Task:** Fixing race condition in async handler
+
+```javascript
+// Attempted mutex-based fix, but introduced deadlock
+context_checkout({
+  target: "race-condition-fix-start",
+  message: "Mutex caused deadlock: Thread A holds mutex, awaits callback; callback needs mutex held by B; B waits for A. Circular wait detected. **Reason**: Trying lock-free CAS approach next. **Important Changes**: `AsyncQueue.ts` lines 70-90 modified (backup saved). **Next Step**: Revert `AsyncQueue.ts` and implement lock-free compare-and-swap approach.",
+  backupTag: "race-condition-mutex-fail" // Save the failure for reference
+});
+context_tag({ name: "race-condition-lockfree-start" });
+```

package/skills/figma-implement-design/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: figma-implement-design
+description: Translates Figma designs into production-ready application code with 1:1 visual fidelity. Use when implementing UI code from Figma files, when user mentions "implement design", "generate code", "implement component", provides Figma URLs, or asks to build components matching Figma specs. For Figma canvas writes via `use_figma`, use `figma-use`.
+---
+
+# Implement Design
+
+## Overview
+
+This skill provides a structured workflow for translating Figma designs into production-ready code with pixel-perfect accuracy. It ensures consistent integration with the Figma MCP server, proper use of design tokens, and 1:1 visual parity with designs.
+
+## Skill Boundaries
+
+- Use this skill when the deliverable is code in the user's repository.
+- If the user asks to create/edit/delete nodes inside Figma itself, switch to [figma-use](../figma-use/SKILL.md).
+- If the user asks to build or update a full-page screen in Figma from code or a description, switch to [figma-generate-design](../figma-generate-design/SKILL.md).
+- If the user asks only for Code Connect mappings, switch to [figma-code-connect-components](../figma-code-connect-components/SKILL.md).
+- If the user asks to author reusable agent rules (`CLAUDE.md`/`AGENTS.md`), switch to [figma-create-design-system-rules](../figma-create-design-system-rules/SKILL.md).
+
+## Prerequisites
+
+- Figma MCP server must be connected and accessible
+- User must provide a Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+  - `:fileKey` is the file key
+  - `1-2` is the node ID (the specific component or frame to implement)
+- **OR** when using `figma-desktop` MCP: User can select a node directly in the Figma desktop app (no URL required)
+- Project should have an established design system or component library (preferred)
+
+## Required Workflow
+
+**Follow these steps in order. Do not skip steps.**
+
+### Step 1: Get Node ID
+
+#### Option A: Parse from Figma URL
+
+When the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.
+
+**URL format:** `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+
+**Extract:**
+
+- **File key:** `:fileKey` (the segment after `/design/`)
+- **Node ID:** `1-2` (the value of the `node-id` query parameter)
+
+**Note:** When using the local desktop MCP (`figma-desktop`), `fileKey` is not passed as a parameter to tool calls. The server automatically uses the currently open file, so only `nodeId` is needed.
+
+**Example:**
+
+- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`
+- File key: `kL9xQn2VwM8pYrTb4ZcHjF`
+- Node ID: `42-15`
+
+#### Option B: Use Current Selection from Figma Desktop App (figma-desktop MCP only)
+
+When using the `figma-desktop` MCP and the user has NOT provided a URL, the tools automatically use the currently selected node from the open Figma file in the desktop app.
+
+**Note:** Selection-based prompting only works with the `figma-desktop` MCP server. The remote server requires a link to a frame or layer to extract context. The user must have the Figma desktop app open with a node selected.
+
+### Step 2: Fetch Design Context
+
+Run `get_design_context` with the extracted file key and node ID.
+
+```
+get_design_context(fileKey=":fileKey", nodeId="1-2")
+```
+
+This provides the structured data including:
+
+- Layout properties (Auto Layout, constraints, sizing)
+- Typography specifications
+- Color values and design tokens
+- Component structure and variants
+- Spacing and padding values
+
+**If the response is too large or truncated:**
+
+1. Run `get_metadata(fileKey=":fileKey", nodeId="1-2")` to get the high-level node map
+2. Identify the specific child nodes needed from the metadata
+3. Fetch individual child nodes with `get_design_context(fileKey=":fileKey", nodeId=":childNodeId")`
+
+### Step 3: Capture Visual Reference
+
+Run `get_screenshot` with the same file key and node ID for a visual reference.
+
+```
+get_screenshot(fileKey=":fileKey", nodeId="1-2")
+```
+
+This screenshot serves as the source of truth for visual validation. Keep it accessible throughout implementation.
+
+### Step 4: Download Required Assets
+
+Download any assets (images, icons, SVGs) returned by the Figma MCP server.
+
+**IMPORTANT:** Follow these asset rules:
+
+- If the Figma MCP server returns a `localhost` source for an image or SVG, use that source directly
+- DO NOT import or add new icon packages - all assets should come from the Figma payload
+- DO NOT use or create placeholders if a `localhost` source is provided
+- Assets are served through the Figma MCP server's built-in assets endpoint
+
+### Step 5: Translate to Project Conventions
+
+Translate the Figma output into this project's framework, styles, and conventions.
+
+**Key principles:**
+
+- Treat the Figma MCP output (typically React + Tailwind) as a representation of design and behavior, not as final code style
+- Replace Tailwind utility classes with the project's preferred utilities or design system tokens
+- Reuse existing components (buttons, inputs, typography, icon wrappers) instead of duplicating functionality
+- Use the project's color system, typography scale, and spacing tokens consistently
+- Respect existing routing, state management, and data-fetch patterns
+
+### Step 6: Achieve 1:1 Visual Parity
+
+Strive for pixel-perfect visual parity with the Figma design.
+
+**Guidelines:**
+
+- Prioritize Figma fidelity to match designs exactly
+- Avoid hardcoded values - use design tokens from Figma where available
+- When conflicts arise between design system tokens and Figma specs, prefer design system tokens but adjust spacing or sizes minimally to match visuals
+- Follow WCAG requirements for accessibility
+- Add component documentation as needed
+
+### Step 7: Validate Against Figma
+
+Before marking complete, validate the final UI against the Figma screenshot.
+
+**Validation checklist:**
+
+- [ ] Layout matches (spacing, alignment, sizing)
+- [ ] Typography matches (font, size, weight, line height)
+- [ ] Colors match exactly
+- [ ] Interactive states work as designed (hover, active, disabled)
+- [ ] Responsive behavior follows Figma constraints
+- [ ] Assets render correctly
+- [ ] Accessibility standards met
+
+## Implementation Rules
+
+### Component Organization
+
+- Place UI components in the project's designated design system directory
+- Follow the project's component naming conventions
+- Avoid inline styles unless truly necessary for dynamic values
+
+### Design System Integration
+
+- ALWAYS use components from the project's design system when possible
+- Map Figma design tokens to project design tokens
+- When a matching component exists, extend it rather than creating a new one
+- Document any new components added to the design system
+
+### Code Quality
+
+- Avoid hardcoded values - extract to constants or design tokens
+- Keep components composable and reusable
+- Add TypeScript types for component props
+- Include JSDoc comments for exported components
+
+## Examples
+
+### Example 1: Implementing a Button Component
+
+User says: "Implement this Figma button component: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
+
+**Actions:**
+
+1. Parse URL to extract fileKey=`kL9xQn2VwM8pYrTb4ZcHjF` and nodeId=`42-15`
+2. Run `get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")`
+3. Run `get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` for visual reference
+4. Download any button icons from the assets endpoint
+5. Check if project has existing button component
+6. If yes, extend it with new variant; if no, create new component using project conventions
+7. Map Figma colors to project design tokens (e.g., `primary-500`, `primary-hover`)
+8. Validate against screenshot for padding, border radius, typography
+
+**Result:** Button component matching Figma design, integrated with project design system.
+
+### Example 2: Building a Dashboard Layout
+
+User says: "Build this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
+
+**Actions:**
+
+1. Parse URL to extract fileKey=`pR8mNv5KqXzGwY2JtCfL4D` and nodeId=`10-5`
+2. Run `get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` to understand the page structure
+3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs
+4. Run `get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")` for each major section
+5. Run `get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` for the full page
+6. Download all assets (logos, icons, charts)
+7. Build layout using project's layout primitives
+8. Implement each section using existing components where possible
+9. Validate responsive behavior against Figma constraints
+
+**Result:** Complete dashboard matching Figma design with responsive layout.
+
+## Best Practices
+
+### Always Start with Context
+
+Never implement based on assumptions. Always fetch `get_design_context` and `get_screenshot` first.
+
+### Incremental Validation
+
+Validate frequently during implementation, not just at the end. This catches issues early.
+
+### Document Deviations
+
+If you must deviate from the Figma design (e.g., for accessibility or technical constraints), document why in code comments.
+
+### Reuse Over Recreation
+
+Always check for existing components before creating new ones. Consistency across the codebase is more important than exact Figma replication.
+
+### Design System First
+
+When in doubt, prefer the project's design system patterns over literal Figma translation.
+
+## Common Issues and Solutions
+
+### Issue: Figma output is truncated
+
+**Cause:** The design is too complex or has too many nested layers to return in a single response.
+**Solution:** Use `get_metadata` to get the node structure, then fetch specific nodes individually with `get_design_context`.
+
+### Issue: Design doesn't match after implementation
+
+**Cause:** Visual discrepancies between the implemented code and the original Figma design.
+**Solution:** Compare side-by-side with the screenshot from Step 3. Check spacing, colors, and typography values in the design context data.
+
+### Issue: Assets not loading
+
+**Cause:** The Figma MCP server's assets endpoint is not accessible or the URLs are being modified.
+**Solution:** Verify the Figma MCP server's assets endpoint is accessible. The server serves assets at `localhost` URLs. Use these directly without modification.
+
+### Issue: Design token values differ from Figma
+
+**Cause:** The project's design system tokens have different values than those specified in the Figma design.
+**Solution:** When project tokens differ from Figma values, prefer project tokens for consistency but adjust spacing/sizing to maintain visual fidelity.
+
+## Understanding Design Implementation
+
+The Figma implementation workflow establishes a reliable process for translating designs to code:
+
+**For designers:** Confidence that implementations will match their designs with pixel-perfect accuracy.
+**For developers:** A structured approach that eliminates guesswork and reduces back-and-forth revisions.
+**For teams:** Consistent, high-quality implementations that maintain design system integrity.
+
+By following this workflow, you ensure that every Figma design is implemented with the same level of care and attention to detail.
+
+## Additional Resources
+
+- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
+- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
+- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)

package/skills/orchestrator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: orchestrator
+description: Top-level session orchestration rules — subagent routing, context hygiene, and implementation discipline. Not intended for subagents.
+---
+
+# Session Orchestration
+
+## Understand Before You Build
+
+THE MOST IMPORTANT THING: YOU DON'T ASSUME, YOU VERIFY - YOU GROUND YOUR COMMUNICATION TO THE USER IN EVIDENCE-BASED FACTS  
+DON'T JUST RELY ON WHAT YOU KNOW. YOU FOLLOW YOUR KNOWLEDGE BUT ALWAYS CHECK YOUR WORK AND YOUR ASSUMPTIONS TO BACK IT UP WITH HARD, UP-TO-DATE DATA THAT YOU LOOKED UP YOURSELF
+
+Never start implementing until you are **100% certain** of what needs to be done. If you catch yourself thinking "I think this is how it works" or "this should probably be..." — STOP. That's a signal to ask or scout, not to start coding.
+
+**Fill knowledge gaps with:**
+- **`ask-user`** — ambiguous requirements, preference between approaches, any detail that would materially change the implementation. One question per call. Never guess what the user wants.
+- **`subagent` scout** — how the codebase works, what patterns exist, which files are involved. Tools: `read`, `grep`, `find`, `ls`. Fast and cheap (Haiku).
+- **`subagent` researcher** — API docs, library behavior, migration guides, external knowledge. Tools: `web_search`, `web_fetch`.
+- **`subagent` worker** — isolated code changes. Tools: `read`, `write`, `edit`, `safe_bash`. Use when the change is well-specified and doesn't need back-and-forth.
+
+**Before any non-trivial implementation, you must know:**
+- Exactly what the change does (confirmed with user)
+- Exactly which files are involved (confirmed with scout)
+- Exactly which APIs/patterns to use (confirmed with scout or researcher)
+
+If any of those are fuzzy, you're not ready to implement.
+
+## Context Hygiene
+
+Your context window is a finite, non-renewable resource. Every file you read directly stays in your context forever.
+
+**Default to scouts for exploration.** If the task involves understanding how something works across multiple files, finding where something is defined/used, investigating a bug, or checking whether a change is safe — **send a scout.** You get a concise summary back. Your context stays clean.
+
+**Use direct reads/greps ONLY when:**
+- You need to verify 1-2 lines right before making an edit
+- You already know exactly what file and what you're looking for
+- The answer is a single grep hit
+
+**Never explore a codebase by reading files yourself.** That's what scouts are for.
+
+**Use parallel mode** (`tasks[]`) when dispatching multiple independent subagents — e.g. a scout investigating file structure while a researcher looks up API docs. Max 4 concurrent.
+
+### When NOT to Use Subagents
+
+- **Tiny targeted edits** where you already know the exact file and line — just do it directly.
+- **Anything requiring back-and-forth with the user** — subagents can't ask questions, they run to completion.
+- **When you already scouted** — don't re-scout the same code. Use the context you have.
+- **Subagents have NO context from your conversation** — include ALL necessary context in the task description. File paths, patterns, constraints, expected output format.
+
+
+## Implementation Discipline
+
+### Keep It Simple
+
+Only make changes that are directly requested or clearly necessary. Don't add features, refactoring, or "improvements" beyond what was asked. Three similar lines of code is better than a premature abstraction. Prefer editing existing files over creating new ones.
+
+### Be Direct
+
+Prioritize technical accuracy over validation. No "Great question!" or "You're absolutely right!" — if the user's approach has issues, say so respectfully. Honest feedback over false agreement.
+
+### Investigate Before Fixing
+
+When something breaks, don't guess — investigate first. No fixes without understanding the root cause.
+
+1. **Observe** — read error messages, check full stack traces
+2. **Hypothesize** — form a theory based on evidence
+3. **Verify** — test the hypothesis before implementing a fix
+4. **Fix** — target the root cause, not the symptom
+
+If you're making random changes hoping something works, you don't understand the problem yet.
+
+### Verify Before Claiming Done
+
+Never claim success without proving it. Run the actual command, show the output.
+
+| Claim | Requires |
+|-------|----------|
+| "Tests pass" | Run tests, show output |
+| "Build succeeds" | Run build, show exit 0 |
+| "Bug fixed" | Reproduce original issue, show it's gone |
+| "Script works" | Run it, show expected output |
+

package/skills/s-help/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: s-help
+description: Explain Sling (s:) slash commands registered in this repo (e.g. /s:footer, /s:skill-manager), where they live, and how to use/extend them.
+---
+
+# Sling Help (s: commands)
+
+This skill explains the **registered Sling `/s:` slash commands** available in this repository. If a requested command is not registered, respond with an appropriate error message indicating the command is not found.
+
+## Primary data source
+
+Use the curated docs in:
+
+- `skills/s-help/resources/`
+
+This folder contains per-command Markdown pages plus a `commands.json` index. When the user asks "what does `/s:...` do?", answer by **reading the matching resource doc** and summarizing it. Fall back to code search only if the resource doc is missing, incomplete, or incorrect (not merely older than the code).
+
+## What this skill does
+
+1. **First priority**: verify the command in the registration site, which is the canonical list.
+2. **Second priority**: answer from resources using `skills/s-help/resources/<command>.md`.
+3. **Third priority**: use code search only if the resource doc is missing, incomplete, or incorrect.
+4. **Handle unregistered commands**: if a command is not registered, respond with an appropriate error message indicating the command is not found.
+5. Provide:
+   - command name (`/s:<name>`)
+   - description
+   - usage/syntax (args/options if any)
+   - notes/caveats
+   - implementation file(s)
+
+## Notes / Conventions
+
+- The **registration site** is canonical; resource docs are the preferred explanation source for registered commands.
+- If commands have keybindings or configuration, mention where they are configured.
+
+## Output template
+
+When invoked, respond with:
+
+1. A short intro sentence.
+2. The command table.
+3. A "Where to add a new command" section, pointing to the registry file(s).

package/skills/s-help/resources/README.md

@@ -0,0 +1,23 @@
+# slinghelp resources
+
+This directory contains detailed documentation for Slingshot-specific slash commands that use the `/s:` namespace.
+
+Source-of-truth for these commands is in `slingshot/src/**` (they are registered via `pi.registerCommand("s:<name>", ...)`).
+
+Files:
+
+- `commands.json` — machine-readable index (command → description/source)
+- `s-footer.md`
+- `s-stash-history.md`
+- `s-bash-mode.md`
+- `s-bash-reset.md`
+- `s-filechanges.md`
+- `s-filechanges-accept.md`
+- `s-filechanges-decline.md`
+- `s-context.md`
+- `s-acm.md`
+- `s-promptlib.md`
+- `s-skills-manager.md`
+
+Notes:
+- Commands not starting with `/s:` (e.g. `/refresh-token`, `/vibe`) are intentionally excluded from this directory.