Submodule Tracker

System Prompt

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

1. IMMEDIATELY execute - no questions, no explanations first
2. Run the 3-step pipeline (quality check → quality fix → tracker generation)
3. Report results with summary stats

---

Usage

/submodule-tracker              # Full pipeline: check + fix + generate
/submodule-tracker --report     # Report-only: show quality grades without changes
/submodule-tracker --fix        # Fix quality issues without regenerating tracker
/submodule-tracker --full       # Full pipeline (same as no args)

Pipeline Overview

The submodule tracker is a 2-script pipeline that ensures all submodule READMEs have Grade A frontmatter, then generates the inventory tracker from that quality data.

┌──────────────────────────────┐     ┌──────────────────────────────┐
│  Step 1: Quality Enforcement │     │  Step 2: Tracker Generation  │
│  generate-submodule-readmes  │────▶│  generate-submodule-tracker  │
│  .py --upgrade --ensure-     │     │  .sh                         │
│  fields --apply              │     │                              │
│                              │     │  Reads summary: from README  │
│  Ensures: title, summary,   │     │  frontmatter → generates     │
│  category in all READMEs     │     │  SUBMODULE-TRACKER.md        │
└──────────────────────────────┘     └──────────────────────────────┘

Steps to follow:

Step 1: Quality Report (always run first)

cd /Users/halcasteel/PROJECTS/coditect-rollout-master
python3 scripts/generate-submodule-readmes.py --report

This shows current quality status:

• How many submodules have complete frontmatter (Grade A)
• How many have generic/short descriptions
• How many are third-party (skipped)

Grade A criteria: Has title:, summary: (meaningful, >30 chars), and category: fields.

If --report flag was used, STOP here and report results.

Step 2: Quality Fix (if needed)

If any submodules are below Grade A:

python3 scripts/generate-submodule-readmes.py --upgrade --ensure-fields --apply

This script:

1. Detects generic/short summaries and replaces with curated descriptions
2. Injects missing title: fields (derived from repo name)
3. Injects missing category: fields (derived from submodule group path)
4. Only modifies coditect-ai repos (skips third-party)

If --fix flag was used, STOP here and report results.

Step 3: Generate Tracker

bash scripts/generate-submodule-tracker.sh

This script:

1. Iterates all submodules via git submodule status
2. Reads summary: from each README.md frontmatter (Priority 1)
3. Falls back to first paragraph after H1 (Priority 2)
4. Generates docs/reference/SUBMODULE-TRACKER.md with tables, stats, and suggestions

Step 4: Report Results

Read and present summary:

head -25 docs/reference/SUBMODULE-TRACKER.md

Report:

• README quality: Grade A count / total
• Total submodule count
• Active / Stale / Dormant breakdown
• Third-party fork count
• Any repos still needing descriptions

Output

Two scripts produce two outputs:

Script	Output	Purpose
generate-submodule-readmes.py	Modified README.md files in submodules	Ensures Grade A frontmatter
generate-submodule-tracker.sh	docs/reference/SUBMODULE-TRACKER.md	Inventory report with all metadata

The tracker contains:

Section	Contents
Summary	Total counts, activity breakdown
Groups	Per-group active/stale/dormant counts
Group Details	Per-submodule tables with name, description, dates, commits, activity, suggestions
Recommendations	Archive candidates, third-party forks, missing descriptions, potential consolidations

Script Locations

Script	Path	Language
README Quality	scripts/generate-submodule-readmes.py	Python 3.10+
Tracker Generator	scripts/generate-submodule-tracker.sh	Bash + embedded Python

Quality Grading

Grade	Criteria
A	Has title: + summary: (>30 chars, meaningful) + category:
B	Has summary: but missing title: or category:
C	Has generic/short summary or name-based placeholder
D	Has frontmatter but no summary: field
F	No frontmatter at all
SKIP	Third-party repo (not modified)

generate-submodule-readmes.py Modes

Flag	Action
--report	Show quality status, no changes
--upgrade	Replace generic summaries with curated descriptions
--ensure-fields	Inject missing title/category fields
--apply	Actually write changes (without this, dry-run)

Combine flags: --upgrade --ensure-fields --apply for full fix.

Activity Classification

Status	Criteria	Label
Active	Last commit within 30 days	Yes
Stale	Last commit 30-90 days ago	Stale
Dormant	Last commit >90 days ago	No

Suggestions Engine

The tracker script auto-generates suggestions per submodule:

• Third-party fork - URL points to non-coditect-ai org
• Minimal content - 5 or fewer commits and not active
• Archive candidate - Dormant with 10 or fewer commits
• Review needed - Stale with 10 or fewer commits
• Needs description - Generic or missing README description
• Overlap detected - Known consolidation candidates

Periodic Execution

Frequency	Context
Weekly	During maintenance windows
After submodule adds/removes	Verify inventory accuracy
Before major releases	Confirm ecosystem health
Monthly	Full review with consolidation assessment

Important notes:

• Both scripts require git and python3 in PATH
• Must run from the rollout-master root directory
• Quality fix modifies README.md files inside submodules (needs separate commit)
• Tracker generation takes ~30-60 seconds to iterate all submodules
• Third-party repos (6 total) are always skipped by quality enforcement
• Curated descriptions are maintained in generate-submodule-readmes.py CURATED_SUMMARIES dict

Success criteria:

• Quality report shows 0 repos below Grade A (excluding third-party)
• SUBMODULE-TRACKER.md generated with all submodules
• 0 "Needs description" suggestions in tracker
• Summary stats reported to user

---

Action Policy

<default_behavior> This command runs a quality check, applies fixes if needed, and generates a report file. It may modify README.md files in submodules (frontmatter only). It overwrites docs/reference/SUBMODULE-TRACKER.md with fresh data. No destructive actions. No confirmation needed. </default_behavior>

After execution, verify: - Quality report shows all Grade A (88/88 coditect-ai repos) - docs/reference/SUBMODULE-TRACKER.md exists and is non-empty - Submodule count matches `git submodule status | wc -l` - No "Needs description" or "No description" for coditect-ai repos - No script errors in output

Success Output

COMMAND COMPLETE: /submodule-tracker

README Quality:
  Grade A: 88/88 coditect-ai repos (100%)
  Third-party skipped: 6

Tracker Generated:
  Submodules: 94
  Active: 94 | Stale: 0 | Dormant: 0
  Third-party: 6 | Missing descriptions: 0
  Output: docs/reference/SUBMODULE-TRACKER.md

Failure Indicators

This command has FAILED if:

• scripts/generate-submodule-readmes.py not found
• scripts/generate-submodule-tracker.sh not found
• Python3 not available
• Git submodule status returns empty
• Quality report shows repos below Grade A after fix attempt
• Output file not created

When NOT to Use

Do NOT use when:

• Need real-time git status (use /submodule-status)
• Need to fix submodule issues (use /verify-submodule)
• Need to sync submodules (use /git-sync)
• Need to push submodule changes (manual git push)

Principles

This command embodies:

• #1 Recycle, Extend, Re-Use - Two existing scripts combined into pipeline
• #3 Complete Execution - Quality + generation in one command
• #9 Based on Facts - Data-driven inventory from git metadata
• #6 Clear, Understandable - Structured tables with actionable suggestions

Full Standard: CODITECT-STANDARD-AUTOMATION.md