@alistigo/artifact-manager

Holos

Alistigo main monorepo. Apps, libraries, documentation, ... — all in one place.

Structure

Directory	Purpose
apps/	Runnable applications — CLI tools, web servers, desktop apps
packages/	Reusable libraries, publishable to npm / GitHub Packages
docs/	Project documentation — plans, goals, architecture docs (no code)
ai/	Agents AI skills, commands (source of truth), and persistent memory

Setup

bash scripts/setup.sh

The script installs mise (if needed), wires shell activation for zsh/bash/sh, installs Node dependencies, and sets up Claude tooling.

Common Commands

pnpm build              # Build all projects
pnpm build:typecheck    # Type-check all packages
pnpm test               # Run all tests

Quality Assurance

All static analysis and linting tools follow the qa:* prefix — keeping QA commands grouped and discoverable, separate from build/run/test commands.

Script	Tool	What it checks
pnpm qa	All QA tools	Run all qa:* checks (lint + arch-check + dead-code + audit + stories)
pnpm qa:lint	Biome	Code style, formatting, and lint rules across all packages
pnpm qa:arch-check	dependency-cruiser	Architectural boundary violations — see docs/arch-check.md
pnpm qa:dead-code	Fallow	Unused files, exports, and dead code (full repo scan)
pnpm qa:audit	Fallow	Changed-file risk gate — fast audit for pre-push and CI
pnpm qa:stories-check	custom script	Every component has a co-located .stories.tsx (ADR 0012)
pnpm build:typecheck	TypeScript	Type correctness across all packages
pnpm test	Bun test / Playwright	Unit, integration, and end-to-end tests

All qa:* checks run automatically:

• Pre-push (via lefthook): qa:lint, qa:arch-check, qa:audit, build:typecheck — blocks the push if any fail
• CI on PRs and merges to main: qa:lint, qa:arch-check, fallow audit (with inline PR annotations), build:typecheck, build, and test

Documentation

Doc	What it covers
docs/sdlc.md	AI-augmented SDLC philosophy — lifecycle stages, AI touchpoints per stage, human review gates, agent orchestration patterns
docs/arch-check.md	Architectural boundary rules enforced
docs/adrs/	Architecture Decision Records — why the repo is shaped the way it is

Continuous Deployment

Every merge to main automatically triggers a full release cycle via nx release: version bumps, changelog generation, GitHub Releases, and npm publishing for all affected packages and apps. If CI passes, it ships.

The QA pipeline is the confidence layer — lint, arch-check, dead-code audit, typecheck, build, and tests all run on every PR. Passing those gates is the definition of "ready to release."

On rollbacks: current apps are client-first (no server, no database). Rolling back means pointing to a previous published version — all npm package versions are retained permanently, and previous app build artifacts can be re-served. A formal rollback mechanism for apps is deferred; quick fix + redeploy is the current recovery strategy. A structured rollback system becomes important as the project grows to include stateful apps.

For unknown bugs that slip through: error monitoring and observability catch them in production. The response is a rapid new commit + redeploy, not a revert.

See docs/adrs/0013-release-strategy.md and docs/adrs/0002-branch-protection.md for the architectural rationale behind these choices.