Skip to content

INDEX.md

Latest commit

 

History

History
231 lines (180 loc) · 13.8 KB

INDEX.md

File metadata and controls

231 lines (180 loc) · 13.8 KB

Documentation Index

Purpose: Navigate the full documentation set for @libar-dev/architect. Use section links for targeted reading.

Package Metadata

Field Value
Package @libar-dev/architect
Purpose Context engineering platform for AI-assisted codebases
Patterns 401 tracked (266 completed, 83 active, 52 planned)
Product Areas 7
License MIT

Quick Navigation

If you want to... Read this
Learn the architecture ARCHITECTURE.md
Browse product area overviews PRODUCT-AREAS.md
Review architecture decisions DECISIONS.md
Check business rules BUSINESS-RULES.md
Understand the tag taxonomy TAXONOMY.md
Check validation rules VALIDATION-RULES.md
Browse the changelog CHANGELOG-GENERATED.md
Query process state via CLI CLI Reference
Find CLI workflow recipes CLI Recipes
Run AI coding sessions Session Workflow Guide
Enforce delivery process rules Process Guard Reference
Learn annotation mechanics Annotation Reference
See codec patterns and options Architecture Codecs
Understand PatternGraph types Architecture Types

Reading Order

Overview

  1. ARCHITECTURE.md -- Architecture diagram from source annotations
  2. PRODUCT-AREAS.md -- Product area overviews with live statistics and diagrams
  3. TAXONOMY.md -- Tag taxonomy configuration and format types

Deep Dive

  1. DECISIONS.md -- Architecture Decision Records extracted from specs
  2. BUSINESS-RULES.md -- Domain constraints and invariants from feature files
  3. VALIDATION-RULES.md -- Process Guard validation rules and FSM reference

Reference Guides

  1. Annotation Reference -- Annotation mechanics and tag reference
  2. Session Workflow Guide -- Planning, Design, Implementation workflows
  3. CLI Reference -- Pattern Graph CLI command reference with flags and examples
  4. Process Guard Reference -- Pre-commit hooks, error codes, programmatic API

Document Roles

Document Audience Focus
ARCHITECTURE.md Developers Architecture diagram from source annotations
PRODUCT-AREAS.md Everyone Product area overviews with live statistics
DECISIONS.md Developers Architecture Decision Records
BUSINESS-RULES.md Developers Domain constraints and invariants
TAXONOMY.md Reference Tag taxonomy structure and format types
VALIDATION-RULES.md CI/CD Process Guard validation rules and FSM reference
CHANGELOG-GENERATED.md Everyone Project changelog from release specs
Annotation Reference Developers Annotation mechanics, shape extraction
Session Workflow Guide AI/Devs Session decision trees and workflow checklists
CLI Reference AI/Devs CLI command reference with flags and examples
CLI Recipes AI/Devs CLI workflow recipes and session guides
Process Guard Reference Team Leads Pre-commit hooks, error codes, programmatic API
Architecture Codecs Developers All codecs with factory patterns and options
Architecture Types Developers PatternGraph interface and type shapes

Key Concepts

Delivery Process -- A code-first documentation and workflow toolkit. Extracts patterns from annotated TypeScript and Gherkin sources, generates markdown documentation, and validates delivery workflow via pre-commit hooks.

Pattern -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the PatternGraph.

PatternGraph -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset.

Codec -- A Zod-based transformer that decodes PatternGraph into a RenderableDocument. Each codec produces a specific document type. Codecs are pure functions with no I/O.

Dual-Source Architecture -- Feature files own planning metadata (status, phase, dependencies). TypeScript files own implementation metadata (uses, used-by, category). This split prevents ownership conflicts.

Delivery Workflow FSM -- A finite state machine enforcing pattern lifecycle: roadmap -> active -> completed. Transitions are validated by Process Guard at commit time.

Document Inventory

Overview

Document Description Audience
Architecture Architecture diagram from source annotations Developers
Product Areas Product area overviews with live statistics and diagrams Everyone
Taxonomy Tag taxonomy configuration and format types Reference
Changelog Project changelog from release specs Everyone

