agentleFS
unxedunxed/f4/.agents/skills/aif-archive/SKILL.md

aif-archive

Skill261 starsChanged 2 months agoBSD-3-ClauseView on GitHub

Archive completed plans and roadmap milestones. Moves finished plans to the archive directory and optionally trims closed milestones from ROADMAP.md. Use when user says \"archive plans\", \"clean up plans\", \"archive completed\", or \"trim roadmap\".

2 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

36 rules. About 0 are common, 19 are distinctive, and 17 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈19

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 17

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .ai-factory/config.yaml if it exists to resolve:

    line 24
  2. Very specific:

    Treat any unknown value as slug.

    line 33
  3. Distinctive:

    If config doesn't exist, use defaults listed above.

    line 36
  4. Very specific:

    Read .ai-factory/skill-context/aif-archive/SKILL.md if it exists — project-specific overrides take priority over general instructions.

    line 38
  5. Distinctive:

    If multiple conflicting modes are given, emit error and STOP

    line 56
  6. Distinctive:

    If no completed plans found:

    line 76
  7. Distinctive:

    Ask which to archive:

    line 91
  8. Very specific:

    Check if <paths.archive>/plans/ exists.

    line 106
  9. Very specific:

    If not: Archive is empty. No plans have been archived yet.

    line 107
  10. Very specific:

    Check <paths.archive>/roadmap/ for snapshots and list them if present:

    line 123
  11. Very specific:

    If no match: Plan not found: <plan-name> with suggestions → STOP.

    line 139
  12. Distinctive:

    If multiple matches: list them and ask user to be more specific → STOP.

    line 140
  13. Distinctive:

    Read the matched entrypoint and check completion status.

    line 144
  14. Distinctive:

    If no completed plans: inform and STOP.

    line 158
  15. Very specific:

    Read the resolved paths.roadmap file.

    line 176
  16. Very specific:

    If it doesn't exist: No ROADMAP.md found at <path>.

    line 177
  17. Very specific:

    If no completed milestones: No closed milestones to archive.

    line 179
  18. Distinctive:

    Collision check: Before writing, verify the destination does not already exist:

    line 196
  19. Very specific:

    If the file exists, append a counter suffix to produce a non-colliding name: YYYY-MM-DD_roadmap-snapshot-2.md, …

    line 200
  20. Distinctive:

    Check each candidate until a free name is found.

    line 202
  21. Distinctive:

    Write the resolved snapshot path with:

    line 203
  22. Distinctive:

    Collision check: Before moving, verify the destination does not already exist:

    line 227
  23. Distinctive:

    If the file exists:

    line 232
  24. Distinctive:

    Do NOT overwrite in either case.

    line 245
  25. Very specific:

    Validate an ultra bundle before moving it: Read index.md and require:

    line 247
  26. Distinctive:

    every linked phase path is a direct child of the bundle and exists.

    line 251
  27. Distinctive:

    Never prepend YAML or move the ultra marker: it must remain the first line or immediately after an optional first-line Handoff annotation.

    line 272
  28. Very specific:

    Use Edit to add archived: YYYY-MM-DD field inside the existing frontmatter block.

    line 277
  29. Distinctive:

    If the full plan has no YAML frontmatter:

    line 279
  30. Very specific:

    Use Edit to prepend a minimal frontmatter block before the first line:

    line 280
  31. Distinctive:

    After all plans are processed, display summary:

    line 292
  32. Very specific:

    ALL lines matching the pattern - [x] or - [ ] within the Tasks section (and its subsections) are checked: every checkbox is - [x].

    line 312
  33. Distinctive:

    If the Tasks section contains zero checkboxes, the plan is considered

    line 314
  34. Distinctive:

    When displaying "completed" dates in interactive mode:

    line 327
  35. Very specific:

    Check YAML frontmatter for a completed field — use if present.

    line 329
  36. Very specific:

    Always ask confirmation: before --all and --roadmap operations

    line 337

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Archive — Move completed plans and roadmap snapshots

