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.

1. 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

1. 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.

1. 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.

1. 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.

1. 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

1. 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>

1. 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).