Governance

Document Description Audience
Decisions Architecture Decision Records extracted from specs Developers
Business Rules Domain constraints and invariants from feature files Developers
Validation Rules Process Guard validation rules and FSM reference CI/CD

Reference Guides

Document Description Audience
Annotation Reference Annotation mechanics, shape extraction, tag reference Developers
Session Workflow Guide Planning, Design, Implementation session workflows AI/Devs
CLI Reference Pattern Graph CLI command reference with flags and examples AI/Devs
CLI Recipes Pattern Graph CLI workflow recipes and session guides AI/Devs
Process Guard Reference Pre-commit hooks, error codes, programmatic API Team Leads
Architecture Codecs All codecs with factory patterns and options Developers
Architecture Types PatternGraph interface and type shapes Developers
Configuration Guide Presets, config files, sources, output, and monorepo setup Users
Validation Tools Guide lint-patterns, lint-steps, lint-process, validate-patterns reference CI/CD
Gherkin Authoring Guide Roadmap specs, Rule blocks, DataTables, tag conventions Developers

Product Area Details

Document Description Audience
Annotation Annotation product area patterns and statistics Developers
Configuration Configuration product area patterns and statistics Users
Core Types Core types product area patterns and statistics Developers
Data API Data API product area patterns and statistics AI/Devs
Generation Generation product area patterns and statistics Developers
Process Process product area patterns and statistics Team Leads
Validation Validation product area patterns and statistics CI/CD

Product Area Statistics

Area Patterns Completed Active Planned Progress
Annotation 27 23 3 1 [███████░] 23/27 85%
Configuration 11 8 0 3 [██████░░] 8/11 73%
CoreTypes 11 7 4 0 [█████░░░] 7/11 64%
DataAPI 40 23 15 2 [█████░░░] 23/40 57%
Generation 96 82 6 8 [███████░] 82/96 85%
Process 11 4 0 7 [███░░░░░] 4/11 36%
Validation 25 16 3 6 [█████░░░] 16/25 64%
Total 221 163 31 27 [██████░░] 163/221 74%

Phase Progress

401 patterns total: 266 completed (66%), 83 active, 52 planned. [█████████████░░░░░░░] 266/401

Status Count Percentage
Completed 266 66%
Active 83 21%
Planned 52 13%

By Phase

Phase Patterns Completed Progress
Phase 18 1 0 0%
Phase 23 2 2 100%
Phase 24 2 2 100%
Phase 25 10 8 80%
Phase 26 2 2 100%
Phase 27 3 3 100%
Phase 28 2 2 100%
Phase 30 1 1 100%
Phase 31 1 1 100%
Phase 32 1 1 100%
Phase 35 5 5 100%
Phase 36 1 1 100%
Phase 37 1 1 100%
Phase 38 1 1 100%
Phase 39 1 1 100%
Phase 40 1 1 100%
Phase 41 1 1 100%
Phase 42 1 1 100%
Phase 43 1 1 100%
Phase 44 2 2 100%
Phase 45 1 0 0%
Phase 46 2 0 0%
Phase 50 1 1 100%
Phase 51 1 1 100%
Phase 99 9 5 56%
Phase 100 16 4 25%
Phase 101 2 1 50%
Phase 102 1 0 0%
Phase 103 1 0 0%
Phase 104 1 0 0%

Regeneration

Regenerate all documentation from annotated sources:

pnpm docs:all          # Regenerate all generated docs
pnpm docs:all-preview  # Also generate ephemeral workflow docs

Individual generators:

pnpm docs:product-areas         # Product area docs
pnpm docs:decisions             # Architecture decisions
pnpm docs:reference             # Reference documents
pnpm docs:business-rules        # Business rules
pnpm docs:taxonomy              # Taxonomy reference
pnpm docs:validation            # Validation rules
pnpm docs:claude-modules        # Claude context modules
pnpm docs:cli-reference         # Pattern Graph CLI reference
pnpm docs:cli-recipe            # CLI recipes & workflow guide