prjct-cli 0.41.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## [0.44.0] - 2026-01-29
+
+### Feature: Workflow State Machine (PRJ-139)
+
+Explicit states with valid transitions for prjct workflow. Users always know what commands are available.
+
+**States:** `idle` → `working` → `completed` → `shipped` (with `paused` branch)
+
+**New: State Machine (`core/workflow/state-machine.ts`)**
+- Explicit state definitions with valid transitions
+- State info shown after each command (e.g., `📍 State: WORKING`)
+- Next steps derived from current state
+
+**Updated Commands**
+- `task` — Shows state: WORKING after starting
+- `done` — Shows state: COMPLETED
+- `pause` — Shows state: PAUSED
+- `resume` — Shows state: WORKING
+
+### Feature: Auto-sync to Linear (PRJ-142 completion)
+
+When starting/completing tasks with Linear IDs, prjct now auto-syncs status.
+
+- `p. task PRJ-123` → Fetches issue title, marks as In Progress in Linear
+- `p. done` → Marks issue as Done in Linear (if task has linearId)
+
+### Feature: Sync Summary (PRJ-119)
+
+After `p. sync`, shows a compact summary with key metrics:
+- Stack detected
+- Files analyzed → context files generated
+- Agents count
+- Time elapsed
+
+### Improvement: Linear CLI filter by team
+
+`list` command now uses configured team, showing only relevant issues.
+
+### Improvement: Clean Terminal UX guidelines
+
+Added guidelines to CLAUDE.md for user-friendly tool call descriptions.
+
+## [0.43.0] - 2026-01-29
+
+### Feature: Bidirectional Sync Linear ↔ prjct (PRJ-142)
+
+When `integrations.linear.enabled === true`, prjct now syncs bidirectionally with Linear, using a local cache for offline access and reduced API calls.
+
+**New: Local Issue Cache (`storage/issues.json`)**
+- Full copy of assigned Linear issues stored locally
+- 30-minute staleness threshold for automatic refresh
+- Local-first reads: no API call if issue is cached and fresh
+
+**New: Sync Layer (`core/integrations/linear/sync.ts`)**
+- `pullAll()` — Fetch all assigned issues to local cache
+- `getIssue()` — Local-first fetch with API fallback
+- `getIssueLocal()` — Local-only fetch (no API call)
+- `pushStatus()` — Push status changes to Linear + update cache
+- `isStale()` — Check if cache needs refresh
+
+**New CLI Commands**
+- `sync` — Pull all assigned issues to local storage
+- `sync-status` — Check local cache status (hasCache, issueCount, isStale)
+- `get-local <id>` — Get issue from local cache without API call
+
+**Updated State Schema**
+- `currentTask.linearId` — Linear identifier (e.g., "PRJ-123")
+- `currentTask.linearUuid` — Linear internal UUID for API calls
+
+**Updated Templates**
+- `sync.md` — Syncs Linear issues when enabled
+- `task.md` — Uses local-first approach, tracks linearId/linearUuid
+- `done.md` — Pushes status to Linear via sync layer
+
+**New Files:**
+- `core/integrations/linear/sync.ts` — Sync layer implementation
+- `core/schemas/issues.ts` — Zod schema for issues.json
+
+## [0.42.0] - 2026-01-29
+
+### Feature: Linear SDK Integration with Per-Project Credentials
+
+Linear integration now uses the native `@linear/sdk` with per-project credential storage, enabling different projects to use different Linear workspaces.
+
+**New: Per-Project Credentials**
+- Credentials stored at `~/.prjct-cli/projects/{projectId}/config/credentials.json`
+- Fallback chain: project credentials → macOS keychain → environment variable
+- Each project can connect to a different Linear workspace
+
+**New: CLI Bridge (`core/cli/linear.ts`)**
+- Direct access to Linear SDK from templates
+- Commands: `setup`, `list`, `get`, `create`, `update`, `start`, `done`, `comment`, `teams`, `projects`, `status`
+- JSON output for easy parsing by Claude
+
+**New: `prjct linear <cmd>` Subcommand**
+- Direct CLI access: `prjct linear status`, `prjct linear list`, etc.
+- Auto-resolves project ID from current directory
+
+**Updated Templates**
+- `linear.md` — Natural language interpretation guide for Claude
+- `enrich.md` — Uses CLI instead of MCP for ticket enrichment
+
+**Breaking: Removed MCP-only Trackers**
+- Removed JIRA, GitHub Issues, Monday.com support (no native SDK)
+- Only Linear is supported (has native SDK)
+
+**New Files:**
+- `core/cli/linear.ts` — CLI bridge for Linear SDK
+- `core/utils/project-credentials.ts` — Per-project credential storage
+
+**Modified:**
+- `bin/prjct.ts` — Added `prjct linear` subcommand
+- `templates/commands/linear.md` — Updated with CLI execution pattern
+- `templates/commands/enrich.md` — Linear-only, uses CLI
+
 ## [0.40.0] - 2026-01-28
 
 ### Feature: Enhanced Skill System

