garrytan / garrytan/gstack

Design question: TODOS.md in git vs other docs in ~/.gstack/

Open
#1,124 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
133k
Forks
19.9k
Avg merge
18h 46m
Merged PRs (30d)
26

Description

Hi Team,

Hope you can help me out on this, as it helps me understand the information model and work better with gstack.

# Context

`/office-hours` saves the design doc as `~/.gstack/projects/{slug}/` directory — local to the user and outside the git repository. Other important documents that drive implementation and QA (like test plans) live in the same local folder. These feel more like shared contracts that drive subsequent phases, yet they are only visible locally.

Meanwhile TODOS.md lives in the repo. CONTRIBUTING.md calls it the "unified backlog" and both `/ship` and `/review` read and write it. However, from using gstack, I noticed that TODOS.md only has a fraction of what actually gets implemented — so it doesn't appear to be a consolidated promotion of those local documents.

# My question

I assume this design is intentional, but I don't understand the principle behind it. Specifically:

- Why do the ~/.gstack/projects/ docs stay local while TODOS.md is checked in?
- How does this model support a team working on a single project?

Thanks for taking the time — really enjoying gstack so far!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.