Skip to content

feat(tooling): enforce docs freshness and modernize agent skills - #6756

Merged
waleedlatif1 merged 5 commits into
stagingfrom
feat/docs-drift-check
Aug 16, 2026
Merged

feat(tooling): enforce docs freshness and modernize agent skills#6756
waleedlatif1 merged 5 commits into
stagingfrom
feat/docs-drift-check

Conversation

@j15z

@j15z j15z commented Aug 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

  • Add a read-only docs:check mode that detects stale generated integration docs and run it through the existing check:audits CI gate.
  • Preserve final-output comparison for trigger-owned pages and regenerate the five pages already stale on staging.
  • Keep .agents/skills/<name>/SKILL.md as the canonical skill source, expose complete skill directories to Claude through generated .claude/skills/<name> symlinks, and let Cursor discover .agents/skills directly.
  • Remove all 36 deprecated .claude/commands projections, all 36 deprecated .cursor/commands projections, and the stale duplicate Cursor add-hosted-key skill.
  • Update skill syncing, pre-commit behavior, contributor guidance, and integration-authoring skills for the new layout; rename skills:check to check:skills so the existing CI audit runner discovers it automatically and continues rejecting stale Claude links or reintroduced command projections.

This prevents generated docs and agent-specific skill copies from silently drifting away from their canonical sources.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • Other: Developer tooling

Testing

  • bun run agent-stream-docs:generate
  • bun run skills:sync
  • bun run lint
  • bun run apps/sim/scripts/check-block-registry.ts origin/staging
  • bun run check:audits (28 audits, including docs:check and check:skills)
  • bun run check:skills
  • git diff --check

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

Not applicable; this PR only changes developer tooling, generated documentation, and agent configuration.

@j15z
j15z requested a review from a team as a code owner August 16, 2026 00:22
@vercel

vercel Bot commented Aug 16, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview Aug 16, 2026 1:56am

Request Review

@cursor

cursor Bot commented Aug 16, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Summary

Low Risk
Changes are contributor docs, agent command removals, and CI-adjacent skill checklists; no runtime product code in the shown diff.

Overview
Integration authoring skills now treat generated integration docs as a CI gate: run bun run docs:check after generate-docs and integration-catalog:check, and add checklist items so stale .mdx fails in check:audits.

Regeneration policy flipped in validate-integration and related skills: contributors must commit the full generator diff, including catch-up pages from earlier PRs that skipped regen — reverting swept-in hunks as "unrelated drift" is documented as breaking docs:check.

Agent skill layout cleanup: large deprecated .claude/commands/* projections (e.g. add-block, add-integration, add-tools) are deleted from the diff; canonical guidance stays under .agents/skills/*/SKILL.md (the PR description also covers skills:sync, check:skills, and symlinked .claude/skills — not all of that appears in this diff hunk set).

Reviewed by Cursor Bugbot for commit 3ce4b6c. Bugbot is set up for automated code reviews on this repo. Configure here.

@greptile-apps

greptile-apps Bot commented Aug 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR adds read-only generated-documentation freshness enforcement and migrates agent integrations from copied command projections to canonical skill directories.

  • Adds docs:check and includes generated-documentation verification in the audit suite.
  • Replaces Claude command copies with generated skill-directory symlinks while allowing Cursor to consume canonical skills directly.
  • Removes deprecated projections, refreshes stale integration documentation, and updates contributor and skill guidance.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up review scope.

No blocking failure remains.

Important Files Changed
Filename Overview
scripts/generate-docs.ts Adds an in-memory overlay and final-output comparison so CI can detect stale generated documentation without mutating the checkout.
scripts/sync-skills.ts Replaces copied command projections with Claude directory symlinks and introduces validation and cleanup for generated skill surfaces.
scripts/run-audits.ts Adds documentation freshness checking while renamed check:skills remains covered through automatic check:* discovery.
package.json Exposes the new documentation and skill checks through repository scripts.
.husky/pre-commit Updates canonical-skill synchronization to stage generated Claude skill links.
.github/CONTRIBUTING.md Documents the canonical skill directory and the current Claude and Cursor discovery model.

Flowchart

 
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Canonical[".agents/skills/name/"] --> Cursor["Cursor direct discovery"]
  Canonical --> Sync["scripts/sync-skills.ts"]
  Sync --> Claude[".claude/skills/name symlink"]
  Sources["Blocks, tools, and triggers"] --> Generator["scripts/generate-docs.ts"]
  Generator --> Docs["Generated integration docs"]
  Audits["check:audits"] --> SkillCheck["check:skills"]
  Audits --> DocsCheck["docs:check"]
  SkillCheck --> Claude
  DocsCheck --> Docs
Loading

Reviews (5): Last reviewed commit: "fix(skills): clean orphaned Claude proje..." | Re-trigger Greptile

cursor[bot]
cursor Bot reviewed Aug 16, 2026
View reviewed changes
Comment thread scripts/generate-docs.ts
@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@greptile

@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@cursor review

cursor[bot]
cursor Bot reviewed Aug 16, 2026
View reviewed changes

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 36e2316. Configure here.

@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@greptile

@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@cursor review

cursor[bot]
cursor Bot reviewed Aug 16, 2026
View reviewed changes

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit ccedbb2. Configure here.

@j15z
j15z force-pushed the feat/docs-drift-check branch from ccedbb2 to 8491532 Compare August 16, 2026 01:42
@j15z j15z changed the title feat(docs): fail CI when generated integration docs are stale feat(tooling): enforce docs freshness and modernize agent skills Aug 16, 2026
@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@greptile

@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@cursor review

cursor[bot]
cursor Bot reviewed Aug 16, 2026
View reviewed changes
Comment thread scripts/sync-skills.ts
@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@greptile

@j15z

j15z commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@cursor review

cursor[bot]
cursor Bot reviewed Aug 16, 2026
View reviewed changes

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 3ce4b6c. Configure here.

@waleedlatif1
waleedlatif1 merged commit 7f936dc into staging Aug 16, 2026
31 checks passed
@waleedlatif1
waleedlatif1 deleted the feat/docs-drift-check branch August 16, 2026 02:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cursor cursor[bot] cursor[bot] left review comments
@waleedlatif1 waleedlatif1 waleedlatif1 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@j15z @waleedlatif1