Project maintainer

project-maintainer

What this skill does

The Maintainer owns the full Open Source Framework v4.1 pipeline on a project. Given the current repo state, it:

1. Audits phase gates — are we in the right phase? Are the deliverables for the current phase complete?
2. Reconciles task tracking — keeps tasks.md, _progress.md, and GitHub issues in sync (the framework's "dual-tracking" rule).
3. Runs stale checks — flags content, links, and claims older than the stale threshold.
4. Triggers CI — re-runs the privacy grep, performance budget check, and link checker.
5. Reports next action — tells the user exactly what to do next and why.

It works for any project that follows the framework — not just llmwiki.

When to invoke

• "Maintain the project" / "maintenance check" / "do a health check"
• "Update progress" / "reconcile tasks" / "sync tasks"
• "Check phase gate" / "can I move to the next phase"
• "Lint the wiki" / "check for stale entries"
• "Monthly verify" / "quarterly review"
• Any time the user is unsure what to work on next

Framework phase awareness

Phase	The Maintainer's job in this phase
0 Capture	Verify idea-brief.md exists and names target users + the 10x mechanism
1 Validate	Verify scorecard /25 is in _progress.md and ≥20
1.25 Research	Verify .temp/ has at least 10 cloned reference repos and docs/research.md exists with a gap matrix
1.5 Steering	Verify _progress.md has "Key Decisions" table filled in
1.75 Agent Survey	For agent-native tools — verify adapter compatibility matrix exists
2 Brand	Verify README.md, LICENSE, and badges are in place
3 Structure	Verify folder layout matches docs/architecture.md
4 Content	Track which M items in docs/roadmap.md are ✅ vs [ ]
5 Contribution	Verify CONTRIBUTING.md, PR template, issue templates, CI workflow
5.25 Adapter Flow	For agent-native tools — verify adapter contract doc + at least one community contribution example
5.5 Pre-Launch QA	Run the full QA checklist from docs/framework.md
6 Launch	Verify git tag + GitHub Release + social posts drafted
6.5 Self-Demo	Verify GitHub Pages workflow triggered and live URL returns 200
7 Grow	Track stars / forks / downloads week-over-week
7.5 Living Knowledge	Verify public wiki is updating on release
8 Maintain	Run monthly verification, merge PRs, update stale entries

Workflow

1. Locate the project root. Look for _progress.md in the current dir or its parents. If missing, tell the user this skill needs a project that follows the framework.

2. Read the state files:

   • _progress.md — current phase + phase status table
   • tasks.md — Kiro-style tasks with [ ]/[/]/[x]/[-] markers
   • docs/roadmap.md — if present, the master MoSCoW table
   • CHANGELOG.md — latest release

3. Audit each phase gate up to the current phase. For each phase marked done, verify the deliverable file exists and is non-empty. Report any gaps.

4. Reconcile task tracking:

   • Are there items in tasks.md marked [x] but not in CHANGELOG.md?
   • Are there open GitHub issues with no matching task in tasks.md?
   • Are there tasks in tasks.md with no corresponding GitHub issue?
   • If any drift — propose fixes before making any changes.

5. Run stale checks:

   • Any last_updated in wiki frontmatter older than 30 days? Flag.
   • Any source_file reference in wiki pointing to a file that no longer exists? Flag.
   • Any entity page mentioned in 3+ sources but with its own last_updated older than the newest source? Flag.
   • Any [[wikilink]] pointing to a non-existent page? Flag.

6. Run CI gates locally (if configured):

   • Privacy grep: grep -r "<real_username>" site/ wiki/ must be empty
   • Link check: python3 -m llmwiki lint-docs (when implemented)
   • Performance budget: build time <15s, HTML <50MB

7. Write the report. Structure:

   ## Health report: <project> — <date>
   
   **Phase:** <current phase> (<status>)
   
   ### ✅ Green
   - <things that are fine>
   
   ### ⚠️ Yellow
   - <minor drift that should be fixed soon>
   
   ### ❌ Red
   - <broken gates that block progress>
   
   ### Next action
   1. <specific thing the user should do next>
   2. <second thing if any>
   

8. Offer to fix green issues automatically. For yellow/red, ask before touching anything.

Hard rules

1. Never silently update _progress.md. Always explain what changed and why.
2. Never close a GitHub issue without the user saying so.
3. Never overwrite tasks.md without showing the diff first.
4. Respect the framework's "one PR per concern" rule — if a fix spans multiple files, surface it as multiple suggestions, not one big patch.
5. Never auto-bump versions. Version bumps are a launch activity, not maintenance.

Related skills

• self-learn — when a new pattern emerges during maintenance, pipe it to self-learn to potentially add it to the framework.
• llmwiki-query — when you need context from past sessions on why a decision was made.
• llmwiki-lint — for wiki-specific lint work (overlaps with step 5).