prjct-cli 0.35.4 → 0.36.1

package/scripts/postinstall.js

@@ -1,136 +1,34 @@
 #!/usr/bin/env node
 
 /**
- * postinstall - Minimal, reliable setup
+ * postinstall - Minimal setup message
  *
- * CRITICAL: Only copies p.md router to ~/.claude/commands/
- * p.md reads templates from npm root, so updates work automatically.
- * Statusline is best-effort (optional).
+ * NOTE: postinstall often doesn't run (npm quirks, --ignore-scripts, etc.)
+ * The reliable setup path is `prjct start` which users run manually.
+ *
+ * This script just shows a helpful message.
  */
 
 const fs = require('fs')
 const path = require('path')
-const os = require('os')
 
 const ROOT = path.resolve(__dirname, '..')
-const HOME = os.homedir()
-const CLAUDE_DIR = path.join(HOME, '.claude')
-const COMMANDS_DIR = path.join(CLAUDE_DIR, 'commands')
-
-// Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'))
 const VERSION = pkg.version
 
-console.log('\n   prjct-cli postinstall\n')
-
-// 1. Copy p.md router (CRITICAL - main entry point)
-try {
-  fs.mkdirSync(COMMANDS_DIR, { recursive: true })
-
-  const pmdSrc = path.join(ROOT, 'templates', 'commands', 'p.md')
-  const pmdDest = path.join(COMMANDS_DIR, 'p.md')
-
-  if (fs.existsSync(pmdSrc)) {
-    fs.copyFileSync(pmdSrc, pmdDest)
-    console.log('   \u2713 p.md router installed')
-  } else {
-    console.log('   ! p.md not found in package')
-  }
-} catch (error) {
-  console.log('   ! Could not install p.md:', error.message)
-  console.log('   Run: npx prjct-cli setup')
-}
-
-// 2. Install individual commands as separate skills (p.task, p.sync, etc.)
-try {
-  const commandsDir = path.join(ROOT, 'templates', 'commands')
-  const commands = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md') && f !== 'p.md')
-
-  let installed = 0
-  for (const cmd of commands) {
-    const src = path.join(commandsDir, cmd)
-    const cmdName = cmd.replace('.md', '')
-    const dest = path.join(COMMANDS_DIR, `p.${cmdName}.md`)
-
-    try {
-      fs.copyFileSync(src, dest)
-      installed++
-    } catch {
-      // Skip files that fail to copy
-    }
-  }
-
-  console.log(`   \u2713 ${installed} individual commands installed (/p.task, /p.sync, etc.)`)
-} catch (error) {
-  console.log('   ! Could not install individual commands:', error.message)
-}
-
-// 3. Statusline (best-effort, not critical)
-try {
-  const STATUSLINE_SRC = path.join(ROOT, 'assets', 'statusline')
-  const STATUSLINE_DEST = path.join(HOME, '.prjct-cli', 'statusline')
-
-  if (fs.existsSync(STATUSLINE_SRC)) {
-    // Create dirs
-    fs.mkdirSync(path.join(STATUSLINE_DEST, 'lib'), { recursive: true })
-    fs.mkdirSync(path.join(STATUSLINE_DEST, 'components'), { recursive: true })
-    fs.mkdirSync(path.join(STATUSLINE_DEST, 'themes'), { recursive: true })
-
-    // Copy main script with version patched
-    const mainScript = path.join(STATUSLINE_SRC, 'statusline.sh')
-    if (fs.existsSync(mainScript)) {
-      let content = fs.readFileSync(mainScript, 'utf-8')
-      content = content.replace(/CLI_VERSION="[^"]*"/, `CLI_VERSION="${VERSION}"`)
-      fs.writeFileSync(path.join(STATUSLINE_DEST, 'statusline.sh'), content, { mode: 0o755 })
-    }
-
-    // Copy subdirs
-    for (const subdir of ['lib', 'components', 'themes']) {
-      const srcDir = path.join(STATUSLINE_SRC, subdir)
-      if (fs.existsSync(srcDir)) {
-        for (const f of fs.readdirSync(srcDir)) {
-          fs.copyFileSync(
-            path.join(srcDir, f),
-            path.join(STATUSLINE_DEST, subdir, f)
-          )
-        }
-      }
-    }
-
-    // Default config (only if not exists)
-    const configSrc = path.join(STATUSLINE_SRC, 'default-config.json')
-    const configDest = path.join(STATUSLINE_DEST, 'config.json')
-    if (fs.existsSync(configSrc) && !fs.existsSync(configDest)) {
-      fs.copyFileSync(configSrc, configDest)
-    }
+// Colors
+const CYAN = '\x1b[36m'
+const GREEN = '\x1b[32m'
+const DIM = '\x1b[2m'
+const BOLD = '\x1b[1m'
+const RESET = '\x1b[0m'
 
-    // Symlink in ~/.claude
-    const symlinkPath = path.join(CLAUDE_DIR, 'prjct-statusline.sh')
-    const targetPath = path.join(STATUSLINE_DEST, 'statusline.sh')
-    try {
-      if (fs.existsSync(symlinkPath)) fs.unlinkSync(symlinkPath)
-      if (fs.existsSync(targetPath)) fs.symlinkSync(targetPath, symlinkPath)
-    } catch {
-      // Symlink failed, copy instead
-      if (fs.existsSync(targetPath)) {
-        fs.copyFileSync(targetPath, symlinkPath)
-        fs.chmodSync(symlinkPath, 0o755)
-      }
-    }
+console.log(`
+${CYAN}${BOLD}   prjct${RESET} ${DIM}v${VERSION}${RESET}
 
-    // Update settings.json
-    const settingsPath = path.join(CLAUDE_DIR, 'settings.json')
-    let settings = {}
-    if (fs.existsSync(settingsPath)) {
-      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) } catch {}
-    }
-    settings.statusLine = { type: 'command', command: symlinkPath }
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2))
+   ${GREEN}✓${RESET} Installed successfully!
 
-    console.log('   \u2713 statusline installed')
-  }
-} catch {
-  // Statusline is optional, don't fail
-}
+   ${BOLD}Next step:${RESET} Run ${CYAN}prjct start${RESET} to configure your AI providers.
 
-console.log('\n')
+   ${DIM}Supports: Claude Code, Gemini CLI, or both${RESET}
+`)

package/templates/agents/AGENTS.md

@@ -1,6 +1,14 @@
 # AGENTS.md
 
-AI assistant guidance for **prjct-cli** - developer momentum tool.
+AI assistant guidance for **prjct-cli** - context layer for AI coding agents. Works with Claude Code, Gemini CLI, and more.
+
+## What This Is
+
+**NOT** project management. NO sprints, story points, ceremonies, or meetings.
+
+**IS** a context layer that gives AI agents the project knowledge they need to work effectively.
+
+---
 
 ## Dynamic Agent Generation
 

package/templates/commands/p.md

@@ -1,5 +1,5 @@
 ---
-description: 'prjct CLI - Developer momentum tool'
+description: 'prjct CLI - Context layer for AI agents'
 allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion, TodoWrite, WebFetch]
 ---
 

package/templates/commands/p.toml

@@ -0,0 +1,37 @@
+# prjct Command Router for Gemini CLI
+description = "prjct - Context layer for AI coding agents"
+
+prompt = """
+# prjct Command Router
+
+You are using prjct, a context layer for AI coding agents.
+
+**ARGUMENTS**: {{args}}
+
+## Instructions
+
+1. Parse arguments: first word = `command`, rest = `commandArgs`
+2. Get npm global root by running: `npm root -g`
+3. Read the command template from:
+   `{npmRoot}/prjct-cli/templates/commands/{command}.md`
+4. Execute the template with `commandArgs` as input
+
+## Example
+
+If arguments = "task fix the login bug":
+- command = "task"
+- commandArgs = "fix the login bug"
+- npm root -g → `/opt/homebrew/lib/node_modules`
+- Read: `/opt/homebrew/lib/node_modules/prjct-cli/templates/commands/task.md`
+- Execute template with: "fix the login bug"
+
+## Available Commands
+
+task, done, ship, sync, init, idea, dash, next, pause, resume, bug,
+linear, feature, prd, plan, review, merge, git, test, cleanup,
+design, analyze, history, enrich, update
+
+## Action
+
+NOW run `npm root -g` and read the appropriate command template.
+"""

package/templates/global/CLAUDE.md

@@ -1,7 +1,7 @@
 <!-- prjct:start - DO NOT REMOVE THIS MARKER -->
 # prjct-cli
 
-**Developer momentum tool** - Track progress through natural language commands without PM overhead.
+**Context layer for AI agents** - Project context for Claude Code, Gemini CLI, and more.
 
 ## HOW TO USE PRJCT (Read This First)
 
@@ -56,6 +56,38 @@ Designed for [Claude](https://www.anthropic.com/claude)
 
 **This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
 
+### 5. Storage Rules (CROSS-AGENT COMPATIBILITY)
+
+**NEVER use temporary files** - Write directly to final destination:
+- WRONG: Create `.tmp/file.json`, then `mv` to final path
+- CORRECT: Write directly to `{globalPath}/storage/state.json`
+
+**JSON formatting** - Always use consistent format:
+- 2-space indentation
+- No trailing commas
+- Keys in logical order (as defined in storage schemas)
+
+**Atomic writes for JSON**:
+```javascript
+// Read → Modify → Write (no temp files)
+const data = JSON.parse(fs.readFileSync(path, 'utf-8'))
+data.newField = value
+fs.writeFileSync(path, JSON.stringify(data, null, 2))
+```
+
+**Timestamps**: Always ISO-8601 with milliseconds (`.000Z`)
+**UUIDs**: Always v4 format (lowercase)
+**Line endings**: LF (not CRLF)
+**Encoding**: UTF-8 without BOM
+
+**NEVER**:
+- Use `.tmp/` directories
+- Use `mv` or `rename` operations for storage files
+- Create backup files like `*.bak` or `*.old`
+- Modify existing lines in `events.jsonl`
+
+**Full specification**: Install prjct-cli and see `{npm root -g}/prjct-cli/templates/global/STORAGE-SPEC.md`
+
 ---
 
 ## CORE WORKFLOW

package/templates/global/GEMINI.md

@@ -0,0 +1,265 @@
+<!-- prjct:start - DO NOT REMOVE THIS MARKER -->
+# prjct-cli
+
+**Context layer for AI agents** - Project context for Claude Code, Gemini CLI, and more.
+
+## HOW TO USE PRJCT (Read This First)
+
+When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it intelligently.
+
+```
+p. sync     → templates/commands/sync.md
+p. task X   → templates/commands/task.md
+p. done     → templates/commands/done.md
+p. ship X   → templates/commands/ship.md
+```
+
+**Key Insight**: Templates are GUIDANCE, not scripts. Use your intelligence to adapt them to the situation.
+
+---
+
+## CRITICAL RULES
+
+### 1. Path Resolution (MOST IMPORTANT)
+**ALL writes go to global storage**: `~/.prjct-cli/projects/{projectId}/`
+
+- **NEVER** write to `.prjct/` (config only, read-only)
+- **NEVER** write to `./` (current directory)
+- **ALWAYS** resolve projectId first from `.prjct/prjct.config.json`
+
+### 2. Before Any Command
+```
+1. Read .prjct/prjct.config.json → get projectId
+2. Set globalPath = ~/.prjct-cli/projects/{projectId}
+3. Execute command using globalPath for all writes
+4. Log to {globalPath}/memory/events.jsonl
+```
+
+### 3. Timestamps & UUIDs
+```bash
+# Timestamp (NEVER hardcode)
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+
+# UUID
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```
+
+### 4. Git Commit Footer (CRITICAL - ALWAYS INCLUDE)
+
+**Every commit made with prjct MUST include this footer:**
+
+```
+🤖 Generated with [p/](https://www.prjct.app/)
+Designed for [Gemini](https://geminicli.com/)
+
+```
+
+**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
+
+### 5. Storage Rules (CROSS-AGENT COMPATIBILITY)
+
+**NEVER use temporary files** - Write directly to final destination:
+- WRONG: Create `.tmp/file.json`, then `mv` to final path
+- CORRECT: Write directly to `{globalPath}/storage/state.json`
+
+**JSON formatting** - Always use consistent format:
+- 2-space indentation
+- No trailing commas
+- Keys in logical order (as defined in storage schemas)
+
+**Atomic writes for JSON**:
+```javascript
+// Read → Modify → Write (no temp files)
+const data = JSON.parse(fs.readFileSync(path, 'utf-8'))
+data.newField = value
+fs.writeFileSync(path, JSON.stringify(data, null, 2))
+```
+
+**Timestamps**: Always ISO-8601 with milliseconds (`.000Z`)
+**UUIDs**: Always v4 format (lowercase)
+**Line endings**: LF (not CRLF)
+**Encoding**: UTF-8 without BOM
+
+**NEVER**:
+- Use `.tmp/` directories
+- Use `mv` or `rename` operations for storage files
+- Create backup files like `*.bak` or `*.old`
+- Modify existing lines in `events.jsonl`
+
+**Full specification**: Install prjct-cli and see `{npm root -g}/prjct-cli/templates/global/STORAGE-SPEC.md`
+
+---
+
+## CORE WORKFLOW
+
+```
+p. sync  →  p. task "description"  →  [work]  →  p. done  →  p. ship
+   │              │                                  │            │
+   │              └─ Creates branch, breaks down     │            │
+   │                 task, starts tracking           │            │
+   │                                                 │            │
+   └─ Analyzes project, generates agents             │            │
+                                                     │            │
+                              Completes subtask ─────┘            │
+                                                                  │
+                                        Ships feature, PR, tag ───┘
+```
+
+### Quick Reference
+
+| Trigger | What It Does |
+|---------|--------------|
+| `p. sync` | Analyze project, generate domain agents |
+| `p. task <desc>` | Start task with auto-classification |
+| `p. done` | Complete current subtask |
+| `p. ship [name]` | Ship feature with PR + version bump |
+| `p. pause` | Pause current task |
+| `p. resume` | Resume paused task |
+| `p. bug <desc>` | Report bug with auto-priority |
+
+---
+
+## ARCHITECTURE: Write-Through Pattern
+
+```
+User Action → Storage (JSON) → Context (MD) → Sync Events
+```
+
+| Layer | Path | Purpose |
+|-------|------|---------|
+| **Storage** | `storage/*.json` | Source of truth |
+| **Context** | `context/*.md` | AI-readable summaries |
+| **Memory** | `memory/events.jsonl` | Audit trail (append-only) |
+| **Agents** | `agents/*.md` | Domain specialists |
+| **Sync** | `sync/pending.json` | Backend sync queue |
+
+### File Structure
+```
+~/.prjct-cli/projects/{projectId}/
+├── storage/
+│   ├── state.json      # Current task (SOURCE OF TRUTH)
+│   ├── queue.json      # Task queue
+│   └── shipped.json    # Shipped features
+├── context/
+│   ├── now.md          # Current task (generated)
+│   └── next.md         # Queue (generated)
+├── config/
+│   └── skills.json     # Agent-to-skill mappings
+├── memory/
+│   └── events.jsonl    # Audit trail
+├── agents/             # Domain specialists (auto-generated)
+└── sync/
+    └── pending.json    # Events for backend
+```
+
+---
+
+## INTELLIGENT BEHAVIOR
+
+### When Starting Tasks (`p. task`)
+1. **Analyze** - Understand what user wants to achieve
+2. **Classify** - Determine type: feature, bug, improvement, refactor, chore
+3. **Explore** - Find similar code, patterns, affected files
+4. **Ask** - Clarify ambiguities
+5. **Design** - Propose 2-3 approaches, get approval
+6. **Break down** - Create actionable subtasks
+7. **Track** - Update storage/state.json
+
+### When Completing Tasks (`p. done`)
+1. Check if there are more subtasks
+2. If yes, advance to next subtask
+3. If no, task is complete
+4. Update storage, generate context
+
+### When Shipping (`p. ship`)
+1. Run tests (if configured)
+2. Create PR (if on feature branch)
+3. Bump version
+4. Update CHANGELOG
+5. Create git tag
+
+### Key Intelligence Rules
+- **Read before write** - Always read existing files before modifying
+- **Explore before coding** - Understand codebase first
+- **Ask when uncertain** - Clarify ambiguities
+- **Adapt templates** - Templates are guidance, not rigid scripts
+- **Log everything** - Append to memory/events.jsonl
+
+---
+
+## OUTPUT FORMAT
+
+Concise responses (< 4 lines):
+```
+✅ [What was done]
+
+[Key metrics]
+Next: [suggested action]
+```
+
+---
+
+## LOADING DOMAIN AGENTS
+
+When working on tasks, load relevant agents from `{globalPath}/agents/`:
+- `frontend.md` - Frontend patterns, components
+- `backend.md` - Backend patterns, APIs
+- `database.md` - Database patterns, queries
+- `uxui.md` - UX/UI guidelines
+- `testing.md` - Testing patterns
+- `devops.md` - CI/CD, containers
+
+These agents contain project-specific patterns. **USE THEM**.
+
+---
+
+## SKILL INTEGRATION
+
+Agents can be linked to skills for specialized expertise.
+
+### How Skills Work
+
+1. **During `p. sync`**: Skills are discovered and installed
+2. **During `p. task`**: Skills are auto-invoked for domain expertise
+3. **Agent frontmatter** has `skills: [skill-name]` field
+
+### Skill Location
+
+Skills are SKILL.md files in `~/.gemini/skills/{skill-name}/`
+
+**Note**: Gemini CLI and Claude Code use the same SKILL.md format, so skills are compatible between both agents.
+
+### Skill Configuration
+
+After sync: `{globalPath}/config/skills.json` contains skill mappings.
+
+---
+
+## GEMINI-SPECIFIC FEATURES
+
+### Context Hierarchy
+
+Gemini CLI loads GEMINI.md files hierarchically:
+1. Global: `~/.gemini/GEMINI.md`
+2. Project ancestors: Walk up to `.git` root
+3. Subdirectories: Scan below cwd (respects `.geminiignore`)
+
+### Modular Imports
+
+You can import content from other files using `@file.md` syntax:
+```markdown
+@./components/instructions.md
+@../shared/style-guide.md
+```
+
+### Memory Commands
+
+- `/memory show` - Display loaded context
+- `/memory refresh` - Reload all GEMINI.md files
+- `/memory add <text>` - Add to global context
+
+---
+
+**Auto-managed by prjct-cli** | https://prjct.app | v0.27.0
+
+<!-- prjct:end - DO NOT REMOVE THIS MARKER -->