# 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 ```bash # 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 ```bash # Generate all agent identities npm run generate -- --all # Generate specific product npm run generate -- --product= # Example npm run generate -- --product=agent-engineer ``` ### Validation ```bash # Full validation (YAML, content, sync, file paths) npm run validate # Check if identities need regeneration npm run check-sync ``` ### Via Makefile ```bash 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/.template.md`: ```markdown --- # YAML front matter (manually maintained) name: "My Agent" title: "My Agent (product/Tech)" # ... metadata --- # My Agent Manual narrative content ## Key Documentation ## Project Location ## Technology Stack ``` ### 2. Create Config Create `.cursor/agents/config/.config.yaml`: ```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/.template.md output_path: .cursor/agents/.agent.md ``` ### 3. Generate ```bash npm run generate -- --product= ``` ### 4. Validate ```bash npm run validate ``` ## Template Markers ### AUTO-GENERATED Sections Sections between these markers are auto-generated: ```markdown Content is replaced on each generation ``` ### MANUAL Sections Sections between these markers are preserved: ```markdown Content is preserved across generations ``` ## 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: ```yaml --- # ... 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 ```bash npm test # (when tests are added) ``` ### Build ```bash npm run build ``` ### Type Check ```bash npx tsc --noEmit ``` ## Troubleshooting ### "Cannot find module" Ensure dependencies are installed: ```bash npm install ``` ### "Config file not found" Check config path in command: ```bash npm run generate -- --product= ``` Config must exist at `.cursor/agents/config/.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: ```bash cd scripts/agent-identities npm run validate || exit 1 ``` ### Makefile Integrated with project Makefile: ```bash 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