---
description: Compress status.json by removing verbose fields and keeping only tracking metadata
---

# compress

Reduce status.json file size by removing verbose story fields and keeping only essential tracking metadata.

## Purpose

**Problem**: status.json exceeds 25000 tokens, causing agents to fail with "file content exceeds maximum allowed tokens"

**Solution**: Strip verbose fields (description, architectureContext, devAgentRecord, etc.) from status.json while preserving full story details in `docs/06-stories/` markdown files.

**Result**: Lightweight tracking index that agents can read + full story content in dedicated files.

## What Gets Removed

The script removes these verbose fields from status.json:
- `description` - Story description and context
- `acceptanceCriteria` - AC bullet points
- `architectureContext` - Architecture details (6 subsections)
- `technicalNotes` - Implementation hints
- `testingStrategy` - Test approach
- `devAgentRecord` - Implementation notes (6 subsections)
- `previousStoryInsights` - Lessons from previous story
- Any other large text fields

## What Gets Kept

Only essential tracking metadata remains:
- `story_id` - Story identifier
- `epic` - Parent epic
- `title` - Story title
- `owner` - Assigned agent
- `status` - Current status (ready/in-progress/blocked/done)
- `estimate` - Time estimate
- `created` / `updated` / `completed_at` - Timestamps
- `dependencies` - Dependent story IDs
- `branch` - Git branch
- `summary` - Short summary
- `last_update` - Last modification message
- `assigned_at` - Assignment timestamp

## Workflow

When user runs `/AgileFlow:compress`:

1. **Validate Environment**:
   - Check if `docs/09-agents/status.json` exists
   - Validate JSON syntax with `jq empty`
   - Check if `jq` is installed

2. **Show Before Stats**:
   ```
   📊 Before Compression:
      Stories: 145
      Size: 384KB
      Lines: 12,847
   ```

3. **Create Backup**:
   - Copy status.json to status.json.backup
   - Preserve original in case rollback needed

4. **Compress Stories**:
   - For each story in status.json:
     - Extract ONLY the essential tracking fields listed above
     - Discard all verbose content fields
   - Update `updated` timestamp to now

5. **Write Compressed File**:
   - Overwrite status.json with compressed version
   - Pretty-print JSON with `jq '.'`

6. **Show After Stats**:
   ```
   ✅ Compression complete!

   📊 After Compression:
      Stories: 145 (unchanged)
      Size: 384KB → 42KB
      Lines: 12,847 → 1,203
      Saved: 89% (342KB)

   ✅ Estimated tokens: ~10,500 (safely under 25000 limit)
   ```

7. **Show Status Summary**:
   ```
   📋 Status Summary:
      ready: 23 stories
      in-progress: 8 stories
      blocked: 2 stories
      done: 112 stories
   ```

8. **Provide Guidance**:
   - Note: Full story details remain in `docs/06-stories/`
   - Agents should read story markdown files for implementation
   - status.json is now a lightweight tracking index

## When to Use

**Run compression when**:
- status.json exceeds 25000 tokens
- Agents fail with "file content exceeds maximum allowed tokens"
- status.json is slow to read/parse
- After major epic completion (many stories with verbose records)

**Combine with archival**:
1. First run archival to move old completed stories: `/AgileFlow:compress` → runs `bash scripts/archive-completed-stories.sh`
2. If still too large, run compression: `/AgileFlow:compress` → runs `bash scripts/compress-status.sh`
3. Result: status.json under 25000 tokens

## Safety

**Backups**:
- Original saved to `status.json.backup`
- Restore anytime: `cp docs/09-agents/status.json.backup docs/09-agents/status.json`

**No Data Loss**:
- Full story content remains in `docs/06-stories/EP-XXXX/US-XXXX-*.md` files
- Only status.json tracking index is compressed
- Story markdown files are NOT modified

**Reversible**:
- Can restore from backup if needed
- Can re-populate verbose fields by reading story markdown files

## Implementation

```bash
bash scripts/compress-status.sh
```

## Related Commands

- `/AgileFlow:status` - View current story statuses
- `/AgileFlow:validate` - Validate AgileFlow system health

## Example Output

```
🗜️  AgileFlow Status Compression
   Purpose: Strip verbose fields from status.json
   Target: Keep only essential tracking metadata

💾 Backup created: docs/09-agents/status.json.backup

📊 Before Compression:
   Stories: 145
   Size: 384KB
   Lines: 12,847

✅ Compression complete!

📊 After Compression:
   Stories: 145 (unchanged)
   Size: 384KB → 42KB
   Lines: 12,847 → 1,203
   Saved: 89% (342KB)

🗑️  Removed Fields (stored in story markdown files):
   • description
   • acceptanceCriteria
   • architectureContext
   • technicalNotes
   • testingStrategy
   • devAgentRecord
   • previousStoryInsights
   • And any other verbose fields

📝 Note: Full story details remain in docs/06-stories/ markdown files
   Agents should read story files for implementation details
   status.json is now a lightweight tracking index

✅ Estimated tokens: ~10,500 (safely under 25000 limit)

📋 Status Summary:
   ready: 23 stories
   in-progress: 8 stories
   blocked: 2 stories
   done: 112 stories

💾 To restore original: cp docs/09-agents/status.json.backup docs/09-agents/status.json
```

## Technical Notes

**Token Estimation**:
- Rough formula: tokens ≈ bytes / 4
- Target: < 100KB for status.json (≈ 25000 tokens)
- After compression: typical 80-90% reduction

**Why This Works**:
- status.json should be a lightweight **tracking index**, not a content store
- Full story content belongs in markdown files
- Agents read status.json for "what to work on" (metadata)
- Agents read story markdown files for "how to build it" (implementation details)

**Separation of Concerns**:
- **status.json** = lightweight tracking (which stories, who owns, what status)
- **docs/06-stories/** = full story content (AC, architecture, implementation)
- **docs/09-agents/status-archive.json** = historical completed stories

## Prompt

You are the Status Compression assistant for AgileFlow.

**Your job**:

**Step 1: Ensure compression script exists**
```bash
# Check if compression script exists in user's project
if [ ! -f scripts/compress-status.sh ]; then
  echo "📦 Compression script not found - deploying from plugin..."

  # Copy from AgileFlow plugin
  cp ~/.claude-code/plugins/AgileFlow/scripts/compress-status.sh scripts/compress-status.sh

  # Make executable
  chmod +x scripts/compress-status.sh

  echo "✅ Deployed compression script: scripts/compress-status.sh"
fi
```

**Step 2: Run compression**
```bash
bash scripts/compress-status.sh
```

**Step 3: Verify and advise**
1. Show output to user
2. Verify estimated tokens < 25000
3. If still too large, suggest archival with shorter threshold

**Safety checks**:
- Verify backup created before compression
- Validate JSON syntax after compression
- Calculate and show token estimate
- Remind user full story content preserved in markdown files

**Example execution**:
```bash
cd /path/to/user/project

# Auto-deploy script if missing (v2.20.1+)
if [ ! -f scripts/compress-status.sh ]; then
  cp ~/.claude-code/plugins/AgileFlow/scripts/compress-status.sh scripts/compress-status.sh
  chmod +x scripts/compress-status.sh
fi

# Run compression
bash scripts/compress-status.sh
```

**If compression isn't enough**:
```bash
# Combine with aggressive archival
bash scripts/archive-completed-stories.sh 3  # Archive stories >3 days old
bash scripts/compress-status.sh              # Then compress remaining
```

**Always**:
- Show clear before/after stats
- Calculate savings percentage
- Verify token estimate
- Confirm agents can now read status.json