prjct-cli 0.60.1 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [0.61.0] - 2026-02-05
+
+### Features
+
+- add .prjct-state.md local state file for persistence (PRJ-112) (#102)
+
+
+## [0.61.0] - 2026-02-05
+
+### Features
+
+- **Local state file (PRJ-112)**: New `.prjct-state.md` file generated in project root for local persistence
+
+### Implementation Details
+
+Created `LocalStateGenerator` service that generates a markdown file showing current task state. Integrated via write-through pattern - `StateStorage.write()` now also generates the local state file. Also hooks into `sync-service.ts` for state.json updates during sync.
+
+### Learnings
+
+- Write-through pattern: JSON storage triggers MD generation automatically
+- State can be written from multiple entry points (storage class + sync service) - need hooks in both places
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` on any project - verify `.prjct-state.md` is generated in project root
+2. Start a task with `p. task "test"` - verify `.prjct-state.md` updates with task info
+3. Check that subtasks, progress, and status are displayed correctly
+4. Verify the file has "DO NOT EDIT" header comment
+
+#### For Users
+- New `.prjct-state.md` file in project root shows current task state
+- Automatic - file updates whenever prjct state changes
+- No breaking changes
+
+
+## [0.60.2] - 2026-02-05
+
+### Performance
+
+- parallelize agent/skill loading with Promise.all (PRJ-110) (#101)
+
+
+## [0.60.2] - 2026-02-05
+
+### Performance
+
+- **Parallel agent/skill loading (PRJ-110)**: Agent and skill loading now uses `Promise.all` for parallel I/O
+
+### Implementation Details
+
+Refactored `loadAgents()` and `loadSkills()` in `core/agentic/orchestrator-executor.ts` to use `Promise.all` with map instead of sequential for loops. Also parallelized `loadAllAgents()` in `core/domain/agent-loader.ts`. Pattern: collect items → map to async promises → Promise.all → filter nulls with type guard.
+
+### Learnings
+
+- Use `Promise.all(items.map(async (item) => ...))` for parallel async operations
+- Return null for failed items, then filter - can't push to array in parallel
+- Collect unique items first (deduplication), then parallelize reads
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` - verify agents load successfully
+2. Run `p. task "test"` - verify orchestrator works
+3. Check no errors in agent/skill loading output
+
+#### For Users
+- Agent and skill loading is now faster (parallel I/O)
+- No changes needed - improvement is automatic
+
+
 ## [0.60.1] - 2026-02-05
 
 ### Bug Fixes

package/core/agentic/orchestrator-executor.ts

@@ -341,13 +341,15 @@ export class OrchestratorExecutor {
    *
    * Reads agent markdown files from {globalPath}/agents/
    * and extracts their content and skills from frontmatter.
+   *
+   * Uses parallel file reads for performance (PRJ-110).
    */
   async loadAgents(domains: string[], projectId: string): Promise<LoadedAgent[]> {
     const globalPath = pathManager.getGlobalProjectPath(projectId)
     const agentsDir = path.join(globalPath, 'agents')
-    const agents: LoadedAgent[] = []
 
-    for (const domain of domains) {
+    // Load all domain agents in parallel
+    const agentPromises = domains.map(async (domain): Promise<LoadedAgent | null> => {
       // Try exact match first, then variations
       const possibleNames = [`${domain}.md`, `${domain}-agent.md`, `prjct-${domain}.md`]
 
@@ -357,21 +359,22 @@ export class OrchestratorExecutor {
           const content = await fs.readFile(filePath, 'utf-8')
           const { frontmatter, body } = this.parseAgentFile(content)
 
-          agents.push({
+          return {
             name: fileName.replace('.md', ''),
             domain,
             content: body,
             skills: frontmatter.skills || [],
             filePath,
-          })
-
-          // Found one, no need to try other variations
-          break
-        } catch {}
+          }
+        } catch {
+          // Try next variation
+        }
       }
-    }
+      return null
+    })
 
-    return agents
+    const results = await Promise.all(agentPromises)
+    return results.filter((agent): agent is LoadedAgent => agent !== null)
   }
 
   /**
@@ -400,51 +403,46 @@ export class OrchestratorExecutor {
    * Load skills from agent frontmatter
    *
    * Skills are stored in ~/.claude/skills/{name}.md
+   *
+   * Uses parallel file reads for performance (PRJ-110).
    */
   async loadSkills(agents: LoadedAgent[]): Promise<LoadedSkill[]> {
     const skillsDir = path.join(os.homedir(), '.claude', 'skills')
-    const skills: LoadedSkill[] = []
-    const loadedSkillNames = new Set<string>()
 
+    // Collect unique skill names from all agents
+    const uniqueSkillNames = new Set<string>()
     for (const agent of agents) {
       for (const skillName of agent.skills) {
-        // Skip if already loaded
-        if (loadedSkillNames.has(skillName)) continue
+        uniqueSkillNames.add(skillName)
+      }
+    }
 
+    // Load all skills in parallel
+    const skillPromises = Array.from(uniqueSkillNames).map(
+      async (skillName): Promise<LoadedSkill | null> => {
         // Check both patterns: flat file and subdirectory (ecosystem standard)
         const flatPath = path.join(skillsDir, `${skillName}.md`)
         const subdirPath = path.join(skillsDir, skillName, 'SKILL.md')
 
-        let content: string | null = null
-        let resolvedPath = flatPath
-
         // Prefer subdirectory format (ecosystem standard)
         try {
-          content = await fs.readFile(subdirPath, 'utf-8')
-          resolvedPath = subdirPath
+          const content = await fs.readFile(subdirPath, 'utf-8')
+          return { name: skillName, content, filePath: subdirPath }
         } catch {
           // Fall back to flat file
           try {
-            content = await fs.readFile(flatPath, 'utf-8')
-            resolvedPath = flatPath
+            const content = await fs.readFile(flatPath, 'utf-8')
+            return { name: skillName, content, filePath: flatPath }
           } catch {
             // Skill not found - not an error, just skip
-            console.warn(`Skill not found: ${skillName}`)
+            return null
           }
         }
-
-        if (content) {
-          skills.push({
-            name: skillName,
-            content,
-            filePath: resolvedPath,
-          })
-          loadedSkillNames.add(skillName)
-        }
       }
-    }
+    )
 
