prjct-cli 0.39.0 → 0.41.0

package/templates/commands/linear.md

@@ -1,6 +1,6 @@
 ---
 allowed-tools: [Read, Write, Bash, AskUserQuestion]
-description: 'Linear issue tracker integration via MCP'
+description: 'Linear issue tracker integration via SDK'
 extends: '_bases/tracker-base.md'
 ---
 
@@ -10,20 +10,12 @@ extends: '_bases/tracker-base.md'
 
 **ARGUMENTS**: $ARGUMENTS
 
-Manage Linear issues directly from prjct using MCP (no SDK needed).
-
-## Tracker-Specific Config
-
-- `{mcpServerName}`: "linear"
-- `{mcpPrefix}`: "mcp__linear__"
-- `{projectKey}`: "teamId"
+Manage Linear issues directly from prjct using the @linear/sdk for fast performance.
 
 ## Context Variables
 
 - `{projectId}`: From `.prjct/prjct.config.json`
 - `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
-- `{agentName}`: Name of the AI agent (Claude Code, Gemini CLI)
-- `{agentSettingsPath}`: Path to agent settings (settings.json)
 - `{args}`: User-provided arguments (subcommand)
 
 ---
@@ -33,7 +25,7 @@ Manage Linear issues directly from prjct using MCP (no SDK needed).
 | Command | Description |
 |---------|-------------|
 | `p. linear` | Show your assigned issues |
-| `p. linear setup` | Configure Linear (first time) |
+| `p. linear setup` | Configure Linear API key (first time) |
 | `p. linear start <ID>` | Start working on issue (e.g., PRJ-59) |
 | `p. linear comment <ID> <text>` | Add comment to issue |
 
@@ -41,11 +33,10 @@ Manage Linear issues directly from prjct using MCP (no SDK needed).
 
 ## Authentication
 
-Linear uses MCP with OAuth - **no API key needed**.
+Linear uses API key authentication for fast SDK access.
 
-**MCP Server**: `https://mcp.linear.app/mcp`
-**Auth**: Browser-based OAuth (first use opens browser)
-**Tools prefix**: `mcp__linear__*`
+**Get API Key**: https://linear.app/settings/api
+**Env Variable**: `LINEAR_API_KEY`
 
 ---
 
@@ -63,46 +54,20 @@ IF file not found:
 
 ---
 
-## Step 2: Install MCP Server (if needed)
+## Step 2: Check API Key
 
 ```
-READ: {agentSettingsPath} (create {} if not exists)
-CHECK: Does mcpServers.linear exist?
-
-IF not exists:
-  READ: templates/mcp-config.json
-  EXTRACT: mcpServers.linear
-
-  MERGE into {agentSettingsPath}:
-  {
-    "mcpServers": {
-      "linear": {
-        "command": "npx",
-        "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
-      }
-    }
-  }
-
-  WRITE: {agentSettingsPath}
-
-  OUTPUT: "✅ Installed Linear MCP server"
-  OUTPUT: ""
-  OUTPUT: "⚠️ Restart {agentName} to activate the MCP server."
-  OUTPUT: "Then run `p. linear setup` again to complete configuration."
-  STOP
-```
-
----
+CHECK: Is LINEAR_API_KEY set in environment?
 
-## Step 3: Check MCP Tools Available
+IF not set:
+  ASK: "Enter your Linear API key"
+  HINT: "Get it from https://linear.app/settings/api"
 
-```
-CHECK: Are mcp__linear__* tools available?
-
-IF not available:
-  OUTPUT: "Linear MCP is installed but not yet active."
-  OUTPUT: "Restart {agentName}, then run `p. linear setup` again."
-  STOP
+  ONCE PROVIDED:
+  OUTPUT: "Add to your shell profile:"
+  OUTPUT: "export LINEAR_API_KEY='your-key'"
+  OUTPUT: ""
+  OUTPUT: "Or add to .env file in project root"
 ```
 
 ---
@@ -111,30 +76,28 @@ IF not available:
 
 ### Flow
 
