DsignLk Spec-Driven AI-Native Pipeline NPM Package 🚀

An advanced, production-ready, spec-driven development CLI engine built in accordance with the Newton Russell Software Engineering Framework. This tool automates the entire software development lifecycle (SDLC) from a simple JSON feature specification down to automated code implementation, directory structure pattern recognition, strict type generation, and autonomous test self-correction.

🏗️ System Architecture & Workflow

The pipeline orchestrates 5 distinct agentic layers designed to safely manipulate and maintain target codebases:

[Feature Spec JSON]
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ STEP 1: Spec Intake & Structural Validation            │
└────────────────────────────────────────────────────────┘
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ STEP 2: Architecture Scanning & Planning Layer         │
│         (Scans native project layout via AST/Filesystem)│
└────────────────────────────────────────────────────────┘
        │
        ▼
[🚨 CHECKPOINT: Human-in-the-Loop Approval (Y/N)]
        │
        ▼ (If Approved)
┌────────────────────────────────────────────────────────┐
│ STEP 3: AI-Assisted Source Code Implementation         │
│         (Enforces Strict JSON Schemas & Guardrails)    │
└────────────────────────────────────────────────────────┘
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ STEP 4: Automated QA Test Suite Generation (Jest)      │
└────────────────────────────────────────────────────────┘
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ STEP 5: Test Execution & Autonomous Self-Correction    │
│         (Executes, captures stack traces, auto-heals)  │
└────────────────────────────────────────────────────────┘
        │
        ▼
[✨ Fully Functional, Tested, and Verified Feature Code]

🔥 Architectural Highlights

• Context-Aware Architecture Injection (Zero Structural Breaks): The pipeline programmatically scans the target directory layout before planning. This ensures Gemini strictly adopts the project's native structural design convention (e.g., Layered/Clean Architecture vs Feature-Based modules) without destroying existing code structures.

• Strict Schema Enforcement: Leverages @google/genai Structured Outputs with strong JSON typing, forcing the LLM to output valid code representations instead of prose.

• Autonomous Self-Correction (Auto-Healing Loop): Runs real-time Jest test environments within a child_process runtime. If tests fail, it captures stdout/stderr stack traces, contextually loops back into Gemini, rewrites, and re-verifies the solution autonomously.

• Rigorous Governance Gates: Includes security directory restrictions prohibiting the AI engine from modifying critical codebases outside the explicit scope of the approved context boundaries.

📦 Installation

This CLI tool is available globally as an NPM Package.

npm install -g dsignlk-specforge-ai

Setup Environment Variable

To power the underlying Gemini LLM engine, fetch a free API key from Google AI Studio and configure your local terminal environment:

Windows Command Prompt (CMD):

set GEMINI_API_KEY=AIzaSyYourActualGeminiKeyHere

Windows PowerShell:

$env:GEMINI_API_KEY="AIzaSyYourActualGeminiKeyHere"

Linux / macOS Terminal:

export GEMINI_API_KEY="AIzaSyYourActualGeminiKeyHere"

🚀 Quick Start Guide

1. Prepare a Feature Specification (feature_spec.json)

Create a clean definition of the feature you wish to build inside your target project directory:

{
  "feature_name": "Order Bulk Discount",
  "business_rules": "Apply a 10% discount automatically if the shopping cart total exceeds $100. Restrict this to authenticated customers only.",
  "tech_stack": "Node.js, TypeScript, Jest"
}

2. Trigger the Engine

Navigate to the workspace root folder of your target development project and execute the pipeline:

dsignLk-specforge-ai --spec ./feature_spec.json

3. Interactive Execution Flow

| Step | Description | |------|-------------| | Intake Gate | Validates JSON schemas | | Planner Contextual Scan | Reads directory structures, analyzes architecture patterns, prints changes safely on screen | | Human Intercept Checkpoint | Prompts user interactive confirmation [Y/N] to approve or decline the change | | Executor / Tester Engine | Code gets written safely; tests get composed and evaluated dynamically until full operational pass integrity is achieved |

🛠️ Local Development & Open Source Setup

If you want to pull down the repository locally to modify or contribute to the engine:

Clone the repository:

git clone https://github.com/Dumuthu2000/dsignlk-specforge-ai.git
cd dsignlk-specforge-ai

Install dependencies and transpile TypeScript:

npm install
npm run build

Link globally for local development:

npm link

Any modifications you perform locally in TypeScript will dynamically map across your system globally via the dsignLk-specforge-ai keyword.