package/bin/prjct.ts

@@ -85,6 +85,32 @@ if (args[0] === 'start' || args[0] === 'setup') {
     console.error('Server error:', (error as Error).message)
     process.exitCode = 1
   }
+} else if (args[0] === 'linear') {
+  // Linear CLI subcommand - direct access to Linear SDK
+  const { spawn } = await import('child_process')
+  const projectPath = process.cwd()
+  const projectId = await configManager.getProjectId(projectPath)
+
+  if (!projectId) {
+    console.error('No prjct project found. Run "prjct init" first.')
+    process.exitCode = 1
+  } else {
+    // Get the path to the linear CLI
+    const linearCliPath = path.join(__dirname, '..', 'core', 'cli', 'linear.ts')
+
+    // Forward args to linear CLI, adding --project flag
+    const linearArgs = ['--project', projectId, ...args.slice(1)]
+
+    // Use bun to run the CLI
+    const child = spawn('bun', [linearCliPath, ...linearArgs], {
+      stdio: 'inherit',
+      cwd: projectPath,
+    })
+
+    child.on('close', (code) => {
+      process.exitCode = code || 0
+    })
+  }
 } else if (args[0] === 'version' || args[0] === '-v' || args[0] === '--version') {
   // Show version with provider status
   const detection = detectAllProviders()

package/core/agentic/command-executor.ts

@@ -20,6 +20,7 @@ import groundTruth from './ground-truth'
 import planMode from './plan-mode'
 import templateExecutor from './template-executor'
 import orchestratorExecutor from './orchestrator-executor'
+import { agentStream } from '../utils/agent-stream'
 
 import type {
   OrchestratorContext,
@@ -183,12 +184,21 @@ export class CommandExecutor {
             projectPath
           )
 
-          // Log orchestrator results
-          console.log(`🎯 Orchestrator:`)
-          console.log(`   → Domains: ${orchestratorContext.detectedDomains.join(', ')}`)
-          console.log(`   → Agents: ${orchestratorContext.agents.map(a => a.name).join(', ') || 'none loaded'}`)
+          // Show orchestration with agent stream
+          if (orchestratorContext.detectedDomains.length > 0) {
+            agentStream.orchestrate(orchestratorContext.detectedDomains)
+          }
+
+          // Show each agent being activated
+          for (const agent of orchestratorContext.agents) {
+            const domain = agent.domain || agent.name.replace('.md', '')
+            agentStream.startAgent(agent.name, domain, `Loading ${domain} specialist...`)
+            agentStream.endAgent(true)
+          }
+
+          // Show subtasks if fragmented
           if (orchestratorContext.requiresFragmentation && orchestratorContext.subtasks) {
-            console.log(`   → Subtasks: ${orchestratorContext.subtasks.length}`)
+            agentStream.status('📋', `${orchestratorContext.subtasks.length} subtasks planned`)
           }
         } catch (error) {
           // Orchestration failed - log warning but continue without it

package/core/ai-tools/formatters.ts

@@ -0,0 +1,302 @@
+/**
+ * AI Tool Formatters
+ *
+ * Each AI tool has different context preferences:
+ * - Claude Code: Detailed markdown with sections
+ * - Cursor: Concise rules format
+ * - Copilot: Minimal bullet points
+ * - Windsurf: Similar to Cursor
+ */
+
+import type { AIToolConfig } from './registry'
+
+export interface ProjectContext {
+  projectId: string
+  name: string
+  version: string
+  ecosystem: string
+  projectType: string
+  languages: string[]
+  frameworks: string[]
+  repoPath: string
+  branch: string
+  fileCount: number
+  commits: number
+  hasChanges: boolean
+  commands: {
+    install: string
+    dev: string
+    test: string
+    build: string
+    lint: string
+    format: string
+  }
+  agents: {
+    workflow: string[]
+    domain: string[]
+  }
+}
+
+/**
+ * Format context for Claude Code (CLAUDE.md)
+ * Detailed markdown with full context
+ */
+export function formatForClaude(ctx: ProjectContext, config: AIToolConfig): string {
+  return `# ${ctx.name} - Project Rules
+<!-- projectId: ${ctx.projectId} -->
+<!-- Generated: ${new Date().toISOString()} -->
+<!-- Ecosystem: ${ctx.ecosystem} | Type: ${ctx.projectType} -->
+
+## THIS PROJECT (${ctx.ecosystem})
+
+**Type:** ${ctx.projectType}
+**Path:** ${ctx.repoPath}
+
+### Commands (USE THESE, NOT OTHERS)
+
+| Action | Command |
+|--------|---------|
+| Install dependencies | \`${ctx.commands.install}\` |
+| Run dev server | \`${ctx.commands.dev}\` |
+| Run tests | \`${ctx.commands.test}\` |
+| Build | \`${ctx.commands.build}\` |
+| Lint | \`${ctx.commands.lint}\` |
+| Format | \`${ctx.commands.format}\` |
+
+### Code Conventions
+
+- **Languages**: ${ctx.languages.join(', ') || 'Not detected'}
+- **Frameworks**: ${ctx.frameworks.join(', ') || 'Not detected'}
+
+---
+
+## PRJCT RULES
+
+### Path Resolution
+**ALL prjct writes go to**: \`~/.prjct-cli/projects/${ctx.projectId}/\`
+- NEVER write to \`.prjct/\`
+- NEVER write to \`./\` for prjct data
+
+### Workflow
+\`\`\`
+p. sync → p. task "desc" → [work] → p. done → p. ship
+\`\`\`
+
+| Command | Action |
+|---------|--------|
+| \`p. sync\` | Re-analyze project |
+| \`p. task X\` | Start task |
+| \`p. done\` | Complete subtask |
+| \`p. ship X\` | Ship feature |
+
+---
+
+## PROJECT STATE
+
+| Field | Value |
+|-------|-------|
+| Name | ${ctx.name} |
+| Version | ${ctx.version} |
+| Ecosystem | ${ctx.ecosystem} |
+| Branch | ${ctx.branch} |
+| Files | ~${ctx.fileCount} |
+| Commits | ${ctx.commits} |
+
+---
+
+## AGENTS
+
+Load from \`~/.prjct-cli/projects/${ctx.projectId}/agents/\`:
+
+**Workflow**: ${ctx.agents.workflow.join(', ')}
+**Domain**: ${ctx.agents.domain.join(', ') || 'none'}
+`
+}
+
+/**
+ * Format context for Cursor (.cursorrules)
+ * Concise rules format, optimized for inline suggestions
+ */
+export function formatForCursor(ctx: ProjectContext, config: AIToolConfig): string {
+  const rules: string[] = []
+
+  // Project identity
+  rules.push(`You are working on ${ctx.name}, a ${ctx.projectType} ${ctx.ecosystem} project.`)
+  rules.push('')
+
+  // Tech stack
+  rules.push('## Tech Stack')
+  if (ctx.languages.length > 0) {
+    rules.push(`- Languages: ${ctx.languages.join(', ')}`)
+  }
+  if (ctx.frameworks.length > 0) {
+    rules.push(`- Frameworks: ${ctx.frameworks.join(', ')}`)
+  }
+  rules.push('')
+
+  // Commands
+  rules.push('## Commands')
+  rules.push(`- Install: \`${ctx.commands.install}\``)
+  rules.push(`- Dev: \`${ctx.commands.dev}\``)
+  rules.push(`- Test: \`${ctx.commands.test}\``)
+  rules.push(`- Build: \`${ctx.commands.build}\``)
+  rules.push('')
+
+  // Code style - language agnostic
+  rules.push('## Code Style')
+  rules.push(`- Follow ${ctx.ecosystem} conventions`)
+  rules.push('- Match existing code patterns in this project')
+  rules.push('- Use idiomatic constructs for the language')
+  rules.push('')
+
+  // Best practices
+  rules.push('## Best Practices')
+  rules.push('- Write clean, readable code')
+  rules.push('- Add comments only for complex logic')
+  rules.push('- Keep functions small and focused')
+  rules.push('- Handle errors appropriately')
+  rules.push('- Write tests for new functionality')
+
+  return rules.join('\n')
+}
+
+/**
+ * Format context for GitHub Copilot (.github/copilot-instructions.md)
+ * Minimal bullet points
+ */
+export function formatForCopilot(ctx: ProjectContext, config: AIToolConfig): string {
+  const lines: string[] = []
+
+  lines.push('# Copilot Instructions')
+  lines.push('')
+  lines.push(`This is ${ctx.name}, a ${ctx.ecosystem} project.`)
+  lines.push('')
+
+  // Key info
+  lines.push('## Project Info')
+  lines.push(`- Type: ${ctx.projectType}`)
+  lines.push(`- Stack: ${ctx.frameworks.join(', ') || ctx.ecosystem}`)
+  lines.push('')
+
+  // Conventions
+  lines.push('## Conventions')
+  lines.push(`- Follow ${ctx.ecosystem} conventions`)
+  lines.push('- Match existing code patterns')
+  lines.push('- Keep code clean and readable')
+  lines.push('')
+
+  // Commands
+  lines.push('## Commands')
+  lines.push(`- Test: \`${ctx.commands.test}\``)
+  lines.push(`- Build: \`${ctx.commands.build}\``)
+
+  return lines.join('\n')
+}
+
+/**
+ * Format context for Windsurf (.windsurfrules)
+ * Optimized for Cascade AI with flow-based suggestions
+ */
+export function formatForWindsurf(ctx: ProjectContext, config: AIToolConfig): string {
+  const rules: string[] = []
+
+  // Project identity
+  rules.push(`# ${ctx.name}`)
+  rules.push('')
+  rules.push(`${ctx.projectType} project using ${ctx.ecosystem}.`)
+  rules.push('')
+
+  // Tech stack (concise)
+  rules.push('## Stack')
+  rules.push(`- ${ctx.languages.join(', ')}`)
+  if (ctx.frameworks.length > 0) {
+    rules.push(`- ${ctx.frameworks.join(', ')}`)
+  }
+  rules.push('')
+
+  // Commands (essential only)
+  rules.push('## Commands')
+  rules.push(`\`\`\`bash`)
+  rules.push(`# Install`)
+  rules.push(ctx.commands.install)
+  rules.push(`# Dev`)
+  rules.push(ctx.commands.dev)
+  rules.push(`# Test`)
+  rules.push(ctx.commands.test)
+  rules.push(`# Build`)
+  rules.push(ctx.commands.build)
+  rules.push(`\`\`\``)
+  rules.push('')
+
+  // Code style - language agnostic
+  rules.push('## Rules')
+  rules.push(`- Follow ${ctx.ecosystem} conventions`)
+  rules.push('- Match existing project patterns')
+  rules.push('- Clean code, minimal comments')
+  rules.push('- Test new functionality')
+
+  return rules.join('\n')
+}
+
+/**
+ * Format context for Continue.dev (.continue/config.json)
+ * JSON config with system message and context providers
+ */
+export function formatForContinue(ctx: ProjectContext, config: AIToolConfig): string {
+  const systemMessage = [
+    `You are working on ${ctx.name}, a ${ctx.projectType} ${ctx.ecosystem} project.`,
+    '',
+    `Stack: ${ctx.languages.join(', ')}${ctx.frameworks.length > 0 ? ` with ${ctx.frameworks.join(', ')}` : ''}`,
+    '',
+    'Commands:',
+    `- Install: ${ctx.commands.install}`,
+    `- Dev: ${ctx.commands.dev}`,
+    `- Test: ${ctx.commands.test}`,
+    `- Build: ${ctx.commands.build}`,
+    '',
+    `Follow ${ctx.ecosystem} conventions. Match existing code patterns.`,
+  ].join('\n')
+
+  const continueConfig = {
+    systemMessage,
+    models: [],
+    contextProviders: [
+      { name: 'code' },
+      { name: 'docs' },
+      { name: 'diff' },
+      { name: 'terminal' },
+      { name: 'problems' },
+      { name: 'folder' },
+      { name: 'codebase' },
+    ],
+    slashCommands: [
+      { name: 'edit', description: 'Edit selected code' },
+      { name: 'comment', description: 'Add comments to code' },
+      { name: 'share', description: 'Export conversation' },
+      { name: 'cmd', description: 'Run terminal command' },
+    ],
+    customCommands: [
+      {
+        name: 'test',
+        prompt: `Write tests for the selected code. Use the project's testing conventions. Test command: ${ctx.commands.test}`,
+      },
+    ],
+  }
+
+  return JSON.stringify(continueConfig, null, 2)
+}
+
+/**
+ * Get formatter function for a tool
+ */
+export function getFormatter(toolId: string): ((ctx: ProjectContext, config: AIToolConfig) => string) | null {
+  const formatters: Record<string, (ctx: ProjectContext, config: AIToolConfig) => string> = {
+    claude: formatForClaude,
+    cursor: formatForCursor,
+    copilot: formatForCopilot,
+    windsurf: formatForWindsurf,
+    continue: formatForContinue,
+  }
+
+  return formatters[toolId] || null
+}

package/core/ai-tools/generator.ts

@@ -0,0 +1,124 @@
+/**
+ * AI Tools Context Generator
+ *
+ * Generates optimized context files for each AI coding tool.
+ * Each tool gets context in its preferred format.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import { AI_TOOLS, DEFAULT_AI_TOOLS, getAIToolConfig, type AIToolConfig } from './registry'
+import { getFormatter, type ProjectContext } from './formatters'
+
+export interface GenerateResult {
+  toolId: string
+  outputFile: string
+  outputPath: string
+  success: boolean
+  error?: string
+}
+
+/**
+ * Generate context files for specified AI tools
+ */
+export async function generateAIToolContexts(
+  context: ProjectContext,
+  globalPath: string,
+  repoPath: string,
+  toolIds: string[] = DEFAULT_AI_TOOLS
+): Promise<GenerateResult[]> {
+  const results: GenerateResult[] = []
+
+  for (const toolId of toolIds) {
+    const config = getAIToolConfig(toolId)
+    if (!config) {
+      results.push({
+        toolId,
+        outputFile: '',
+        outputPath: '',
+        success: false,
+        error: `Unknown tool: ${toolId}`,
+      })
+      continue
+    }
+
+    const result = await generateForTool(context, config, globalPath, repoPath)
+    results.push(result)
+  }
+
+  return results
+}
+
+/**
+ * Generate context for a single AI tool
+ */
+async function generateForTool(
+  context: ProjectContext,
+  config: AIToolConfig,
+  globalPath: string,
+  repoPath: string
+): Promise<GenerateResult> {
+  const formatter = getFormatter(config.id)
+  if (!formatter) {
+    return {
+      toolId: config.id,
+      outputFile: config.outputFile,
+      outputPath: '',
+      success: false,
+      error: `No formatter for: ${config.id}`,
+    }
+  }
+
+  try {
+    // Generate content
+    const content = formatter(context, config)
+
+    // Determine output path
+    let outputPath: string
+    if (config.outputPath === 'repo') {
+      outputPath = path.join(repoPath, config.outputFile)
+    } else {
+      outputPath = path.join(globalPath, 'context', config.outputFile)
+    }
+
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(outputPath), { recursive: true })
+
+    // Write file
+    await fs.writeFile(outputPath, content, 'utf-8')
+
+    return {
+      toolId: config.id,
+      outputFile: config.outputFile,
+      outputPath,
+      success: true,
+    }
+  } catch (error) {
+    return {
+      toolId: config.id,
+      outputFile: config.outputFile,
+      outputPath: '',
+      success: false,
+      error: (error as Error).message,
+    }
+  }
+}
+
+/**
+ * Get list of files that would be generated
+ */
+export function getOutputFiles(
+  toolIds: string[] = DEFAULT_AI_TOOLS
+): { toolId: string; file: string; location: 'repo' | 'global' }[] {
+  return toolIds
+    .map(id => {
+      const config = AI_TOOLS[id]
+      if (!config) return null
+      return {
+        toolId: id,
+        file: config.outputFile,
+        location: config.outputPath,
+      }
+    })
+    .filter((item): item is NonNullable<typeof item> => item !== null)
+}

package/core/ai-tools/index.ts

@@ -0,0 +1,15 @@
+/**
+ * AI Tools Module
+ *
+ * Multi-agent context generation for AI coding tools.
+ * Supports: Claude Code, Cursor, Copilot, Windsurf, Continue.dev
+ *
+ * Features:
+ * - Auto-detection of installed tools
+ * - Language-agnostic formatters
+ * - Tool-specific output formats
+ */
+
+export * from './registry'
+export * from './formatters'
+export * from './generator'