Space Architect ๐
The Architect Loop โ structured judgment-and-build cycles for humans and their agents! โจ๐ฐ๏ธ
space-architect is the gem behind the Architect Loop: a structured
judgment-and-build cycle in which a strong reasoning model (the architect)
plans, freezes acceptance criteria, and judges the work of a fleet of headless
AI builders โ one per lane, each in its own git worktree. The loop runs inside
task-scoped spaces: directories that hold repos, notes, and artifacts under
one obvious filesystem root. Nothing lives only in a chat window โ every
decision, spec, and verdict is committed to the space repo.
It installs one executable, architect. The spaces substrate is a sibling
gem:
| Gem | Dependency | What it provides |
|---|---|---|
| space-cadet | hard | The spaces substrate (Space::Core): create, manage & containerize task-scoped workspaces โ the space binary โ plus the copy-on-write evergreen-checkout substrate repos provision from |
Installation ๐ฆ
gem install space-architectThe gem installs one executable: architect. ๐ (Or add
gem "space-architect" to your Gemfile and bundle install.)
Upgrading from the 8.x monolith? Uninstall space-architect 8.x first โ
its space/src executables collide with the ones the new gems ship โ see
the upgrade guide.
60-second start ๐
Run one full loop iteration in a scratch space โ the tutorial walks it end to end:
space init # create the XDG config + state files (space-cadet gem)
space new "Docsmith Tutorial" # blast off a new space ๐
cd ~/architect/spaces/<id>-docsmith-tutorial
architect init # scaffold ARCHITECT.md + the space.yaml project: blockFrom there the loop is: architect new โ architect section โฆ โ architect freeze โ architect dispatch โ architect gate โ architect integrate. The
tutorial runs every step on a scratch repo.
The four quadrants ๐งญ
| Quadrant | Read it when youโฆ | Start here |
|---|---|---|
| Tutorials โ learning-oriented | are new and want a guided journey | docs/tutorials |
| How-to guides โ goal-oriented | have a specific task to do | docs/how-to |
| Reference โ information-oriented | need a fact about a command, flag, or file | docs/reference |
| Explanation โ understanding-oriented | want the why behind the design | docs/explanation |
Development ๐ ๏ธ
bundle install
bundle exec rake test # the full minitest suite
bundle exec rake build # build the gem into pkg/
bundle exec rake install # build + install into your user gem homeBug reports and pull requests are welcome on GitHub at https://github.com/jetpks/space-architect. Available as open source under the MIT License.
Made with ๐ and fibers ๐งต by Eric