@girardelli/architect 1.3.0 → 2.1.0

package/README.md

@@ -1,32 +1,21 @@
 # Architect
 
-**AI-powered architecture analysis tool**
+**AI-powered architecture analysis, refactoring, and agent system generator**
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-339933.svg)](https://nodejs.org/)
+[![npm](https://img.shields.io/npm/v/@girardelli/architect)](https://www.npmjs.com/package/@girardelli/architect)
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-Understand your codebase architecture in seconds. Detect anti-patterns, visualize dependencies, and get actionable refactoring suggestions — all from a single command.
+Understand your codebase architecture in seconds. Detect anti-patterns, get refactoring plans, and generate AI agent configurations — all from a single command.
 
-## Overview
+## What's New in v2.1
 
-Architect performs deep structural analysis of software projects. It generates visual architecture diagrams, calculates quality metrics, and identifies architectural anti-patterns that could indicate technical debt or design problems.
-
-## Features
-
-- **Architecture Quality Score** — 0-100 score with weighted component breakdown (Modularity, Coupling, Cohesion, Layering)
-- **Premium HTML Reports** — Dark-themed visual reports with interactive Mermaid diagrams, score gauges, and responsive layout
-- **Anti-Pattern Detection**
-  - God Class (excessive responsibilities and methods)
-  - Circular Dependencies (mutual dependencies creating tight coupling)
-  - Leaky Abstractions (internal implementation details exposed publicly)
-  - Feature Envy (classes excessively using other class methods)
-  - Shotgun Surgery (changes requiring scattered modifications)
-- **Layer Detection** — Automatically identifies architectural layers (API, Service, Data, UI, Infrastructure)
-- **Framework Detection** — Auto-detects NestJS, React, Angular, Vue.js, Express, Next.js, TypeORM, Prisma, Spring Boot, Django, and more
-- **Multi-Language Support** — TypeScript, JavaScript, Python, Java, Go, Ruby, PHP, Rust, SQL, and more
-- **Multiple Output Formats** — HTML, JSON, and Markdown
-- **NestJS-Aware** — Calibrated thresholds for NestJS module architecture (entities, DTOs, guards, pipes, interceptors)
+- 🔧 **Unified `analyze` command** — Architecture analysis + refactoring plan + agent system suggestions in one report
+- 🤖 **AI Agent System Generator** — Suggests agents, rules, guards, workflows, and skills based on detected stack
+- 🧠 **Skills from [skills.sh](https://skills.sh)** — Stack-specific skill recommendations with install commands
+- 🎯 **Interactive UI** — Toggle cards with Select All/None, dynamic command builder, and copy-to-clipboard
+- 📊 **Refactoring Plan** — Tier-based refactoring steps with score impact predictions
 
 ## Quick Start
 
@@ -39,90 +28,126 @@ npm install -g @girardelli/architect
 architect analyze ./src
 ```
 
+## Features
+
+### 📊 Architecture Analysis
+- **Quality Score** — 0-100 score with weighted breakdown (Modularity, Coupling, Cohesion, Layering)
+- **Anti-Pattern Detection** — God Class, Circular Dependencies, Leaky Abstractions, Feature Envy, Shotgun Surgery
+- **Layer Detection** — Automatically identifies API, Service, Data, UI, and Infrastructure layers
+- **Dependency Graph** — Interactive D3.js force-directed graph visualization
+- **Framework Detection** — NestJS, React, Angular, Vue, Next.js, Express, Django, Flask, Spring Boot, and more
+- **Multi-Language** — TypeScript, JavaScript, Python, Java, Go, Ruby, PHP, Rust, SQL
+
+### 🔧 Refactoring Plan
+- **Tier 1 (Quick Wins)** — Low-risk improvements for immediate impact
+- **Tier 2 (Strategic)** — Larger refactoring with architecture-level benefits
+- **Score Impact** — Before/after predictions for each refactoring step
+- **File Operations** — CREATE, MOVE, MODIFY, DELETE with detailed descriptions
+
+### 🤖 AI Agent System
+- **Stack Detection** — Identifies languages, frameworks, backend/frontend/mobile/database
+- **Agent Suggestions** — Orchestrator, Backend Developer, Frontend Developer, Database Engineer, Security Auditor, QA, Tech Debt Controller
+- **Rules & Guards** — Architecture rules, security rules, preflight checks, quality gates
+- **Workflows** — Development, bug-fix, code review workflows
+- **Skills** — [skills.sh](https://skills.sh) recommendations mapped to your stack (TDD, debugging, security, performance, etc.)
+- **Audit Mode** — If `.agent/` exists, audits and suggests improvements
+- **Interactive UI** — Toggle cards for selecting which items to generate
+- **Command Builder** — Dynamic CLI command updates based on selection
+
+### 📄 Premium HTML Report
+- Dark-themed responsive design with Inter font
+- Animated score gauge with gradient
+- Interactive D3.js dependency graph
+- Bubble chart for anti-pattern severity
+- Collapsible refactoring steps with code previews
+- Toggle cards for agent system selection
+- Single self-contained HTML file (no external dependencies)
+
 ## CLI Commands
 
 ### `architect analyze [path]`
-Full architecture analysis with diagram generation, quality scoring, and anti-pattern detection.
+**The unified command** — runs architecture analysis, refactoring plan, and agent suggestions.
 
 ```bash
-# Generate HTML report (default)
+# Full analysis with HTML report (default)
 architect analyze ./src
 
-# Generate specific format
-architect analyze ./src --format html --output report.html
+# Custom output path
+architect analyze ./src --output docs/report.html
+
+# JSON or Markdown output
 architect analyze ./src --format json --output report.json
 architect analyze ./src --format markdown --output report.md
 ```
 
-### `architect diagram [path]`
-Generate architecture diagram in Mermaid format.
+### `architect refactor [path]`
+Generate a standalone refactoring plan.
 
 ```bash
-architect diagram ./src
+architect refactor ./src --output refactor-plan.html
 ```
 
-### `architect score [path]`
-Calculate architecture quality score with component breakdowns.
+### `architect agents [path]`
+Generate or audit the `.agent/` directory for AI coding assistants.
 
 ```bash
-architect score ./src
-```
+# Generate agent configuration files
+architect agents ./
 
-### `architect anti-patterns [path]`
-Detect and report anti-patterns with severity levels and remediation suggestions.
-
-```bash
-architect anti-patterns ./src
+# With specific selections
+architect agents ./ --agents ORCHESTRATOR,QA-TEST-ENGINEER --rules 00-general,01-architecture
 ```
 
-### `architect layers [path]`
-Analyze layer structure and code distribution across architectural layers.
-
-```bash
-architect layers ./src
-```
+### `architect diagram [path]`
+Generate architecture diagram in Mermaid format.
 
-## How It Works
+### `architect score [path]`
+Calculate architecture quality score.
 
-Architect uses a multi-agent pipeline to analyze your codebase:
+### `architect anti-patterns [path]`
+Detect anti-patterns with severity levels.
 
-1. **Scanner** — Traverses project directory, identifies file types, counts lines of code, detects frameworks (including parent `package.json` files), and builds a file tree structure.
+### `architect layers [path]`
+Analyze layer structure and distribution.
 
-2. **Analyzer** — Parses import statements across JavaScript, TypeScript, Python, and Java. Builds a dependency graph and identifies architectural layers (API, Service, Data, UI, Infrastructure) with NestJS-aware heuristics.
+## Output Example
 
-3. **Anti-Pattern Detector** — Scans for God Classes, Circular Dependencies, Leaky Abstractions, Feature Envy, and Shotgun Surgery with configurable thresholds calibrated for modern frameworks.
+```
+🏗️  Architect — Architecture Analysis
+📂 Path: /path/to/project/src
+📋 Command: analyze
+📄 Format: html
 
-4. **Scorer** — Evaluates architecture quality across four dimensions:
-   - **Modularity (40%)** — Appropriate module boundaries and cohesion
-   - **Coupling (25%)** — Dependencies between modules minimized
-   - **Cohesion (20%)** — Related functionality grouped together
-   - **Layering Compliance (15%)** — Proper separation of concerns
+✅ HTML report saved to: architect-report.html
+📊 Score: 82/100
+⚠️  Anti-patterns: 1
+🔧 Refactoring steps: 2
+🤖 Suggested agents: 6
 
-5. **Reporter** — Generates comprehensive reports in HTML, Markdown, or JSON with diagrams, scores, findings, and suggestions.
+═══════════════════════════════════════
+  SCORE: 82/100
+═══════════════════════════════════════
+├─ Modularity: 95
+├─ Coupling:   50
+├─ Cohesion:   95
+└─ Layering:   85
+
+📁 Files: 12 | 📝 Lines: 1,521
+⚠️  Anti-patterns: 1
+🤖 Agents: 6 suggested | No .agent/ found
+```
 
 ## Configuration
 
-Create a `.architect.json` file in your project root to customize analysis:
+Create `.architect.json` in your project root:
 
 ```json
 {
-  "ignore": [
-    "node_modules",
-    "dist",
-    ".git",
-    "coverage"
-  ],
-  "frameworks": {
-    "detect": true
-  },
+  "ignore": ["node_modules", "dist", ".git", "coverage"],
+  "frameworks": { "detect": true },
   "antiPatterns": {
-    "godClass": {
-      "linesThreshold": 500,
-      "methodsThreshold": 10
-    },
-    "shotgunSurgery": {
-      "changePropagationThreshold": 8
-    }
+    "godClass": { "linesThreshold": 500, "methodsThreshold": 10 },
+    "shotgunSurgery": { "changePropagationThreshold": 8 }
   },
   "score": {
     "modularity": 0.40,
@@ -162,13 +187,11 @@ jobs:
 npm install -D @girardelli/architect
 ```
 
-Add to your `package.json` scripts:
-
 ```json
 {
   "scripts": {
-    "architect": "architect analyze ./src --format html --output docs/architect-report.html",
-    "architect:json": "architect analyze ./src --format json --output docs/architect-report.json"
+    "architect": "architect analyze ./src --output docs/architect-report.html",
+    "architect:json": "architect analyze ./src --format json --output docs/report.json"
   }
 }
 ```
@@ -176,40 +199,22 @@ Add to your `package.json` scripts:
 ## Programmatic Usage
 
 ```typescript
-import { architect, HtmlReportGenerator } from '@girardelli/architect';
-
-const report = await architect.analyze('./src');
+import { Architect, HtmlReportGenerator } from '@girardelli/architect';
 
-console.log(`Score: ${report.score.overall}/100`);
-console.log(`Anti-patterns: ${report.antiPatterns.length}`);
-console.log(`Frameworks: ${report.projectInfo.frameworks.join(', ')}`);
+const architect = new Architect();
 
-// Generate HTML
-const htmlGenerator = new HtmlReportGenerator();
-const html = htmlGenerator.generateHtml(report);
-```
-
-## Output Example
-
-```
-🏗️  Architect — Architecture Analysis
-📂 Path: /path/to/project/src
-📋 Command: analyze
-📄 Format: html
+// Full analysis
+const report = await architect.analyze('./src');
 
-✅ HTML report saved to: architect-report.html
-📊 Score: 59/100
+// Refactoring plan
+const plan = architect.refactor(report, './src');
 
-═══════════════════════════════════════
-  SCORE: 59/100
-═══════════════════════════════════════
-├─ Modularity: 70
-├─ Coupling:   85
-├─ Cohesion:   30
-└─ Layering:   25
+// Agent suggestions (dry-run, no files created)
+const agents = architect.suggestAgents('./');
 
-📁 Files: 1125 | 📝 Lines: 195,709
-⚠️  Anti-patterns: 463
+// Generate unified HTML report
+const htmlGenerator = new HtmlReportGenerator();
+const html = htmlGenerator.generateHtml(report, plan, agents);
 ```
 
 ## Supported Frameworks
@@ -227,18 +232,12 @@ const html = htmlGenerator.generateHtml(report);
 | Spring Boot | `spring-boot` in pom.xml |
 | Django | `django` in requirements.txt |
 | Flask | `flask` in requirements.txt |
-
-## Installation
-
-```bash
-npm install
-npm run build
-npm test
-```
+| Flutter | `flutter` in pubspec.yaml |
 
 ## Development
 
 ```bash
+npm install
 npm run build    # Compile TypeScript
 npm run dev      # Watch mode
 npm test         # Run tests
@@ -266,4 +265,4 @@ See [LICENSE](LICENSE) for details.
 
 ---
 
-**Architect** — Making software architecture analysis accessible to every developer.
+**Architect** — Architecture analysis, refactoring plans, and AI agent generation for every developer.

package/dist/agent-generator.d.ts

@@ -0,0 +1,95 @@
+import { AnalysisReport, RefactoringPlan } from './types.js';
+/**
+ * Stack detection result from project analysis.
+ */
+export interface StackInfo {
+    primary: string;
+    languages: string[];
+    frameworks: string[];
+    hasBackend: boolean;
+    hasFrontend: boolean;
+    hasMobile: boolean;
+    hasDatabase: boolean;
+    testFramework: string;
+    packageManager: string;
+}
+/**
+ * Audit finding for existing agent directories.
+ */
+export interface AgentAuditFinding {
+    type: 'MISSING' | 'OUTDATED' | 'IMPROVEMENT' | 'OK';
+    category: string;
+    file: string;
+    description: string;
+    suggestion?: string;
+}
+/**
+ * Result from suggest() — no files written, just recommendations.
+ */
+export interface AgentSuggestion {
+    stack: StackInfo;
+    hasExistingAgents: boolean;
+    suggestedAgents: string[];
+    suggestedRules: string[];
+    suggestedGuards: string[];
+    suggestedWorkflows: string[];
+    suggestedSkills: {
+        name: string;
+        source: string;
+        description: string;
+    }[];
+    audit: AgentAuditFinding[];
+    command: string;
+}
+/**
+ * Agent Generator — Creates or audits .agent/ directories
+ * customized to the analyzed project's stack and architecture.
+ */
+export declare class AgentGenerator {
+    private stack;
+    private report;
+    private plan;
+    /**
+     * Suggest agents without writing files — for unified report.
+     */
+    suggest(report: AnalysisReport, plan: RefactoringPlan, projectPath: string): AgentSuggestion;
+    /**
+     * Main entry: generate or audit .agent/ for a project.
+     */
+    generate(report: AnalysisReport, plan: RefactoringPlan, projectPath: string, outputDir?: string): {
+        generated: string[];
+        audit: AgentAuditFinding[];
+    };
+    /**
+     * Detect technology stack from the analysis report.
+     */
+    private detectStack;
+    private auditExisting;
+    private findAgentByRole;
+    private generateMissing;
+    private generateFull;
+    private getTemplateFor;
+    private get projectName();
+    private get stackLabel();
+    private genIndex;
+    private genSchema;
+    private genOrchestrator;
+    private genBackendAgent;
+    private genFrontendAgent;
+    private genMobileAgent;
+    private genDatabaseAgent;
+    private genSecurityAgent;
+    private genQAAgent;
+    private genTechDebtAgent;
+    private genGeneralRules;
+    private genArchitectureRules;
+    private genSecurityRules;
+    private genStackRules;
+    private genPreflight;
+    private genQualityGates;
+    private genCodeReview;
+    private genDevelopWorkflow;
+    private genFixBugWorkflow;
+    private genReviewWorkflow;
+}
+//# sourceMappingURL=agent-generator.d.ts.map

package/dist/agent-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-generator.d.ts","sourceRoot":"","sources":["../src/agent-generator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,aAAa,GAAG,IAAI,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,CAAC;IACjB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,IAAI,CAAmB;IAE/B;;OAEG;IACH,OAAO,CACL,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,GAClB,eAAe;IA2FlB;;OAEG;IACH,QAAQ,CACN,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,iBAAiB,EAAE,CAAA;KAAE;IAkBtD;;OAEG;IACH,OAAO,CAAC,WAAW;IAiEnB,OAAO,CAAC,aAAa;IAgFrB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,YAAY;IAoDpB,OAAO,CAAC,cAAc;IAgBtB,OAAO,KAAK,WAAW,GAEtB;IAED,OAAO,KAAK,UAAU,GAKrB;IAED,OAAO,CAAC,QAAQ;IAkDhB,OAAO,CAAC,SAAS;IAmCjB,OAAO,CAAC,eAAe;IAmHvB,OAAO,CAAC,eAAe;IAiFvB,OAAO,CAAC,gBAAgB;IAiDxB,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,gBAAgB;IAiCxB,OAAO,CAAC,gBAAgB;IAoDxB,OAAO,CAAC,UAAU;IAkElB,OAAO,CAAC,gBAAgB;IAoDxB,OAAO,CAAC,eAAe;IA2EvB,OAAO,CAAC,oBAAoB;IA0C5B,OAAO,CAAC,gBAAgB;IAsCxB,OAAO,CAAC,aAAa;IAuCrB,OAAO,CAAC,YAAY;IA4CpB,OAAO,CAAC,eAAe;IAiCvB,OAAO,CAAC,aAAa;IAsCrB,OAAO,CAAC,kBAAkB;IA0C1B,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,iBAAiB;CAqB1B"}