Immutable. This exact content is served forever at /api/v1/blob/60129cc21824b1a1.
--- name: doc-synchronization description: >- High-priority rules and automated procedures for continuously keeping repository documentation, API references, architecture guides, changelogs, and agent skills synchronized with code changes autonomously without requiring human reminders. --- # Autonomous Documentation & Skill Synchronization Engine This skill establishes the **Zero-Reminder Automatic Synchronization Rule**: whenever ANY code, API, database schema, workflow, or architecture change is introduced or modified in the repository, all corresponding architectural documents, API references, READMEs, changelogs, and AI agent skills (`.agents/skills/`) MUST be automatically inspected, updated, and expanded by the agent **without requiring any prompting or reminders from the human user**. --- ## 1. High-Priority Rule: Zero-Reminder Automatic Synchronization > [!IMPORTANT] > **AUTONOMOUS DOCUMENTATION & SKILL UPDATES (No Human Prompting Needed)**: > - AI agents are strictly required to treat **Agent Skills (`.agents/skills/`)** and **Documentation (`docs/`, `README.md`, `CHANGELOG.md`)** as first-class codebase artifacts. > - Every feature addition (`feat`), improvement (`perf`/`refactor`), bug fix (`fix`), database migration (`db`), or DevOps pipeline (`ci`) MUST automatically trigger a synchronization pass across relevant skills and markdown specifications before finalizing commits. > - The human developer should **NEVER** have to ask: *"please update the docs"* or *"please update the agent skills"*. This is a mandatory, automated built-in reflex. --- ## 2. Universal Subsystem-to-Documentation Synchronization Matrix Whenever modifying files in any subsystem, the agent MUST automatically update the corresponding documentation and skill files: | Subsystem Modified | Typical Source Locations | Target Documentation & Skill Updates | | :--- | :--- | :--- | | **Git Workflow & Branching** | `.githooks/`, `scripts/git-*.sh`, `.github/workflows/` | `.agents/skills/git-commit-workflow/SKILL.md`<br>`.agents/skills/git-branch-management/SKILL.md`<br>`.agents/skills/git-post-merge-cleanup/SKILL.md`<br>`docs/GIT_WORKFLOW.md`<br>`CHANGELOG.md` | | **Database & Migrations** | `db/migrations/`, `backend/db/`, `migrations/` | `.agents/skills/repository-maintenance/SKILL.md`<br>`.agents/skills/polyglot-microservice-architecture/SKILL.md`<br>`docs/ARCHITECTURE.md`<br>`README.md`<br>`CHANGELOG.md` | | **AI Agents & RAG** | `agent/`, `ai-service/`, `tools/`, `utils/rag.py` | `.agents/skills/agent-observatory-workflow/SKILL.md`<br>`docs/ARCHITECTURE.md`<br>`docs/AI_AGENT_WORKFLOW.md`<br>`CHANGELOG.md` | | **SaaS Connectors & Cloud Storage** | `connectors/`, `storage/`, `integrations/` | `.agents/skills/saas-and-mcp-architecture/SKILL.md`<br>`docs/ARCHITECTURE.md`<br>`CHANGELOG.md` | | **Model Context Protocol (MCP)** | `mcp/`, `tools/mcp/`, server handlers | `.agents/skills/saas-and-mcp-architecture/SKILL.md`<br>`docs/MCP_GUIDE.md`<br>`CHANGELOG.md` | | **Backend & REST/WebSocket APIs** | `backend/`, `handlers/`, `routes/`, `api/` | `docs/API_REFERENCE.md`<br>`docs/ARCHITECTURE.md`<br>`backend/README.md`<br>`CHANGELOG.md` | | **Workers & Background Daemons** | `worker/`, `cmd/worker/`, `service/` | `docs/ARCHITECTURE.md`<br>`worker/README.md`<br>`CHANGELOG.md` | | **Frontend & UI Components** | `frontend/`, `web/`, `src/components/` | `README.md`<br>`frontend/README.md`<br>`CHANGELOG.md` | | **CI/CD & Containerization** | `.github/workflows/`, `*Dockerfile`, `docker-compose.yml`, `render.yaml`, `vercel.json` | `.agents/skills/ci-cd-workflow/SKILL.md`<br>`.agents/skills/docker-first-architecture/SKILL.md`<br>`docs/DEPLOYMENT_GUIDE.md`<br>`CHANGELOG.md` | --- ## 3. Autonomous Skill Creation & Evolution Rule - **When to Create a New Agent Skill (`.agents/skills/<name>/SKILL.md`)**: - Whenever introducing a new architectural pattern, operational domain, or subsystem that future AI agents must interact with or maintain (e.g. `saas-and-mcp-architecture`, `git-post-merge-cleanup`, `cli-tooling-guide`). - Format: Include YAML frontmatter (`name`, `description`) and comprehensive operational guidelines, rules, and example commands. - **When to Update Existing Skills**: - Whenever modifying runtime behaviors, adding flags to scripts, updating CLI commands, or changing deployment configurations. - Keep skills concise, actionable, and strictly synchronized with the live implementation. --- ## 4. Pre-Commit Autonomous Synchronization Checklist Before executing `git commit` or finalizing any milestone, execute this 5-step checklist: 1. **Inspect Staged/Modified Files**: ```bash git status --short ``` 2. **Cross-Reference Subsystem Matrix**: Identify all target docs and agent skills impacted by the modified files. 3. **Apply Documentation & Skill Edits**: Update markdown files and skills with exact details. 4. **Log in Changelog**: Add concise bullet points under `## [Unreleased]` in `CHANGELOG.md`. 5. **Sync Skills Upstream**: If any skill inside `.agents/skills/` was added or modified, execute `skills-sync push` to propagate updates to the central skills catalog.