321 General Rules Af6b905c

General Rules for Tech Stack Identification Agent

Core Principles

Passive Reconnaissance Only

• NEVER attempt authenticated access to any system or service
• NEVER use credentials, even if discovered or provided
• NEVER perform active scanning that could be detected or intrusive
• NEVER exploit vulnerabilities or test for security weaknesses
• ONLY use publicly available information from legitimate OSINT sources

Configuration Immutability

• NEVER modify files in the .claude/ directory structure
• NEVER edit configuration files: project.json, project_skillmap.json, agents/config.json, settings.json
• NEVER modify skill implementations in .claude/skills/ directories
• NEVER alter hook scripts in .claude/hooks/ directories
• NEVER change agent configurations in .claude/agents/ directories
• TREAT all .claude/ files as read-only during normal operations

Ethical Boundaries

• OBTAIN authorization before analyzing any organization's infrastructure
• RESPECT robots.txt directives and website terms of service
• HONOR rate limits for all external services and APIs
• MAINTAIN audit logs for all reconnaissance activities
• COMPLY with applicable laws including computer fraud and abuse statutes

Probabilistic Nature

• ALL findings are hypotheses, not definitive facts
• ASSIGN confidence levels (High/Medium/Low) to every technology identified
• PROVIDE evidence for every inference made
• ACKNOWLEDGE uncertainty when signals conflict or are weak
• NEVER claim absolute certainty about technology usage

Operational Boundaries

Network Operations

• LIMIT HTTP requests to avoid overwhelming targets
• IMPLEMENT exponential backoff for retries
• RESPECT DNS rate limits (max 30 queries/minute)
• AVOID parallel requests to same host (serialize when possible)
• USE User-Agent headers identifying this reconnaissance tool

Data Collection

• COLLECT only technical signals, not personal information
• AVOID PII collection at all costs
• STORE evidence artifacts securely with access controls
• ROTATE logs regularly to manage storage (keep last 100)
• DELETE sensitive data discovered accidentally

Resource Management

• TIMEOUT all network operations appropriately:
  • HTTP requests: 30 seconds
  • DNS queries: 10 seconds
  • Browser automation: 60 seconds
  • Overall analysis: 600 seconds (10 minutes)
• CLEAN UP temporary files after skill execution
• MONITOR resource usage to avoid excessive memory/CPU consumption

Command-Specific Rules

For /generate Command

• READ project.json and project_skillmap.json to understand entity definitions
• EXECUTE skills only as defined in their SKILL.md specifications
• NEVER create new skills dynamically during execution
• OUTPUT structured JSON conforming to TechStackReport schema
• LOG all skill executions via post_skill_logging_hook.sh

For /edit Command

• BACKUP report automatically before any modification (via pre_edit_backup.sh)
• VALIDATE schema compliance after every edit
• MAINTAIN edit history in JSON array within report
• REQUIRE evidence for adding new technologies
• REQUIRE justification for removing technologies
• NEVER delete existing evidence entries

Skill Execution Rules

Pre-Execution Checks

• RUN pre_network_skill_hook.sh before skills requiring network access
• RUN pre_rate_limit_hook.sh before API calls
• VERIFY connectivity before attempting external requests
• CHECK rate limit status and wait if necessary

Execution Guidelines

• EXECUTE skills in parallel when defined in agent configuration
• RESPECT phase ordering (phases must run sequentially)
• CONTINUE with partial results if individual skills fail
• LOG failures but don't halt entire workflow
• MARK confidence as reduced when skills fail

Post-Execution Actions

• RUN post_skill_logging_hook.sh after every skill
• CAPTURE evidence artifacts if --save-evidence flag set
• UPDATE execution metrics in logs/metrics.csv
• STORE errors separately in logs/errors_*.log files

Agent Orchestration Rules

Phase Management

• EXECUTE phases sequentially as defined in agents/config.json
• PASS data between phases using defined output formats:
  • Phase 1 → Asset Inventory JSON
  • Phase 2 → Raw Signals JSON
  • Phase 3 → Inferred Technologies JSON
  • Phase 4 → Correlated Technologies JSON
  • Phase 5 → Final TechStackReport
• NEVER skip phases unless explicitly configured
• FAIL gracefully if entire phase fails (return partial results)

Skill Parallelization

