Project Cleanup Workflow¶

Purpose: Prune unused guides, archive stale files, and reduce .claude/ bloat after project initialization or during maintenance.

When to Use¶

Prerequisites¶

Before starting cleanup:

• Project has been initialized (.claude/project.md exists or stack is clear)
• No active development in progress that might need guides being pruned
• Git working directory is clean (commit or stash changes first)

Process Overview¶

Step 1: Analyze Project Stack
    ↓
Step 2: Prune Unused Guides
    ↓
Step 3: Archive Stale Tasks
    ↓
Step 4: Consolidate Memory
    ↓
Step 5: Clean Patterns
    ↓
Step 6: Update Documentation
    ↓
Output: Leaner .claude/ directory

Step 1: Analyze Project Stack¶

1.1 Detect Active Languages¶

Scan project files to identify which languages are actually used:

AI Action: List all detected languages based on project files.

1.2 Detect Active Frameworks¶

Check dependency files for framework usage:

Node.js/TypeScript (package.json dependencies): - react, react-dom → React - next → Next.js - express → Express

Python (requirements.txt, pyproject.toml): - django → Django - fastapi → FastAPI - flask → Flask

Go (go.mod): - github.com/gin-gonic/gin → Gin - github.com/labstack/echo → Echo - github.com/gofiber/fiber → Fiber

Rust (Cargo.toml): - axum → Axum - actix-web → Actix-web - rocket → Rocket

(Continue for all language families)

AI Action: List all detected frameworks based on dependencies.

1.3 Generate Active Guides Manifest¶

Create .claude/active-guides.json:

{
  "generated": "2025-01-15T10:00:00Z",
  "languages": [
    "typescript"
  ],
  "frameworks": [
    "react",
    "nextjs"
  ],
  "guides_kept": [
    "skills/typescript-guide/SKILL.md",
    "skills/react/SKILL.md",
    "skills/nextjs/SKILL.md"
  ],
  "guides_archived": [
    "skills/python-guide/SKILL.md",
    "skills/go-guide/SKILL.md",
    "..."
  ]
}

AI Action: Create active-guides.json with detected stack.

Step 2: Prune Unused Guides¶

2.1 Identify Unused Guides¶

Compare existing guides against active-guides.json:

All Language Guides: 21
Active Languages: 1 (TypeScript)
Unused Guides: 20 (95% reduction possible)

All Framework Skills: 33
Active Frameworks: 2 (React, Next.js)
Unused Skills: 31 (94% reduction possible)

2.2 Archive Strategy (Recommended)¶

Move unused skills to .claude/.archive/ for potential future use:

# Create archive directory
mkdir -p .claude/.archive/skills

# Move unused language guides
mv .claude/skills/python-guide/ .claude/.archive/skills/
mv .claude/skills/go-guide/ .claude/.archive/skills/
# ... (all unused)

# Move unused framework skills
mv .claude/skills/django/ .claude/.archive/skills/
mv .claude/skills/fastapi/ .claude/.archive/skills/
# ... (all unused)

2.3 Delete Strategy (Minimal Footprint)¶

For maximum reduction, delete unused skills entirely:

# Delete unused language guides
rm -rf .claude/skills/python-guide/
rm -rf .claude/skills/go-guide/
# ... (all unused)

# Delete unused framework skills
rm -rf .claude/skills/django/
rm -rf .claude/skills/fastapi/
# ... (all unused)

Note: Deleted skills can be restored from the template repository if needed later.

2.4 Always Keep¶

Never remove these files regardless of stack:

• .claude/README.md - Directory documentation
• .claude/skills/README.md - Skills index
• .claude/skills/<workflow>/SKILL.md - All workflows (stack-agnostic)

AI Action: Execute chosen strategy (archive or delete). Report space saved.

Step 3: Archive Stale Tasks¶

3.1 Identify Stale PRDs¶

Find PRDs and task files older than 6 months:

# Find PRDs older than 180 days
find .claude/tasks -name "*.md" -mtime +180 -type f

3.2 Check Status¶

For each old PRD, determine status:

3.3 Archive Process¶

# Create archive directory
mkdir -p .claude/tasks/ARCHIVE

# Move completed/abandoned PRDs
mv .claude/tasks/0001-prd-old-feature.md .claude/tasks/ARCHIVE/
mv .claude/tasks/tasks-0001-prd-old-feature.md .claude/tasks/ARCHIVE/

# For abandoned, rename with prefix
mv .claude/tasks/0002-prd-never-built.md .claude/tasks/ARCHIVE/ABANDONED-0002-prd-never-built.md