Archive completed single-file plans and ultra bundle directories from paths.plans/ into paths.archive/plans/ and optionally trim closed milestones from ROADMAP.md into dated snapshots under paths.archive/roadmap/.

Workflow

Step 0: Load Config

Read .ai-factory/config.yaml if it exists to resolve:

  • paths.plans (default: .ai-factory/plans/)
  • paths.archive (default: .ai-factory/archive/)
  • paths.plan (default: .ai-factory/PLAN.md)
  • paths.fix_plan (default: .ai-factory/FIX_PLAN.md)
  • paths.roadmap (default: .ai-factory/ROADMAP.md)
  • workflow.plan_id_format (default: slug) — active values: slug and sequential. timestamp and uuid are reserved and behave like slug. Treat any unknown value as slug.
  • language.ui for user-facing prompts

If config doesn't exist, use defaults listed above.

Read .ai-factory/skill-context/aif-archive/SKILL.md if it exists — project-specific overrides take priority over general instructions.

Step 1: Parse Arguments

Extract mode from arguments:

(no args)        → interactive mode: scan, show completable plans, ask which to archive
list             → show archive contents, then STOP
--roadmap        → trim closed milestones from ROADMAP.md into a snapshot
--all            → archive ALL completed plans (ask confirmation first)
<plan-name>      → archive a specific plan by filename or partial stem match

Parsing rules:

  • list and --roadmap are mutually exclusive with <plan-name> and --all
  • If multiple conflicting modes are given, emit error and STOP
  • <plan-name> can be:
    • full filename: 0005_feature-auth.md
    • ultra directory/entrypoint: 0005_feature-auth or 0005_feature-auth/index.md
    • stem without extension: 0005_feature-auth
    • partial match: feature-auth (must match exactly one plan)

Step 2: Execute Mode


Mode: Interactive (no arguments)

  1. Scan paths.plans/ for root *.md files and direct child */index.md candidates using Glob. Exclude the resolved paths.plan and paths.fix_plan; count a directory only when its entrypoint declares <!-- aif:plan-mode:ultra -->. Do not treat phase files or unrelated directories as plans.
  2. For each artifact, read the entrypoint's ## Tasks section.
  3. Determine completion: a plan is completed when ALL task checkboxes are - [x]. Plans with any - [ ] are incomplete.
  4. If no completed plans found:
    No completed plans found in <paths.plans/>.
    → STOP.
  5. Display completed plans:
    Completed plans ready to archive:
    
      1. 0001_feature-alpha.md (completed 2026-05-20)
      2. 0003_feature-gamma.md (completed 2026-05-24)
    
    Incomplete plans (skipped):
      - 0005_feature-delta.md (3/7 tasks done)
  6. Ask which to archive:
    AskUserQuestion: Which plans to archive?
    
    Options:
    1. All completed plans listed above
    2. Select specific plans (enter numbers)
    3. Cancel
  7. Execute archive operation for selected plans (see Archive Operation).

Mode: list

  1. Check if <paths.archive>/plans/ exists.
  2. If not: Archive is empty. No plans have been archived yet. → STOP.
  3. Glob root <paths.archive>/plans/*.md files and direct child <paths.archive>/plans/*/index.md entrypoints containing exactly one <!-- aif:plan-mode:ultra -->.
  4. For each archived artifact, extract its date from YAML frontmatter (full plans) or <!-- aif:archived:YYYY-MM-DD --> immediately after the ultra marker (index.md).
  5. Display:
    Archived plans (<paths.archive>/plans/):
    
      1. 0001_feature-alpha.md  (archived: 2026-05-20)
      2. 0003_feature-gamma.md  (archived: 2026-05-24)
    
    Total: 2 archived plans
  6. Check <paths.archive>/roadmap/ for snapshots and list them if present:
    Roadmap snapshots (<paths.archive>/roadmap/):
    
      1. 2026-05-20_roadmap-snapshot.md (3 milestones)
  7. STOP.

