docs: add self-deleting first-time setup hint to AGENTS.md and CLAUDE.md - #52
Merged
Conversation
A fresh template clone needs the README "Setup Your Plugin" steps (rename placeholder/, edit pyproject.toml etc.). Today the agent instruction files don't mention this, so an AI agent jumps straight to uv sync / tox on an uninitialized repo. Add a top-of-file "First-time setup" section that detects an uninitialized template via the presence of placeholder/, points to the README setup steps, and instructs the agent to delete the section itself once setup is complete - so it only lives in fresh-template repos.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
## First-time setupsection to the top of bothAGENTS.mdandCLAUDE.mdthat triggers on the presence ofplaceholder/, points to the README### Setup Your Pluginsteps, and instructs the agent to delete the section itself once setup is complete.Why
Today neither file mentions that the template needs initialization. An agent jumps straight to
uv sync/toxon an uninitialized clone and can ship a plugin still namedplaceholder-my-plugin. Detection byplaceholder/directory existence is a single load-bearing artifact, so one check is enough.Test plan
AGENTS.mdandCLAUDE.mdtop-to-bottom; confirm flow makes sense for a first-time user.placeholder/directory still exists in the template repo (trigger condition correctly active here).diff CLAUDE.md AGENTS.mdreturns empty (files stay 1:1 identical).