Skip to main content

Production Cleanup

Clean repository: $ARGUMENTS

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Arguments​

$ARGUMENTS - Cleanup Configuration (optional)​

Specify cleanup scope:

  • Full repository: No arguments or "--target all" - cleans entire repository
  • Specific directory: "--target docs/" - cleans single directory
  • Submodules only: "--target submodules" - cleans all submodule roots
  • With options: "--target all --mode full --priority P0 --dry-run"

Default Behavior​

If no arguments:

  • Targets all directories and submodules
  • Executes full 6-phase cleanup
  • Processes all priority levels
  • Makes real changes (not dry-run)

Required Tools​

ToolPurposeRequired
ReadAnalyze files and directoriesYes
GlobFind files matching patternsYes
BashRun file operations, git commandsYes
WriteCreate reports and documentationYes
TodoWriteTrack multi-phase progressOptional

Agents Used:

  • production-cleanup-orchestrator - Main orchestration
  • codebase-analyzer - Assessment phase
  • project-organizer - Planning and execution
  • code-locator - Verification
  • codi-documentation-writer - Reporting

Invocation​

Invoke the production-cleanup-orchestrator agent to coordinate cleanup operations:

Task(
  subagent_type="production-cleanup-orchestrator",
  prompt="""
Execute comprehensive production cleanup of {TARGET}.

**Configuration:**
- Target: {TARGET} (all | directory_path | submodules | root)
- Mode: {MODE} (full | assess | plan | execute | verify)
- Priority: {PRIORITY} (P0 | P0,P1 | all)
- Dry Run: {DRY_RUN} (true | false)

**Phases to Execute:**
1. Assessment - Analyze current state and score directories
2. Planning - Create detailed cleanup plan with file mappings
3. Execution - Move/organize files using project-organizer
4. Verification - Verify production readiness with codebase-analyst
5. Submodules - Clean all 50 submodule roots
6. Reporting - Generate comprehensive production readiness report

**Agent Coordination:**
- codebase-analyzer (assessment)
- project-organizer (planning + execution)
- code-locator (verification)
- codi-documentation-writer (documentation)
- submodule-orchestrator (submodules)

**Success Criteria:**
- Production score ≥ 80/100 per directory
- Root files ≤ 15 per directory
- README.md present in all directories
- No broken symlinks
- Comprehensive documentation

**Deliverables:**
- Production readiness assessment (JSON)
- Cleanup plan (JSON)
- Per-directory execution reports (JSON)
- Verification reports (JSON)
- Final comprehensive report (Markdown)

**Output Location:** `reports/` and `docs/project-management/`
"""
)

Usage Examples​

Full Repository Cleanup​

/production-cleanup --target all --mode full

Executes all 6 phases on entire repository:

  • Analyzes every directory
  • Creates comprehensive cleanup plan
  • Executes file organization
  • Verifies results
  • Cleans all submodules
  • Generates master report

Specific Directory​

/production-cleanup --target docs/ --mode full

Cleans only the docs/ directory through all phases.

Assessment Only​

/production-cleanup --target all --mode assess

Generates production readiness assessment without making changes.

Dry Run​

/production-cleanup --target all --mode full --dry-run true

Previews all changes without executing file moves.

Critical Directories Only​

/production-cleanup --target all --mode full --priority P0

Cleans only directories with production score < 40.

Submodules Only​

/production-cleanup --target submodules --mode full

Cleans ROOT of all 50 submodules (does not reorganize internal structure).

Parameters​

--target (required)

  • all - Entire repository (root + docs + scripts + submodules)
  • <path> - Specific directory (e.g., docs/, scripts/)
  • submodules - All submodule roots only
  • root - Repository root only

--mode (default: full)

  • full - All 6 phases (recommend for comprehensive cleanup)
  • assess - Assessment only (phase 1)
  • plan - Assessment + Planning (phases 1-2)
  • execute - Through execution (phases 1-3)
  • verify - Add verification (phases 1-4)

--priority (default: all)

  • P0 - Critical only (score < 40)
  • P0,P1 - Critical + High (score < 60)
  • P0,P1,P2 - Through medium (score < 80)
  • all - All directories

--dry-run (default: false)

  • true - Preview changes, generate reports, but don't move files
  • false - Execute cleanup operations

Output​

JSON Reports:

  • reports/production-readiness-assessment-{TIMESTAMP}.json
  • reports/cleanup-plan-{TIMESTAMP}.json
  • reports/cleanup-execution-{DIRECTORY}-{TIMESTAMP}.json
  • reports/verification-{DIRECTORY}-{TIMESTAMP}.json
  • reports/submodule-cleanup-{SUBMODULE}-{TIMESTAMP}.json

Markdown Reports:

  • docs/project-management/PRODUCTION-READINESS-REPORT-{TIMESTAMP}.md

Updated Documentation:

  • README.md files (created/updated in cleaned directories)
  • Migration notes (if significant structural changes)

What It Does​

Phase 1: Assessment (codebase-analyzer)​

  • Counts files in each directory (depth 1)
  • Classifies file types (docs, code, data, logs, temp)
  • Calculates production readiness scores
  • Identifies issues and recommendations

Phase 2: Planning (project-organizer)​

  • Prioritizes directories by score
  • Maps files to destination directories
  • Identifies files for deletion/archival
  • Assesses risks and required approvals

Phase 3: Execution (project-organizer + code-locator + codi-documentation-writer)​

  • Creates subdirectory structure
  • Moves files to proper locations
  • Verifies all moves successful
  • Creates/updates README.md files
  • Generates execution reports

Phase 4: Verification (codebase-analyst)​

  • Verifies file count ≤ target
  • Checks proper organization
  • Validates functionality (no broken links)
  • Confirms documentation present
  • Generates pass/fail reports

