Repository navigation
docs: state the purpose, goals, and non-goals of the repository and each package - #1633
Conversation
…nes from README.md AGENTS.md lists the `## Purpose`, `## Goals`, `## Non-goals`, and `## Milestones` sections of the root README.md, so the text people read is the text agents get. The configuration file is `wbfy.json` and holds only `typos`. Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
…ach package Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request standardizes the documentation across the repository by introducing consistent 'Purpose', 'Goals', and 'Non-goals' sections in the root and package-level README files. These changes facilitate better integration with the 'wbfy' tool and provide clearer context for both human developers and AI agents working within the WillBooster ecosystem. Highlights
New Features🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. The docs were scattered, thin and wide, With purpose hidden deep inside. Now goals are clear and set in stone, For agents working on their own. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds Purpose, Goals, and Non-goals sections to the main README, package-specific READMEs, and AGENTS.md to clearly define the objectives and constraints of the repository and its packages. However, a new instruction was added directly to AGENTS.md, which is generated by wbfy and will be overwritten; this instruction should be moved to AGENTS_EXTRA.md.
| - Put temporary files in `.tmp`; use `/tmp` only for files that must live outside the repo. | ||
| - Before finishing, delete every temporary file, backup, and external resource (e.g., databases, deployed Workers, branches) you created during the task for experiments or verification, without asking, after recording any findings worth keeping in your final response or in a file you keep. Keep an item only when a next step the user requested needs it or it holds the only copy of pre-task data the task was not meant to discard (e.g., a backup a tool kept because restoring it conflicted), and then state in your final response why and the command that deletes it. | ||
| - `AGENTS.md` and `.gemini/styleguide.md` are generated by `wbfy`; edit agent instructions only in `AGENTS_EXTRA.md`, and the project's purpose, goals, non-goals, and milestones only in the `## Purpose` (one paragraph), `## Goals`, `## Non-goals`, and `## Milestones` (one list each) sections of `README.md`. | ||
| - `Goals` and `Milestones` under Project Information are not yet achieved: use them to choose between alternatives and to propose work, never to implement beyond what a task requests, and never present them as existing features or achieved results (e.g., in announcements). Delete a line from `README.md` once it is achieved. |
There was a problem hiding this comment.
This new instruction is added directly to AGENTS.md. However, as noted in line 48, AGENTS.md is automatically generated by wbfy, and manual edits will be overwritten. Please move this instruction to AGENTS_EXTRA.md instead so that it is preserved when the file is regenerated.
There was a problem hiding this comment.
This line is not a manual edit: it is wbfy's own output. generateAgentInstruction in packages/wbfy/src/generators/agents.ts emits the goal instruction whenever the README front matter has goals, and AGENTS.md here is the result of running wbfy from main on this branch, so regenerating reproduces it. Moving it to AGENTS_EXTRA.md would duplicate a generated instruction.
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
…kpoints Generated instructions define the four README sections where agents are told to edit them, forbid inferring them from the code, and apply the "not yet reached, delete once reached" rule to milestones only. Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
…e is realized Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
# Conflicts: # packages/wbfy/src/generators/agents.ts # packages/wbfy/test/unit/agentInstructions.test.ts
# Conflicts: # AGENTS.md
…nes from the README front matter Sections in the body blend into the rest of the README; the front matter keeps them apart and gives wbfy a schema to validate. Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
# Conflicts: # AGENTS.md
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
…goals # Conflicts: # AGENTS.md # docs/expected-repository-rules.md # packages/wbfy/src/generators/agents.ts # packages/wbfy/src/projectDirection.ts # packages/wbfy/test/unit/agentInstructions.test.ts
Co-authored-by: WillBooster (Claude Code) <agent@willbooster.com>
Why
The project direction that
wbfyreads from the README front matter (#1632) had no real example. This writes it for the repository, states each package's purpose and goals in its README, and regeneratesAGENTS.md. It is separate from #1632 because that PR is afeat, and a squashedfeatcommit touching every package directory would release every package.Requirements
wb's goals include printing to standard output only the minimum an agent needs, with what it does not need removed.AGENTS_EXTRA.md, the READMEs, the owner's stated aim of AI agents developing and operating software without people); the three framework libraries have only a purpose.MotivationandPhilosophyinpackages/wbfy/README.mdare replaced bypurposeand a goal, because they said the same thing.Customer Summary
The root README and each package README say what the package exists to achieve.
AGENTS.mdlists the root's purpose, goals, and non-goals underProject Information.Technical Summary
The wording is a draft: review each sentence for whether it is what the package is actually for, and the order of the goals, which decides which goal wins when two conflict. Non-goals restate rules already in
AGENTS_EXTRA.mdand the READMEs (WillBooster and WillBoosterLab repositories only, macOS and Linux only, one canonical format per generated file).Testing
bun run verifyAGENTS.mdis the output ofwbfyrun from the source ofmainon this branch.readProjectDirectionand parsed.Notes
How npmjs.com renders front matter was not confirmed: a Markdown renderer without front matter support shows
---as a horizontal rule and the keys as text. The package READMEs are published, so look at one package page after its next release.The title of
packages/shared-lib-node/README.mdwas# libraryand is now the package name.