siriusscan--sirius/scripts/agent-identities

Agent Identity Generation System

A TypeScript-based system for generating comprehensive agent identity files from documentation and code.

Overview

This system combines manual templates (role summaries, best practices) with auto-generated sections (file structure, ports, dependencies, configs) to create comprehensive agent identities (~1200-1500 lines).

Quick Start

# Install dependencies
npm install

# Generate all agent identities
npm run generate -- --all

# Generate specific agent
npm run generate -- --product=agent-engineer

# Validate agent identities
npm run validate

# Check for stale identities
npm run check-sync

Commands

Generation

# Generate all agent identities
npm run generate -- --all

# Generate specific product
npm run generate -- --product=<product-name>

# Example
npm run generate -- --product=agent-engineer

Validation

# Full validation (YAML, content, sync, file paths)
npm run validate

# Check if identities need regeneration
npm run check-sync

Via Makefile

cd testing/container-testing

# Generation
make regenerate-agents                    # All
make regenerate-agent PRODUCT=agent-engineer  # Specific

# Validation
make lint-agents                          # Full
make check-agent-sync                     # Sync check

Project Structure

scripts/agent-identities/
├── package.json              # Project config
├── tsconfig.json             # TypeScript config
├── src/
│   ├── generators/           # Data extractors
│   │   ├── index.ts         # Main orchestrator
│   │   ├── file-structure.ts
│   │   ├── ports.ts
│   │   ├── dependencies.ts
│   │   ├── config-examples.ts
│   │   ├── documentation.ts
│   │   └── merge.ts
│   ├── validators/           # Validation modules
│   │   ├── yaml-validator.ts
│   │   ├── content-validator.ts
│   │   ├── sync-validator.ts
│   │   └── file-path-validator.ts
│   ├── types/                # Type definitions
│   └── utils/                # Utilities
├── lint-agents.ts            # Validation CLI
├── generate-agents.ts        # Generation CLI
└── check-sync.ts             # Sync check CLI

Creating a New Agent Identity

1. Create Template

Create .cursor/agents/templates/<name>.template.md:

---
# YAML front matter (manually maintained)
name: "My Agent"
title: "My Agent (product/Tech)"
# ... metadata
---

# My Agent

<!-- MANUAL SECTION -->
Manual narrative content
<!-- END MANUAL SECTION -->

## Key Documentation

<!-- AUTO-GENERATED: documentation-links -->
<!-- END AUTO-GENERATED -->

## Project Location

<!-- AUTO-GENERATED: file-structure -->
<!-- END AUTO-GENERATED -->

## Technology Stack

<!-- AUTO-GENERATED: dependencies -->
<!-- END AUTO-GENERATED -->

2. Create Config

Create .cursor/agents/config/<name>.config.yaml:

product: my-product
product_path: /path/to/product
docker_service_name: my-service

metadata:
  name: "My Agent"
  title: "My Agent (product/Tech)"
  description: "Brief description"
  role_type: engineering
  version: "1.0.0"
  last_updated: "2025-10-25"
  author: "Sirius Team"
  specialization: ["skill1", "skill2"]
  technology_stack: ["Tech1", "Tech2"]
  system_integration_level: high
  categories: ["category"]
  tags: ["tag1", "tag2"]
  related_docs: ["doc1.md", "doc2.md"]
  dependencies: ["path/"]
  llm_context: high
  context_window_target: 1400

generation:
  include_file_structure: true
  file_structure_depth: 3
  file_structure_ignore: [node_modules, dist, bin]
  
  include_ports: true
  ports_config:
    "8080": "HTTP server"
  
  include_dependencies: true
  dependencies_source: go.mod  # or package.json
  dependencies_grouping:
    "Category":
      - "package-name"
  
  include_config_examples: true
  config_files:
    - path: config/server.yaml
      title: "Server Configuration"
  
  extract_code_patterns_from_docs:
    - documentation/dev/file.md

template_path: .cursor/agents/templates/<name>.template.md
output_path: .cursor/agents/<name>.agent.md

3. Generate

npm run generate -- --product=<name>

4. Validate

npm run validate

Template Markers

AUTO-GENERATED Sections

Sections between these markers are auto-generated:

<!-- AUTO-GENERATED: section-name -->
Content is replaced on each generation
<!-- END AUTO-GENERATED -->

MANUAL Sections

Sections between these markers are preserved:

<!-- MANUAL SECTION -->
Content is preserved across generations
<!-- END MANUAL SECTION -->

Available Generators

file-structure

Extracts directory tree from product path with max depth and ignore patterns.

ports

Extracts port mappings from docker-compose.yaml for specified service.

dependencies

Extracts and groups dependencies from go.mod or package.json.

config-examples

Extracts and formats configuration file contents.

documentation-links

Generates documentation links from related_docs list.

code-patterns

Extracts code patterns, best practices, and common tasks from documentation.

Validation

YAML Front Matter

• Required fields present
• Enum values valid (role_type, llm_context, etc.)
• Version format (semver: 1.0.0)
• Date format (YYYY-MM-DD)

Content

• Line count in range (150-2000)
• Warning if outside target (800-1500)
• Required sections present

Sync Status

• Compares source file modification times
• Detects when regeneration needed
• Tracks source files via metadata

File Paths

• Extracts file references from content
• Verifies files exist
• Reports missing files

Generation Metadata

Generated files include metadata:

---
# ... standard metadata ...
_generated_at: "2025-10-25T10:30:00.000Z"
_source_files:
  - "/path/to/source1"
  - "/path/to/source2"
---

This enables:

• Staleness detection
• Source tracking
• Regeneration decisions

Development

Run Tests

npm test  # (when tests are added)

Build

npm run build

Type Check

npx tsc --noEmit

Troubleshooting

"Cannot find module"

Ensure dependencies are installed:

npm install

"Config file not found"

Check config path in command:

npm run generate -- --product=<exact-name>

Config must exist at .cursor/agents/config/<exact-name>.config.yaml

"Template not found"

Check template_path in config file points to valid template.

Generation Fails

Check:

1. Product path exists and is accessible
2. Source files (go.mod, docker-compose.yaml) exist
3. Config YAML is valid
4. Template has proper markers

Validation Fails

Check:

1. YAML front matter has all required fields
2. Field values match enum options
3. Version and date formats correct
4. File is within line count limits

Integration with Workflow

Pre-Commit Hook

Agent identities are validated on commit when source files change.

CI/CD

Use in CI/CD pipelines:

cd scripts/agent-identities
npm run validate || exit 1

Makefile

Integrated with project Makefile:

make regenerate-agents        # Generate all
make regenerate-agent PRODUCT=name  # Generate specific
make check-agent-sync         # Check staleness
make lint-agents              # Validate all

Best Practices

1. Manual Sections: Use for narrative, philosophy, best practices
2. Auto-Generated Sections: Use for structural info (files, ports, deps)
3. Regular Regeneration: Regenerate after major changes
4. Validate Before Commit: Run validation before committing
5. Keep Templates Clean: Don't add manual content in auto-generated sections

Resources

• Plan: /agent-identity-system.plan.md
• Implementation Summary: /AGENT-IDENTITY-GENERATION-IMPLEMENTED.md
• Templates: .cursor/agents/templates/
• Configs: .cursor/agents/config/
• Generated Identities: .cursor/agents/*.agent.md

---

Version: 1.0.0
Last Updated: 2025-10-25