Skip to content

docs(repo): add contributor orientation guides#652

Open
horacioh wants to merge 1 commit into
mainfrom
builder-context-kit-docs
Open

docs(repo): add contributor orientation guides#652
horacioh wants to merge 1 commit into
mainfrom
builder-context-kit-docs

Conversation

@horacioh
Copy link
Copy Markdown
Collaborator

Summary

  • Add a canonical Seed Builder Guide with read order, repo map, doc status conventions, and workflow entry points.
  • Add architecture, code map, domain glossary, dev setup, and feature brief docs for cross-subsystem contributor orientation.
  • Add backend and frontend subsystem READMEs covering package ownership, sources of truth, and common commands.
  • Refresh existing README and agent/editor command docs to use current pnpm, web, and repo workflow guidance.

Breaking Changes

None.

Add subsystem READMEs, architecture and setup docs, glossary, code map,
and a feature brief template. Update agent and editor guidance to use pnpm
commands and avoid implicit git mutations during push checks.
@horacioh horacioh self-assigned this May 22, 2026
Comment thread backend/README.md
@@ -0,0 +1,47 @@
# Backend
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

If this is for agents, why is it in the README.md and not in AGENTS.md?

On the other hand:

I'm not a big fan of listing files and directories in markdown files, because it often confuses the agent when stuff changes and document goes stale. And even if it stays up to date, it would often hallucinate something because it would rely on the docs instead of checking the actual code.

In my experience with Claude, Codex, and Kimi, no amount of asking to keep docs up to date reliably keeps them up to date.

The code itself + per-folder AGENTS.md when necessary works pretty good for me. Some additional tools that would index the code and search for it more quickly also help:

  1. https://github.com/dmtrKovalenko/fff
  2. https://github.com/glommer/memelord
  3. https://github.com/tobi/qmd
  4. There's lots of them...

Comment thread docs/code-map.md
@@ -0,0 +1,129 @@
# Code map
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Same comment here: I'm very reluctant to duplicating stuff that's already clear from the file-system layout into markdown files.

This file in particular looks very overwhelming. I can't see how this could help us save tokens or drive the agent better. I wouldn't be surprised if it was actually harming — causing the agent to read unnecessary files, and blowing up the context window with irrelevant information.

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.

2 participants