-    return skills
+    const results = await Promise.all(skillPromises)
+    return results.filter((skill): skill is LoadedSkill => skill !== null)
   }
 
   /**

package/core/domain/agent-loader.ts

@@ -94,22 +94,22 @@ class AgentLoader {
 
   /**
    * Load all agents for the project
+   *
+   * Uses parallel file reads for performance (PRJ-110).
    */
   async loadAllAgents(): Promise<Agent[]> {
     try {
       const files = await fs.readdir(this.agentsDir)
       const agentFiles = files.filter((f) => f.endsWith('.md') && !f.startsWith('.'))
 
-      const agents: Agent[] = []
-      for (const file of agentFiles) {
+      // Load all agents in parallel
+      const agentPromises = agentFiles.map((file) => {
         const agentName = file.replace('.md', '')
-        const agent = await this.loadAgent(agentName)
-        if (agent) {
-          agents.push(agent)
-        }
-      }
+        return this.loadAgent(agentName)
+      })
 
-      return agents
+      const results = await Promise.all(agentPromises)
+      return results.filter((agent): agent is Agent => agent !== null)
     } catch (error) {
       if (isNotFoundError(error)) {
         return [] // Agents directory doesn't exist yet

package/core/services/local-state-generator.ts

@@ -0,0 +1,158 @@
+/**
+ * Local State Generator
+ *
+ * Generates .prjct-state.md in the project root for local persistence.
+ * This provides a quick reference to current task state without needing
+ * to access global storage.
+ *
+ * @see PRJ-112
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { StateJson } from '../schemas/state'
+import { isNotFoundError } from '../types/fs'
+
+const LOCAL_STATE_FILENAME = '.prjct-state.md'
+
+// Extended runtime types (state.json has fields not in strict schema)
+interface RuntimeTask {
+  description: string
+  startedAt: string
+  linearId?: string
+  branch?: string
+  status?: string
+  subtasks?: Array<{
+    description: string
+    status: string
+  }>
+  currentSubtaskIndex?: number
+}
+
+interface RuntimePreviousTask {
+  description: string
+  status: string
+  prUrl?: string
+}
+
+class LocalStateGenerator {
+  /**
+   * Generate .prjct-state.md in the project root
+   */
+  async generate(projectPath: string, state: StateJson): Promise<void> {
+    const filePath = path.join(projectPath, LOCAL_STATE_FILENAME)
+    const content = this.toMarkdown(state)
+    await fs.writeFile(filePath, content, 'utf-8')
+  }
+
+  /**
+   * Remove local state file
+   */
+  async remove(projectPath: string): Promise<void> {
+    const filePath = path.join(projectPath, LOCAL_STATE_FILENAME)
+    try {
+      await fs.unlink(filePath)
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error
+    }
+  }
+
+  /**
+   * Check if local state file exists
+   */
+  async exists(projectPath: string): Promise<boolean> {
+    const filePath = path.join(projectPath, LOCAL_STATE_FILENAME)
+    try {
+      await fs.access(filePath)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Convert state to markdown format
+   * Note: Uses runtime types since state.json has fields not in strict Zod schema
+   */
+  private toMarkdown(state: StateJson): string {
+    const lines: string[] = [
+      '<!-- Auto-generated by prjct - DO NOT EDIT -->',
+      '<!-- This file provides local state persistence for AI tools -->',
+      '',
+      '# prjct State',
+      '',
+    ]
+
+    if (state.currentTask) {
+      // Cast to runtime type (state.json has additional fields)
+      const task = state.currentTask as unknown as RuntimeTask
+      lines.push('## Current Task')
+      lines.push('')
+      lines.push(`**${task.description}**`)
+      lines.push('')
+      lines.push(`- Started: ${task.startedAt}`)
+      if (task.linearId) {
+        lines.push(`- Linear: ${task.linearId}`)
+      }
+      if (task.branch) {
+        lines.push(`- Branch: ${task.branch}`)
+      }
+      lines.push(`- Status: ${task.status || 'active'}`)
+      lines.push('')
+
+      // Subtasks
+      if (task.subtasks && task.subtasks.length > 0) {
+        lines.push('### Subtasks')
+        lines.push('')
+
+        task.subtasks.forEach((subtask, index) => {
+          const statusIcon =
+            subtask.status === 'completed' ? '✅' : subtask.status === 'in_progress' ? '▶️' : '⏳'
+          const isActive = index === task.currentSubtaskIndex ? ' ← **Active**' : ''
+          lines.push(`${index + 1}. ${statusIcon} ${subtask.description}${isActive}`)
+        })
+
+        lines.push('')
+
+        // Progress
+        const completed = task.subtasks.filter((s) => s.status === 'completed').length
+        const total = task.subtasks.length
+        const percentage = Math.round((completed / total) * 100)
+        lines.push(`**Progress**: ${completed}/${total} (${percentage}%)`)
+        lines.push('')
+      }
+    } else {
+      lines.push('*No active task*')
+      lines.push('')
+      lines.push('Start a task with `p. task "description"`')
+      lines.push('')
+    }
+
+    // Previous task info
+    if (state.previousTask) {
+      // Cast to runtime type
+      const prevTask = state.previousTask as unknown as RuntimePreviousTask
+      lines.push('---')
+      lines.push('')
+      lines.push('## Previous Task')
+      lines.push('')
+      lines.push(`**${prevTask.description}**`)
+      lines.push('')
+      lines.push(`- Status: ${prevTask.status}`)
+      if (prevTask.prUrl) {
+        lines.push(`- PR: ${prevTask.prUrl}`)
+      }
+      lines.push('')
+    }
+
+    // Footer
+    lines.push('---')
+    lines.push(`*Last updated: ${state.lastUpdated || new Date().toISOString()}*`)
+    lines.push('')
+
+    return lines.join('\n')
+  }
+}
+
+export const localStateGenerator = new LocalStateGenerator()
+export default localStateGenerator

package/core/services/sync-service.ts

@@ -33,6 +33,7 @@ import { metricsStorage } from '../storage/metrics-storage'
 import dateHelper from '../utils/date-helper'
 import { ContextFileGenerator } from './context-generator'
 import type { SyncDiff } from './diff-generator'
+import { localStateGenerator } from './local-state-generator'
 import { type StackDetection, StackDetector } from './stack-detector'
 
 const execAsync = promisify(exec)
@@ -826,6 +827,16 @@ You are the ${name} expert for this project. Apply best practices for the detect
     }
 
     await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf-8')
+
+    // Also generate local .prjct-state.md (PRJ-112)
+    try {
+      await localStateGenerator.generate(
+        this.projectPath,
+        state as import('../schemas/state').StateJson
+      )
+    } catch {
+      // Silently fail - local state is optional
+    }
   }
 
   // ==========================================================================

package/core/storage/state-storage.ts

@@ -3,6 +3,9 @@
  *
  * Manages current task state via storage/state.json
  * Generates context/now.md for Claude
+ *
+ * Note: Local .prjct-state.md is generated by sync-service which has access
+ * to projectPath. This class only has projectId.
  */
 
 import { generateUUID } from '../schemas'