Mode: <plan-name>

  1. Resolve <plan-name> to one artifact in paths.plans/:
    • Try exact root filename, exact ultra directory, or exact */index.md match
    • Then try with .md extension appended
    • Then try partial match against root filenames and ultra directory names
  2. If no match: Plan not found: <plan-name> with suggestions → STOP.
  3. If multiple matches: list them and ask user to be more specific → STOP.
  4. For a directory match, read the entrypoint and require <!-- aif:plan-mode:ultra -->; otherwise it is not an archivable AI Factory plan.
  5. Read the matched entrypoint and check completion status.
  6. If incomplete:
    Plan <filename> is not completed (5/8 tasks done).
    Only completed plans can be archived.
    → STOP.
  7. Execute archive operation (see Archive Operation).

Mode: --all

  1. Scan paths.plans/ for completed plans (same logic as interactive mode).
  2. If no completed plans: inform and STOP.
  3. Display list and ask confirmation:
    AskUserQuestion: Archive ALL completed plans?
    
      1. 0001_feature-alpha.md
      2. 0003_feature-gamma.md
    
    Options:
    1. Yes, archive all 2 plans
    2. Cancel
  4. Execute archive operation for all confirmed plans.

Mode: --roadmap

  1. Read the resolved paths.roadmap file.
  2. If it doesn't exist: No ROADMAP.md found at <path>. → STOP.
  3. Find milestones with - [x] checkbox (completed milestones).
  4. If no completed milestones: No closed milestones to archive. → STOP.
  5. Display and ask confirmation:
    Closed milestones found in ROADMAP.md:
    
      - [x] MVP Launch — core features shipped
      - [x] Beta Testing — user feedback round
    
    AskUserQuestion: Trim these milestones from ROADMAP.md into a snapshot?
    
    Options:
    1. Yes, create snapshot and trim
    2. Cancel
  6. Create snapshot:
    • mkdir -p <paths.archive>/roadmap/
    • Determine snapshot filename: YYYY-MM-DD_roadmap-snapshot.md
    • Collision check. Before writing, verify the destination does not already exist:
      Read <paths.archive>/roadmap/YYYY-MM-DD_roadmap-snapshot.md
      If the file exists, append a counter suffix to produce a non-colliding name: YYYY-MM-DD_roadmap-snapshot-2.md, YYYY-MM-DD_roadmap-snapshot-3.md, etc. Check each candidate until a free name is found.
    • Write the resolved snapshot path with:
      # Roadmap Snapshot — YYYY-MM-DD
      
      Archived from: <paths.roadmap>
      
      ## Archived Milestones
      
      - [x] MVP Launch — core features shipped
      - [x] Beta Testing — user feedback round
  7. Edit paths.roadmap: remove the archived - [x] lines from the ## Milestones section. Keep the ## Completed table if it exists. Do NOT edit paths.roadmap unless the snapshot write in step 6 succeeded.
  8. Logging: INFO [aif-archive] roadmap snapshot: <resolved-path> (<N> milestones archived)

Archive Operation (plans)

