trellis's ablate command copies your specs outside the project and keeps them there until restore verifies

The comparison command writes your spec and task text outside the project and keeps it there

One FAQ entry on this front page is a security disclosure, and it is the most useful thing in the document.

The question is whether you can temporarily compare a project with and without this tool. The answer is yes, via a command that removes the project's tool-specific surfaces, and the important detail is in how.

Before it removes anything, it creates what the text calls a verified recovery transaction outside the project. Then a fresh agent session runs the comparison, and a restore command recovers the exact prior state. Both operations can be previewed with a dry-run flag, which is good.

Then the paragraph you should not skip. The private recovery transaction includes the exact bytes of your tasks, specs and workspace, the text says these may contain user-authored sensitive text, and it says the transaction is kept until the restore verifies successfully.

So a reversible-sounding comparison operation copies your specifications, your task documents and your session journals to a location outside your repository, and that copy persists after the tool has finished with it.

The consequence is that this is a write of your content somewhere you did not choose, with a retention policy that depends on a restore succeeding. If your specs contain anything you would not paste into a ticket, read where that transaction is written before running this, and confirm the restore actually ran.

The documented install is a global install at the latest tag

The quick start gives one install command, and it has three properties worth separating.

It installs globally, which means the command becomes available on your path rather than being a dependency of a project.

It pins to a distribution channel labelled latest, which resolves to whatever the newest published version is at the moment you run it.

And the package name is scoped, so it comes from one registry namespace, which the front page does not tie to the repository's own organisation name.

The middle one is the interesting choice for a tool that writes files into your repository. This is not a library you import at a pinned version in a lockfile. It is a command you put on your machine, which then creates directories and files inside whichever repository you run it against. Running it twice on different days can produce different behaviour in the same repository.

If you want reproducibility, which is reasonable for anything that modifies a working tree, the documented command does not give you that. You would need to install a specific version explicitly, which means departing from the quick start.

The documented install and init are two commands:

npm install -g @mindfoldhq/trellis@latest

trellis init -u your-name

So the consequence is that this is a tool you trust the same way you trust a globally installed formatter or linter, rather than the way you trust a pinned dependency. Worth being deliberate about, because its whole purpose is to write into your source tree.

The verification phase runs your own lint, type-check and tests, not a model's opinion

The four-phase loop is the architecture, and one of its phases is the reason the project is worth a look.

Phase one is planning. A named sub-agent walks through requirements one question at a time and writes a requirements document. Research-heavy items are handed to a second sub-agent. The output is a set of curated specification files plus research files, referenced from two manifest files with a line-oriented format.

Phase two is implementation. A sub-agent writes code from that document with the curated context injected automatically. And here is a detail worth noting: the front page states explicitly that this phase makes no version-control commit.

Phase three is verification. A third sub-agent reviews the diff against the specifications and runs linting, type checking and tests, self-fixing where it can.

Phase four is finishing. A final check runs, then a fourth sub-agent promotes whatever was learned back into the specifications so the next session starts with it.

Phase three is the load-bearing one. The claim is not that the agent reviews its own work well. It is that the check runs the tooling you already trust, so a change that fails your linter or your type checker fails the loop regardless of what the model thinks.

So the consequence is that this works best where your existing checks are strict. If your lint rules are loose or your tests are slow, phase three is weak, and no amount of specification writing fixes that.

Eight platform directories are committed to the repository it is meant to help

The top level of this repository is a list of dot-directories, one per coding agent, and it is the clearest evidence of what the tool does.

There are eight of them. They cover a general agent convention, two named assistants, a coding tool, an orchestration tool, and three others whose names the front page does not explain. Alongside them sit two agent instruction files at the top level, one for each of the two best-known assistants.

So the tool that says these files become monolithic ships nine of them itself.

There is a reasonable explanation. A tool that supports twenty-two platforms has to have somewhere to put its own instructions, and the repository is the natural place. It is also the honest answer to the comparison the FAQ makes: the project needs an agent instruction file like anyone else, and it writes one for each platform it supports.