-1. **Install MCP + Verify tools available**
+1. **Check for API key**
    ```
-   Execute Step 2 (auto-install if needed)
-   Execute Step 3 (verify tools active)
-   IF not available: Prompt restart and STOP
+   IF LINEAR_API_KEY not in environment:
+     ASK: "Enter your Linear API key"
+     PROVIDE: Link to https://linear.app/settings/api
    ```
 
-2. **Test connection (triggers OAuth if needed)**
+2. **Test SDK connection**
    ```
-   USE TOOL: mcp__linear__list_issues
-   PARAMS: { "limit": 1 }
+   IMPORT: linearService from core/integrations/linear
+   CALL: linearService.initializeFromApiKey(apiKey)
 
-   # First use will open browser for OAuth
+   # This will verify the connection
    ```
 
 3. **Get user info and teams**
    ```
-   USE TOOL: mcp__linear__get_viewer
-   EXTRACT: userId, name, email
-
-   USE TOOL: mcp__linear__list_teams
+   CALL: linearService.getTeams()
+   EXTRACT: List of teams with id, name, key
    ```
 
-4. **Ask user to select team**
+4. **Ask user to select default team**
    ```
    ASK: "Select your default team"
    OPTIONS: List of teams
@@ -146,11 +109,10 @@ IF not available:
      "integrations": {
        "linear": {
          "enabled": true,
-         "authMode": "mcp",
+         "authMode": "api-key",
          "teamId": "{teamId}",
          "teamName": "{teamName}",
          "teamKey": "{teamKey}",
-         "userId": "{userId}",
          "setupAt": "{timestamp}"
        }
      }
@@ -160,11 +122,10 @@ IF not available:
 ### Output
 
 ```
-✅ Linear configured
+Linear configured
 
-Connected as: {name} ({email})
 Team: {teamName} ({teamKey})
-Auth: MCP (OAuth)
+Auth: API Key (SDK)
 
 Next: `p. linear` to see your issues
 ```
@@ -174,18 +135,15 @@ Next: `p. linear` to see your issues
 ## Subcommand: status (default, no args)
 
 ```
-USE TOOL: mcp__linear__list_issues
-PARAMS:
-  assignedToMe: true
-  limit: 10
+CALL: linearService.fetchAssignedIssues({ limit: 10 })
 
 OUTPUT:
-Linear: Connected ✓
+Linear: Connected
 Team: {teamName} ({teamKey})
 
 Your issues ({count}):
-• {PRJ-123} {title} ({status})
-• {PRJ-124} {title} ({status})
+  {PRJ-123} {title} ({status})
+  {PRJ-124} {title} ({status})
 ...
 
 Next: `p. linear start PRJ-123` to begin work
@@ -197,24 +155,25 @@ Next: `p. linear start PRJ-123` to begin work
 
 ```
 1. Get issue
-   USE TOOL: mcp__linear__get_issue
-   PARAMS: { "issueId": "{ID}" }
+   CALL: linearService.fetchIssue("{ID}")
+   EXTRACT: id, title, description, status
 
 2. Update status to In Progress
-   USE TOOL: mcp__linear__update_issue
-   PARAMS:
-     issueId: "{uuid}"
-     stateId: "{in_progress_state_id}"
+   CALL: linearService.markInProgress("{ID}")
 
 3. Create prjct task from issue
+   - Use issue title as task description
+   - Link externalId to Linear issue
 
-4. Create git branch: feature/{ID}-{slug}
+4. Create git branch
+   PATTERN: feature/{ID}-{slug}
+   EXAMPLE: feature/PRJ-59-add-user-auth
 
 OUTPUT:
 Started: {ID} - {title}
 
 Branch: feature/PRJ-59-add-user-auth
-Linear: In Progress ✓
+Linear: In Progress
 
 Next: Work on the task, then `p. done`
 ```