Phase 5: Submodules (submodule-orchestrator)​

  • Cleans ROOT of each submodule
  • Verifies symlinks intact (.coditect, .claude)
  • Ensures README.md and CLAUDE.md present
  • Organizes root files (target ≤ 12 per submodule)

Phase 6: Reporting (codi-documentation-writer)​

  • Generates executive summary
  • Creates directory-by-directory results table
  • Lists key achievements and improvements
  • Provides maintenance recommendations
  • Assesses overall production readiness

Production Readiness Scoring​

Score Formula (per directory):

File Count Score = 100 - (files - 10) * 5  (max 100, min 0)
Organization Score = (files in subdirs / total files) * 100
Documentation Score = README present (50) + README quality (50)

Overall Score = (File Count + Organization + Documentation) / 3

Score Ranges:

  • 0-39 (Critical): Not production ready, major cleanup needed
  • 40-59 (Needs Work): Approaching readiness, organize files
  • 60-79 (Acceptable): Production acceptable, minor improvements
  • 80-89 (Good): Well-organized, meets production standards
  • 90-100 (Excellent): Exemplary organization, best practices

Safety Features​

Never Modifies:

  • .git* files (git metadata)
  • .coditect, .claude (symlinks)
  • Files currently open/in use
  • Files matching .gitignore patterns

Requires Approval:

  • Files matching "export" or "EXPORT"
  • Large files (>10MB) before deletion
  • Directories with score < 30 (too risky)
  • Files with unclear purpose

Always Preserves:

  • File permissions and timestamps
  • Symlink integrity
  • Git history (no force operations)
  • Critical operational files

Integration​

Manual CLI:

cd /path/to/repo
/production-cleanup --target all --mode full

Python Script:

python3 .coditect/scripts/production-cleanup.py \
  --orchestrate \
  --target all \
  --mode full \
  --priority all \
  --dry-run false

Hook Integration:

# .claude/hooks/pre-push.yml
- name: Verify production readiness
  command: /production-cleanup --target all --mode assess --dry-run true
  fail_on: production_score < 80

Automated Maintenance:

# .github/workflows/weekly-cleanup.yml
schedule:
  - cron: '0 2 * * 0'  # 2 AM every Sunday
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - run: /production-cleanup --target all --mode full --priority P0,P1

Agents:

  • production-cleanup-orchestrator - Main orchestration agent
  • codebase-analyzer - Assessment and analysis
  • project-organizer - Cleanup execution
  • code-locator - File verification
  • codi-documentation-writer - Documentation
  • submodule-orchestrator - Submodule operations

Commands:

  • /assess-production-readiness - Assessment only
  • /verify-structure - Verification only
  • /clean-submodules - Submodules only

Skills:

  • production-cleanup - Core cleanup logic
  • production-assessment - Scoring system
  • submodule-maintenance - Submodule operations

Scripts:

  • scripts/production-cleanup.py - Main script
  • scripts/assess-production.py - Assessment utility
  • scripts/verify-cleanup.py - Verification utility

Notes​

Best Practices:

  1. Run assessment first (--mode assess) to preview scope
  2. Use dry run (--dry-run true) for first execution
  3. Start with critical directories (--priority P0)
  4. Review generated reports before proceeding
  5. Commit after each phase for rollback capability

Recommended Schedule:

  • Before Release: Full cleanup (--target all --mode full)
  • Weekly: P0/P1 cleanup (--priority P0,P1)
  • Monthly: Assess all (--mode assess)
  • After Refactoring: Affected directories only

Performance:

  • Assessment: ~5 minutes for 100 directories
  • Planning: ~10 minutes for 100 directories
  • Execution: ~30-60 minutes per directory (varies)
  • Verification: ~5 minutes per directory
  • Submodules: ~10 minutes per submodule
  • Total (full): ~2-6 hours for entire repository

Version: 1.0 Created: 2025-11-28 Status: ✅ Active​

Action Policy​

<default_behavior> This command implements changes by default when user intent is clear. Proceeds with:

  • Code generation/modification
  • File creation/updates
  • Configuration changes
  • Git operations (if applicable)

Provides concise progress updates during execution. </default_behavior>

After execution, verify: - Files created/modified as intended - Code compiles/tests pass (if applicable) - Git changes committed (if applicable) - Next recommended step provided

Success Output​

When production-cleanup completes:

✅ COMMAND COMPLETE: /production-cleanup
Target: <target>
Mode: <mode>
Score: <before> → <after>
Directories: <N> cleaned
Status: Production ready

Output Validation​

Before completing, verify output contains:

  • Target and mode specified
  • Score improvement (before → after)
  • Number of directories cleaned
  • JSON reports generated (assessment, plan, execution, verification)
  • Markdown report created
  • README.md updated in cleaned directories
  • Status: Production ready (or reason why not)
  • Success summary with all phases confirmed

Completion Checklist​

Before marking complete:

  • Assessment complete
  • Plan generated
  • Execution done
  • Verification passed
  • Report generated

Failure Indicators​

This command has FAILED if:

  • ❌ Assessment failed
  • ❌ Execution errors
  • ❌ Score not improved
  • ❌ Verification failed

When NOT to Use​

Do NOT use when:

  • Assessment only needed (/production-audit)
  • Single directory (use /organize)
  • No cleanup needed

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Skip assess modeBlind executionAssess first
Skip dry-runUnexpected movesPreview first
Full mode on productionRiskyUse --priority P0 first

Principles​

This command embodies:

  • #3 Complete Execution - Full 6-phase cleanup
  • #1 Self-Provisioning - Auto agent coordination
  • #4 Idempotent - Safe to re-run

Full Standard: CODITECT-STANDARD-AUTOMATION.md