geb-protocol_skill

Overview

This skill implements the GEB protocol for lightweight project positioning using a three-level Root/Folder/File metadata convention. It ensures AI agents can self-locate anywhere in the repository by maintaining _dir.md templates and brief file header I/O/Pos comments. The hook auto-generates _dir.md when a folder is created so AI fills Input/Output/Pos quickly.

How this skill works

On folder creation the hook inserts a _dir.md template prompting the module purpose, Input, Output, and Pos. Files include a three-line header comment indicating Input, Output, and Pos to describe dependencies and exposed interfaces. A lightweight Root file lists high-level modules and layering to give global coordinates for navigation.

When to use it

• When you want AI agents to find their location and responsibilities anywhere in a repo.
• For projects growing beyond a few dozen files where undocumented structure slows contributions.
• When maintaining consistent interfaces and change traceability across modules.
• When adding new folders so the hook can scaffold module metadata automatically.
• For Python-based services like a Discord bot where simple metadata accelerates automation.

Best practices

• Keep Root summary to one sentence plus a one-line module map for fast orientation.
• Fill _dir.md with concise Input/Output/Pos entries (3–4 lines) and update on behavior changes.
• Place 3-line file headers in Python files: # Input / # Output / # Pos and update on refactors.
• Enforce post-change checks: update file headers, _dir.md, and architecture when dependencies change.
• Adopt full three-layer protocol for projects with 50+ files; minimal headers suffice for small repos.

Example use cases

• A Discord bot repo where new command folders get an auto-generated _dir.md for consistent interfaces.
• Refactoring core rules: update file headers and corresponding _dir.md so AI and humans can trace changes.
• Onboarding contributors: quick Root overview plus folder-level Pos markers to show where to add features.
• Automated CI lint that asserts presence and currency of I/O/Pos metadata before merge.
• Scaling a microservice repo: use Root module map to document layering (cli → flows → core → data).