Skip to content

feat: Add AI agent docs#11881

Merged
mekarpeles merged 4 commits into
internetarchive:masterfrom
lokesh:ai-docs
Feb 18, 2026
Merged

feat: Add AI agent docs#11881
mekarpeles merged 4 commits into
internetarchive:masterfrom
lokesh:ai-docs

Conversation

@lokesh
Copy link
Copy Markdown
Collaborator

@lokesh lokesh commented Feb 17, 2026

[feature] Add AI instruction bridge: one canonical guide, thin wrappers for each AI tool

Note: In the spirit of this direction, most of the PR description text is AI generated, though edited and verified by me.

Sets up a maintainable system for guiding AI coding assistants (Claude Code, OpenAI Codex, GitHub Copilot, Cursor). A single canonical guide lives at docs/ai/README.md; each tool gets a minimal bridge file in the location it natively discovers.

Files added/changed:

File What Why
docs/ai/README.md Canonical guide (~150 lines) Single source of truth for all AI tools
CLAUDE.md Thin bridge (~40 lines) Claude Code auto-discovers this at repo root
AGENTS.md Thin bridge (~40 lines) OpenAI Codex and Cursor natively read this
.github/copilot-instructions.md Thin bridge (~40 lines) GitHub Copilot natively reads this path

No .cursorrules file is added — Cursor reads AGENTS.md natively and .cursorrules is legacy/deprecated.

Technical

  • The canonical doc is docs/ai/README.md).
  • Each bridge file contains an identical quick-reference section (stack summary, key commands, code style rules, critical entry points) so an AI agent can orient on small tasks without reading the full guide. Each opens with a callout pointing to the canonical doc for deeper context.
  • Maintenance going forward: update only docs/ai/README.md when project guidance changes. The bridges should rarely need touching - they contain only stable quick-reference content (commands, style rules, entry points).

Testing

Screenshot

Stakeholders

@mekarpeles @cdrini @jimchamp

… guidelines for contributing to the docs. This includes instructions for adding new topics and updating general guidance.
@lokesh lokesh requested a review from mekarpeles February 17, 2026 06:52
…ns and add a new checklist for creating components. Emphasize the preference for using `Ol` prefix over `OL` for new components.
@RayBB
Copy link
Copy Markdown
Collaborator

RayBB commented Feb 17, 2026

Two relevant issues: #11147 and #11006

Will come back with more thoughts later.

@mekarpeles
Copy link
Copy Markdown
Member

Also related: #11887 -- I wonder if we can reconcile

@mekarpeles mekarpeles merged commit a062e6b into internetarchive:master Feb 18, 2026
2 checks passed
@mekarpeles mekarpeles self-assigned this Feb 18, 2026
@RayBB
Copy link
Copy Markdown
Collaborator

RayBB commented Feb 18, 2026

@mekarpeles I still wanted to give feedback. I'm not sure if you've read the docs on copilot but I don't think this follows them.
Also I don't think having duplicated agents and claud.md is worthwhile it should be a sim link at best.
Adding docs for AI specific things in general should be done with care as to not further fragment out human docs.
Is there a good reason why we should write all separate docs for AI?

@@ -0,0 +1,39 @@
# Copilot Instructions
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think this file actually has to be in an .github/agents/ dir

@mekarpeles
Copy link
Copy Markdown
Member

@RayBB the approach @lokesh put in place DRY's documentation into a single readme and also contains a single high-level AGENTS.md.

Github suggests using .github/copilot-instructions.md (for copilot -- which we have credits for) and
https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#creating-repository-wide-custom-instructions

@RayBB
Copy link
Copy Markdown
Collaborator

RayBB commented Feb 18, 2026

@mekarpeles
How is it DRY? AGENDTS.md and CLAUDE.md are exactly the same minus the header.

The following markdown block is also repeated in 4 files part of this PR.

## Code Style

- **Python:** ...
- **JavaScript:** ...
- **CSS/LESS:** ...
- ```

@lokesh
Copy link
Copy Markdown
Collaborator Author

lokesh commented Feb 19, 2026

@RayBB @mekarpeles

There is some code duplication here, but this PR enables support for multiple tools and we get the benefits now, rather than waiting for a perfect AI docs architecture design.

On maintainability: the bridge files should be stable and only require occasional updates, and if they get out of sync, they are a prompt away from getting realigned. Most importantly, the standards for AI docs are evolving, and I expect we'll be moving, renaming, and reorganizing files and content in the future. These files are not precious, better to start and iterate than wait.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants