# Project Maintainer

> Use when initializing, querying, auditing, or updating a structured `.doc_project_maintainer/` project map; analyzing a repository; documenting modules, directories, cross-boundary flows, source symbols, changes, or decisions; or using that map as scoped context during a bug fix, feature change, or refactor. Route ordinary code changes through scoped maintenance, expand only for boundary or high-risk changes, and reserve full inventory, coverage closure, signing, and trusted symbol audit for explicit knowledge-base or audit delivery.

- Skill: `pygent-ai/project-maintainer` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add pygent-ai/project-maintainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pygent-ai/project-maintainer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: Apache-2.0
- Author: pygent-ai (https://skillmd.com/u/pygent-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pygent-ai/project-maintainer

---


# Project Maintainer

Maintain `.doc_project_maintainer/` as a compact, agent-readable project map. Use modules for capability boundaries, directories for source evidence, flows for causal behavior across boundaries, and code symbols for executable detail.

## Task Intent Router

Classify the task before reading the artifact or running a script.

### Maintenance-Aware Fix Mode

Use this mode for a bug fix, feature change, or refactor. Project Maintainer supplies context and preserves affected knowledge; it must not become the primary debugging workflow.

Use the `scoped` profile by default:

1. Check whether `.doc_project_maintainer/` exists without creating files.
2. Read only artifact slices related to the target paths. Prefer `scripts/project_context.py` when available.
3. Find applicable active failure evidence before trusting lower-level passing tests.
4. Reproduce, diagnose, implement, and verify through the normal development workflow.
5. Synchronize only existing claims directly contradicted or affected by the verified change. Record missing unrelated documentation as pending; do not block the code repair on repository-wide coverage.
6. Keep bugfix synchronization separate from formal symbol health audit. A bugfix may update Actual Role, behavior, tests, verification links, and known risk, but it must not promote `agent_audited` unless the user requested an audit and the audit workflow was completed.

Load `references/scoped-maintenance.md` for every code change that uses this skill. Load `references/evidence-and-verification.md` when evaluating test sufficiency, unresolved failures, or completion claims.

Use the `expanded` profile when the change affects a public contract, module or process boundary, persistence or recovery, security or permissions, resource ownership, concurrency, shutdown, or multiple externally relied-on flows. Expanded maintenance reads additional relevant slices and risk references; it still does not imply full inventory or coverage closure.

If the artifact or target slice is unavailable, continue source-based debugging. Do not ask the user to analyze the repository first unless analysis is itself required to make the requested code change safely.

### Knowledge Base Delivery Mode

Use this mode when `.doc_project_maintainer/` is the requested output: initialize, analyze, map, document, summarize, make current, or deliver full repository coverage.

1. Run the delivery preflight in `references/repository-delivery.md`.
2. Build or refresh only the requested slices unless the user requests complete coverage.
3. For complete or project-wide goals, continue until coverage closure has no actionable pending slices; otherwise report the artifact as partial with the exact next slice.

Load `references/artifact-structure.md`, `references/templates.md`, and `references/repository-delivery.md` before creating or broadly revising an artifact.

### Audit Delivery Mode

Use this mode only when the user requests source-symbol coverage, health/risk audit, trusted audit state, integrity verification, or an audit report.

Load `references/audit-workflows.md` and `references/code-symbol-docs.md`. Full audit work remains strict: scripts may inventory, queue, validate, or record reviewed results, but they must not bulk-generate health or impersonate an agent/human audit.

## Read-Only And Signing Boundary

Keep queries and checks read-only unless the user requested an artifact mutation.

- Do not run `audit_integrity.py ensure-key` during ordinary preflight.
- Reading, context lookup, inventory without output paths, sync checks, integrity `verify`, and integrity `report` must not create a signing key.
- Create or reuse a key only for `promote`, explicit signing, or an explicit `ensure-key` request.
- If verification has no environment key and no existing artifact key, report the audit as unverifiable; do not create a key to make verification pass.
- Treat the artifact-local key as workflow integrity, not a tamper-proof security boundary.

## Evidence And Completion Gate

Rank evidence by applicability first, then freshness, realism, and directness. For otherwise comparable evidence, use:

```text
live or real-provider
> real integration
> synthetic integration
> mock or unit
> static analysis
> documentation claim
```

Scenario labels such as subprocess lifecycle, cancellation, replay, or shutdown describe coverage; they are not separate evidence levels.

Do not claim fixed, working, current, or verified while a newer applicable high-level failure remains active and only weaker evidence passes. Close the conflict only with post-fix evidence for the same scenario or stronger, an explicit supersession/invalidity record, or a clearly disclosed accepted limitation. Use the structured record contract in `references/evidence-and-verification.md`.

## Scope And Status

Keep global coverage separate from the current task slice:

```yaml
global_coverage_status: current | partial | stale | unknown
task_slice_sync_status: current | pending | unavailable
```

- A scoped run may set the task slice current; it must not promote global coverage.
- A fully synchronized local change does not automatically downgrade an already-current artifact.
- An unsynchronized affected claim makes the task slice pending and may make global coverage stale.
- A pre-existing partial artifact remains globally partial even when the task slice is current.

## Bugfix Sync Versus Symbol Health Audit

Bugfix sync updates facts established by the change: affected behavior, Actual Role, contracts, tests, verification evidence, flow consequences, known risk, and a meaningful change record when warranted. Do not require missing historical docs to be created during the fix.

Formal health audit is separate. Use it only when requested. It requires implementation and evidence review, health dimensions and issues, controlled promotion, and integrity verification. `scripts/inventory_symbols.py` is not an auditor and must not mark a symbol `agent_audited`.

## Agent Symbol Audit Contract

- For a single symbol audit, personally read the implementation, relevant callers/callees, tests or missing-test evidence, and linked flows before recording health.
- For multiple symbol audits, use one audit agent per required symbol by default when independent agents are available.
- An assignment is incomplete until that agent's recent call signature batch promotes the exact symbol to `audit.status: agent_audited` and verification classifies it as `trusted_agent_audit`.
- Missing signatures downgrade to `script_assessed`; the symbol remains pending.
- If independent audit agents are unavailable, keep the requested audit partial. Scripts may only inventory, queue, validate, or record reviewed results and must not bulk-generate health.

## Reference Router

- Code change or defect repair: read `references/scoped-maintenance.md`.
- Evidence comparison or verification record: read `references/evidence-and-verification.md`.
- Artifact initialization, full analysis, git history, flows, or closure: read `references/repository-delivery.md` plus `references/artifact-structure.md` and `references/templates.md` as applicable.
- Inventory, coverage maps, symbol audit, integrity, or HTML report: read `references/audit-workflows.md` and `references/code-symbol-docs.md`.
- Async streams, cancellation, resource ownership, or shutdown: also read `references/resource-lifecycle-checklist.md`.

Read only references selected by the router. Do not load all references for a scoped task.

## Final Response Checklist

For every task using this skill, state:

- whether `.doc_project_maintainer/` exists;
- whether the task used scoped, expanded, knowledge-base, or audit delivery;
- whether the task slice is current, pending, or unavailable;
- whether affected flow and code-symbol facts were updated, not applicable, or pending;
- any active higher-level failure that limits the completion claim;
- whether any command created or modified audit integrity artifacts.

For complete delivery or audit work, also state the global coverage/audit status, closure source, pending slices, inventory and audit summaries, and report freshness. Never describe a project-wide goal as complete while actionable requested-scope slices remain.

## Validation

- Run tests for every changed script.
- Run `scripts/check_doc_sizes.py` with `--profile scoped` for scoped maintenance and `--profile full` for complete delivery.
- Run the skill-creator `quick_validate.py` after changing skill metadata or structure.
- Regenerate `project/audit-report.html` if its source ledgers or integrity report changed after generation.