For each plan artifact to archive:

  1. mkdir -p <paths.archive>/plans/
  2. Collision check. Before moving, verify the destination does not already exist:
    Read <paths.archive>/plans/<original-name>          # full plan
    Read <paths.archive>/plans/<original-name>/index.md # ultra bundle
    If the file exists:
    • Single plan (interactive or <plan-name>): STOP with an error:
      ERROR [aif-archive] destination already exists: <paths.archive>/plans/<filename>
      A previously archived plan has the same filename. This can happen when
      sequential numbering reuses a freed number after archiving.
      To resolve: rename the existing archive file, or delete it if it is no
      longer needed.
    • Batch (--all): SKIP this plan with a warning, continue to the next:
      WARN [aif-archive] skipped: <filename> — destination already exists
    Do NOT overwrite in either case.
  3. Validate an ultra bundle before moving it. Read index.md and require:

    • exactly one <!-- aif:plan-mode:ultra -->, as the first line or immediately after an optional first-line <!-- handoff:task:<id> -->;
    • a non-empty ## Phase Index;
    • every linked phase path is a direct child of the bundle and exists.

    A malformed bundle is not safe to archive. STOP for a single plan, or emit WARN [aif-archive] skipped malformed ultra bundle: <filename> and continue in --all mode.

  4. Move the complete source artifact into the archive path first:
    mv <paths.plans>/<name> <paths.archive>/plans/<name>
    For ultra, <name> is the whole directory, so all linked phase files move together. This atomically removes the plan from active discovery.
  5. Add archive metadata to the moved entrypoint using Edit (index.md for ultra, the moved plan file otherwise).

    For ultra, preserve the canonical header and insert this comment immediately after <!-- aif:plan-mode:ultra -->:

    <!-- aif:archived:YYYY-MM-DD -->

    Never prepend YAML or move the ultra marker: it must remain the first line or immediately after an optional first-line Handoff annotation.

    For a full plan, if the file already has YAML frontmatter (between --- markers at the top):

    • Use Edit to add archived: YYYY-MM-DD field inside the existing frontmatter block.

    If the full plan has no YAML frontmatter:

    • Use Edit to prepend a minimal frontmatter block before the first line:
      ---
      archived: YYYY-MM-DD
      ---

    The original filename or directory name is preserved exactly, including any sequential NNNN_ prefix.

  6. Logging: INFO [aif-archive] archived: <filename> -> <paths.archive>/plans/<filename>
  7. After all plans are processed, display summary:
    ## Archive Complete
    
    Archived N plan(s) to <paths.archive>/plans/:
      - 0001_feature-alpha.md
      - 0003_feature-gamma.md
    
    Skipped: K (destination already exists)
      - 0002_feature-beta.md
    
    Plans directory: <paths.plans/> (M plans remaining)
    Omit the "Skipped" section when K is 0.

Completion Detection Algorithm

A plan is completed when:

  1. The plan entrypoint contains a ## Tasks section (case-insensitive header match).
  2. ALL lines matching the pattern - [x] or - [ ] within the Tasks section (and its subsections) are checked: every checkbox is - [x].
  3. If the Tasks section contains zero checkboxes, the plan is considered not completed (empty plans are not archivable).

Edge cases:

  • Checkboxes outside ## Tasks (e.g., in ## Settings or ## Commit Plan) are NOT counted for completion.
  • Nested checkboxes (indented - [x]) ARE counted.
  • Plans whose entrypoint lacks ## Tasks are not archivable — emit WARN [aif-archive] <name> has no ## Tasks section; skipping.

Completion Date Inference

When displaying "completed" dates in interactive mode:

  1. Check YAML frontmatter for a completed field — use if present.
  2. Fall back to git: git log -1 --format=%ai -- <plan-file> to get last modification date.
  3. Fall back to filesystem: entrypoint modification time.

Important Rules

  1. Never archive incomplete plans — all tasks must be - [x]
  2. Always ask confirmation before --all and --roadmap operations
  3. Preserve original file/directory names — including sequential NNNN_ prefix
  4. Add archive metadata — YAML frontmatter for full plans; the stable <!-- aif:archived:YYYY-MM-DD --> comment after the ultra marker for bundles
  5. Do not modify fast plans (paths.plan) or fix plans (paths.fix_plan) — those are single-file artifacts managed by /aif-implement and /aif-fix
  6. Do not count archived plans for sequential numbering — archived plans live in paths.archive/plans/, not paths.plans/, so /aif-plan sequential scan does not include them

Artifact Ownership

  • Owns: paths.archive/plans/*.md, archived ultra bundle directories, and paths.archive/roadmap/*.md
  • Reads: root paths.plans/*.md, direct child ultra */index.md + linked phases, and paths.roadmap
  • Modifies: paths.roadmap (only with --roadmap, only after confirmation)
  • Does NOT touch: paths.plan, paths.fix_plan, paths.description, paths.architecture, paths.rules_file

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.