Troubleshooting and FAQ
Resolve discovery, Python, state validation, and dependency problems.
The skill does not appear
Confirm that the complete directory is installed and SKILL.md has its name and description frontmatter. Project installation uses .agents/skills/devthread/; global installation uses ~/.agents/skills/devthread/. Start a fresh chat and explicitly ask to use $devthread. Codex detects skill changes automatically; if the skill is missing, restart Codex and consult the current OpenAI guidance. The renamed user installation has been loaded in Codex on Windows; see compatibility for the evidence limits.
Python cannot run
Run python --version on Windows, or python3 --version on Linux and macOS. If your shell cannot find it or invokes an incorrect executable, repair the local Python setup before running the scripts. The tested environments used Python 3.13. Other versions are untested.
GitHub installation cannot find the skill
The source is available at kurarensu16/devthread. Confirm the installer is using that repository and the skill/devthread path, including SKILL.md and its supporting directories. Check any selected branch or ref and GitHub access. The installation page also provides source and archive installation steps. Additional installer routes remain untested for DevThread.
npm install devthread fails
DevThread v0.1.0 is public on npm. Check that Node.js is version 22 or later and that your configured registry can reach the package. npm view devthread version --registry=https://registry.npmjs.org/ checks the public release. npm install devthread downloads the CLI package; npx devthread install places the complete skill in its discovery directory. See the installation guide for source and archive alternatives.
The installer says the destination already exists
The installer preserves files, directories, and linked destinations, including empty directories. Review and retain your existing copy before updating it, or select a different exact directory with --dest. There is no automatic replacement option.
An installation stopped partway through
Read the error and resolve the filesystem problem. The installer writes SKILL.md last and reports the partial directory if copying fails. Review and preserve that directory before retrying; the installer does not remove it automatically.
Target is not a directory
Create the project directory first. Initialization expects an existing directory; quote a target path containing spaces.
Validation fails
Read the specific error and compare the file with the format reference. Common causes include malformed frontmatter, a filename/ID mismatch, missing required sections, an undefined requirement, missing dependencies, a cycle, or a ready task with an unfinished dependency. Review and repair the map manually; initialization does not erase invalid state.
Both state directories exist
If a project has both .devthread/ and legacy .devmap/, all scripts stop to avoid choosing the wrong map. Review which state is authoritative and preserve the other map in a safe location before rerunning the scripts. Existing .devmap/ projects do not need to rename their directory to use DevThread.
No task is eligible
Check that at least one task is ready and all of its dependencies are done. Backlog, blocked, and review tasks do not qualify. Status reports the saved state; changing it requires an explicit review decision.
Is verified the same as done?
No. Evidence describes what checks support; status describes work progression. A task can have verified criteria while awaiting acceptance in review.
Does DevThread run my tests automatically?
The agent's verify workflow runs relevant available checks when requested and permitted. The status and validation scripts inspect the map; they do not execute application tests. A check that cannot run must be recorded as not run with a reason.
Can I use another agent?
The packaging is readable and self-contained, but other hosts have not been tested. Follow their current installation guidance and record a representative exercise before claiming support.