@kolaystack/agent

A lightweight project-side agent that generates machine-readable project memory for KolayStack to consume.

Why It Exists

KolayStack Agent scans a project locally, detects its architecture and readiness, and writes standardized memory/status files into a .kolaystack/ folder. KolayStack central will later read these files instead of deeply parsing every repo on every request.

Installation

# Using npx (recommended for quick usage)
npx @kolaystack/agent init

# Or install globally
npm install -g @kolaystack/agent

# Or add to your project
npm install --save-dev @kolaystack/agent

Quick Start

# Initialize KolayStack in your project
npx kolaystack-agent init

# Scan the project and see what it detects
npx kolaystack-agent scan

# Export results to .kolaystack/ folder
npx kolaystack-agent export

# Check project status
npx kolaystack-agent status

# Validate setup
npx kolaystack-agent doctor

Commands

init

Creates the .kolaystack/ directory with:

• config.json - Project configuration and metadata
• README.md - Documentation

npx kolaystack-agent init

scan

Scans the local repository and prints a summary to the terminal:

• Detected framework (Next.js, React, Express, etc.)
• Detected backend (Express, FastAPI, NestJS)
• Database (Supabase, PostgreSQL, etc.)
• Auth solution
• AI providers
• Integrations
• Implementation scores

npx kolaystack-agent scan

export

Writes structured JSON files into .kolaystack/:

• project.json - Project info
• status.json - Current status
• implementation.json - Implementation scores
• interconnectivity.json - Related apps
• audit.json - Audit findings
• gtm.json - Go-to-market recommendations
• evidence.json - All evidence used for scoring

npx kolaystack-agent export

status

Prints a compact human-readable summary of the project based on .kolaystack/*.json files.

npx kolaystack-agent status

doctor

Validates whether required data files exist, checks for stale exports, and warns about missing evidence.

npx kolaystack-agent doctor

Output Files

.kolaystack/config.json

Project metadata (should be committed to git):

{
  "project_name": "my-app",
  "preferred_company": "KolayStack",
  "preferred_customer": "Enterprise",
  "preferred_project_manager": "Technical",
  "tags": ["saas", "b2b"],
  "category": "webapp",
  "importance": "high",
  "output_mode": "full"
}

.kolaystack/project.json

Detected project information:

{
  "project_name": "my-app",
  "repo_name": "my-app",
  "detected_framework": "Next.js",
  "detected_language": "TypeScript",
  "app_type": "web",
  "description": "My SaaS application",
  "primary_branch": "main",
  "package_manager": "npm",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-15T00:00:00.000Z"
}

.kolaystack/implementation.json

Implementation and readiness scores:

{
  "frontend_status": { "score": 75, "stage": "progressing", "evidence": [...] },
  "backend_status": { "score": 60, "stage": "progressing", "evidence": [...] },
  "database_status": { "score": 80, "stage": "mature", "evidence": [...] },
  "auth_status": { "score": 90, "stage": "mature", "evidence": [...] },
  "testing_status": { "score": 40, "stage": "early", "evidence": [...] },
  "ci_cd_status": { "score": 70, "stage": "progressing", "evidence": [...] },
  "observability_status": { "score": 50, "stage": "early", "evidence": [...] },
  "implementation_percent": 66,
  "readiness_score": 65,
  "stage": "progressing",
  "generated_at": "2024-01-15T00:00:00.000Z"
}

.kolaystack/evidence.json

All evidence used for scoring (critical for debugging):

{
  "found_files": ["package.json", "tsconfig.json", ...],
  "detected_routes": ["/api/users", "/api/posts"],
  "detected_pages": ["/app/page.tsx", "/app/about/page.tsx"],
  "migrations_count": 5,
  "tests_count": 12,
  "docker_present": true,
  "ci_present": true,
  "auth_files": ["src/auth.ts"],
  "ai_provider_files": [],
  "env_keys_present": ["DATABASE_URL", "OPENAI_API_KEY"],
  "integration_markers": {},
  "generated_at": "2024-01-15T00:00:00.000Z"
}

Supported Technologies

Frameworks

• Next.js
• React
• Vue
• Svelte
• Deno
• Express
• FastAPI
• NestJS
• Fastify

Databases

• Supabase
• PostgreSQL
• MySQL
• MongoDB
• Prisma
• Drizzle

Infrastructure

• Docker
• Vercel
• Railway
• Netlify
• GitHub Actions
• GitLab CI

AI

• OpenAI
• Anthropic
• Gemini
• LangChain
• LlamaIndex

Auth

• NextAuth.js
• Clerk
• Supabase Auth
• Firebase Auth
• Auth0

Integrations

• Stripe
• Resend
• SendGrid
• Twilio
• PostHog
• Sentry

Security

• Never sends data to remote servers by default
• No telemetry
• No secret values written to output files
• Only writes presence/absence of env keys (e.g., "OPENAI_API_KEY": true, never the actual value)
• All scanning is local-only

Architecture

src/
  cli.ts              # CLI entry point
  index.ts            # Package exports
  commands/
    init.ts           # Initialize .kolaystack/
    scan.ts           # Scan and detect technologies
    export.ts         # Write JSON files
    status.ts         # Print project status
    doctor.ts         # Validate setup
  core/
    buildReport.ts    # Orchestrate detection + scoring
    detectors/
      framework.ts    # Detect frameworks
      backend.ts      # Detect backends
      database.ts     # Detect databases
      infra.ts        # Detect infra (Docker, CI, etc.)
      ai.ts           # Detect AI providers
      auth.ts         # Detect auth solutions
      integrations.ts # Detect integrations
    scanners/
      fileScanner.ts  # Scan filesystem
      packageScanner.ts # Scan package.json
      envScanner.ts   # Scan env files
      codeScanner.ts  # Scan code patterns
    scoring/
      index.ts        # Calculate scores
    writers/
      index.ts        # Write JSON files
  types/
    index.ts          # TypeScript interfaces
  utils/
    fileSystem.ts     # File operations
    logger.ts         # Console output
    safeJson.ts       # Safe JSON handling
    config.ts         # Config loading

How KolayStack Consumes This

KolayStack central reads the .kolaystack/ folder:

1. config.json - Project metadata (company, customer, tags)
2. project.json - Framework, language, app type
3. implementation.json - Scores and readiness
4. evidence.json - All raw evidence for verification

This allows KolayStack to:

• Skip deep repo parsing on every request
• Get standardized project metadata
• Verify implementation claims against evidence
• Make informed recommendations

Roadmap

• [ ] Add more framework detections (Laravel, Django, Ruby on Rails)
• [ ] Add Python/PHP/Go scanner support
• [ ] Add custom marker support for project-specific detection
• [ ] Add diff detection for incremental updates
• [ ] Add optional remote sync (disabled by default)

License

MIT