aq2bq/gy

<img src="https://raw.githubusercontent.com/aq2bq/gy/main/docs/images/logo.svg" alt="gy" width="200"

gy — good,yes

English | 日本語

What is gy?

gy aims to free you from the chores of "telling the AI the context it needs, and organizing that context so it gets across", so that you finish your work sooner and go home earlier. Concretely, it takes the large amount of context that arises "after the need, before the deliverable" and holds it, together with strict invariants, as a graph of the following nodes and edges.

flowchart LR
  N[Need]
  Q[Question]
  D[Decision]
  R[Requirement]
  AC[Acceptance criterion]
  N -- spawned-by --> D
  N -- filed-as --> R
  N -- waits-on --> Q
  N -- waits-on --> R
  N -- depends-on --> N
  N -- targets --> AC

R -- relies-on -- D R -- raised -- Q Q -- closes -- D D -- "narrows /<br widens /<br supersedes /<br completes" -- D

Using it is simple:

1. Make the AI aware of gy
   (a skill named `gy-loop` is bundled, so telling it "from today, let's work along gy-loop" is enough)
2. Tell it what you want to do and why it is needed

That is all. From then on, even in a new session, ask the AI "what's next?" and it tells you what to do next.
Details come later, but the moment gy helps most is when you overturn one of your own past decisions.

## How to use

cargo install gy

# optional (the quick way to tell the AI about `gy`)
npx skills add aq2bq/gy

Once a day, in the background, gy runs cargo info gy to learn the newest release on crates.io. When it is newer than yours, gy handover and gy next say so in one line on stderr, with the command to update. No other request leaves your machine unless you share a ledger.

Telling the AI about gy

Put a sentence like the following in a prompt or in AGENTS.md / CLAUDE.md so it gets across, and the AI agent resumes from gy handover and gy next every time.

This project tracks its progress in gy. Before you start or resume anything, read the gy-loop skill and follow the record.

Where the record itself lives

The record itself is saved by default under $XDGDATAHOME/gy/<hash of the repository root/. Unless you set up team sharing (described below), gy never goes out to the network. Putting it inside the project's repository is not recommended, because the cycle of changes "after the need, before the deliverable" and the cycle of changes to the deliverable are completely different.

[EXPERIMENTAL] Using gy as a team / putting the record on a remote

Still experimental, but

gy remote set https://github.com/you/yourproject-gy.git