readme.rules

Root README Maintenance Rules

Last Updated: 2025-04-01 06:22:55 PM EDT

Purpose

The root README.md serves as the primary introduction and quick-start guide for the project. It is crucial that it accurately reflects the project's current state, core features, structure, and how to install, run, build, and test it. This rule ensures the README is considered for updates after significant changes.

Trigger for README Update ("Major Changes")

A review and potential update of the root README.md MUST be considered by the agent after successfully completing tasks that involve any of the following major changes:

1. New Package/App: Adding a new workspace package under apps/ or packages/.
2. Major Feature Implementation: Completing a significant, user-facing feature or core functionality update.
3. Build/Run/Test Command Changes: Modifying fundamental scripts in root or workspace package.json files, turbo.json, or core config files (vite.config.ts, vitest.workspace.ts) that alter how developers interact with the project.
4. Installation/Setup Changes: Adding new required dependencies, environment variables, or setup steps.
5. Core Architectural Shifts: Significant refactoring that changes the project structure or how key modules interact (which might necessitate updating structure diagrams or descriptions).
6. Deprecation/Removal: Removing a package or significant feature.

Minor changes (e.g., internal refactors, simple bug fixes, dependency bumps unless they change usage) generally do not require a root README update, although related package-level READMEs might.

README Update Workflow (Agent Action)

When you determine that a completed task qualifies as a major change:

1. Flag Need: Acknowledge internally or log that the README.md should be reviewed for potential updates.
2. Read Current README: Load the full content of the root README.md file.
3. Analyze Impact & Identify Sections: Based on the nature of the major change, determine which sections of the README are likely affected. Common sections include:
   • Project Overview / Introduction
   • Features List
   • Repository Structure / Architecture Overview
   • Prerequisites / Installation
   • Getting Started / Usage / Development Workflow
   • Available Scripts / Commands (Build, Test, Lint, etc.)
   • Configuration
   • Deployment (if applicable)
4. Generate Necessary Updates: Draft clear, concise, and accurate updates for only the affected sections. Ensure commands, file paths, and descriptions are correct.
5. Apply Updates: Modify the README.md file content with the generated updates. If unsure about the impact or wording, you may optionally present the proposed changes to the user before applying.
6. Log & Commit: Report that the README.md has been updated. Ensure the updated README.md is included in the same commit or PR as the major change it documents.