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):

List new files

git status --porcelain | grep "^??" | cut -c4-

Manually review and delete if appropriate

Step 6: Verify clean state:

git status

Should show: "nothing to commit, working tree clean"

Step 7: Clean up partial metadata:

rm -f .archive-metadata.yaml.tmp

If .archive-metadata.yaml was created in this session:

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

Find the commit SHA before the archive-workflow commit

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):

WARNING: Destructive operation - confirm with user first

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.

.archive-metadata.yaml

Generated by archive-workflow on successful completion

DO NOT EDIT MANUALLY - regenerate by running archive-workflow

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" # code | research | data | mixed type_confidence: "high" # high | medium secondary_type: null # null or secondary type if mixed

naming_conventions: summary: files: "snake_case" # snake_case | kebab-case | camelCase | PascalCase directories: "lowercase" # lowercase | snake_case | kebab-case 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" - "mixed case at same directory level" full_reference: "/Users/username/.claude/skills/archive-workflow/references/naming-conventions-code.md"

NOTE: absolute path, expanded at generation time

structure: summary: source_code: "src/" tests: "tests/" documentation: "docs/" scripts: "scripts/" data: null experiments: null top_level_directories: - name: "src/" purpose: "Source code" enforced: true - name: "tests/" purpose: "Test code" enforced: true - name: "docs/" purpose: "Documentation" enforced: true required_files: - "README.md" - "CLAUDE.md" - ".gitignore" full_reference: "/Users/username/.claude/skills/archive-workflow/references/structure-template-code.md"

NOTE: absolute path, expanded at generation time

enforcement: mode: "advisory" # advisory | soft-mandatory | hard-mandatory

advisory: present options, never block

soft-mandatory: present options, default to archival, log override

hard-mandatory: no override, archival path is mandatory

organization_report: location: "docs/organization/final-organization-report.md"

gitignore: patterns_enforced: true last_reviewed: "2026-02-06T14:30:00Z"

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