Why I keep an Entry Point repo
A fictional theatre needs its tickets to show when the doors open. Its programme and box office live in separate repos.
~/posts/entry-point-for-ai$cat post.md
Suppose a little theatre called Paper Moon keeps its evening programme in one repository and prints its tickets from another. The theatre, the repositories, and the paths below are all made up.
The programme says “Doors at 7, curtain at 7:30.” The ticket just says “7:30.” Someone asks the coding agent to put the doors time on the ticket, using the wording from the programme. A perfectly ordinary request, except that from inside the ticket checkout “the programme” is a couple of words with no path attached.
I like to keep a small Git repo for starting jobs like this. I call it Entry Point. It gives the agent somewhere to look up both ends of that sentence.
What the box office owns
Put the active projects in docs/projects.md. Paper Moon could get by with two rows:
| Project ID | Everyday name | Profile |
|---|---|---|
paper-programme |
programme | docs/projects/paper-programme.md |
paper-box-office |
box office, tickets | docs/projects/paper-box-office.md |
Link each row to its profile in the entry repo. The box office profile needs a couple of facts worth keeping around. Ticket layouts belong here. Start at printing/README.md, relative to the checkout. The exact spelling of the time field can stay in the template. Copy it into the profile and a field rename becomes an edit in two repositories.
Now the agent can read the programme to find out which time means doors and which means curtain, then edit the ticket layout in the box office. If the request had just said “change the time for Paper Moon,” I’d want it to ask where. Both repos can put the wrong time in front of an audience.
Where the checkouts live
Say the directories happen to be called playbill and tickets on our imaginary machine. Here’s the entry repo’s local entry-point.local.toml:
[projects]
paper-programme = "/example/paper-moon/playbill"
paper-box-office = "/example/paper-moon/tickets"
For your own setup, run git rev-parse --show-toplevel in each checkout and use the absolute paths it prints. Stop at tickets in this example. The profile already supplies printing/. If the theatre ever puts both products in a monorepo, the IDs can point to the same Git root and the profiles can give each product’s directory.
Put /entry-point.local.toml in the root .gitignore. Share an entry-point.local.example.toml containing a [projects] header and a commented example. Whoever clones the box office onto a different drive gets to pick their own path.
The first project
Open the Git repo where you want to start your sessions. Give the agent the following, with the brackets filled in.
Set up this repo as my Entry Point. Start with <project name>. I usually
call it <alias>. Its repository is <URL> and my checkout is at <path,
or blank if unknown>. Make the setup changes here in the entry repo.
Keep any existing entries. Add the project to the Active projects table
in docs/projects.md. Give it a lowercase, hyphenated ID. In
docs/projects/<id>.md, record what it's for, its aliases, its URL, its
directory within the repo, and which docs to open. Verify those paths.
Save the checkout's Git root under [projects] in entry-point.local.toml.
Keep the other mappings. Ignore the local file in Git and include a
shareable entry-point.local.example.toml. Tell me if the path is missing.
Write a short root AGENTS.md. When I name a project, look up its profile.
Read that project's AGENTS.md and README.md and any instructions closer
to the files being changed. Ask about ambiguous aliases. Only visit the
whole active list when I explicitly ask for all of it. Git status and
diff are fine. Fetching, staging, committing, pushing, and deploying
each need an explicit request from me.
Open a fresh session and give it a small read-only job first. “I want to change the ticket layout. Which instructions should I open?” At Paper Moon it should land on printing/README.md inside the box office checkout. For your own project, ask it to open the file and find a template you recognise. An agent can repeat a name from the index even with a typo in the checkout path.
Back in the entry repo, check what Git knows about the local file:
git check-ignore -- entry-point.local.toml
git ls-files -- entry-point.local.toml
The first command should print the filename and the second should print nothing. Next time there’s a correction to the tickets, “box office” will do.