@champpaba/claude-agent-kit 2.0.1 → 2.1.1

package/.claude/CLAUDE.md

@@ -103,6 +103,13 @@ Universal, framework-agnostic template for AI-assisted development.
 - `/cdev {change-id}` - Start/continue multi-agent development
 - `/cview {change-id}` - View detailed progress for a change
 - `/cstatus {change-id}` - Quick progress status for a change
+- `/pstatus` - Update PROJECT_STATUS.yml (cross-session context)
+
+**Cross-Session Context (v2.1.0):**
+- `PROJECT_STATUS.yml` (project root) - Quick context snapshot for new sessions
+- Contains: infrastructure state, blockers, completed work, next priorities
+- Created by: `cak init` (optional) or manually
+- Updated by: `/pstatus` command or Main Claude prompts
 
 **Best Practices (Dynamic):**
 - `.claude/contexts/domain/project/best-practices/` (auto-generated by `/csetup`)
@@ -378,4 +385,54 @@ Beyond the 6 agent files, these supporting files were also updated:
 
 ---
 
+## 📊 PROJECT_STATUS.yml Protocol (v2.1.0)
+
+**WHY this exists:** New Claude sessions lose context about infrastructure state, blockers, and priorities. This file provides a quick snapshot.
+
+### Session Start Behavior
+
+If `PROJECT_STATUS.yml` exists in project root:
+1. Read it first before other files
+2. Note: `current_focus`, `blockers`, `infrastructure` state
+3. If `last_updated` > 7 days (or `_config.stale_warning_days`) → Suggest: "PROJECT_STATUS.yml may be outdated. Run /pstatus?"
+
+### Intelligent Update Prompts
+
+Prompt "Update PROJECT_STATUS.yml?" when detecting these patterns:
+
+| Event Detected | What to Update |
+|----------------|----------------|
+| After `/openspec:archive` completes | Add to `completed_changes` |
+| User says "waiting for...", "need X from...", "blocked by..." | Add to `blockers` |
+| User mentions blocker resolved | Remove from `blockers` |
+| Infrastructure change (deploy, tunnel, DB migration) | Update `infrastructure` |
+| User discusses priority shift | Update `next_priorities` |
+| `/csetup {change-id}` started | Update `current_focus.active_change` |
+
+### Update Protocol
+
+- Always ask before modifying (user confirms)
+- Use `/pstatus` for comprehensive review
+- Keep updates atomic (one section at a time during work)
+- Auto-detect archived changes not listed and suggest additions
+
+### Example Interaction
+
+```
+# Session start
+Claude: *reads PROJECT_STATUS.yml*
+Claude: "I see auth-system is active, tunnel running but waiting for domain."
+
+# During work
+User: "Domain is now configured"
+Claude: "Update PROJECT_STATUS.yml?
+         - Remove 'domain' from blockers
+         - Update cloudflare_tunnel.waiting_for to null"
+
+# After archiving
+Claude: "Auth-system archived. Add to completed_changes?"
+```
+
+---
+
 **💡 Remember:** This template is universal. Use Context7 for framework-specific docs!

package/.claude/commands/csetup.md