What is worth noticing is the contrast with the pitch. The argument against the single-file approach is that it becomes monolithic. The remedy is scoped specifications under a directory, auto-injected per session, plus a task directory and a workspace directory for journals. That is the `.trellis` directory at the top of this repository, which is the tool's own configuration for itself.

So the consequence is that adopting it means adopting a directory structure, and reviewing the resulting diff is part of the work rather than an afterthought. If your team is not ready to review generated files in a repository, this is the wrong shape of tool.

A TypeScript tool that requires Python, with a Python type checker configured

The prerequisites list two runtimes for a project whose primary language is a scripting language that compiles to JavaScript, and there is a configuration file for the other one.

The prerequisites are Node at version eighteen or newer, and Python at version three point nine or newer.

At the top level of the repository there is a configuration file for a Python static type checker.

So the Python requirement is not incidental to a build script. There is type checking configured for Python code in a project whose shipped package is a Node command.

The manifest does not explain why. The package is split into two workspace packages, a core and the command line tool, and each has its own build, test and lint scripts. The core is the more likely home for anything that might want a scripting runtime for templating or generation, and the presence of a type checker config suggests the Python code is meant to be checked rather than merely run.

It is worth asking about before you install it, because a second language runtime is a second thing to provision on every machine that runs the command, and on every continuous integration runner.

So the consequence is that the footprint is larger than a single Node package, and the front page does not say which part needs the other runtime.

The release process has seven scripts and no published releases

The workspace manifest devotes eight scripts to releasing this project, and the platform's release list is empty.

The scripts are: a general release, then separate ones for a minor, a major, a beta and a release candidate. Then one called promote. Then two that are not releases at all, a check and a plan, both invoking a preflight script with different arguments.

The naming tells the story. Beta and candidate channels exist, and promote is the step that turns one into the other. That is a conventional progression, and the fact that each stage is a distinct script means promoting a candidate is a deliberate act rather than an accident of a version bump.

The two preflight scripts are the interesting ones. One checks versions, the other produces a publish plan. Having a plan step that prints what is about to go out, before it goes out, is a small discipline that many projects would benefit from.

And there are no published releases. The changelog is not on the platform either; the front page links it on the documentation site.

So the consequence is that you cannot pin a version by release, and you cannot read a changelog in the place you would expect to find one. The install command asks for the latest tag, which is consistent with a project whose release artefacts live somewhere else entirely.

The comparison with the alternative tools is about file size, not about capability

The FAQ opens by naming the three files a developer probably already has, and the argument it makes is narrower than you might expect.

It says those files are useful entry points, but they tend to become monolithic. The reply is that this tool adds scoped specifications, task documents, workflow gates, workspace memory and platform-aware generated files around them.

So the claim is not that the alternative files are wrong. It is that they grow without structure, and the structure is the product.

That is a fair argument, and it is also a much smaller claim than the repository's own description, which is four words asserting that this is the best harness of its kind, with nothing behind it.

The rest of the FAQ is where the design choices are actually documented. One entry answers whether it is only for one assistant, and says it is a project layer that works across multiple agents and editors. One answers whether it is for individuals or teams, and says both, with the larger benefit for teams on shared standards, task boundaries, reviewable context and platform portability. One answers whether you have to write every specification by hand, and says teams often let the model draft specifications from existing code and then tighten the important parts.

And one answers the question a team actually asks first, which is whether this causes constant merge conflicts. The answer is that personal journals stay separate per developer while shared specifications and tasks live in the repository where they can be reviewed.

So the consequence is that the merge-conflict question has a considered answer and the superlative does not. Read the FAQ, not the description.

Editorial conclusion

This is aimed at teams where an agent writes most of the code and the recurring cost is re-explaining conventions. The design decision that earns its keep is that specifications live in the repository as reviewable artefacts rather than in a prompt you paste, and the four-phase loop runs your own lint, type-check and tests against the result rather than asking the model whether it looks right. Two things to check before you adopt it. Where the recovery transaction from its comparison command is written, because the front page says it contains your task, spec and workspace bytes and is kept until a restore verifies. And whether global installation at the latest tag is acceptable, since the documented install command gives you no way to pin a version.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository