Troubleshooting and FAQ

Quick answers first, then fixes for the problems new users hit most. The Architect layer shows how to debug a run from the records Guild Stack keeps.

FAQ

Which version should I use?

Use 3.0.0. It is the current stable release. The main branch of the Guild Stack repo always holds the stable version. The next branch holds the beta.

Which AI coding tools does it work with?

Claude Code and Codex. These are the two tools the 3.0.0 release was tested on before it shipped. See Use one release in Claude Code and Codex.

Will Guild Stack change my code without asking?

/guild:init does not touch your code or tests. It writes its notes into .guild/. When you ask for a change, Guild Stack changes the files the task needs. Always review the change with git diff before you commit.

Where does Guild Stack keep its work?

In the .guild/ folder in your project. See Reading what Guild Stack wrote.

I used Guild Stack 2. Did the commands change?

Yes. Guild Stack v3 has 13 commands instead of 22. Eleven old command names still exist for now. Each one prints its new name and stops. For example, /guild:fix tells you to use /guild:maintain fix. The old names go away in a later release.

How do I know the release is good?

The 3.0.0 release shipped with test evidence: 31 out of 31 checks passed on both Claude Code and Codex, signed and tied to the exact source commit. Deeper: the Architect docs.

Troubleshooting

I don't see the `/guild:` commands

Close Claude Code and start a new session. Claude Code loads plugins when a session starts.
Check the install receipt exists:
```
cat ~/.guild/receipts/claude-code-cli.json
```
If the file is missing, run the install again.
If the commands are still missing, go back to the folder where you ran the install (the one that contains src/). Run the install line again, then start a new session:
```
bash src/install.sh --host claude-code-cli
```
Deleted that folder? Follow the full install again.
Still missing? See Still stuck? below.

A command just prints another command and stops

You typed an old Guild Stack v2 name. Guild Stack v3 renamed it. Use the name it prints:

Old	New
`/guild:fix`	`/guild:maintain fix`
`/guild:audit`	`/guild:maintain audit`
`/guild:evolve`	`/guild:maintain evolve`
`/guild:rollback`	`/guild:maintain rollback`
`/guild:stats`	`/guild:status stats`
`/guild:dashboard`	`/guild:status dashboard`
`/guild:resume`	`/guild:status resume`
`/guild:goal`	`/guild:plan goal`
`/guild:adopt`	`/guild:init adopt`
`/guild:migrate`	`/guild:config migrate`
`/guild:models`	`/guild:config models`

Known issues

These are open issues. Our test suite tracks each one.

/guild:status creates a .guild/ folder in a project where you never ran /guild:init. Run /guild:init first. (Issue #217, scenario status-readonly.)
The code map misses some imports. A file that only does module.exports = require('./b') gets no import link in codebase-map.json. (Issue #218, scenario learn-map.)
A recorded decision is not linked from the wiki start page. The decision page is in .guild/wiki/decisions/; open it from there. (Issue #220, scenario wiki-decision-capture.)
Adding several similar notes in a row can pause some of them. Guild Stack holds a note that looks like one it already has. After adding notes, check that each one appears in .guild/wiki/. (Issue #222, scenario wiki-recall-precision.)

Still stuck?

Open an issue on GitHub. Include the output of cat ~/.guild/receipts/claude-code-cli.json and the path to the run folder in .guild/runs/.

Debug a run from its records

Every run keeps its own evidence under .guild/runs/<run-id>/. When something looks wrong, read in this order:

verify.md — the final check's verdict, with the failing check and its evidence when it failed.
handoffs/*.md — one receipt per lane: what changed, what was assumed, what is left open.
logs/v1.4-events.jsonl — the full event trace: every phase, tool call, gate decision, and escalation, one JSON object per line.

/guild:maintain fix [run-id|symptom] loads Guild Stack's systematic-debug discipline over the same records: it finds the root cause before it proposes any fix. The full record layout is on Runs and operations.