@@ -224,15 +183,8 @@ Next: Work on the task, then `p. done`
 ## Subcommand: comment <ID> <text>
 
 ```
-1. Get issue UUID
-   USE TOOL: mcp__linear__get_issue
-   PARAMS: { "issueId": "{ID}" }
-
-2. Add comment
-   USE TOOL: mcp__linear__create_comment
-   PARAMS:
-     issueId: "{uuid}"
-     body: "{text}"
+1. Add comment via SDK
+   CALL: linearService.addComment("{ID}", "{text}")
 
 OUTPUT:
 Comment added to {ID}
@@ -240,44 +192,31 @@ Comment added to {ID}
 
 ---
 
-## MCP Tool Reference
+## SDK Service Reference
 
-| Operation | MCP Tool |
-|-----------|----------|
-| List issues | `mcp__linear__list_issues` |
-| Get issue | `mcp__linear__get_issue` |
-| Update issue | `mcp__linear__update_issue` |
-| Create issue | `mcp__linear__create_issue` |
-| Add comment | `mcp__linear__create_comment` |
-| Get viewer | `mcp__linear__get_viewer` |
-| List teams | `mcp__linear__list_teams` |
+The `linearService` from `core/integrations/linear` provides:
 
-### Example: List My Issues
+| Operation | SDK Method |
+|-----------|------------|
+| Initialize | `linearService.initializeFromApiKey(key, teamId?)` |
+| List assigned | `linearService.fetchAssignedIssues(options?)` |
+| Get issue | `linearService.fetchIssue(id)` |
+| Create issue | `linearService.createIssue(input)` |
+| Update issue | `linearService.updateIssue(id, input)` |
+| Mark in progress | `linearService.markInProgress(id)` |
+| Mark done | `linearService.markDone(id)` |
+| Add comment | `linearService.addComment(id, body)` |
+| Get teams | `linearService.getTeams()` |
+| Get projects | `linearService.getProjects()` |
 
-```
-USE TOOL: mcp__linear__list_issues
-PARAMS:
-  assignedToMe: true
-  includeArchived: false
-  limit: 20
-```
+### Caching
 
-### Example: Get Issue by ID
+All read operations are cached for 5 minutes:
+- Issues are cached by ID and identifier (e.g., "PRJ-123")
+- Assigned issues list is cached per user
+- Teams and projects are cached globally
 
-```
-USE TOOL: mcp__linear__get_issue
-PARAMS:
-  issueId: "PRJ-59"
-```
-
-### Example: Add Comment
-
-```
-USE TOOL: mcp__linear__create_comment
-PARAMS:
-  issueId: "{uuid}"
-  body: "Implementation complete. Used MCP instead of SDK."
-```
+Cache is automatically invalidated on writes (create, update, status changes).
 
 ---
 
@@ -285,9 +224,8 @@ PARAMS:
 
 | What | Where |
 |------|-------|
-| Auth | MCP OAuth (managed by Linear) |
+| API Key | `LINEAR_API_KEY` environment variable |
 | Config | `{globalPath}/project.json` → `integrations.linear` |
-| Issue cache | `{globalPath}/storage/issues.json` |
 
 ---
 
@@ -295,9 +233,10 @@ PARAMS:
 
 | Error | Action |
 |-------|--------|
-| MCP tools not found | "Add Linear MCP to settings, restart {agentName}" |
-| OAuth failed | "Re-authenticate via browser" |
+| No API key | "Set LINEAR_API_KEY or run `p. linear setup`" |
+| Invalid API key | "Check your API key at https://linear.app/settings/api" |
 | Issue not found | "Issue {ID} not found in Linear" |
+| Network error | "Check your internet connection" |
 
 ---
 
@@ -310,3 +249,15 @@ PARAMS:
 
 Next: {suggested action}
 ```
+
+---
+
+## Performance
+
+SDK operations are significantly faster than MCP:
+
+| Operation | SDK | MCP (deprecated) |
+|-----------|-----|------------------|
+| Fetch issue | ~150ms | ~600ms |
+| Create issue | ~200ms | ~800ms |
+| Batch (10) | ~500ms | ~8000ms |

package/templates/commands/skill.md

@@ -1,22 +1,26 @@
 ---
-allowed-tools: [Read, Glob]
+allowed-tools: [Read, Glob, Bash]
 description: 'List, search, and invoke skills'
 timestamp-rule: 'None'
-architecture: 'Skill discovery and execution'
+architecture: 'Skill discovery, installation, and execution'
 ---
 
 # /p:skill - Skill Management
 
