@docyt/panda-cli 0.1.1

package/QUICKSTART.md

@@ -0,0 +1,153 @@
+# Quick Start Guide
+
+## For Package Maintainers (Publishing)
+
+### First-time Setup
+
+1. **Navigate to the CLI directory**:
+   ```bash
+   cd ~/Project/docyt/bb/reports-auto-test/docyt-panda-oncall-cli
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Test locally** (optional):
+   ```bash
+   npm link
+   cd ~/Project/docyt/bb
+   docyt-oncall list
+   ```
+
+4. **Login to npm** (one-time):
+   ```bash
+   npm login
+   ```
+
+5. **Publish to npm**:
+   ```bash
+   npm publish --access public
+   ```
+
+### Publishing Updates
+
+1. **Update assets** (add/modify files in `assets/`):
+   ```bash
+   # Add new command
+   cp ~/.cursor/commands/new-command.md assets/commands/
+   
+   # Or update existing
+   cp ~/.cursor/commands/docyt-panda-oncall-issues.md assets/commands/
+   ```
+
+2. **Bump version**:
+   ```bash
+   npm version patch  # for bug fixes: 1.0.0 -> 1.0.1
+   npm version minor  # for new features: 1.0.1 -> 1.1.0
+   npm version major  # for breaking changes: 1.1.0 -> 2.0.0
+   ```
+
+3. **Publish**:
+   ```bash
+   npm publish
+   ```
+
+---
+
+## For End Users (Installing/Using)
+
+### Installation
+
+From your project workspace (e.g., `~/Project/docyt/bb`):
+
+```bash
+# Install all tools
+npx @docyt/panda-oncall-cli install
+
+# Or install specific types
+npx @docyt/panda-oncall-cli install --commands
+```
+
+### Checking for Updates
+
+```bash
+# See what's available
+npx @docyt/panda-oncall-cli list
+
+# Check differences
+npx @docyt/panda-oncall-cli diff
+
+# Preview upgrade
+npx @docyt/panda-oncall-cli upgrade --preview
+
+# Upgrade
+npx @docyt/panda-oncall-cli upgrade
+```
+
+### Daily Usage
+
+After installation, the Cursor commands are available in Cursor:
+- `/docyt-panda-oncall-issues` - Scan Slack for on-call issues
+
+---
+
+## Troubleshooting
+
+### "Could not find workspace root"
+Make sure you run the command from within a Git repository or Cursor workspace.
+
+### "Command not found: docyt-oncall"
+Use `npx @docyt/panda-oncall-cli` instead, or run `npm link` if testing locally.
+
+### Permission Issues
+The CLI needs write access to `.cursor/` directory in your workspace.
+
+---
+
+## Development Workflow
+
+### Adding a New Command
+
+1. **Create/update command in your workspace**:
+   ```bash
+   # Edit in Cursor or any editor
+   vim ~/.cursor/commands/my-new-command.md
+   ```
+
+2. **Copy to CLI assets**:
+   ```bash
+   cp ~/.cursor/commands/my-new-command.md ~/Project/docyt/bb/reports-auto-test/docyt-panda-oncall-cli/assets/commands/
+   ```
+
+3. **Bump version and publish**:
+   ```bash
+   cd ~/Project/docyt/bb/reports-auto-test/docyt-panda-oncall-cli
+   npm version minor
+   npm publish
+   ```
+
+4. **Users upgrade**:
+   ```bash
+   npx @docyt/panda-oncall-cli upgrade
+   ```
+
+---
+
+## Testing Before Publishing
+
+```bash
+# Link for local testing
+cd ~/Project/docyt/bb/reports-auto-test/docyt-panda-oncall-cli
+npm link
+
+# Test in another project
+cd ~/Project/docyt/bb
+docyt-oncall install --commands
+docyt-oncall list
+docyt-oncall upgrade --preview
+
+# Unlink when done
+npm unlink -g @docyt/panda-oncall-cli
+```

package/README.md

@@ -0,0 +1,201 @@
+# Docyt Panda CLI
+
+A CLI tool for installing and managing Docyt Team Panda development tools, including Cursor commands, skills, and rules.
+
+## Quick Start
+
+### Install Globally (Recommended)
+
+```bash
+npm install -g @docyt/panda-cli
+```
+
+Now you can run `panda-cli` from anywhere!
+
+### Usage
+
+```bash
+# Go to your project
+cd ~/Project/docyt/bb
+
+# Install to current directory
+panda-cli install
+```
+
+**That's it!** The command will be installed to `.cursor/commands/` in your current directory.
+
+## Installation Location
+
+Files are installed to your **current directory** (or specified path):
+- **Commands**: `[current-dir]/.cursor/commands/`
+- **Skills**: `[current-dir]/.cursor/skills/`
+- **Rules**: `[current-dir]/.cursor/rules/`
+- **Manifest**: `[current-dir]/.cursor/.panda-cli-manifest.json`
+
+Example: If you run from `/Users/sheng/Project/docyt/bb`:
+```
+/Users/sheng/Project/docyt/bb/.cursor/commands/docyt-panda-oncall-issues.md
+```
+
+## Commands
+
+### `install` - Install Tools
+
+```bash
+# Install to current directory
+panda-cli install
+
+# Install to specific directory
+panda-cli install /path/to/project
+
+# Install only commands
+panda-cli install --commands
+
+# Install only skills
+panda-cli install --skills
+
+# Install only rules
+panda-cli install --rules
+
+# Install everything (default)
+panda-cli install --all
+```
+
+### `list` - List Tools
+
+List all installed and available tools.
+
+```bash
+panda-cli list
+```
+
+### `upgrade` - Upgrade Tools
+
+Upgrade installed tools to the latest version.
+
+```bash
+# Preview changes without installing
+panda-cli upgrade --preview
+
+# Upgrade (will prompt for local changes)
+panda-cli upgrade
+
+# Force upgrade (overwrite all local changes)
+panda-cli upgrade --force
+```
+
+### `diff` - Show Differences
+
+Show differences between your local version and the latest available.
+
+```bash
+panda-cli diff
+```
+
+## What Gets Installed
+
+### Cursor Commands
+
+Currently includes:
+- `docyt-panda-oncall-issues.md` - Scan Slack channels for Team Panda on-call issues
+
+More commands will be added over time.
+
+### Cursor Skills
+
+Coming soon...
+
+### Cursor Rules
+
+Coming soon...
+
+## How It Works
+
+1. **Simple Detection**: Uses current directory (or specified path)
+2. **Installation**: Copies files from the CLI package to your workspace
+3. **Tracking**: Creates a manifest file (`.cursor/.panda-cli-manifest.json`) to track versions
+4. **Smart Upgrades**: Detects local changes and prompts before overwriting
+
+## Manifest File
+
+The CLI creates a manifest file at `.cursor/.panda-cli-manifest.json` to track:
+- Installed version
+- Installation/upgrade timestamps
+- List of installed assets
+- Local customizations
+
+Example manifest:
+```json
+{
+  "version": "0.1.1",
+  "installed": "2026-02-01T08:00:00Z",
+  "assets": {
+    "commands": ["docyt-panda-oncall-issues.md"],
+    "skills": [],
+    "rules": []
+  },
+  "customizations": {}
+}
+```
+
+## Alternative: Use with npx (No Install)
+
+You can also use the CLI without installing globally:
+
+```bash
+# Install to current directory
+npx @docyt/panda-cli install
+
+# List tools
+npx @docyt/panda-cli list
+
+# Upgrade
+npx @docyt/panda-cli upgrade
+```
+
+**Note**: `npx` runs slower than global install because it downloads each time.
+
+## Development
+
+### Local Development
+
+```bash
+# Install dependencies
+cd docyt-panda-oncall-cli
+npm install
+
+# Make CLI available globally for testing
+npm link
+
+# Now you can run it from anywhere
+panda-cli list
+```
+
+### Publishing Updates
+
+```bash
+# Bump version
+npm version patch  # or minor, major
+
+# Publish to npm
+npm publish --access public
+```
+
+### Adding New Assets
+
+1. Add files to `assets/commands/`, `assets/skills/`, or `assets/rules/`
+2. Bump the version in `package.json`
+3. Publish to npm
+4. Users run `panda-cli upgrade` to get updates
+
+## Requirements
+
+- Node.js >= 14.0.0
+
+## License
+
+ISC
+
+## Support
+
+For issues or questions, contact Team Panda.

package/assets/commands/docyt-panda-oncall-issues.md

@@ -0,0 +1,249 @@
+---
+name: /docyt-panda-oncall-issues
+id: docyt-panda-oncall-issues
+category: On-call
+description: Retrieve Slack threads from Team Panda and customer-issue channels and highlight unresolved issues
+---
+
+Retrieve threads from Team Panda and customer-issue Slack channels, fetch thread replies, and determine whether each thread has been processed (conclusion/fix/solution reached). Highlight threads with no resolution so on-call can respond quickly. Post the report to **#panda-new-work** with a message starting with "My human asked to generate this report". Designed to be extended later with triage, Jira creation, and assignment.
+
+**Input**: Optional time range (e.g. "last 3 days", "last 7 days"). Default: last 3 days. Optionally specify channel(s) to limit scope.
+
+---
+
+## Reference: Channels and Team Panda Scope
+
+**Team Panda channels** (scrum team, panda-specific issues):
+
+| Channel name (Slack) | Purpose |
+|----------------------|--------|
+| #team-panda-leadership | Leadership / decisions |
+| #team-panda | General team panda |
+
+**Customer-issue channels** (figure out Team Panda scope, respond quickly):
+
+| Channel name (Slack) | Purpose |
+|---------------------|--------|
+| #product-questions | Product questions from customers/support |
+| #product_feedback | Product feedback |
+| #production-errors | Production errors / incidents |
+
+**Team Panda is responsible for** features implemented in these services:
+
+- dashboards-service
+- reports-service
+- report-dc-service
+- report-btf-service
+- report-helper-service
+
+When reviewing customer-issue channels, treat a thread as **in Team Panda scope** if it clearly relates to: dashboards, reports, report builder, report data, report export, or any of the above services. If unclear, still include the thread in the report but mark scope as "Unclear"; on-call can triage.
+
+## Steps
+
+1. **Ensure Slack MCP is available**
+
+   - Confirm the Slack MCP server is enabled and tools are listed (e.g. `channels_list`, `conversations_history`, `conversations_replies`).
+   - If Slack MCP is not available, report: "Slack MCP is not available. Enable the Slack MCP server in Cursor Settings → MCP and ensure tokens are configured." Then stop.
+
+2. **Resolve channel identifiers**
+
+   - Channels to query (use these names with `#` for Slack API):
+     - Team Panda: `#team-panda-leadership`, `#team-panda`
+     - Customer-issue: `#product-questions`, `#product_feedback`, `#production-errors`
+   - If needed, use `channels_list` with `channel_types: "public_channel,private_channel"` to map names to channel IDs (e.g. `Cxxxxxxxxxx`). The Slack MCP accepts channel name (e.g. `#product-questions`) or ID.
+
+3. **Fetch recent messages (and thread parents) from each channel**
+
+   - Parse input for time range; default to **3 days** (e.g. `limit: "3d"`). If user said "last 7 days", use `limit: "7d"`.
+   - If the user specified channel(s) (e.g. "only #product-questions"), query only those channels; otherwise query all 5 channels.
+   - For each channel to query, call **conversations_history**:
+     - `channel_id`: channel name with `#` (e.g. `#product-questions`) or resolved ID
+     - `limit`: chosen time range (e.g. `"3d"`)
+   - Collect all messages. Note which messages have a **thread_ts** (they are replies) and which are **thread parents** (same message has `ts`; replies will reference this `ts` as `thread_ts`). Build a list of **thread roots**: unique `(channel_id, thread_ts)` where `thread_ts` is the parent message `ts` of a thread (messages that have at least one reply, or that you will fetch replies for).
+
+4. **Fetch full thread for each thread root**
+
+   - For each thread root `(channel_id, thread_ts)`:
+     - Call **conversations_replies** with `channel_id`, `thread_ts`, and same `limit` (e.g. `"3d"`) to get all replies in the thread.
+   - If a channel has no threads (only top-level messages), treat each top-level message as a single-message "thread" for consistency (no need to call replies).
+
+5. **Classify each thread: processed vs not processed**
+
+   For each thread (parent + replies), decide:
+
+   **Processed (resolution reached)** if any reply or the parent clearly indicates one or more of:
+
+   - A **fix** (e.g. "fixed", "deployed", "patch applied")
+   - A **solution** or **workaround** (e.g. "workaround: ...", "you can do X")
+   - A **conclusion** (e.g. "resolved", "closed", "not a bug", "by design")
+   - **Ownership/tracking** (e.g. "created Jira X", "assigned to Y", "tracking in Z")
+   - **Clear next step with timeline** (e.g. "we'll ship this next week", "engineering is investigating")
+
+   **Not processed (no resolution)** if:
+
+   - No replies, or
+   - Replies only ask for more info, acknowledge, or discuss without any fix/solution/conclusion/ticket/timeline
+
+   **Inconclusive** if:
+
+   - Thread is long or ambiguous and you cannot tell; mark as "Needs review".
+
+   When in doubt, mark as **not processed** so on-call can triage.
+
+6. **Identify Team Panda scope for customer-issue threads**
+
+   For threads in **#product-questions**, **#product_feedback**, **#production-errors**:
+
+   - If the topic clearly involves **dashboards, reports, report builder, report data, report export**, or any of **dashboards-service, reports-service, report-dc-service, report-btf-service, report-helper-service**, mark scope: **Team Panda**.
+   - If clearly unrelated (e.g. auth, billing, another team’s service), mark scope: **Other** (still list in report but note).
+   - If unclear, mark scope: **Unclear**.
+
+   Threads in Team Panda channels (#team-panda-leadership, #team-panda) are **Team Panda** by default.
+
+7. **Build and present the report**
+
+   Use the **Output format** below. Always include:
+
+   - **Unresolved / not processed** threads first (highlighted).
+     - **CRITICAL**: Sort so Team Panda scope issues appear FIRST within each section
+   - Then **Needs review** (inconclusive).
+     - Also sort Team Panda scope first
+   - Then **Processed** (resolved) for reference.
+   - For each thread: channel, short summary, scope (Team Panda / Other / Unclear).
+   - For **Unresolved/Needs Review**: Add a short "State" field (2-5 words) describing current status: e.g., "No replies yet", "Awaiting confirmation", "Not reproduced", "Checking with team", "FYI only—no action"
+   - For **Processed**: Add "Resolution" field describing how it was resolved: e.g., "Ticket created", "Workaround provided", "Fixed in PR", "User found solution", "Assigned to engineer"
+   - **Do NOT include thread_ts** in the output (not useful to humans reading the report)
+
+8. **Optional: suggest next actions**
+
+   For each **Unresolved** thread in Team Panda scope (or Unclear), suggest one of: "Triage", "Reply with ETA", "Create Jira", "Escalate". Do not execute these yet; the command only reports and highlights.
+
+9. **Post the report to #panda-new-work**
+
+   - Call **conversations_add_message** with:
+     - `channel_id`: `#panda-new-work`
+     - `payload`: A message that **starts with** "My human asked to generate report" (or "My human asked me to generate report"), then the full report in the Output format below (same content as presented in step 7).
+     - `content_type`: `text/plain` (use plain text; Slack will auto-format asterisks, underscores, emojis).
+   - **IMPORTANT**: Unicode box-drawing characters like `━` and `└` work in Slack. Emojis (🚨, ⚠️, ✅) work. Use these for visual formatting.
+   - If the payload exceeds Slack's message length limit (~40,000 characters), post a shortened version: the opening line, then the **Unresolved** section and suggested next steps, plus a one-line summary of Processed count (e.g. "Processed: N threads."). Optionally post the full Processed/Needs review sections in a follow-up reply in the same thread (using `thread_ts` of the first message if the tool supports replying in thread).
+   - After posting, confirm in the command output: "Report posted to #panda-new-work."
+
+---
+
+## Output format
+
+Format the Slack message for optimal readability:
+
+```
+My human asked to generate report.
+
+*Panda On-call Issues — [Time range]*
+
+*Channels scanned:* [comma-separated list with #]
+*Unresolved (needs attention):* [count]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🚨 *UNRESOLVED (No conclusion/fix/solution)*
+
+[IMPORTANT: List Team Panda scope threads FIRST, then Other/Unclear]
+
+[For Team Panda scope threads, use this format with 🔴 marker:]
+🔴 *[Channel]* | [Brief summary]
+   └ _Scope:_ *Team Panda* ⚠️
+   └ _State:_ [2-5 word current status]
+   └ _Suggested:_ [Triage / Reply with ETA / Create Jira]
+
+[For Other/Unclear scope threads, use this format:]
+• *[Channel]* | [Brief summary]
+   └ _Scope:_ [Other / Unclear]
+   └ _State:_ [2-5 word current status]
+   └ _Suggested:_ [Triage / Reply with ETA / Create Jira]
+
+[Blank line between each thread]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️ *NEEDS REVIEW (Inconclusive)*
+
+[IMPORTANT: List Team Panda scope threads FIRST, then Other/Unclear]
+
+[For Team Panda scope threads with 🔴 marker:]
+🔴 *[Channel]* | [Brief summary]
+   └ _Scope:_ *Team Panda* ⚠️
+   └ _State:_ [2-5 word current status]
+
+[For Other/Unclear scope threads:]
+• *[Channel]* | [Brief summary]
+   └ _Scope:_ [Other / Unclear]
+   └ _State:_ [2-5 word current status]
+
+[Blank line between each thread]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ *PROCESSED (Resolution reached)*
+
+[For each processed thread, keep brief:]
+• *[Channel]* | [Brief summary]
+   └ _Resolution:_ [How resolved in 3-8 words]
+
+[Blank line between threads if many, otherwise can be compact]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+*Summary:* [X unresolved (Y Team Panda), Z needs review, W processed across N channels]
+```
+
+**Formatting guidelines:**
+- **CRITICAL SORTING**: Team Panda scope issues appear FIRST in Unresolved and Needs Review sections
+- **Team Panda highlighting**: Use `🔴` red circle emoji at start of line + bold "Team Panda" text with ⚠️ emoji
+- **State field** (Unresolved/Needs Review): 2-5 word summary of current status:
+  - "No replies yet" (no one has responded)
+  - "Awaiting confirmation" (waiting for someone to confirm/check)
+  - "Not reproduced" (issue cannot be reproduced)
+  - "Checking with team" (someone said "let me check")
+  - "FYI only—no action" (informational, no one taking action)
+  - "Needs triage" (unclear who should handle)
+- **Resolution field** (Processed): How the issue was resolved in 3-8 words:
+  - "Ticket ENG-XXXXX created" or "Ticket ENG-XXXXX assigned to [name]"
+  - "Workaround provided" (temporary solution given)
+  - "Fixed in PR #XXXX" or "PR merged"
+  - "User found solution" (user resolved themselves)
+  - "Assigned to [name]" (ownership established)
+  - "Discussion concluded" (decision made)
+  - "Clarified approach" (scope/plan agreed)
+- **DO NOT include thread_ts timestamps** (not useful to humans)
+- Use `*bold*` for emphasis on channel names and section headers
+- Use `_italic_` for labels like "Scope:", "State:", "Resolution:", "Suggested:"
+- Use emojis (🚨, ⚠️, ✅, 🔴) to make sections visually distinct
+- Use `━` separator lines between major sections
+- Use bullet points `•` for regular threads; use `🔴` for Team Panda scope threads
+- Use `└` (box drawing character) for sub-details with 3-space indentation
+- Keep summaries to one line (max ~80 chars)
+- Add blank lines between threads for readability
+- If Unresolved or Needs Review sections are empty, show: "None — all clear! 🎉"
+- In Summary line, include count of Team Panda issues in parentheses: "8 unresolved (2 Team Panda)"
+
+---
+
+## Guardrails
+
+- Use only **Slack MCP** to read channels and threads; do not guess or invent message content.
+- If a channel is private and Slack MCP returns permission errors, note "Channel X not accessible" and continue with other channels.
+- Default time range is **3 days** unless the user specifies otherwise.
+- When classifying, prefer **not processed** when uncertain so issues are not missed.
+- **Posting:** This command posts the on-call report to **#panda-new-work** only (step 9). Do not post to other channels, create Jira tickets, or modify other external systems. (Future versions may add triage/Jira steps.)
+
+---
+
+## Extensibility (future)
+
+This command is designed so that later you can:
+
+- **Triage**: For each unresolved thread, add a triage label (e.g. bug, feature, question, incident) and owner.
+- **Identify**: Map thread to code/service (e.g. report-btf-service) and suggest owners.
+- **Create Jira ticket**: For unresolved Team Panda scope threads, draft or create a Jira ticket and post the link in the thread (when such automation is enabled).
+- **Assign**: Assign to on-call or a specific engineer.
+
+For now, the command only **retrieves threads, checks for resolution, and highlights unresolved**; next steps are suggested in the report but not executed.

package/bin/panda-cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const { install } = require('../lib/installer');
+const { upgrade } = require('../lib/upgrader');
+const { list } = require('../lib/list');
+const { diff } = require('../lib/diff');
+const packageJson = require('../package.json');
+
+program
+  .name('panda-cli')
+  .description('Docyt Team Panda development tools CLI')
+  .version(packageJson.version);
+
+program
+  .command('install')
+  .description('Install Docyt dev tools to workspace')
+  .argument('[path]', 'Target directory (defaults to current directory)')
+  .option('--commands', 'Install only Cursor commands')
+  .option('--skills', 'Install only skills')
+  .option('--rules', 'Install only rules')
+  .option('--all', 'Install everything (default)', true)
+  .action(async (targetPath, options) => {
+    try {
+      console.log(chalk.blue('🚀 Installing Docyt Panda On-Call Tools...\n'));
+      await install(targetPath, options);
+      console.log(chalk.green('\n✓ Installation complete!'));
+    } catch (error) {
+      console.error(chalk.red('\n✗ Installation failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('upgrade')
+  .description('Upgrade to latest version')
+  .option('--preview', 'Show what would change')
+  .option('--force', 'Overwrite local changes')
+  .action(async (options) => {
+    try {
+      console.log(chalk.blue('🔄 Checking for updates...\n'));
+      await upgrade(options);
+      if (!options.preview) {
+        console.log(chalk.green('\n✓ Upgrade complete!'));
+      }
+    } catch (error) {
+      console.error(chalk.red('\n✗ Upgrade failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List installed and available tools')
+  .action(async () => {
+    try {
+      await list();
+    } catch (error) {
+      console.error(chalk.red('\n✗ Failed to list tools:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('diff')
+  .description('Show differences between local and latest')
+  .action(async () => {
+    try {
+      await diff();
+    } catch (error) {
+      console.error(chalk.red('\n✗ Failed to show diff:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/lib/diff.js

@@ -0,0 +1,61 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const {
+  findWorkspaceRoot,
+  loadManifest,
+  getAssetsDir,
+  getAvailableCommands
+} = require('./utils');
+
+/**
+ * Show diff between local and latest versions
+ */
+async function diff() {
+  try {
+    const workspace = findWorkspaceRoot();
+    const manifest = loadManifest(workspace);
+    
+    if (!manifest) {
+      console.log(chalk.yellow('No installation found. Run `docyt-oncall install` first.'));
+      return;
+    }
+    
+    console.log(chalk.bold('\n📊 Differences between local and latest\n'));
+    
+    const commands = getAvailableCommands();
+    const commandsDir = path.join(workspace, '.cursor', 'commands');
+    
+    let hasDifferences = false;
+    
+    for (const command of commands) {
+      const sourcePath = path.join(getAssetsDir(), 'commands', command);
+      const targetPath = path.join(commandsDir, command);
+      
+      if (!fs.existsSync(targetPath)) {
+        console.log(chalk.blue(`+ ${command} (new)`));
+        hasDifferences = true;
+        continue;
+      }
+      
+      const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
+      const targetContent = fs.readFileSync(targetPath, 'utf-8');
+      
+      if (sourceContent !== targetContent) {
+        console.log(chalk.yellow(`± ${command} (modified)`));
+        hasDifferences = true;
+      }
+    }
+    
+    if (!hasDifferences) {
+      console.log(chalk.green('✓ No differences found - you are up to date!'));
+    }
+    
+    console.log('');
+    
+  } catch (error) {
+    throw error;
+  }
+}
+
+module.exports = { diff };

package/lib/installer.js

@@ -0,0 +1,138 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const {
+  findWorkspaceRoot,
+  loadManifest,
+  saveManifest,
+  getAssetsDir,
+  getAvailableCommands,
+  getAvailableSkills,
+  getAvailableRules
+} = require('./utils');
+
+/**
+ * Install commands to workspace
+ */
+async function installCommands(workspace) {
+  const commands = getAvailableCommands();
+  const targetDir = path.join(workspace, '.cursor', 'commands');
+  
+  fs.ensureDirSync(targetDir);
+  
+  console.log(chalk.blue('Installing Cursor commands...'));
+  
+  for (const command of commands) {
+    const sourcePath = path.join(getAssetsDir(), 'commands', command);
+    const targetPath = path.join(targetDir, command);
+    
+    await fs.copy(sourcePath, targetPath, { overwrite: true });
+    console.log(chalk.green(`  ✓ Installed: ${command}`));
+  }
+  
+  return commands;
+}
+
+/**
+ * Install skills to workspace
+ */
+async function installSkills(workspace) {
+  const skills = getAvailableSkills();
+  
+  if (skills.length === 0) {
+    console.log(chalk.gray('  No skills available'));
+    return [];
+  }
+  
+  const targetDir = path.join(workspace, '.cursor', 'skills');
+  
+  fs.ensureDirSync(targetDir);
+  
+  console.log(chalk.blue('Installing Cursor skills...'));
+  
+  for (const skill of skills) {
+    const sourcePath = path.join(getAssetsDir(), 'skills', skill);
+    const targetPath = path.join(targetDir, skill);
+    
+    await fs.copy(sourcePath, targetPath, { overwrite: true });
+    console.log(chalk.green(`  ✓ Installed: ${skill}`));
+  }
+  
+  return skills;
+}
+
+/**
+ * Install rules to workspace
+ */
+async function installRules(workspace) {
+  const rules = getAvailableRules();
+  
+  if (rules.length === 0) {
+    console.log(chalk.gray('  No rules available'));
+    return [];
+  }
+  
+  const targetDir = path.join(workspace, '.cursor', 'rules');
+  
+  fs.ensureDirSync(targetDir);
+  
+  console.log(chalk.blue('Installing Cursor rules...'));
+  
+  for (const rule of rules) {
+    const sourcePath = path.join(getAssetsDir(), 'rules', rule);
+    const targetPath = path.join(targetDir, rule);
+    
+    await fs.copy(sourcePath, targetPath, { overwrite: true });
+    console.log(chalk.green(`  ✓ Installed: ${rule}`));
+  }
+  
+  return rules;
+}
+
+/**
+ * Main install function
+ */
+async function install(targetPath, options) {
+  try {
+    // Find workspace (use targetPath if provided, otherwise current directory)
+    const workspace = findWorkspaceRoot(targetPath);
+    console.log(chalk.gray(`Installing to: ${workspace}\n`));
+    
+    const installedAssets = {
+      commands: [],
+      skills: [],
+      rules: []
+    };
+    
+    // Install based on options
+    if (options.all || options.commands) {
+      installedAssets.commands = await installCommands(workspace);
+    }
+    
+    if (options.all || options.skills) {
+      installedAssets.skills = await installSkills(workspace);
+    }
+    
+    if (options.all || options.rules) {
+      installedAssets.rules = await installRules(workspace);
+    }
+    
+    // Save manifest
+    const packageJson = require('../package.json');
+    const manifest = {
+      version: packageJson.version,
+      installed: new Date().toISOString(),
+      assets: installedAssets,
+      customizations: {}
+    };
+    
+    saveManifest(workspace, manifest);
+    
+    console.log(chalk.gray(`\nManifest saved to ${path.join(workspace, '.cursor/.panda-cli-manifest.json')}`));
+    
+  } catch (error) {
+    throw error;
+  }
+}
+
+module.exports = { install };

package/lib/list.js

@@ -0,0 +1,88 @@
+const chalk = require('chalk');
+const {
+  findWorkspaceRoot,
+  loadManifest,
+  getAvailableCommands,
+  getAvailableSkills,
+  getAvailableRules
+} = require('./utils');
+
+/**
+ * List installed and available tools
+ */
+async function list() {
+  try {
+    const workspace = findWorkspaceRoot();
+    const manifest = loadManifest(workspace);
+    const packageJson = require('../package.json');
+    
+    console.log(chalk.bold('\n📦 Docyt Panda On-Call Tools\n'));
+    
+    if (manifest) {
+      console.log(chalk.green('✓ Installed'));
+      console.log(chalk.gray(`  Version: ${manifest.version}`));
+      console.log(chalk.gray(`  Installed: ${new Date(manifest.installed).toLocaleString()}`));
+      
+      if (manifest.upgraded) {
+        console.log(chalk.gray(`  Last upgraded: ${new Date(manifest.upgraded).toLocaleString()}`));
+      }
+    } else {
+      console.log(chalk.yellow('○ Not installed'));
+      console.log(chalk.gray('  Run `docyt-oncall install` to get started'));
+    }
+    
+    console.log(chalk.gray(`  Latest available: ${packageJson.version}\n`));
+    
+    // List commands
+    const availableCommands = getAvailableCommands();
+    console.log(chalk.bold('Cursor Commands:'));
+    console.log(chalk.gray('  (Installed to: .cursor/commands/)'));
+    
+    if (availableCommands.length === 0) {
+      console.log(chalk.gray('  None available'));
+    } else {
+      availableCommands.forEach(cmd => {
+        const isInstalled = manifest?.assets?.commands?.includes(cmd);
+        const icon = isInstalled ? chalk.green('✓') : chalk.gray('○');
+        console.log(`  ${icon} ${cmd}`);
+      });
+    }
+    
+    // List skills
+    const availableSkills = getAvailableSkills();
+    console.log(chalk.bold('\nCursor Skills:'));
+    console.log(chalk.gray('  (Installed to: .cursor/skills/)'));
+    
+    if (availableSkills.length === 0) {
+      console.log(chalk.gray('  None available'));
+    } else {
+      availableSkills.forEach(skill => {
+        const isInstalled = manifest?.assets?.skills?.includes(skill);
+        const icon = isInstalled ? chalk.green('✓') : chalk.gray('○');
+        console.log(`  ${icon} ${skill}`);
+      });
+    }
+    
+    // List rules
+    const availableRules = getAvailableRules();
+    console.log(chalk.bold('\nCursor Rules:'));
+    console.log(chalk.gray('  (Installed to: .cursor/rules/)'));
+    
+    if (availableRules.length === 0) {
+      console.log(chalk.gray('  None available'));
+    } else {
+      availableRules.forEach(rule => {
+        const isInstalled = manifest?.assets?.rules?.includes(rule);
+        const icon = isInstalled ? chalk.green('✓') : chalk.gray('○');
+        console.log(`  ${icon} ${rule}`);
+      });
+    }
+    
+    console.log('');
+    
+  } catch (error) {
+    throw error;
+  }
+}
+
+module.exports = { list };

package/lib/upgrader.js

@@ -0,0 +1,140 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const prompts = require('prompts');
+const semver = require('semver');
+const {
+  findWorkspaceRoot,
+  loadManifest,
+  saveManifest,
+  getAssetsDir,
+  getAvailableCommands,
+  getAvailableSkills,
+  getAvailableRules
+} = require('./utils');
+
+/**
+ * Check if a file has been modified by comparing checksums
+ */
+function hasLocalChanges(filePath, originalContent) {
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+  
+  const currentContent = fs.readFileSync(filePath, 'utf-8');
+  return currentContent !== originalContent;
+}
+
+/**
+ * Upgrade commands
+ */
+async function upgradeCommands(workspace, manifest, options) {
+  const commands = getAvailableCommands();
+  const targetDir = path.join(workspace, '.cursor', 'commands');
+  const upgraded = [];
+  
+  console.log(chalk.blue('Upgrading Cursor commands...'));
+  
+  for (const command of commands) {
+    const sourcePath = path.join(getAssetsDir(), 'commands', command);
+    const targetPath = path.join(targetDir, command);
+    const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
+    
+    // Check if file exists and has local changes
+    if (fs.existsSync(targetPath)) {
+      const hasChanges = manifest?.customizations?.[`commands/${command}`] === 'modified' ||
+                         hasLocalChanges(targetPath, sourceContent);
+      
+      if (hasChanges && !options.force) {
+        // Ask user what to do
+        if (!options.preview) {
+          const response = await prompts({
+            type: 'select',
+            name: 'action',
+            message: `${command} has local changes. What do you want to do?`,
+            choices: [
+              { title: 'Keep local version', value: 'keep' },
+              { title: 'Overwrite with new version', value: 'overwrite' },
+              { title: 'Skip', value: 'skip' }
+            ]
+          });
+          
+          if (response.action === 'keep') {
+            console.log(chalk.yellow(`  ⊙ Kept local: ${command}`));
+            continue;
+          } else if (response.action === 'skip') {
+            console.log(chalk.gray(`  ○ Skipped: ${command}`));
+            continue;
+          }
+        } else {
+          console.log(chalk.yellow(`  ⊙ Would ask about: ${command} (has local changes)`));
+          continue;
+        }
+      }
+    }
+    
+    if (!options.preview) {
+      await fs.copy(sourcePath, targetPath, { overwrite: true });
+      console.log(chalk.green(`  ✓ Updated: ${command}`));
+      upgraded.push(`commands/${command}`);
+    } else {
+      console.log(chalk.blue(`  → Would update: ${command}`));
+    }
+  }
+  
+  return upgraded;
+}
+
+/**
+ * Main upgrade function
+ */
+async function upgrade(options) {
+  try {
+    // Find workspace
+    const workspace = findWorkspaceRoot();
+    const manifest = loadManifest(workspace);
+    const packageJson = require('../package.json');
+    
+    if (!manifest) {
+      console.log(chalk.yellow('No installation found. Run `docyt-oncall install` first.'));
+      return;
+    }
+    
+    console.log(chalk.gray(`Workspace: ${workspace}`));
+    console.log(chalk.gray(`Current version: ${manifest.version}`));
+    console.log(chalk.gray(`Latest version: ${packageJson.version}\n`));
+    
+    // Check if upgrade is needed
+    if (semver.gte(manifest.version, packageJson.version)) {
+      console.log(chalk.green('✓ You are already on the latest version!'));
+      return;
+    }
+    
+    const upgradedAssets = [];
+    
+    // Upgrade commands
+    if (manifest.assets.commands && manifest.assets.commands.length > 0) {
+      const upgraded = await upgradeCommands(workspace, manifest, options);
+      upgradedAssets.push(...upgraded);
+    }
+    
+    // TODO: Add skills and rules upgrade when they exist
+    
+    if (options.preview) {
+      console.log(chalk.blue('\n📋 Preview mode - no changes were made'));
+      return;
+    }
+    
+    // Update manifest
+    manifest.version = packageJson.version;
+    manifest.upgraded = new Date().toISOString();
+    saveManifest(workspace, manifest);
+    
+    console.log(chalk.gray(`\n✓ Upgraded to version ${packageJson.version}`));
+    
+  } catch (error) {
+    throw error;
+  }
+}
+
+module.exports = { upgrade };

package/lib/utils.js

@@ -0,0 +1,119 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Find the workspace root - use specified path or current directory
+ */
+function findWorkspaceRoot(specifiedPath = null) {
+  // If path is specified, use it directly
+  if (specifiedPath) {
+    const resolvedPath = path.resolve(specifiedPath);
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`Specified path does not exist: ${resolvedPath}`);
+    }
+    return resolvedPath;
+  }
+  
+  // Otherwise, use current working directory
+  return process.cwd();
+}
+
+/**
+ * Get the manifest file path
+ */
+function getManifestPath(workspace) {
+  return path.join(workspace, '.cursor', '.panda-cli-manifest.json');
+}
+
+/**
+ * Load the manifest file
+ */
+function loadManifest(workspace) {
+  const manifestPath = getManifestPath(workspace);
+  
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  
+  try {
+    return fs.readJsonSync(manifestPath);
+  } catch (error) {
+    console.warn(chalk.yellow('Warning: Could not read manifest file'));
+    return null;
+  }
+}
+
+/**
+ * Save the manifest file
+ */
+function saveManifest(workspace, manifest) {
+  const manifestPath = getManifestPath(workspace);
+  const cursorDir = path.dirname(manifestPath);
+  
+  // Ensure .cursor directory exists
+  fs.ensureDirSync(cursorDir);
+  
+  // Write manifest
+  fs.writeJsonSync(manifestPath, manifest, { spaces: 2 });
+}
+
+/**
+ * Get the assets directory from this CLI package
+ */
+function getAssetsDir() {
+  return path.join(__dirname, '..', 'assets');
+}
+
+/**
+ * Get list of available commands
+ */
+function getAvailableCommands() {
+  const commandsDir = path.join(getAssetsDir(), 'commands');
+  
+  if (!fs.existsSync(commandsDir)) {
+    return [];
+  }
+  
+  return fs.readdirSync(commandsDir)
+    .filter(file => file.endsWith('.md'));
+}
+
+/**
+ * Get list of available skills
+ */
+function getAvailableSkills() {
+  const skillsDir = path.join(getAssetsDir(), 'skills');
+  
+  if (!fs.existsSync(skillsDir)) {
+    return [];
+  }
+  
+  return fs.readdirSync(skillsDir)
+    .filter(file => file.endsWith('.md'));
+}
+
+/**
+ * Get list of available rules
+ */
+function getAvailableRules() {
+  const rulesDir = path.join(getAssetsDir(), 'rules');
+  
+  if (!fs.existsSync(rulesDir)) {
+    return [];
+  }
+  
+  return fs.readdirSync(rulesDir)
+    .filter(file => file.endsWith('.md'));
+}
+
+module.exports = {
+  findWorkspaceRoot,
+  getManifestPath,
+  loadManifest,
+  saveManifest,
+  getAssetsDir,
+  getAvailableCommands,
+  getAvailableSkills,
+  getAvailableRules
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@docyt/panda-cli",
+  "version": "0.1.1",
+  "description": "CLI tool for installing and managing Docyt Team Panda development tools (Cursor commands, skills, rules)",
+  "main": "index.js",
+  "bin": {
+    "panda-cli": "./bin/panda-cli.js"
+  },
+  "preferGlobal": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "docyt",
+    "cursor",
+    "commands",
+    "cli",
+    "development-tools"
+  ],
+  "author": "Docyt Team Panda",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^4.1.2",
+    "prompts": "^2.4.2",
+    "fs-extra": "^11.2.0",
+    "semver": "^7.5.4"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "assets/",
+    "README.md",
+    "QUICKSTART.md"
+  ]
+}