Spec-Driven AI-Native Pipeline NPM Package V1 🚀

Built an advanced, production-ready, specification-driven CLI engine that automates end-to-end software development workflows. The platform transforms structured JSON feature specifications into fully implemented code, leveraging intelligent project structure analysis, strict type generation, automated testing, and self-healing validation mechanisms. This approach reduces manual development effort, improves consistency, and enables faster delivery of scalable, maintainable software systems.

🏗️ 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 ai-native-dev-pipeline

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_objective": "Implement an automatic 10% discount for orders exceeding $100 inside the checkout service.",
  "user_story": "As a registered customer, I want to receive a 10% discount automatically when my cart total is over $100, so that I can save money on bulk purchases.",
  "business_rules": [
    "The 10% discount applies only to the subtotal before taxes and shipping fees.",
    "The discount is only applicable if the user is logged in.",
    "Maximum discount allowed per order is $50."
  ],
  "acceptance_criteria": [
    "Verify that a cart total of $150 receives exactly a $15 discount.",
    "Verify that a cart total of $80 receives $0 discount.",
    "Verify that a cart total of $600 receives a maximum of $50 discount instead of $60.",
    "Ensure the final calculated total is always formatted to 2 decimal places."
  ],
  "non_functional_requirements": [
    "The discount calculation should execute in less than 50ms.",
    "The system must handle concurrent validation requests safely."
  ],
  "out_of_scope_items": [
    "Stacking multiple coupon codes on top of this automatic discount.",
    "Applying discounts to guest (unregistered) checkout sessions."
  ]
}

2. Trigger the Engine

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

ai-native-dev-pipeline --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 [email protected]:dumuthujayasinghe/ai-native-pipeline.git
cd ai-native-dev-pipeline

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 ai-native-dev-pipeline keyword.