Copilot Instructions for Citizen Intelligence Agency

April 17, 2026 · View on GitHub

Context Files — Read First

ALWAYS read at the start of EVERY task:

  1. README.md — Project overview, features, docs
  2. copilot-setup-steps.yml — Build environment (Java 26, Maven 3.9.15, PostgreSQL 18)
  3. copilot-mcp-config.json — MCP servers (GitHub, filesystem, memory, sequential-thinking, playwright)
  4. skills/ — 80 skills for security, testing, architecture, compliance (see skills/README.md)
  5. agents/ — 6 specialized agents (see agents/README.md)
  6. Hack23 Information Security Policy — apex ISMS policy (via hack23-information-security-policy skill)

Project Overview

Citizen Intelligence Agency — volunteer-driven OSINT platform analyzing Swedish political activities. Monitors politicians and institutions with financial metrics, risk analytics, trend analysis, and transparency insights. Strictly independent and non-partisan.

ComponentVersion/Detail
BackendJava 26 (source 21), Spring Framework 5.x, Hibernate/JPA
UIVaadin
DatabasePostgreSQL 18 (pgaudit, pgcrypto, pg_stat_statements)
BuildMaven 3.9.15, 49+ modules
External APIsRiksdagen, Swedish Election Authority, World Bank, ESV
SecurityOpenSSF 7.2/10, SLSA 3, CII Best Practices, zero critical CVEs 5+ years

Build Commands

mvn clean install              # Full build with tests
mvn clean install -DskipTests  # Build without tests
mvn test -Dtest='!**ITest*,!**/XmlDateTypeAdapterTest,!**/XmlTimeTypeAdapterTest,!**/XmlDateTimeTypeAdapterTest'  # Tests only (excludes integration and Xml*TypeAdapterTest)
mvn clean test jacoco:report   # Tests with coverage
mvn dependency-check:check     # OWASP dependency scan
mvn site                       # Generate site documentation

Database changes: Follow service.data.impl/README-SCHEMA-MAINTENANCE.md. Never manually edit full_schema.sql — always regenerate via pg_dump.

Coding Standards

  • Java: Source level 21, runtime 26. Constructor injection preferred. @Service, @Repository, @Controller annotations. @Transactional for DB operations.
  • JPA: Entities in model.* packages. Proper annotations. Appropriate fetch types. Avoid N+1 queries.
  • Style: Meaningful names. JavaDoc for public APIs. Minimal comments. Follow existing patterns.
  • Security: Never commit secrets. Parameterized queries. Input validation. Output encoding. Spring Security for access control. GDPR compliance.

Quality Requirements

MetricThreshold
Line coverage≥ 80%
Branch coverage≥ 70%
Cyclomatic complexity< 10
Code duplication< 3%
Critical SonarCloud issues0
Critical/High CVEs0

Mandatory Rules

1. Minimal, Surgical Changes

Change only what's needed. Don't refactor unrelated code. Review impact before committing.

2. Validate Before Committing

Compile (mvn clean compile), test relevant areas, check git diff, verify no secrets.

3. Security is Non-Negotiable

Pass CodeQL + OWASP checks. Validate all inputs. Parameterized queries. Encode outputs. Update SECURITY_ARCHITECTURE.md and THREAT_MODEL.md when relevant.

4. ISMS Compliance

Align with ISO 27001:2022, NIST CSF 2.0, CIS Controls v8, GDPR. Update security documentation for security-related changes.

The Hack23 Information Security Policy (ISP) is the apex policy — every change must defer to it. It is implemented through the supporting policies below; consult the ones relevant to your task. See the hack23-information-security-policy skill for a developer-facing mapping.

ConcernPolicyPrimary Skill
Apex (everything)Information Security Policyhack23-information-security-policy
SDLC / code / buildSecure Development Policysecure-development-policy
Open-source postureOpen Source Policyopen-source-policy
Secrets / tokensSecrets Managementsecrets-management
TLS / crypto / hashingCryptography Policycryptography-policy / crypto-best-practices
AuthN / AuthZAccess Controlaccess-control-policy
Data labellingCLASSIFICATIONclassification-framework-enforcement
Personal dataData Protection, Privacy Policydata-protection, gdpr-compliance
CVE triageVulnerability Managementvulnerability-management
Releases / migrationsChange Managementchange-management
Backup / DRBackup Recoverybackup-recovery-policy
IncidentsIncident Response Planincident-response
Threat modellingThreat Modelingthreat-modeling
Third-party / depsThird Party Managementopen-source-policy
AI / Copilot agentsAI Policyai-governance
StrategyInformation Security Strategyinformation-security-strategy

5. Test Everything

Unit tests for all new functionality. Maintain or improve coverage. JUnit 5, Mockito. Follow existing test patterns.

6. Use Skills and Agents

Check relevant skills before implementing. Delegate to specialized agents when appropriate:

  • ISMS / policy: hack23-information-security-policy (apex), hack23-isms-compliance, compliance-frameworks
  • Security: secure-code-review, security-by-design, input-validation, threat-modeling, vulnerability-management
  • Architecture: spring-framework-patterns, jpa-hibernate-optimization, vaadin-component-design
  • Testing: unit-testing-patterns, testing-strategy-enforcement, playwright-ui-testing
  • CI/CD: github-actions-workflows, github-agentic-workflows, ci-cd-security
  • AI governance: ai-governance (AI Policy + OWASP LLM + EU AI Act)

7. Clear Commit Messages

Format: <type>: <description> — Types: feat, fix, docs, style, refactor, test, chore

Architecture Documentation (Hack23 Standard)

Every repository maintains C4 model documentation:

Current: ARCHITECTURE.md, DATA_MODEL.md, FLOWCHART.md, STATEDIAGRAM.md, MINDMAP.md, SWOT.md Future: FUTURE_ARCHITECTURE.md, FUTURE_DATA_MODEL.md, FUTURE_FLOWCHART.md, FUTURE_STATEDIAGRAM.md, FUTURE_MINDMAP.md, FUTURE_SWOT.md Security: SECURITY_ARCHITECTURE.md, FUTURE_SECURITY_ARCHITECTURE.md, THREAT_MODEL.md

Decision Framework

When uncertain:

  1. Check relevant skill in .github/skills/
  2. Review similar code patterns in the repository
  3. Consult ARCHITECTURE.md, SECURITY_ARCHITECTURE.md
  4. Apply security-by-design (deny by default, validate input, encrypt data)
  5. Follow ISMS requirements
  6. Only then ask for clarification