Project Context Maintainer

Project Context Maintainer

Overview

Use this skill to keep Codex anchored in the current project's own documentation. Project facts belong in the project folder being worked on, not in this skill; this skill only defines how to discover, read, use, and maintain those project-local docs.

Start Of Work

Before making changes or running services, inspect the current project folder for context documents. Prefer rg --files or the fastest available file search.

Look for these files and directories, in this order:

• AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules
• Project-local skill folders such as .agents/skills/, .codex/skills/, or repo-specific skills/
• Project overview docs such as docs/project-map.md, docs/architecture.md, docs/overview.md, docs/*structure*.md
• Environment docs such as docs/environments.md, docs/local-test-services.md, docs/*environment*.md, docs/*deploy*.md
• Pitfall and operations docs such as docs/pitfalls.md, docs/runbook.md, docs/troubleshooting.md, docs/*notes*.md
• Main readmes such as README.md and package/workspace docs

Read only the documents relevant to the task. If a project-local skill exists and matches the task, read its SKILL.md and any referenced files required by that skill.

New Project Bootstrap

If the project has no local context documents yet, create the first project documentation set before substantial project work unless the user explicitly requested a read-only investigation.

Create missing files as needed:

• AGENTS.md
• docs/project-map.md
• docs/environments.md
• docs/pitfalls.md
• docs/troubleshooting.md

Create docs/runbook.md or docs/operations.md only when the project already has repeatable operational procedures worth documenting.

Build the initial files from actual project evidence:

• Inspect existing instruction files such as CLAUDE.md, .cursorrules, .windsurfrules, and project-local skills.
• Read the main README.md, package/workspace manifests, build scripts, test scripts, configuration examples, and relevant docs.
• Summarize the repository's real stack, architecture, commands, environment boundaries, testing expectations, and coding conventions.
• Include any known safety boundaries for production, deployment, databases, secrets, external services, or destructive operations.
• Preserve existing project names, branding, attributions, import paths, module names, and license/copyright references.
• Mark unknown facts as unknown or omit them. Do not invent commands, ports, credentials, maintainers, deployment targets, or policies.
• Use placeholders for secrets and sensitive configuration.

Use this default split:

• AGENTS.md: agent-facing rules, workflow requirements, project constraints, and a short navigation guide.
• docs/project-map.md: repository structure, major modules, ownership boundaries, and where to look for common changes.
• docs/environments.md: known local/test/staging/production environments, ports, DSN shapes, service dependencies, and startup commands.
• docs/pitfalls.md: recurring mistakes, risky assumptions, compatibility traps, and decisions that future agents should not rediscover.
• docs/troubleshooting.md: symptoms, likely causes, recovery steps, and validation commands.

Keep generated documents concise and operational. They should guide future coding agents and human maintainers, not replace full product or architecture documentation.

User-Supplied Facts

Ask the user for missing information when the repository cannot reveal facts that are necessary to write accurate project context.

Prefer one concise batch of questions before creating the initial docs. Ask only for facts that materially affect future work, such as:

• Project purpose, product direction, or non-obvious domain constraints.
• Required local startup commands when scripts/configs do not reveal them.
• Supported environments and production safety boundaries.
• External services, databases, queues, caches, providers, or deployment targets that are not visible in files.
• Protected names, branding, attribution, compliance rules, or "never change" areas.
• Preferred test/build commands when multiple plausible commands exist.

If the user does not know yet, write TBD with a short note in the relevant project-local doc and continue. Never turn a guess into documented fact.

Environment Check

For tasks involving startup, deployment, tests, services, databases, queues, caches, external hosts, Docker, Nginx, or production-like behavior:

• Identify the intended environment: local, test, staging, production, or unknown.
• Read the project-local environment doc before running commands.
• Prefer local/test settings unless the user explicitly requests production.
• Confirm service hosts, ports, database DSNs, cache DSNs, frontend proxy targets, and startup commands from project-local docs or local runtime files.
• Do not invent missing environment facts. Discover them from files, process state, commands, or user-provided context.

Documentation Placement

Keep project knowledge inside the project folder currently being worked on.

Use existing project conventions when possible. Common durable locations are:

• AGENTS.md for agent-facing rules, required workflows, protected project constraints, and concise repository onboarding.
• docs/project-map.md for structure, product direction, major modules, and navigation anchors.
• docs/environments.md or docs/local-test-services.md for local/test/staging/production configuration, service locations, ports, DSN shapes, and startup commands.
• docs/pitfalls.md for recurring mistakes, known traps, and "do not do this again" notes.
• docs/troubleshooting.md for symptoms, diagnoses, recovery steps, and validation commands.
• docs/runbook.md or docs/operations.md for repeatable operational procedures.
• .agents/skills/<project-name>/references/*.md when the repository already uses project-local Codex skills and the knowledge is specialized enough to support that skill.

Do not store project-specific facts in this global skill. This skill should remain generic.

If the preferred document does not exist and the fact is durable enough to record, create the smallest appropriate project-local document rather than adding unrelated notes to this global skill. For a brand-new project, prefer creating the default bootstrap set in New Project Bootstrap so future notes have a clear home.

End Of Work Audit

Before the final response, check whether this turn discovered or changed durable project knowledge.

Update project-local docs when the answer is yes for any of these:

• A new stable environment fact was discovered, such as a host, port, DSN pattern, service boundary, or startup command.
• An old environment assumption was corrected.
• A recurring pitfall, failure mode, or troubleshooting step was learned.
• A repeated issue, bug pattern, investigation result, or workaround should be available to future agents.
• Project structure, architecture, ownership boundaries, or preferred workflows changed.
• A command or validation path became the recommended way to work in the project.
• The user explicitly asks to record or remember a project fact.

Do not update docs for one-off observations, temporary logs, transient process IDs, local-only noise, or speculative conclusions.

Sensitive Data

Never commit or document real secrets. This includes passwords, API keys, access tokens, session secrets, private keys, OAuth secrets, database dumps, and sensitive customer or provider credentials.

When documenting configuration, use placeholders:

SQL_DSN=postgres://<user>:<password>@<host>:<port>/<database>?sslmode=disable
REDIS_CONN_STRING=redis://<host>:<port>/<db>
SESSION_SECRET=<secret>

If a user provides a secret during the conversation, use it only for the requested operation and record only the non-sensitive shape or location in docs.

Final Response

Mention any project docs that were read or updated when relevant. If documents should be updated but were not, state the reason briefly.