Add .github/copilot-instructions.md for agent onboarding

[Copilot]

Creates comprehensive onboarding documentation for GitHub Copilot agents to reduce build failures and minimize exploration time. All commands verified from clean checkout.

Repository Context

• Type: Python 3.11+ ML pipeline for CVE analysis (defense-only)
• Stack: NumPy/scikit-learn, Docker, Kubernetes, GitHub Actions
• Architecture: 5 pipeline stages + orchestration tasks (010-090)

Setup & Build Workflows

• Virtual environment creation and dependency installation sequence
• Main entry point: python -m src.main (displays pipeline status)
• Test suite: pytest with markers (integration, heavy, gpu, slow)
• Code quality: black (100 char), flake8, mypy, isort

CI/CD Documentation

• ci.yml: Lint, test, validate (standard runners)
• codeql.yml: Security analysis
• container-scan.yml: Trivy scanning
• notion-sync.yml: Documentation sync (Task 060)
• publish-capsules.yml: Release publishing (Task 070)

Local CI simulation commands provided to mirror GitHub Actions behavior.

Known Issues Documented

• Docker build fails on missing charset-normalizer transitive dependency
• Workaround: Add to requirements.txt or modify Dockerfile --no-deps flag

Project Structure

/src/main.py          # Entry point (scaffolding complete)
/tests/               # 12 structural tests passing
/.copilot/tasks/      # File-anchored task definitions (010-090)
/.github/workflows/   # 5 CI/CD workflows
/prompts/             # System descriptions (LID-LIFT v1.4)
/capsules/            # H-MOC and runbook configs

Agent Guidance

• Task-based workflow: read .copilot/AGENT_GUIDE.md + task definitions before changes
• Sequential execution: 010 → 020 → ... → 090, one PR per task
• Defense-only mission: review SECURITY.md before all changes
• Minimal surgical changes to files specified in task definitions

File includes common issues/solutions, environment variables, quick reference commands, and emphasizes trusting instructions over exploration.

Original prompt

Your task is to “onboard” this repository to the Copilot coding agent by creating a file:
.github/copilot-instructions.md

This file is for a coding agent seeing the repo for the first time. It should explain how to work efficiently in this repo, reduce build/validation failures, and minimize aimless exploration. You will do this once per repository. Take your time, think carefully, and search thoroughly before writing.

- Reduce the chance that an agent’s pull request is rejected due to: - Failing CI builds or validation pipelines. - Misbehavior, incorrect assumptions, or misuse of tools. - Minimize bash command and build failures. - Let the agent complete tasks faster by reducing the need for grep/find/search or trial-and-error command runs. - .github/copilot-instructions.md must be no longer than about 2 pages of text. - Instructions must describe how to work in this repo in general and must NOT be task-specific. In the instructions file, add the following high-level details so the agent can understand the repo without re-discovering them each time:

• A concise summary of what the repository does and its primary domain.
• High-level repository information:
  • Approximate size or complexity (for example: mono-repo vs. small service).
  • Project type(s) (for example: web service, CLI tools, infrastructure-as-code, ML, etc.).
  • Languages, frameworks, and runtimes in use (for example: Python, Node.js, Go, Docker, Terraform, Kubernetes).
  • Any notable external services (for example: cloud providers, databases, message queues).

Document how to set up, build, test, run, and validate changes so the agent does NOT have to rediscover these each time.

For each of the following, clearly document:

• bootstrap / setup
• build
• test
• run / demo
• lint / format
• any other scripted workflow (for example: security scan, codegen, docs, migrations)

For each step:

• Record the sequence of commands that you have personally verified works from a clean checkout.
• Include required versions of runtimes and tools (for example: Node version, Python version, Docker, language toolchains).
• Explicitly identify preconditions (for example: “always run X before Y”, “require Docker running”, “require .env file”).
• Note postconditions (for example: “artifacts in ./dist”, “database seeded”).
• When relevant, mention whether certain jobs are expected to run on standard GitHub-hosted runners or larger GitHub-hosted runners (for example: long-running, GPU, or memory-heavy jobs should call out large-runner usage per the GitHub Actions runner documentation).

While exploring:

• Try running commands in different orders; record errors, timeouts, and misbehavior and how you resolved them.
• Make at least one small code change; document any unexpected build/test issues and the workarounds.
• Document environment setup steps that appear “optional” but you confirm are actually required.
• When you discover a sequence that consistently works for a particular purpose, write it down exactly and clearly mark it as the recommended sequence.

Document the layout and architecture so the agent can quickly find where to make changes:

• Describe the major architectural components and their locations, for example:
  • entrypoints, main services, CLIs, libraries
  • core modules vs. support or experimental code
• List the relative paths to:
  • Main project files and entrypoints.
  • Configuration for build/test/lint/format tools (for example: package.json, pyproject.toml, Makefile, Dockerfile, .github/workflows/, .eslintrc.*, .prettierrc, .flake8, etc.).
  • Infrastructure and deployment config (for example: Terraform, Helm charts, Kubernetes manifests, Docker Compose).
• Describe checks that run before merge:
  • GitHub Actions workflows (filenames and a short description of what each does).
  • Any external CI, validation, or deployment pipelines.
  • Steps the agent can run locally to closely mirror CI behavior.
• Mention dependencies that aren’t obvious from layout (for example: tools installed via system package managers, language-specific global tools, pre-commit hooks).
• If space remains, use it to reduce agent exploration:
  • List the files in the repo root and briefly describe their roles.
  • Summarize the README contents.
  • Call out key source files and directories (for example: files containing main methods, router definitions, core business logic).
  • Include small, representative code snippets when they help the agent recognize patterns.

When preparing .github/copilot-instructions.md, follow these steps:

1. Perform a comprehensive inventory of the codebase:
   • Review README.md, CONTRIBUTING.md, SECURITY.md, and all other documentation.
   • Search for build/setup scripts (for example: Makefile, package....

Custom agent used: Legendary LID-LIFT Orchestrator v1.4
Full System orchestration for Instinct.OS / CVE Matter-Analysis OS.
Produces human report + H-MOC run_report, using LID-LIFT, BBS tensor macrosegments,
positional alignment, and reverse-adversarial refractors.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.