AI Action: Identify stale tasks, confirm status with user, archive appropriately.

Step 4: Consolidate Memory¶

4.1 Identify Old Memory Files¶

Find memory files older than 3 months:

# Find memory files older than 90 days
find .claude/memory -name "*.md" -mtime +90 -type f

4.2 Create Quarterly Summary¶

Consolidate old memory files into quarterly summaries:

# Q4 2024 Decision Summary

## Overview
This file consolidates decisions from October-December 2024.

## Key Decisions

### Authentication Strategy (2024-10-15)
- Chose JWT over sessions for stateless API
- See: archived/2024-10-15-auth-strategy.md

### Database Selection (2024-11-02)
- Selected PostgreSQL over MySQL
- See: archived/2024-11-02-database-choice.md

### Caching Approach (2024-12-10)
- Implemented Redis for distributed caching
- See: archived/2024-12-10-caching-approach.md

## Archived Files
- 2024-10-15-auth-strategy.md
- 2024-11-02-database-choice.md
- 2024-12-10-caching-approach.md

4.3 Archive Individual Files¶

# Create archive directory
mkdir -p .claude/memory/archived

# Move old files
mv .claude/memory/2024-10-*.md .claude/memory/archived/
mv .claude/memory/2024-11-*.md .claude/memory/archived/
mv .claude/memory/2024-12-*.md .claude/memory/archived/

AI Action: Create quarterly summary, archive old memory files.

Step 5: Clean Patterns¶

5.1 Review patterns.md¶

If .claude/patterns.md exists, review for:

• Patterns referencing pruned languages/frameworks
• Duplicate or similar patterns
• Outdated patterns (superseded by newer approaches)

5.2 Remove Irrelevant Patterns¶

Example: If Python was pruned, remove Python-specific patterns:

## Removed Patterns

<!-- Remove this section if Python pruned -->
## Python Patterns
...

5.3 Consolidate Similar Patterns¶

Merge similar patterns across languages into generic versions where applicable.

AI Action: Review and clean patterns.md if it exists.

Step 6: Update Documentation¶

6.1 Update .claude/README.md¶

Add project-specific information:

# .claude/ Directory

> **Project**: MyApp
> **Stack**: TypeScript, React, Next.js
> **Last Cleaned**: 2025-01-15

## Active Guides
- Language: TypeScript
- Frameworks: React, Next.js

## Archived Content
See `.archive/` for pruned guides (can be restored if stack changes).

6.2 Update active-guides.json¶

Ensure manifest reflects final state after cleanup.

6.3 Add to .gitignore (Optional)¶

If not tracking generated content:

# Optional: Don't track cleanup artifacts
.claude/active-guides.json
.claude/.archive/
.claude/memory/archived/
.claude/tasks/ARCHIVE/

AI Action: Update documentation to reflect cleaned state.

Output Summary¶

After cleanup, report:

## Cleanup Summary

### Space Reduction
- Before: 2.4 MB
- After: 156 KB
- Saved: 2.24 MB (93% reduction)

### Skills
- Language guide skills: 21 → 1 (20 archived)
- Framework skills: 33 → 2 (31 archived)

### Tasks
- Active PRDs: 3
- Archived PRDs: 5

### Memory
- Active decisions: 4
- Archived to quarterly: 12

### Files Updated
- .claude/README.md ✓
- .claude/active-guides.json ✓

Restoration¶

If you need a pruned guide later:

From Archive¶

# Restore from archive
mv .claude/.archive/skills/python-guide/ .claude/skills/
mv .claude/.archive/skills/django/ .claude/skills/

From Template Repository¶

# Re-download from template
curl -o .claude/skills/python-guide/SKILL.md \
  https://raw.githubusercontent.com/ar4mirez/samuel/main/.claude/skills/python-guide/SKILL.md

Update Manifest¶

After restoration, regenerate active-guides.json by re-running Step 1.

Automation (Future)¶

This workflow can be automated with a script:

#!/bin/bash
# .claude/scripts/cleanup.sh

# Run cleanup workflow
# TODO: Implement automated detection and cleanup

Checklist¶

Before completing cleanup:

• Active languages correctly identified
• Active frameworks correctly identified
• active-guides.json created
• Unused guides archived/deleted
• Stale tasks archived
• Memory files consolidated
• patterns.md cleaned (if exists)
• README.md updated with project info
• Space reduction reported
• Git commit created (if desired)

Related Workflows¶

• initialize-project - Run cleanup after initialization
• troubleshooting - If cleanup causes issues
• generate-agents-md - Regenerate AGENTS.md after cleanup