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.
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.
# npm
npm install @libar-dev/architect@pre
# pnpm (recommended)
pnpm add @libar-dev/architect@preRequirements: Node.js >= 18.0.0, ESM project ("type": "module" in package.json)
/** @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-genericpreset uses@architect-*(shown above). See docs/CONFIGURATION.md.
npx architect-generate -g patterns -i "src/**/*.ts" -o docs -fnpx architect-guard --stagedThis validates FSM transitions and blocks invalid status changes.
TypeScript annotations define pattern metadata and relationships:
/**
* @architect
* @architect-pattern TransformDataset
* @architect-status completed
* @architect-uses PatternGraph, ExtractedPattern, TagRegistry
*/
export function transformToPatternGraph(input: TransformInput): PatternGraph {
// ...
}Gherkin feature files own planning metadata (status, phase, deliverables). The generator merges both sources into a unified PatternGraph.
Pipeline: Config → Scanner → Extractor → Transformer → Codec — files become patterns, patterns become a PatternGraph, the PatternGraph renders to Markdown and JSON.
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.
| Command | Purpose | Docs |
|---|---|---|
architect-generate |
Generate documentation from annotated sources | architect-generate --help |
architect |
Query delivery state for AI coding sessions | CLI 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 |
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.
| 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 |
MIT © Libar AI
