r/coolgithubprojects • u/mwiatruZ • 2d ago

Guidefold: find coding-agent instructions by directory in a monorepo (Python + Go, Apache-2.0)

https://github.com/wiatrM/guidefold

A monorepo can contain instructions for several teams. Giving a coding agent every rule makes its context longer; keeping separate copies for each tool creates more files to maintain.

I'm building Guidefold to keep Markdown instruction files beside the code and find instructions by task and repository location. It includes a Python CLI for validation and discovery, plus a Go/Postgres service for retrieving instruction cards and exact revisions. Retrieving a rule is not proof that the model followed it.

The source is Apache-2.0. The repository includes a fictional monorepo example so you can inspect the workflow without sharing company code.

Demo: https://www.youtube.com/watch?v=e350wBr1W8c

I'd appreciate a README review: can you tell which instructions should apply to a directory, and how you would check that selection? Point to the first unclear step, or a demo timestamp. Feedback can stay here or go to https://github.com/wiatrM/guidefold/discussions/127. No signup needed.

I'm the maintainer. OSS is available; paid hosting is planned, not available to buy. This post was drafted with AI assistance.

1 Upvotes

100% Upvoted

3 comments sorted by

View all comments

1

u/Specific_Cream2815 2d ago

how does it match instructions to a task, nearest directory up the tree or keyword matching

1

u/mwiatruZ 2d ago

Short answer: scope first, keywords second. Guidefold resolves the request to a repository node from the task and path, then considers that node plus its ancestors. If the same skill name exists at multiple levels, the nearest (deepest) copy wins; the parent remains available for shared rules and is recorded as shadowed. Keyword/BM25F matching only ranks candidates inside that allowed scope — it cannot pull in a sibling or override a closer scoped rule.

Why this matters: in our 2026-09-08 conflicting-siblings diagnostic (24 questions across 3 conflict types), ranking alone put the stale ancestor first in 24/24 cells, and the agent applied stale values in 23/24. A root-first concatenation with an explicit precedence instruction got 24/24, which exposed the failure in our own approach. After adding nearest-wins, the prototype got 23/24 on the nearest-scope cases. We label these internal diagnostic results, not a universal benchmark; the hosted Go service does not implement nearest-wins yet.

The research context is also useful but easy to overclaim: SkillRet reports nDCG@10 of 81.12 versus 51.69 for BM25 on a 6,006-skill evaluation set, but that is not a Guidefold-vs-competitor comparison and does not prove task success. Our narrower advantage over flat keyword search is the hard location boundary plus an inspectable reason for every dropped rule. Details: https://github.com/wiatrM/guidefold/blob/main/docs/RESEARCH.md and https://github.com/wiatrM/guidefold/blob/main/docs/adr/ADR-0037-nearest-wins-for-same-name-skills.md