Menu
Use when completing development phases or branches to identify and update AGENTS.md files that may have become stale - analyzes what changed, determines affected contracts and documentation, and coordinates updates
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Use when analyzing a large corpus of text, code, or data that exceeds a single agent's effective context - orchestrates parallel Worker subagents, Critic review subagents, and a final Summarizer subagent with task tracking and failure recovery
Use to decide what kind of basic agent you should use
Use when creating a new opencode plugin or setting up plugin structure - provides complete file organization, manifest format, and component definitions for commands, agents, skills, hooks, and MCP servers
Use when creating specialized subagents for opencode or the task tool - covers description writing for auto-delegation, tool selection, prompt structure, and testing agents
Use when creating, releasing, or maintaining an opencode Plugin Marketplace - covers marketplace.json schema, version management, release checklists, changelog conventions, and validation to prevent sync drift between plugin.json and marketplace.json
Use when creating or editing skills, before deployment, to verify they work under pressure and resist rationalization - applies RED-GREEN-REFACTOR cycle to process documentation by running baseline without skill, writing to address failures, iterating to close loopholes
| name | maintaining-project-context |
| description | Use when completing development phases or branches to identify and update AGENTS.md files that may have become stale - analyzes what changed, determines affected contracts and documentation, and coordinates updates |
REQUIRED SUB-SKILL: Use the writing-agents-md-files skill for all context file creation and updates.
Context files (AGENTS.md) document contracts and architectural intent. When code changes contracts, the documentation must update. Stale documentation is worse than no documentation.
We use OUR format structure (Purpose, Contracts, Dependencies, Invariants, etc.) — AGENTS.md is the cross-platform AI agent context filename.
Trigger: End of development phase, branch completion, or any work that changed contracts, APIs, or domain structure.
| Change Type | Update Required? | What to Update |
|---|---|---|
| New domain/module | Yes | Create domain context file |
| API/interface change | Yes | Contracts section |
| Architectural decision | Yes | Key Decisions section |
| Invariant change | Yes | Invariants section |
| Dependency change | Yes | Dependencies section |
| Bug fix (no contract change) | No | - |
| Refactor (same behavior) | No | - |
| Test additions | No | - |
Diff against the base (branch start or phase start):
# Get changed files
git diff --name-only <base-sha> HEAD
# Get detailed changes
git diff <base-sha> HEAD --stat
Categorize changes:
For each significant change, determine which context file should document it:
| Change Location | Context File Location |
|---|---|
| Project-wide pattern | Root AGENTS.md |
| New domain | <domain>/AGENTS.md (create) |
| Existing domain contract | <domain>/AGENTS.md (update) |
| Cross-domain dependency | Both affected domains |
Hierarchy rule: Information belongs at the lowest level where it applies. Domain-specific contracts go in domain files, not root.
For each affected context file, verify:
# Find domain's public exports
grep -r "export" <domain>/index.ts
# Find domain's imports (dependencies)
grep -r "from '\.\." <domain>/
For updates:
date +%Y-%m-%dFor new domains:
<domain>/AGENTS.md using the template from writing-agents-md-filesgit add <affected AGENTS.md files>
git commit -m "docs: update project context for <branch-name>"
Has code changed?
├─ No → Skip (nothing to update)
└─ Yes → What changed?
├─ Only tests/internal details → Skip
└─ Contracts/APIs/structure → Continue
│
├─ New domain created?
│ └─ Create <domain>/AGENTS.md
│
├─ Existing domain changed?
│ └─ Update domain AGENTS.md (read first!)
│
└─ Project-wide pattern changed?
└─ Update root AGENTS.md
Always update when:
Never update for:
| Mistake | Fix |
|---|---|
| Updating for every change | Only update for contract changes |
| Forgetting freshness date | Always use date +%Y-%m-%d |
| Documenting implementation | Document contracts and intent |
| Putting domain info in root | Use domain context files for domain contracts |
| Skipping verification | Read the code, confirm contracts hold |
| Writing AGENTS.md without reading | Always read existing content before updating |
Called by:
Uses: