Almirah is distributed as a Ruby gem. This page takes you from an empty machine to a rendered project in your browser.
The gem requires Ruby 3.0 or newer. Check what you have:
$ ruby -v
ruby 3.2.0 (2022-12-25 revision a528908271) [arm64-darwin22]If your Ruby is older, install a current one with your version manager of choice (rbenv, rvm, asdf) or from ruby-lang.org.
$ gem install Almirah
Successfully installed AlmirahPlease note that the gem has a capital letter in the name. It is essential for installation.
The easiest way to start is to let Almirah scaffold a small example project:
$ almirah create my_projectThe command creates a folder with two specifications, three test protocols, two executed test runs, and one decision record — a miniature of a real project:
my_project/
├── decisions/adr-001-start-project-decision.md
├── specifications/
│ ├── req/req.md
│ └── arch/arch.md
└── tests/
├── protocols/tp-001 tp-002 tq-001
└── runs/001 010$ almirah please my_project
Project file not found: project.yml
parsing specifications ..... 2 ok
parsing test protocols ..... 3 ok
parsing decisions .......... 1 ok
parsing risk records ....... 0 ok
traceability matrices ...... 1 ok
coverage matrices .......... 2 ok
decision links ............. 1 ok
risk links ................. 0 ok
rendering HTML ............. my_project/build/index.htmlThe Project file not found warning is harmless here: without a project.yml Almirah falls back to defaults. You will add a project.yml once you want to configure inputs, risk registers, or linked source-code repositories.
Open the result in your browser — every reference is now a hyperlink, and traceability and coverage matrices are generated next to the documents:
$ open my_project/build/index.htmlThe tests/protocols folder holds non-executed test cases. To execute them, copy a protocol into a numbered run folder, fill in the results, and process the project against that run:
$ cp -r my_project/tests/protocols/tp-001 my_project/tests/runs/002/
# mark each test step with a pass or fail result, then:
$ almirah please my_project --run 002The coverage matrix now reflects that exact test run.