libgraphql-plans

Manage project planning for the

libgraphql

workspace via

plans.md

files and code TODO comments.

Overview

The libgraphql project tracks work in two ways:

1. plans.md

   files — Structured planning documents at crate roots and workspace root
2. Code TODOs — Inline comments marking work to be done

This skill keeps these synchronized and helps prioritize work.

File Hierarchy

libgraphql/
├── plans.md                           # Workspace-level plans (items outside crates)
└── crates/
    ├── libgraphql-parser/plans.md     # Parser crate plans
    ├── libgraphql-core/plans.md       # Core crate plans
    └── libgraphql-macros/plans.md     # Macros crate plans

Rule: TODOs go to the nearest

plans.md

— if in a crate, use that crate's file; otherwise use the root.

Workflows

1. Sync TODOs from Codebase

When asked to sync or update plans:

1. Run

   .claude/skills/libgraphql-plans/scripts/scan_todos.py <repo-path>

   to find all TODOs
2. For each

   plans.md

   file, compare found TODOs against the "Appendix: Code TODOs" table
3. New TODOs: Present them to the user for review before adding to the appropriate section
4. Missing TODOs: If a TODO in the appendix no longer exists in code, it may have been completed or removed — investigate and update accordingly
5. Regenerate the "Appendix: Code TODOs" table
6. Update "Last Updated" date

2. Mark Work Complete

When asked to mark something done:

1. Locate the plan item by section number (e.g., "2.1") or description
2. Wholly complete:
   • Move to "Past Completed Work" section with title, terse description, and date
   • Check all "Definition of Done" boxes
3. Partially complete:
   • Leave in place
   • Update "Current Progress" to reflect what's done
   • Update description to reflect remaining work
4. NEVER re-number plan identifiers — IDs like 2.1, 4.3 must remain stable
5. Update "Last Updated" date

3. Add New Task

When asked to track a new task:

1. Determine the appropriate

   plans.md

   file based on which crate it affects
2. Determine the appropriate section (or create a new section if needed)
3. Draft the new plan item following the format in

   references/plans_format.md

4. Present to user for review before adding
5. Assign the next available ID within that section (never reuse IDs)
6. Update "Last Updated" date

4. Identify High-Impact Work

When asked what to work on next:

1. First, sync TODOs and update all

   plans.md

   files
2. Analyze by priority markers (HIGH/MEDIUM/LOW) in the Priority Summary
3. Consider dependencies (blocked items vs ready items)
4. Consider scope (quick wins vs large efforts)
5. Present top 3-5 recommendations with rationale

TODO Comment Patterns

Scan for these patterns in

.rs

files:

Explicit markers:

• // TODO:

  or

  // TODO

  — Standard TODO

• // FIXME:

  or

  // FIXME

  — Bug or broken code

• // NOTE:

  — May indicate future consideration. Exclude these if they only explain something but do not indicate a need to come back and change or otherwise take action on something.

• // HACK:

  — Temporary solution needing cleanup

Semantic patterns (use judgment):

• Comments mentioning "fix this", "clean up", "reconsider", "revisit"
• Comments about "temporary", "workaround", "should be changed"
• Comments with future tense about changes ("will need to", "should eventually")

Not every comment needs to become a plan item — only clear action items.

plans.md Format

See

references/plans_format.md

for the full template.

General style:

• All markdown table cells in a column should have consistent width for human-readability

Key sections:

• Current State Summary — Test counts, implementation status
• Numbered Sections — Grouped by category (Testing, Performance, etc.)
• Priority Summary — HIGH/MEDIUM/LOW categorization
• Past Completed Work — Archive of finished items
• Appendix: Code TODOs — Auto-generated table of inline TODOs

Each plan item includes:

• Purpose — Why this matters
• Current Progress — What's done
• Priority — HIGH/MEDIUM/LOW
• Tasks — Numbered subtasks
• Definition of Done — Checkboxes for completion criteria

Important Rules

1. Stable IDs: Never renumber plan items. If Section 2.1 is completed, the next item in Section 2 is 2.7 (or whatever follows), not 2.1.

2. Always regenerate Code TODOs appendix when updating any

   plans.md

   .

3. Ask before adding: New items from TODO scans should be presented for user review.

4. Update timestamps: Always update "Last Updated" date when modifying a

   plans.md

   .

5. Terse completions: When moving to "Past Completed Work", use only a title and one-line description.