https://github.com/libar-dev/architect
https://github.com/libar-dev/architect
astro documentation starlight typescript
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/libar-dev/architect
- Owner: libar-dev
- License: other
- Created: 2026-01-26T10:29:56.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T05:44:36.000Z (3 months ago)
- Last Synced: 2026-04-04T00:47:34.689Z (3 months ago)
- Topics: astro, documentation, starlight, typescript
- Language: TypeScript
- Homepage: https://libar.dev/
- Size: 8.42 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Maintainers: MAINTAINERS.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @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.
[](https://www.npmjs.com/package/@libar-dev/architect)
[](https://github.com/libar-dev/delivery-process/actions)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
---
## 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
```bash
# 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
```typescript
/** @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](docs/CONFIGURATION.md).
### 3. Generate Documentation
```bash
npx architect-generate -g patterns -i "src/**/*.ts" -o docs -f
```
### 4. Enforce Workflow (Pre-commit Hook)
```bash
npx architect-guard --staged
```
This validates FSM transitions and blocks invalid status changes.
---
## How It Works
**TypeScript annotations** define pattern metadata and relationships:
```typescript
/**
* @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.
---
## What Gets Generated
All output goes to [`docs-live/`](docs-live/INDEX.md) — 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`](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 | [CLI Reference](docs-live/reference/CLI-REFERENCE.md) |
| `architect-lint-patterns` | Validate annotation quality (missing tags, etc.) | [Validation Rules](docs-live/VALIDATION-RULES.md) |
| `architect-guard` | Validate delivery workflow FSM transitions | [Process Guard Reference](docs-live/reference/PROCESS-GUARD-REFERENCE.md) |
| `architect-lint-steps` | Validate vitest-cucumber feature/step compatibility | [Validation Rules](docs-live/VALIDATION-RULES.md) |
| `architect-validate` | Cross-source validation with Definition of Done checks | [Validation Rules](docs-live/VALIDATION-RULES.md) |
---
## Documentation
### Generated Docs (auto-maintained)
**[`docs-live/INDEX.md`](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](docs/CONFIGURATION.md) | Presets, tags, config files |
| [METHODOLOGY.md](docs/METHODOLOGY.md) | Core thesis, dual-source "why" |
| [GHERKIN-PATTERNS.md](docs/GHERKIN-PATTERNS.md) | Writing effective specs |
| [SESSION-GUIDES.md](docs/SESSION-GUIDES.md) | Day-to-day AI/dev workflows |
| [VALIDATION.md](docs/VALIDATION.md) | Automated quality checks |
---
## License
MIT © Libar AI