@libar-dev/architect

Context engineering for AI-assisted codebases.

Turn TypeScript annotations and Gherkin specs into a structured, queryable delivery state — living documentation, architecture graphs, and FSM-enforced workflows that AI agents consume without hallucinating.

---

Why This Exists

AI coding agents need architectural context to generate correct code. This package makes code the single source of truth for both humans and machines — annotations in code and Gherkin specs replace manually maintained docs that drift out of date.

---

Quick Start

1. Install

# npm
npm install @libar-dev/architect@pre

# pnpm (recommended)
pnpm add @libar-dev/architect@pre

Requirements: Node.js >= 18.0.0, ESM project ("type": "module" in package.json)

2. Annotate Your Code

/** @architect */

/**
 * @architect-pattern UserAuthentication
 * @architect-status roadmap
 * @architect-uses SessionManager, TokenValidator
 *
 * ## User Authentication
 *
 * Handles user login, logout, and session management.
 */
export class UserAuthentication {
  // ...
}

Tag prefix is configurable. The default libar-generic preset uses @architect-* (shown above). See docs/CONFIGURATION.md.

3. Generate Documentation

npx architect-generate -g patterns -i "src/**/*.ts" -o docs -f

4. Enforce Workflow (Pre-commit Hook)

npx architect-guard --staged

This validates FSM transitions and blocks invalid status changes.

---

How It Works

TypeScript annotations define pattern metadata and relationships:

/**
 * @architect
 * @architect-pattern TransformDataset
 * @architect-status completed
 * @architect-uses MasterDataset, ExtractedPattern, TagRegistry
 */
export function transformToMasterDataset(input: TransformInput): MasterDataset {
  // ...
}

Gherkin feature files own planning metadata (status, phase, deliverables). The generator merges both sources into a unified MasterDataset.

Pipeline: Config → Scanner → Extractor → Transformer → Codec — files become patterns, patterns become a MasterDataset, the MasterDataset renders to Markdown and JSON.

---

What Gets Generated

All output goes to docs-live/ — 57+ auto-generated files from annotated source code:

Output	Files	Source
Product area docs	7	@architect-uses, @architect-status, relationship tags
Business rules	7	Gherkin Rule: Invariant/Rationale blocks
Architecture decisions (ADRs)	7	Decision feature files
Reference guides	8	CLI schema, codec patterns, annotations
Live Mermaid diagrams	—	@architect-uses, @architect-depends-on relationships
API type shapes	—	@architect-shape on TypeScript declarations
Validation rules	3	Process Guard FSM specs
Taxonomy reference	3	Tag registry
AI context modules	13	@architect-claude-module tagged specs
Changelog	1	Release specs

Browse it: docs-live/INDEX.md is the navigation hub with reading order, document roles, and product area statistics.

---

CLI Commands

Command	Purpose	Docs
architect-generate	Generate documentation from annotated sources	architect-generate --help
architect	Query delivery state for AI coding sessions	Process API Reference
architect-lint-patterns	Validate annotation quality (missing tags, etc.)	Validation Rules
architect-guard	Validate delivery workflow FSM transitions	Process Guard Reference
architect-lint-steps	Validate vitest-cucumber feature/step compatibility	Validation Rules
architect-validate	Cross-source validation with Definition of Done checks	Validation Rules

---

Documentation

Generated Docs (auto-maintained)

docs-live/INDEX.md is the navigation hub — 57+ files generated from annotated source code, organized into product areas, reference guides, business rules, ADRs, taxonomy, and validation rules.

Editorial Docs (hand-maintained)

Document	Focus
CONFIGURATION.md	Presets, tags, config files
METHODOLOGY.md	Core thesis, dual-source "why"
GHERKIN-PATTERNS.md	Writing effective specs
SESSION-GUIDES.md	Day-to-day AI/dev workflows
VALIDATION.md	Automated quality checks

---

License

MIT © Libar AI