@@ -35,6 +35,81 @@ If not found:
 Please create the change with OpenSpec first
 ```
 
+### Step 1.5: Read PROJECT_STATUS.yml (v2.1.0)
+
+**WHY:** Cross-session context helps understand blockers and infrastructure state before starting work.
+
+```typescript
+const projectStatusPath = 'PROJECT_STATUS.yml'
+
+if (fileExists(projectStatusPath)) {
+  const projectStatus = parseYaml(Read(projectStatusPath))
+
+  output(`\n📊 Project Context (from PROJECT_STATUS.yml)`)
+
+  // Show current focus
+  if (projectStatus.current_focus?.description) {
+    output(`   Focus: ${projectStatus.current_focus.description}`)
+  }
+
+  // Check for blockers that might affect this change
+  if (projectStatus.blockers?.length > 0) {
+    const relevantBlockers = projectStatus.blockers.filter(b =>
+      b.blocks?.some(blocked =>
+        blocked.toLowerCase().includes(changeId.toLowerCase()) ||
+        changeId.toLowerCase().includes(blocked.toLowerCase())
+      )
+    )
+
+    if (relevantBlockers.length > 0) {
+      output(`\n   ⚠️ Potential blockers for this change:`)
+      relevantBlockers.forEach(b => {
+        output(`      - ${b.id}: ${b.description}`)
+      })
+      output(`\n   Consider resolving blockers before starting.`)
+    }
+  }
+
+  // Show infrastructure status summary
+  if (projectStatus.infrastructure) {
+    const downServices = Object.entries(projectStatus.infrastructure)
+      .filter(([_, info]) => info.status === 'down' || info.status === 'degraded')
+
+    if (downServices.length > 0) {
+      output(`\n   ⚠️ Infrastructure issues:`)
+      downServices.forEach(([service, info]) => {
+        output(`      - ${service}: ${info.status}${info.notes ? ` (${info.notes})` : ''}`)
+      })
+    }
+  }
+
+  // Check stale status
+  const lastUpdated = new Date(projectStatus.last_updated)
+  const daysSinceUpdate = Math.floor((Date.now() - lastUpdated) / (1000 * 60 * 60 * 24))
+  const staleThreshold = projectStatus._config?.stale_warning_days || 7
+
+  if (daysSinceUpdate > staleThreshold) {
+    output(`\n   ℹ️ PROJECT_STATUS.yml last updated ${daysSinceUpdate} days ago.`)
+    output(`      Consider running /pstatus to refresh.`)
+  }
+
+  // Update active change
+  if (projectStatus.current_focus?.active_change !== changeId) {
+    output(`\n   📍 Update current_focus.active_change to "${changeId}"? (yes/no)`)
+    const updateFocus = await askUser()
+    if (updateFocus) {
+      projectStatus.current_focus = projectStatus.current_focus || {}
+      projectStatus.current_focus.active_change = changeId
+      projectStatus.last_updated = new Date().toISOString().split('T')[0]
+      Write(projectStatusPath, toYaml(projectStatus))
+      output(`   ✅ Updated active_change to "${changeId}"`)
+    }
+  }
+
+  output(``) // Blank line
+}
+```
+
 ### Step 2: Read OpenSpec Files
 
 Read in order:

package/.claude/commands/cstatus.md

@@ -1,6 +1,6 @@
 ---
 name: Change Status
-description: Quick progress status for a change
+description: Quick progress status for a change (with project context)
 category: Multi-Agent
 tags: [status, progress, quick]
 ---
@@ -9,20 +9,88 @@ tags: [status, progress, quick]
 
 ```bash
 /cstatus {change-id}
+/cstatus                # Shows project status only (no change-id)
 ```
 
 ## What It Does
 
 Shows quick progress summary:
+- **Project context** (from PROJECT_STATUS.yml if exists)
 - Progress percentage with bar
 - Current phase
 - Time spent/remaining
 - Quick stats
 
+---
+
+## Step 1: Show Project Context (v2.1.0)
+
+```typescript
+const projectStatusPath = 'PROJECT_STATUS.yml'
+
+if (fileExists(projectStatusPath)) {
+  const projectStatus = parseYaml(Read(projectStatusPath))
+
+  output(`
+📊 Project Status
+├─ Focus: ${projectStatus.current_focus?.description || 'Not set'}
+├─ Active change: ${projectStatus.current_focus?.active_change || 'None'}
+├─ Blockers: ${projectStatus.blockers?.length || 0}
+├─ Infra: ${summarizeInfraStatus(projectStatus.infrastructure)}
+└─ Updated: ${projectStatus.last_updated}
+`)
+
+  // Show blockers if any
+  if (projectStatus.blockers?.length > 0) {
+    output(`
+🚧 Active Blockers:
+${projectStatus.blockers.map(b => `   - ${b.id}: ${b.description}`).join('\n')}
+`)
+  }
+}
+
+// If no change-id provided, stop here
+if (!changeId) {
+  output(`
+Commands:
+→ Update project status: /pstatus
+→ View change status: /cstatus {change-id}
+`)
+  return
+}
+```
+
+---
+
+## Step 2: Show Change Status
+
+```typescript
+// Read change flags
+const flagsPath = `openspec/changes/${changeId}/.claude/flags.json`
+
+if (!fileExists(flagsPath)) {
+  return output(`❌ Change ${changeId} not found or not set up. Run /csetup ${changeId} first.`)
+}
+
+const flags = JSON.parse(Read(flagsPath))
+```
+
 ## Output Format
 
 ```
-📊 CHANGE-{id}: {type} | {template}
+📊 Project Status
+├─ Focus: Building authentication system
+├─ Active change: auth-system
+├─ Blockers: 1
+├─ Infra: DB ✅ | API ✅ | Tunnel ⏳
+└─ Updated: 2025-11-30
+
+🚧 Active Blockers:
+   - domain-config: Need domain for Cloudflare public routes
+
+─────────────────────────────────────────
+
+📦 CHANGE-{id}: {type} | {template}
 
 Progress: [████████░░] 64% (7/11 phases)
 