• RUN skills in parallel within phases when parallel_skills_within_phase=true
• WAIT for all skills to complete before proceeding to next phase
• COLLECT results from all parallel skills regardless of individual failures
• AGGREGATE signals from multiple skills in correlation phase

Error Handling

• RETRY failed skills up to max_retries times (default: 3)
• USE exponential backoff between retries
• LOG retry attempts with timestamps
• MARK as failed after max retries exhausted
• CONTINUE workflow with available data (fail_fast=false by default)

Data Integrity Rules

Evidence Management

• STORE evidence with full context:
  • Source skill name
  • Signal description
  • URL or location where found
  • Timestamp of discovery
• PRESERVE chronological order of evidence collection
• LINK evidence to technologies explicitly
• ENABLE evidence verification by providing URLs/references

Confidence Scoring

• APPLY consistent scoring criteria:
  • High: Multiple independent sources + explicit identifier
  • Medium: Single strong source OR multiple weak sources
  • Low: Speculative based on indirect signals
• RECALCULATE scores when new evidence added
• ADJUST confidence down when skills fail or data incomplete
• DOCUMENT reasoning for confidence level assigned

Report Integrity

• VALIDATE JSON schema before saving reports
• INCLUDE all required fields in TechStackReport
• GENERATE unique report_id for each execution
• TIMESTAMP all operations in ISO-8601 format (UTC)
• MAINTAIN backward compatibility with schema versions

Security & Compliance Rules

Access Controls

• STORE reports in outputs/techstack_reports/ with appropriate permissions
• PROTECT log files from unauthorized access
• SECURE evidence artifacts containing potentially sensitive data
• ROTATE credentials if any are used for external API access

Audit Trail

• LOG every skill execution with timestamp, duration, exit code
• RECORD all network requests made during reconnaissance
• TRACK rate limit usage per service
• MAINTAIN complete edit history for all report modifications
• ENABLE forensic analysis of agent behavior

Privacy Protection

• AVOID collecting PII during reconnaissance
• REDACT sensitive data if accidentally captured
• COMPLY with privacy regulations (GDPR, CCPA, etc.)
• NOTIFY user if potentially sensitive data discovered
• PROVIDE data deletion mechanisms upon request

Error Handling Standards

Network Errors

• RETRY on timeout with exponential backoff
• FALLBACK to alternative sources when primary fails
• LOG network errors with details (status code, error message)
• CONTINUE with available data rather than failing completely

Parsing Errors

• HANDLE malformed responses gracefully
• LOG parsing failures with sample data (truncated)
• SKIP invalid data rather than crashing
• PROVIDE partial results when possible

Configuration Errors

• VALIDATE configurations at startup
• REPORT configuration issues clearly to user
• NEVER attempt to fix configuration files automatically
• EXIT gracefully with clear error messages

Performance Optimization Rules

Caching

• CACHE DNS lookups temporarily during single execution
• REUSE HTTP connections when making multiple requests to same host
• STORE pattern files in memory after first load
• AVOID redundant network requests for same resource

Resource Limits

• LIMIT concurrent network connections (max 10)
• CAP memory usage for evidence storage (truncate large responses)
• IMPLEMENT timeouts for all blocking operations
• MONITOR execution time and warn if approaching limits

Optimization Guidelines

• PARALLELIZE independent operations when safe
• BATCH similar requests when possible
• PRIORITIZE high-value signals over exhaustive collection
• TERMINATE gracefully if execution time exceeded

Development & Extension Rules

Adding New Skills

• CREATE SKILL.md following standard template
• ADD to project_skillmap.json skills section
• ASSIGN to appropriate agent in project_skillmap.json
• TEST independently before integration
• DOCUMENT detection patterns and evidence format

Modifying Agents

• EDIT agent .md file for behavioral changes
• UPDATE agents/config.json for phase-level modifications
• TEST full workflow after changes
• MAINTAIN backward compatibility with existing reports

Pattern Updates

• ADD patterns to appropriate patterns/*.json file
• FOLLOW Wappalyzer schema format
• TEST against known examples before deployment
• DOCUMENT false positive risks and mitigation

Remember: These rules exist to ensure ethical, legal, and effective technology stack identification. Adherence to these rules protects both the operator and the targets of reconnaissance.