-List, search, and invoke reusable skills.
+List, search, install, and invoke reusable skills.
 
 ## Usage
 
 ```
-/p:skill                    # List all skills
-/p:skill list               # List all skills
-/p:skill search <query>     # Search skills
-/p:skill show <id>          # Show skill details
-/p:skill invoke <id>        # Invoke a skill
+/p:skill                        # List all skills
+/p:skill list                   # List all skills
+/p:skill search <query>         # Search skills
+/p:skill show <id>              # Show skill details
+/p:skill invoke <id>            # Invoke a skill
+/p:skill add <source>           # Install skill from remote source
+/p:skill remove <name>          # Remove an installed skill
+/p:skill init <name>            # Scaffold a new skill
+/p:skill check                  # Check for available updates
 ```
 
 ## Flow
@@ -24,11 +28,14 @@ List, search, and invoke reusable skills.
 ### List Skills (`/p:skill` or `/p:skill list`)
 
 1. Load skills from all sources:
-   - Project: `.prjct/skills/*.md`
-   - Global: `~/.prjct-cli/skills/*.md`
+   - Project: `.prjct/skills/*.md` and `.prjct/skills/*/SKILL.md`
+   - Provider: `~/.claude/skills/*/SKILL.md` and `~/.claude/skills/*.md`
+   - Global: `~/.prjct-cli/skills/*.md` and `~/.prjct-cli/skills/*/SKILL.md`
    - Built-in: `templates/skills/*.md`
 
-2. Output grouped by source:
+2. Check lock file at `~/.prjct-cli/skills/.skill-lock.json` for source info
+
+3. Output grouped by source:
 
 ```
 ## Available Skills
@@ -36,13 +43,13 @@ List, search, and invoke reusable skills.
 ### Project Skills
 - **custom-deploy** - Deploy to staging server
 
-### Global Skills
+### Global Skills (Provider)
+- **frontend-design** - Create production-grade UIs [github: vercel-labs/skills]
 - **my-template** - Personal code template
 
 ### Built-in Skills
 - **code-review** - Review code for quality
 - **refactor** - Refactor code structure
-- **debug** - Systematic debugging
 ```
 
 ### Search Skills (`/p:skill search <query>`)
@@ -55,14 +62,17 @@ List, search, and invoke reusable skills.
 
 1. Load skill by ID
 2. Display metadata and content
