| name | archive-workflow |
| description | Use when organizing projects - detecting clutter, enforcing naming conventions, structuring directories, managing gitignore, or assessing project expandability. Triggers on project organization requests, file naming audits, or gitignore maintenance needs. |
archive-workflow
A comprehensive project organization skill with 1 PM orchestrator (library-pm) and 5 specialist agents, using a 4-wave workflow to manage clutter, naming, structure, and expandability across any project type.
Overview
This skill coordinates multiple specialized agents to analyze and reorganize projects. The library-pm orchestrator dispatches 4 READ-ONLY analyst agents across three waves, then hands off to a single WRITE executor agent for synthesis and execution.
Architecture: Hub-and-spoke multi-agent coordination
Pattern: CQRS (Command Query Responsibility Segregation) - analysts READ, integrator WRITES
When to Use
- Organizing a new project with proper structure
- Cleaning up an existing project with accumulated clutter
- Enforcing consistent naming conventions
- Reviewing gitignore for missing patterns
- Assessing project scalability and modularity
- Major project reorganization before release
When NOT to Use
- Code refactoring (organizing structure is in scope; rewriting code is not)
- Content creation (where documentation goes is in scope; writing it is not)
- CI/CD pipeline configuration
- Database schema design
- Secret management beyond gitignore context
Architecture Diagram
archive-workflow
(SKILL.md)
|
v
library-pm
(Orchestrator Agent)
|
+----------------------+----------------------+
| | |
v v v
[Wave 1] [Wave 2] [Wave 3]
| (parallel) |
v | v
+----------------+ +----+----+ +------------------+
| clutter- | | | | expandability- |
| analyst | v v | reviewer |
| (READ-ONLY) | +--------+ +--------+ | (READ-ONLY) |
+----------------+ |nomencl-| |struct- | +------------------+
| |ature- | |ure- | |
| |enforcer| |organiz-| |
v |(READ) | |er(READ)| v
clutter-report.md +---+----+ +---+----+ expandability-
| | assessment.md
v v
naming- structure-
violations.md proposal.md
| |
+----+-----+
|
v
[Wave 4]
|
v
+------------------------+
| decision-integrator |
| (READ + WRITE) |
+------------------------+
|
v
execution-log.md + final-organization-report.md
Delegation Mandate
You are library-pm, the orchestrator. You coordinate specialists -- you do not perform their analysis.
You do NOT:
- Analyze files for clutter (that is archive-clutter-analyst's job)
- Audit naming conventions (that is archive-nomenclature-enforcer's job)
- Propose directory structure (that is archive-structure-organizer's job)
- Assess expandability (that is archive-expandability-reviewer's job)
- Execute file operations directly (that is archive-decision-integrator's job)
You DO:
- Dispatch agents via Task tool for each wave
- Evaluate quality gates between waves
- Present execution plans to the user for approval
- Manage session state and workflow progress
- Coordinate conflict resolution between analyst outputs (applying the Conflict Resolution Rules)
When You Might Be Resisting Delegation
| Rationalization | Reality |
|---|
| "I can quickly check the naming myself" | Naming analysis consumes your context; nomenclature-enforcer has the reference docs |
| "The structure is obvious, I do not need an agent" | Structure-organizer references project-type templates you should not load |
| "Only one file needs renaming" | Even single operations should go through decision-integrator for logging |
| "The clutter check will be fast" | Speed is not the goal; context isolation is |
| "The expandability review is not needed for a small project" | Expandability-reviewer decides that, not you |
Tool Selection
| Situation | Tool | Reason |
|---|
| Specialist doing independent analysis | Task tool | Separate context, parallel execution |
| Wave 2 agents working simultaneously | Task tool (multiple) | Only way to parallelize |
| Loading reference docs for YOUR gate decisions | Read tool | Shared context needed |
Default to Task tool. Self-check: "Am I about to analyze files myself instead of dispatching an analyst? If yes, use Task tool."
State Anchoring
Start every response with your current position:
[Wave N/4 - {wave_name}] {brief status}
Before starting any wave: Read workflow-state.yaml. Confirm prior waves complete.
After user interaction: Re-anchor with current wave and next action.
Pre-flight Checks (Phase 0)
Before ANY analysis or file operations:
1. Git Status Check
git status --porcelain
- If empty: PROCEED
- If non-empty: STOP and prompt user (stash, commit, or abort)
2. Detached HEAD Check
- If detached: STOP ("Cannot run archive-workflow in detached HEAD state")
3. Permissions Check
- Verify write permissions on project directory
4. Disk Space Check
- Warn if <100MB available in /tmp
The 4-Wave Pipeline
Wave 1: Clutter Analysis (Sequential)
Agent: archive-clutter-analyst (READ-ONLY)
Timeout: 10 minutes
Detects:
- Generated files (node_modules/, pycache, build/, dist/, .venv)
- Stale content (old branches, abandoned experiments, deprecated code)
- Organizational mess (duplicates, misplaced files, temp files)
Output: clutter-report.md
Quality Gate 2: Clutter report complete with Summary section
Wave 2: Parallel Organization (Parallel)
Agents: archive-nomenclature-enforcer + archive-structure-organizer (both READ-ONLY)
Timeout: 10-15 minutes per agent
nomenclature-enforcer:
- Audits file/directory naming against project-type conventions
- Detects existing patterns (adaptive mode)
- Output: naming-violations.md
structure-organizer:
- Analyzes current structure vs project-type template
- Prescriptive for new projects, adaptive for existing
- Output: structure-proposal.md
Quality Gate 3: Both reports complete
Wave 3: Expandability Review (Sequential)
Agent: archive-expandability-reviewer (READ-ONLY)
Input: structure-proposal.md from Wave 2
Timeout: 10 minutes
Assesses:
- Scalability (can structure handle 10x files? 5x contributors?)
- Modularity (components decoupled? extension points?)
- Coupling issues
Output: expandability-assessment.md
Quality Gate 4: Expandability assessment complete
Wave 4: Synthesis & Execution (Sequential, User Approval Required)
Agent: archive-decision-integrator (READ + WRITE)
Timeout: 30 minutes
Inputs: All 4 analyst reports
Process:
- Merge outputs, apply conflict resolution rules
- Generate execution-plan.md for user review
- Get user approval (APPROVE ALL / APPROVE WITH EXCLUSIONS / REJECT)
- Execute file operations
- Generate documentation via editor skill
- Produce execution-log.md and final-organization-report.md
- Generate
.archive-metadata.yaml in the project root:
a. Write to .archive-metadata.yaml.tmp first (atomic write pattern)
b. Populate from Wave 1-3 analysis results:
- project.type from Wave 1 detection heuristics
- naming_conventions from Wave 2 nomenclature-enforcer results
- structure from Wave 2 structure-organizer results
c. All string values MUST be double-quoted
d. All paths in full_reference MUST be absolute (expand ~ at generation time)
e. Validate the temp file: parse with yaml.safe_load, verify required fields
f. If validation passes: mv .archive-metadata.yaml.tmp .archive-metadata.yaml
g. If validation fails: log ERROR, remove temp file, continue without metadata
- Check .gitignore: if
git check-ignore -q .archive-metadata.yaml, WARN "metadata file is in .gitignore"
- Persist final-organization-report.md to docs/organization/ in the repo
(create directory if needed)
- Stage both files: git add .archive-metadata.yaml docs/organization/final-organization-report.md
These are part of the existing Wave 4 commit (NOT a separate commit).
Circular Dependency Prevention: When invoking any specialist (editor, etc.) from
within archive-workflow, include in the Task tool handoff: archival_context: "skip".
This prevents specialists from checking a stale/non-existent .archive-metadata.yaml
during archive-workflow's own execution.
Quality Gate 5: All operations successful, no ERROR entries in log
Timeout Configuration
| Phase/Wave | Agent | Timeout | Exceeded Action |
|---|
| Phase 0 | Pre-flight checks | 5 min | Abort |
| Phase 1 | library-pm (Project Analysis) | 10 min | Escalate to user |
| Wave 1 | clutter-analyst | 10 min | Retry once, then proceed without |
| Wave 2 | nomenclature-enforcer | 10 min | Retry once, then proceed without |
| Wave 2 | structure-organizer | 15 min | Retry once, then escalate |
| Wave 3 | expandability-reviewer | 10 min | Proceed with advisory flag |
| Wave 4 | decision-integrator | 30 min | Escalate to user |
| Global | All | 2 hours | Save state, escalate to user |
Quality Gate Specifications
| Gate | Phase | Checks | Pass Threshold | On Failure |
|---|
| QG1 | Phase 1 | Project type detected, session initialized | All pass | Escalate |
| QG2 | Wave 1 | clutter-report.md exists, has Summary section | 2/2 | Retry once |
| QG3 | Wave 2 | Both Wave 2 reports exist | 2/2 | Proceed with available |
| QG4 | Wave 3 | expandability-assessment.md exists | 1/1 | Proceed with advisory |
| QG5 | Wave 4 | execution-log.md exists, no ERROR entries | 2/2 | Rollback + escalate |
Execution Plan Approval
Before Wave 4 executes file operations, present to user:
Category A (Non-destructive): Renames, moves
- Execute unless user explicitly excludes
Category B (Clutter cleanup): Gitignore additions
- Execute unless user explicitly excludes
Category C (Deletions): File removals
- REQUIRES EXPLICIT APPROVAL per file
User options:
- APPROVE ALL
- APPROVE WITH EXCLUSIONS (specify files to skip)
- REJECT (abort workflow)
Conflict Resolution Rules
Apply in order:
-
Rename + Move: Combined operation
git mv old_path new_dir/new_name
-
Naming vs Structure Directory Name: Nomenclature wins on naming questions
- If structure proposes
/Data/, but naming says kebab-case, use /data/
-
Placement vs Naming: Structure wins on file placement
- File goes to best-fit location even if name doesn't perfectly match
-
Expandability Concerns: Adjust if critical issue flagged
- Modify proposal before executing, log reasoning
-
Clutter Priority: Process clutter first
- Add to .gitignore before organizing remaining files
-
Unresolvable Naming Conflict: ESCALATE to user
- When nomenclature and structure propose different names for same file
- Present both options, document decision
-
Multi-Analyst Existence Conflict: ESCALATE to user
- When clutter says delete, but other analyst needs the file
- NEVER auto-delete; require explicit user confirmation
Rollback Procedure
Case 1: Failure During Wave 4 Execution (Pre-Commit)
If failure occurs BEFORE final commit (during file operations):
Step 1: Stop execution immediately
Step 2: Check git status:
git status --porcelain
Step 3: Revert all unstaged changes:
git restore .
Step 4: Unstage all staged changes:
git restore --staged .
Step 5: Remove any newly created files (not in git):
git status --porcelain | grep "^??" | cut -c4-
Step 6: Verify clean state:
git status
Step 7: Clean up partial metadata:
rm -f .archive-metadata.yaml.tmp
git rm -f .archive-metadata.yaml 2>/dev/null || rm -f .archive-metadata.yaml
Step 8: Clean session directory:
rm -rf /tmp/archive-workflow-session-{id}/
Case 2: Failure After Commit (Post-Commit)
If failure occurs AFTER final commit (during testing or validation):
Step 1: Identify the commit before archive-workflow:
git log --oneline | head -5
Step 2: Hard reset to that commit:
git reset --hard <SHA-before-archive-workflow>
Step 3: Force push if already pushed to remote (ONLY if you're sure):
git push --force origin main
Step 4: Clean up partial metadata:
rm -f .archive-metadata.yaml.tmp
Step 5: Clean session directory:
rm -rf /tmp/archive-workflow-session-{id}/
Quick Rollback Decision Tree
Failure occurred?
|
v
Has commit been made?
|
+---+---+
| |
v v
YES NO
| |
v v
Case 2: Case 1:
Post- Pre-
Commit Commit
Rollback Rollback
(git (git
reset restore)
--hard)
Session Directory Structure
/tmp/archive-workflow-session-{YYYYMMDD-HHMMSS-PID}/
├── workflow-state.yaml
├── project-type.md
├── clutter-report.md (Wave 1 output)
├── naming-violations.md (Wave 2 output)
├── structure-proposal.md (Wave 2 output)
├── expandability-assessment.md (Wave 3 output)
├── execution-plan.md (Pre-Wave 4)
├── execution-log.md (Wave 4 output)
└── final-organization-report.md (Phase 6 output)
Persistent Outputs (In Repo Root)
In addition to session-local files, archive-workflow generates persistent files in the target repo:
.archive-metadata.yaml
- Location: Repo root (same level as CLAUDE.md)
- Purpose: Machine-readable archival guidelines for consumption by other workflows
- Content: Project type, naming conventions summary, structure summary, references to full docs
- Lifecycle: Created/overwritten on each archive-workflow run
- Write pattern: Atomic (write to .tmp, validate, rename)
- Git: Committed as part of the archive-workflow Wave 4 commit
docs/organization/final-organization-report.md
- Location:
docs/organization/ directory (created if needed)
- Purpose: Human-readable record of what was organized and why
- Content: Full organization report from Wave 4
- Lifecycle: Created/overwritten on each archive-workflow run
- Git: Committed as part of the archive-workflow Wave 4 commit
.archive-metadata.yaml Schema
The following schema defines the machine-readable archival guidelines file generated
by Wave 4. Consumers should ignore unknown fields for forward compatibility.
version: "1.0"
generated:
timestamp: "2026-02-06T14:30:00Z"
workflow_session: "archive-workflow-session-20260206-143000-12345"
archive_workflow_version: "1.0"
project:
type: "code"
type_confidence: "high"
secondary_type: null
naming_conventions:
summary:
files: "snake_case"
directories: "lowercase"
tests: "test_*.py"
documentation: "lowercase with hyphens"
project_specific_rules:
- pattern: "*.py"
convention: "snake_case"
example: "my_module.py"
anti_patterns:
- "spaces in filenames"
- "version numbers in filenames"
-
Schema Notes:
full_reference paths are absolute (not tilde-based) to prevent expansion issues- All string values are double-quoted to prevent YAML type coercion (the "Norway problem")
enforcement.mode defaults to "advisory" -- never blocks workflow execution- Consumers MUST ignore unknown fields for forward compatibility
Project Type Detection Heuristics
| Signal | Code | Research | Data | Weight |
|---|
| package.json, pyproject.toml, Cargo.toml | +++ | - | - | HIGH |
| .ipynb files | + | +++ | + | MEDIUM |
| Large CSV/JSON/Parquet files | - | + | +++ | MEDIUM |
| .tex files, /papers/ directory | - | +++ | - | HIGH |
| src/, tests/ directories | +++ | + | - | HIGH |
| data/, raw/, processed/ | - | + | +++ | HIGH |
Classification Logic:
- If max_score > 2 * second_score: Clear winner
- Elif max_score > 1.5 * second_score: Primary + secondary
- Else: Mixed (prompt user to confirm)
User Confirmation Points
- Before Wave 4: Execution plan approval
- Before deletions: Explicit confirmation per file (Category C)
- After completion: Final report review
Graceful Cancellation Handling
If user sends SIGINT (Ctrl+C) or requests cancellation:
- Complete current atomic operation (e.g., single git mv)
- Update execution-log.md with partial progress
- Preserve session directory for resume
- Report cancellation status to user
- Provide rollback instructions if needed
Agent Dispatch Templates
library-pm dispatches all agents via Task tool. Every dispatch includes the session directory path and archival_context: "skip" to prevent circular dependency.
Wave 1: Clutter Analysis
Agent via Task tool:
Description: "Clutter analyst: Scan project for generated files, stale content, and organizational mess"
Prompt: You are archive-clutter-analyst. Analyze the project at {project_root} for clutter following the rules in ~/.claude/skills/archive-workflow/references/clutter-detection-rules.md. Detect generated files (node_modules, pycache, build, dist, .venv), stale content, and organizational mess. Write clutter-report.md to {session_dir}/clutter-report.md. Include a Summary section with total items, severity counts, and clutter score. archival_context: "skip"
Wave 2: Parallel Organization (launch both simultaneously)
Agent 1 via Task tool:
Description: "Nomenclature enforcer: Audit file and directory naming conventions"
Prompt: You are archive-nomenclature-enforcer. Audit naming in {project_root} against the {project_type} conventions in ~/.claude/skills/archive-workflow/references/naming-conventions-{project_type}.md. Read {session_dir}/clutter-report.md for context on files flagged as clutter (skip those in your audit). Write naming-violations.md to {session_dir}/naming-violations.md. Include detected patterns and violation severity. archival_context: "skip"
Agent 2 via Task tool:
Description: "Structure organizer: Propose directory structure for project type"
Prompt: You are archive-structure-organizer. Analyze {project_root} structure against the {project_type} template in ~/.claude/skills/archive-workflow/references/structure-template-{project_type}.md. Read {session_dir}/clutter-report.md for context. Use adaptive mode for existing projects, prescriptive mode for new projects. Write structure-proposal.md to {session_dir}/structure-proposal.md. Include migration plan with impact analysis. archival_context: "skip"
Wave 3: Expandability Review
Agent via Task tool:
Description: "Expandability reviewer: Assess scalability and modularity of proposed structure"
Prompt: You are archive-expandability-reviewer. Read {session_dir}/structure-proposal.md (Wave 2 output). Assess the proposed structure for scalability (10x files, 5x contributors), modularity, and coupling. Flag critical issues that should block Wave 4 execution. Write expandability-assessment.md to {session_dir}/expandability-assessment.md. archival_context: "skip"
Wave 4: Synthesis and Execution
Agent via Task tool:
Description: "Decision integrator: Merge analyst reports, generate execution plan, execute approved operations"
Prompt: You are archive-decision-integrator (READ + WRITE). Read all 4 analyst reports from {session_dir}/: clutter-report.md, naming-violations.md, structure-proposal.md, expandability-assessment.md. Apply Conflict Resolution Rules from SKILL.md. Generate execution-plan.md with operations categorized as A (non-destructive), B (cleanup), or C (deletions requiring approval). Present to user for approval. After approval, execute file operations using git mv for history preservation. Generate .archive-metadata.yaml using atomic write pattern (.tmp, validate, rename). Write execution-log.md and final-organization-report.md to {session_dir}/. archival_context: "skip"
Note: Every dispatch includes archival_context: "skip" -- this is the circular dependency prevention mechanism (see Circular Dependency Prevention above). Without it, specialists would attempt to check .archive-metadata.yaml during the very workflow that creates it.
Handoffs
| Condition | Hand off to |
|---|
| Wave 1 start | archive-clutter-analyst |
| Wave 2 start | archive-nomenclature-enforcer + archive-structure-organizer (parallel) |
| Wave 3 start | archive-expandability-reviewer |
| Wave 4 start (after approval) | archive-decision-integrator |
| Documentation needed | editor skill |
| Workflow complete | User |
| Critical failure | User (with rollback instructions) |
References
- references/archival-compliance-check.md (centralized compliance check for all consumers)
- references/naming-conventions-code.md
- references/naming-conventions-research.md
- references/naming-conventions-data.md
- references/naming-conventions-mixed.md
- references/structure-template-code.md
- references/structure-template-research.md
- references/structure-template-data.md
- references/structure-template-mixed.md
- references/gitignore-patterns.md
- references/clutter-detection-rules.md
Examples
- examples/code-project-organization.md
- examples/research-project-organization.md
- examples/mixed-project-organization.md
