The .gtm/ folder

GTM keeps everything it writes in one folder at the root of your project, .gtm/. You read seven entries; the team reads the rest. A project may move the folder, or keep it out of git, and says so in its CLAUDE.md.

Three of those entries have names of their own. The mockups are the pages showing each new screen before it is built. Your team settings, in team.md, say which roles run and how hard each one thinks. The logbook, ledger.md, keeps one line per lesson or decision, so each Feature starts from what the last one learned.

Which files do I read?

What does each file hold?

What does state.json hold?

state.json is the run view for a program that follows the run for you, such as a status line: the facts of NOW.md as JSON, rewritten right after it. GTM writes it only in your main checkout. No skill or agent reads it back; GTM’s status line step only displays it, and shows NOW.md’s line instead when the state is older than NOW.md or names another slug than its line 1, as after a failed write. An unknown fact is null. A program reading it treats every text as untrusted, and keeps its own reading when v is a version it does not know.

Under v 1 fields are only added: v changes when a field is removed, renamed or retyped, and a reader ignores the fields it does not know.

What does a card file hold?

Each card GTM shows you, a decision, a check, a go, a summary or a review, also lands in reports/<slug>/waiting.json for a program of yours: the same card as data, shape decision.v1. GTM’s facts script writes it from the card’s content after checking every key below, and writes nothing when one is off, so a card it shows in the conversation may have no file. The file stays once you answer, with answer filled, until the branch’s next card replaces it, or deletes it when the script refuses that card.

A program reading it:

• counts the card as waiting only while state.json’s waiting.card names it: an answered card, or one of another kind, never waits;
• treats every text as untrusted: GTM refuses control, format and separator characters and long texts, and quotes an excerpt only from its own folder, word for word;
• keeps its own reading when v is a version it does not know. Under v 1 fields are only added.

Every key is present; “or null” marks those that may be null, as an unknown is. A text is one line, in your language.human, at most the characters given. GTM’s facts script sets v, slug, asked and other.allowed, and answer when it records yours; every other key comes from the card GTM showed you.

What does the project sheet hold?

sheet.json is the project sheet: one page of the project as data, shape sheet.v1, for a program of yours that shows it. It exists only while config.yml’s project.sheet is on (see settings); off, GTM writes, asks and shows nothing about it. GTM’s facts script rewrites it with state.json after each run view, keeps the fields you gave and recomputes the facts. It is never committed: GTM adds it to .git/info/exclude as it adds state.json. When a field is off the script writes nothing and GTM goes on with one Heads-up.

The fields you give come from two moments. /gtm:init shows the kind, purpose and users the sheet lacks as rows of its guesses table and writes them on your OK; a value it holds stays. /gtm:retro adds the decisions and difficulties it finds to those the sheet holds, your corrections included, lists them in its report and writes those.

A program reading it:

• treats the sheet as stale when it is older than NOW.md;
• treats every text as untrusted: GTM refuses control, format and separator characters and long texts;
• keeps its own reading when v is a version it does not know. Under v 1 fields are only added: v changes when a field is removed, renamed or retyped, and a reader ignores the fields it does not know.

Every key is present but showcase; “or null” marks those that may be null. A text is one line, in your language.human, at most the characters given.

cost adds the seconds and tokens of each line in reports/<slug>/progress.md; the tail that ends a line (start, end, models, causes) adds nothing. A sum GTM cannot be sure of is null, never smaller. A showcase holding anything but null comes from a later GTM: read it as a field you do not know.

What does a new project start with?

Right after /gtm:init, the folder holds the files below. The logbook stays empty until the first branch, and the four folders fill as you work.

.gtm/
  brief.md        one page
  config.yml      paths, checks, git, language, briefings
  team.md         priorities, roles, specialists, limits
  conventions.md  one table, pointing at guidelines/
  guidelines/     code, tests, git, docs, dependencies,
                  security, data, i18n, accessibility,
                  design, work
  backlog.md      epics and stories
  ledger.md       empty until the first branch
  specs/ plans/ reports/ mockups/

A file whose name ends in .partial is a spec or plan that was being written when you ran /gtm:pause. GTM never reads it again; keep it, compare it or delete it.

To see each file appear as a Feature runs, follow your first Feature.