@@ -51,10 +119,35 @@ Current Phase: #8 Refactor (test-debug)
 3. Documentation (15 min)
 
 Commands:
+→ Update project status: /pstatus
 → Detailed view: /cview {change-id}
 → Continue dev: /cdev {change-id}
 ```
 
-## Implementation
+---
+
+## Helper: summarizeInfraStatus()
+
+```typescript
+function summarizeInfraStatus(infrastructure) {
+  if (!infrastructure) return 'Not configured'
+
+  return Object.entries(infrastructure)
+    .map(([service, info]) => {
+      const icon = info.status === 'healthy' ? '✅' :
+                   info.status === 'degraded' ? '⚠️' :
+                   info.status === 'down' ? '❌' :
+                   info.status === 'waiting' ? '⏳' : '❓'
+      return `${service} ${icon}`
+    })
+    .join(' | ')
+}
+```
+
+---
+
+## Implementation Notes
 
-Read `openspec/changes/{change-id}/.claude/flags.json` and format output using helper functions.
+1. **Always show project status first** (if PROJECT_STATUS.yml exists)
+2. **Then show change status** (if change-id provided)
+3. **Include /pstatus in commands** to encourage keeping status updated

package/.claude/commands/pstatus.md

@@ -0,0 +1,431 @@
+---
+name: Project Status
+description: Update PROJECT_STATUS.yml for cross-session context
+category: Multi-Agent
+tags: [status, context, cross-session]
+---
+
+## Usage
+
+```bash
+/pstatus
+/pstatus quick     # Quick update (outdated sections only)
+/pstatus full      # Full review (all sections)
+/pstatus blockers  # Update blockers section only
+```
+
+## What It Does
+
+Interactive update of `PROJECT_STATUS.yml` - the cross-session context file that helps Claude understand project state in new sessions.
+
+**WHY this exists:** New Claude sessions lose context about infrastructure, blockers, and priorities. This command helps maintain that context.
+
+---
+
+## Step 1: Check File Exists
+
+```typescript
+const statusPath = 'PROJECT_STATUS.yml'
+
+if (!fileExists(statusPath)) {
+  output(`
+📊 PROJECT_STATUS.yml not found
+
+This file provides cross-session context for Claude.
+It helps new sessions understand:
+- Infrastructure state (DB, API, tunnels)
+- Blockers (waiting for domain, API keys)
+- Completed work & next priorities
+
+Create it now? (yes/no)
+  `)
+
+  const answer = await askUser()
+  if (answer === 'yes') {
+    // Copy from template
+    copy('.claude/templates/PROJECT_STATUS.template.yml', statusPath)
+    output('✅ Created PROJECT_STATUS.yml - please fill in your project details')
+    return
+  } else {
+    return output('Skipped. Run /pstatus again when ready.')
+  }
+}
+```
+
+---
+
+## Step 2: Read Current Status
+
+```typescript
+const status = parseYaml(Read(statusPath))
+const lastUpdated = new Date(status.last_updated)
+const daysSinceUpdate = Math.floor((Date.now() - lastUpdated) / (1000 * 60 * 60 * 24))
+
+output(`
+📊 PROJECT_STATUS.yml
+
+Last updated: ${status.last_updated} (${daysSinceUpdate} days ago)
+Current focus: ${status.current_focus?.description || 'Not set'}
+Active change: ${status.current_focus?.active_change || 'None'}
+Blockers: ${status.blockers?.length || 0}
+Completed changes: ${status.completed_changes?.length || 0}
+`)
+```
+
+---
+
+## Step 3: Select Update Mode
+
+```typescript
+// If mode provided via argument, use it
+// Otherwise, ask user
+
+const mode = args[0] || await askUserQuestion({
+  questions: [{
+    question: 'What would you like to update?',
+    header: 'Mode',
+    options: [
+      { label: 'Quick Update', description: 'Only sections that seem outdated' },
+      { label: 'Full Review', description: 'Walk through all sections' },
+      { label: 'Specific Section', description: 'Update one section only' }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+---
+
+## Step 4: Section-by-Section Updates
+
+### 4.1 Update `last_updated`
+
+```typescript
+// Always update timestamp
+status.last_updated = new Date().toISOString().split('T')[0]
+```
+
+### 4.2 Update `current_focus`
+
+```typescript
+output(`
+📍 Current Focus
+   Description: "${status.current_focus?.description || 'Not set'}"
+   Active change: ${status.current_focus?.active_change || 'None'}
+`)
+
+const updateFocus = await askUserQuestion({
+  questions: [{
+    question: 'Update current focus?',
+    header: 'Focus',
+    options: [
+      { label: 'Keep as is', description: 'No changes needed' },
+      { label: 'Update description', description: 'Change what you are working on' },
+      { label: 'Set active change', description: 'Link to OpenSpec change' },
+      { label: 'Clear active change', description: 'Not working on a change' }
+    ],
+    multiSelect: false
+  }]
+})
+
+// Handle user selection...
+```
+
+### 4.3 Update `completed_changes`
+
+```typescript
+output(`
+✅ Completed Changes (${status.completed_changes?.length || 0})
+${status.completed_changes?.map(c => `   - ${c.id} (${c.date}): ${c.summary}`).join('\n') || '   (none)'}
+`)
+
+// Auto-detect archived changes not in list
+const archivedChanges = listFiles('openspec/changes/archive/')
+const missingChanges = archivedChanges.filter(dir => {
+  const id = path.basename(dir)
+  return !status.completed_changes?.some(c => c.id === id)
+})
+
+if (missingChanges.length > 0) {
+  output(`
+📦 Found ${missingChanges.length} archived change(s) not in completed_changes:
+${missingChanges.map(c => `   - ${path.basename(c)}`).join('\n')}
+
+Add them? (yes/no)
+  `)
+
+  const addMissing = await askUser()
+  if (addMissing) {
+    for (const changePath of missingChanges) {
+      const id = path.basename(changePath)
+      // Try to read proposal.md for summary
+      const proposalPath = `${changePath}/proposal.md`
+      let summary = 'No summary available'
+      if (fileExists(proposalPath)) {
+        const proposal = Read(proposalPath)
+        // Extract first sentence or title
+        summary = extractSummary(proposal)
+      }
+
+      status.completed_changes = status.completed_changes || []
+      status.completed_changes.push({
+        id,
+        date: new Date().toISOString().split('T')[0],
+        summary
+      })
+      output(`   ✅ Added: ${id}`)
+    }
+  }
+}
+```
+
+### 4.4 Update `infrastructure`
+
+```typescript
+output(`
+🏗️ Infrastructure Status
+${Object.entries(status.infrastructure || {}).map(([service, info]) =>
+  `   ${service}: ${info.status}${info.waiting_for ? ` (waiting: ${info.waiting_for})` : ''}${info.notes ? ` - ${info.notes}` : ''}`
+).join('\n') || '   (none configured)'}
+`)
+
+const updateInfra = await askUserQuestion({
+  questions: [{
+    question: 'Update infrastructure status?',
+    header: 'Infra',
+    options: [
+      { label: 'Keep as is', description: 'No changes needed' },
+      { label: 'Update status', description: 'Change service status' },
+      { label: 'Add service', description: 'Track new infrastructure' },
+      { label: 'Remove service', description: 'Stop tracking a service' }
+    ],
+    multiSelect: false
+  }]
+})
+
+// Handle user selection...
+// For status update, walk through each service:
+if (updateInfra === 'Update status') {
+  for (const [service, info] of Object.entries(status.infrastructure || {})) {
+    output(`\n${service}: Currently "${info.status}"`)
+    const newStatus = await askUserQuestion({
+      questions: [{
+        question: `Update ${service} status?`,
+        header: service,
+        options: [
+          { label: 'healthy', description: 'Working normally' },
+          { label: 'degraded', description: 'Working with issues' },
+          { label: 'down', description: 'Not working' },
+          { label: 'waiting', description: 'Pending external action' },
+          { label: 'Keep current', description: `Stay as "${info.status}"` }
+        ],
+        multiSelect: false
+      }]
+    })
+
+    if (newStatus !== 'Keep current') {
+      status.infrastructure[service].status = newStatus
+
+      // If changed to healthy, clear waiting_for
+      if (newStatus === 'healthy') {
+        status.infrastructure[service].waiting_for = null
+      }
+
+      // If changed to waiting, ask what for
+      if (newStatus === 'waiting') {
+        output('What is it waiting for?')
+        status.infrastructure[service].waiting_for = await askUser()
+      }
+    }
+  }
+}
+```
+
+### 4.5 Update `blockers`
+
+```typescript
+output(`
+🚧 Blockers (${status.blockers?.length || 0})
+${status.blockers?.map(b => `   - ${b.id}: ${b.description} (blocks: ${b.blocks?.join(', ') || 'nothing specified'})`).join('\n') || '   (none)'}
+`)
+
+const updateBlockers = await askUserQuestion({
+  questions: [{
+    question: 'Update blockers?',
+    header: 'Blockers',
+    options: [
+      { label: 'Keep as is', description: 'No changes needed' },
+      { label: 'Add blocker', description: 'New external dependency' },
+      { label: 'Remove blocker', description: 'Blocker resolved' },
+      { label: 'Update blocker', description: 'Change existing blocker' }
+    ],
+    multiSelect: false
+  }]
+})
+
+// Handle user selection...
+```
+
+### 4.6 Update `next_priorities`
+
+```typescript
+output(`
+🎯 Next Priorities
+${status.next_priorities?.map((p, i) => `   ${i + 1}. ${p.id}: ${p.reason}`).join('\n') || '   (none set)'}
+`)
+
+const updatePriorities = await askUserQuestion({
+  questions: [{
+    question: 'Update priorities?',
+    header: 'Priorities',
+    options: [
+      { label: 'Keep as is', description: 'No changes needed' },
+      { label: 'Add priority', description: 'New item to work on' },
+      { label: 'Remove priority', description: 'Completed or deprioritized' },
+      { label: 'Reorder', description: 'Change priority order' }
+    ],
+    multiSelect: false
+  }]
+})
+
+// Handle user selection...
+```
+
+### 4.7 Update `notes`
+
+```typescript
+output(`
+📝 Notes
+${status.notes || '   (empty)'}
+`)
+
+const updateNotes = await askUserQuestion({
+  questions: [{
+    question: 'Update notes?',
+    header: 'Notes',
+    options: [
+      { label: 'Keep as is', description: 'No changes needed' },
+      { label: 'Replace', description: 'Replace all notes' },
+      { label: 'Append', description: 'Add to existing notes' },
+      { label: 'Clear', description: 'Remove all notes' }
+    ],
+    multiSelect: false
+  }]
+})
+
+// Handle user selection...
+```
+
+---
+
+## Step 5: Write Changes
+
+```typescript
+// Show diff
+output(`
+📝 Changes to be written:
+
+${generateYamlDiff(originalStatus, status)}
+`)
+
+const confirm = await askUserQuestion({
+  questions: [{
+    question: 'Save changes?',
+    header: 'Confirm',
+    options: [
+      { label: 'Yes', description: 'Write changes to PROJECT_STATUS.yml' },
+      { label: 'No', description: 'Discard changes' }
+    ],
+    multiSelect: false
+  }]
+})
+
+if (confirm === 'Yes') {
+  Write(statusPath, toYaml(status))
+  output(`
+✅ PROJECT_STATUS.yml updated!
+
+Last updated: ${status.last_updated}
+Changes saved: ${countChanges(originalStatus, status)} section(s)
+  `)
+} else {
+  output('Changes discarded.')
+}
+```
+
+---
+
+## Quick Mode Behavior
+
+When `/pstatus quick` is used:
+
+1. Check `last_updated` - if > 7 days, suggest full review
+2. Auto-detect archived changes not in `completed_changes`
+3. Show current blockers - ask if any resolved
+4. Skip unchanged sections
+5. Update timestamp and save
+
+---
+
+## Output Example
+
+```
+📊 PROJECT_STATUS.yml Review
+
+Last updated: 2025-11-25 (6 days ago)
+Current focus: "Building authentication system"
+Active change: auth-system
+
+📦 Found 1 archived change not in completed_changes:
+   - infrastructure-cicd
+
+Add it? (yes)
+   ✅ Added: infrastructure-cicd
+
+🚧 Blockers (1)
+   - domain-config: Need domain for Cloudflare (blocks: production-launch)
+
+Any blockers resolved? (no)
+
+🎯 Priorities look current.
+
+📝 Changes to be written:
+   + completed_changes: infrastructure-cicd
+   ~ last_updated: 2025-11-25 → 2025-12-01
+
+Save changes? (yes)
+
+✅ PROJECT_STATUS.yml updated!
+```
+
+---
+
+## Integration with Other Commands
+
+| Command | Integration |
+|---------|-------------|
+| `/csetup` | Reads PROJECT_STATUS.yml for context, updates `current_focus.active_change` |
+| `/cstatus` | Shows both change status AND project status summary |
+| `/openspec:archive` | Prompts to add to `completed_changes` |
+
+---
+
+## Blocker Detection Patterns
+
+Main Claude should recognize these phrases and suggest adding blockers:
+
+| Pattern | Example |
+|---------|---------|
+| "waiting for..." | "waiting for domain configuration" |
+| "need X from..." | "need API key from client" |
+| "blocked by..." | "blocked by DevOps team" |
+| "pending..." | "pending approval" |
+| "can't proceed until..." | "can't proceed until payment gateway ready" |
+
+When detected, prompt:
+```
+This sounds like an external blocker. Add to PROJECT_STATUS.yml?
+- id: {suggested-id}
+- description: {extracted-description}
+- blocks: [{related-work}]
+```