+3. If remotely installed, show source tracking info
 
 ```
-## Skill: code-review
+## Skill: frontend-design
 
-**Description:** Review code for quality
-**Source:** builtin
-**Tags:** review, quality, security
-**Agent:** general
+**Description:** Create production-grade frontend interfaces
+**Source:** global (github: vercel-labs/skills)
+**Tags:** frontend, design, ui
+**Version:** 1.0.0
+**Installed:** 2026-01-28T12:00:00.000Z
+**SHA:** abc123
 
 ### Content
 [Full skill prompt content]
@@ -74,9 +84,122 @@ List, search, and invoke reusable skills.
 2. Return skill content for execution
 3. The skill content becomes the prompt
 
+### Add Skill (`/p:skill add <source>`)
+
+Install skills from remote sources.
+
+**Supported source formats:**
+- `owner/repo` — Clone GitHub repo, install all discovered skills
+- `owner/repo@skill-name` — Install specific skill from GitHub repo
+- `./local-path` — Install from local directory
+
+**Install flow:**
+1. Parse source string
+2. For GitHub: `git clone --depth 1` to temp dir (60s timeout)
+3. Discover SKILL.md files (scans `*/SKILL.md` and `skills/*/SKILL.md`)
+4. Copy to `~/.claude/skills/{name}/SKILL.md` (ecosystem standard format)
+5. Add `_prjct` metadata block to frontmatter (sourceUrl, sha, installedAt)
+6. Update lock file at `~/.prjct-cli/skills/.skill-lock.json`
+7. Clean up temp dir
+
+**Example:**
+```
+p. skill add vercel-labs/skills
+p. skill add my-org/custom-skills@api-designer
+p. skill add ./my-local-skill
+```
+
+**Output:**
+```
+✅ Installed 3 skills from vercel-labs/skills
+
+- frontend-design → ~/.claude/skills/frontend-design/SKILL.md
+- find-skills → ~/.claude/skills/find-skills/SKILL.md
+- code-review → ~/.claude/skills/code-review/SKILL.md
+
+Lock file updated: ~/.prjct-cli/skills/.skill-lock.json
+```
+
+### Remove Skill (`/p:skill remove <name>`)
+
+1. Remove skill directory from `~/.claude/skills/{name}/`
+2. Also remove flat file if it exists (`~/.claude/skills/{name}.md`)
+3. Remove entry from lock file
+4. Confirm removal
+
+**Output:**
+```
+✅ Removed skill: frontend-design
+
+Deleted: ~/.claude/skills/frontend-design/
+Lock file updated.
+```
+
+### Init Skill (`/p:skill init <name>`)
+
+Scaffold a new skill in the project.
+
+1. Create `.prjct/skills/{name}/SKILL.md` with template frontmatter
+2. Open for editing
+
+**Template:**
+```markdown
+---
+name: {name}
+description: TODO - describe what this skill does
+agent: general
+tags: []
+version: 1.0.0
+author: {detected-author}
+---
+
+# {Name} Skill
+
+## Purpose
+
+Describe what this skill helps with.
+
+## Instructions
+
+Step-by-step instructions for the AI agent...
+```
+
+### Check Updates (`/p:skill check`)
+
+Compare lock file SHAs with remote repositories to detect available updates.
+
+1. Read lock file entries
+2. For each GitHub-sourced skill, run `git ls-remote` to get latest SHA
+3. Compare with stored SHA
+4. Report skills with available updates (no auto-update)
+
+**Output:**
+```
+## Skill Update Check
+
+- **frontend-design** (vercel-labs/skills) — Update available
+  Current: abc123 → Latest: def456
+- **code-review** (vercel-labs/skills) — Up to date
+- **my-local-skill** (local) — Skipped (local source)
+
+1 update available. Run `p. skill add <source>` to update.
+```
+
 ## Skill File Format
 
-Skills are markdown files with frontmatter:
+Skills are markdown files with frontmatter. Two formats are supported:
+
+### Subdirectory Format (Ecosystem Standard)
+```
+~/.claude/skills/my-skill/SKILL.md
+```
+
+### Flat Format (Legacy)
+```
+~/.claude/skills/my-skill.md
+```
+
+### Frontmatter Schema
 
 ```markdown
 ---
@@ -85,6 +208,13 @@ description: What the skill does
 agent: general
 tags: [tag1, tag2]
 version: 1.0.0
+author: Author Name
+category: development
+_prjct:
+  sourceUrl: https://github.com/owner/repo
+  sourceType: github
+  installedAt: 2026-01-28T12:00:00.000Z
+  sha: abc123
 ---
 
 # Skill Content
@@ -94,11 +224,30 @@ The actual prompt/instructions...
 
 ## Creating Custom Skills
 
-### Project Skill
-Create `.prjct/skills/my-skill.md`
-
-### Global Skill
-Create `~/.prjct-cli/skills/my-skill.md`
+### Project Skill (repo-specific)
+Create `.prjct/skills/my-skill/SKILL.md` or `.prjct/skills/my-skill.md`
+
+### Global Skill (all projects)
+Create `~/.claude/skills/my-skill/SKILL.md` or `~/.prjct-cli/skills/my-skill.md`
+
+## Lock File
+
+Installed skills are tracked in `~/.prjct-cli/skills/.skill-lock.json`:
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-01-28T...",
+  "skills": {
+    "frontend-design": {
+      "name": "frontend-design",
+      "source": { "type": "github", "url": "vercel-labs/skills", "sha": "abc123" },
+      "installedAt": "2026-01-28T...",
+      "filePath": "~/.claude/skills/frontend-design/SKILL.md"
+    }
+  }
+}
+```
 
 ## Output Format
 
@@ -106,5 +255,5 @@ Create `~/.prjct-cli/skills/my-skill.md`
 ## Skills ({count} total)
 
 ### {source}
-- **{name}** ({id}): {description}
+- **{name}** ({id}): {description} [{sourceInfo}]
 ```