Keeping Docs Synced

VibeReady includes an auto-documentation system that keeps your codebase documentation synchronized with code changes. Git hooks trigger documentation generation on every commit, so your AI tools always have current context.

---

How It Works

1. Setup once: npm install (Husky hooks auto-install)
2. Code and commit — The post-commit hook creates README templates for new routes (if they do not already exist)
3. Prompt AI: “Use the readme-updater skill to update READMEs for my recent changes.”
4. Commit docs — Push (validated)

---

Critical: AI Must Fill READMEs

Git hooks create empty templates only. You must prompt AI to fill them with actual business logic and context:

Use the readme-updater skill to update READMEs for my recent changes.

Hooks never overwrite existing READMEs — your content is safe. The auto-generation script only creates new templates for routes that do not have a README yet.

---

Commands

make generate-docs      # Force regenerate all docs
make validate-ai        # Validate completeness
git commit --no-verify  # Skip hooks temporarily

---

Maintaining the Principles/Implementation Split

Many rule files in the AI context layer use a two-section structure: Principles (universal approach) and Implementation (library-specific patterns). When editing these files, follow these guidelines:

Deciding where new content goes:

• Principles section: Architectural decisions, design rationale, “what” and “why” guidance. Must contain no library imports, no specific API calls, no framework syntax. Example: “All database queries must be scoped by organizationId.”
• Implementation section: Concrete code patterns, library-specific examples, “how” guidance. Example: a Prisma query with where: { organizationId }.

After modifying any rule file, run the setup command to regenerate per-tool rules (for Cursor, Windsurf, and others) from the master files. Skipping this step means your AI tools will use stale patterns.

Keep Principles portable. If you find a library import or a framework-specific API call inside a Principles section, move it to the Implementation section. The Principles section should make sense even if you swap the underlying technology. See Stack Customization for more on the principles/implementation separation.

---

Troubleshooting

Issue	Fix
Docs not generating	Run npm install to reinstall Husky hooks
Validation failing	Run make validate-ai and fix the reported issues
Stale AI patterns	Run the setup command to regenerate per-tool rules

---

Related Documentation

• AI Development Framework — Full architecture and git hooks overview
• Stack Customization — How the principles/implementation split enables technology swaps
• Prompt Library and Skills — The readme-updater skill and other workflows