Imported from SSENN/AI-DC-UK (docs/AGENTS.md). Install upstream with npx skills add SSENN/AI-DC-UK --skill docs. Copyright stays with the author.

AI-DC-UK Agent Instructions

Purpose

This file defines how ChatGPT, Codex, Claude, and future AI agents should work inside the AI-DC-UK repository.

It owns agent behaviour, validation discipline, commit discipline, and session closeout rules.

It should not become a roadmap, repository map, completed-work ledger, or session log.

Operating Principle

Research First. Implementation Second. Evidence Before Architecture.

Do not implement before checking the current project state, existing files, and latest session handoff.

Required Startup Protocol

Before modifying anything, run:

cd ~/AI-DC-UK
source .venv/bin/activate
git status
git log --oneline -10

Use python from the virtual environment, not system python3.

Optional verification:

which python
python --version

Required Reading Order

Read these files before significant work:

1. docs/PROJECT-BOOTSTRAP.md
2. intelligence/sessions/README.md
3. latest intelligence/sessions/SESSION-*.md
4. docs/ROADMAP.md
5. docs/AGENTS.md
6. intelligence/REPOSITORY-MAP.md
7. intelligence/governance/COMPLETED-WORK.md

Use docs/CONTEXT-SPINE-STANDARD.md to understand the purpose of each context-spine file.

Human-Facing Writing Voice

When composing any human-facing writing — outreach emails, investor copy, agent/owner messages, README or public docs, pitch or marketing text — read docs/VOICE-RICHARD.md first and write in Richard's voice.

This is conditional and scoped for efficiency: it is NOT required for code-only tasks. Load docs/VOICE-RICHARD.md only when writing to a person, then write plainly per that card (no embellishment, no buzzwords, warm and direct, sign as Richard K Ssennyonjo).

docs/VOICE-RICHARD.md owns Richard's writing voice (tone, structure, banned words, sign-off).

Current Strategic Position

AI-DC-UK has moved from:

Building Intelligence -> Delivering Intelligence

For the current product milestone, use docs/PROJECT-BOOTSTRAP.md.

Agents must not reopen completed intelligence work unless a regression is found or Richard explicitly approves it.

Source-of-Truth Rules

PostgreSQL is the operational source of truth for:

• opportunity intake
• opportunity workflow updates
• portfolio coverage
• due diligence queue
• opportunity dashboard summaries

The following scripts must remain PostgreSQL-backed:

• automation/scripts/intelligence/portfolio_coverage.py
• automation/scripts/intelligence/due_diligence_queue.py
• automation/scripts/intelligence/opportunity_dashboard.py

Do not reintroduce CSV-based opportunity loading for operational dashboard or portfolio views.

Do not treat the legacy intake CSV file as the live operational source of truth.

Active opportunity workflow scripts under automation/scripts/intelligence/ must read and write opportunity state through db/db.py helpers, not through local CSV registers.

Work Rules

1. Check existing assets before creating new files.
2. Prefer small, focused changes.
3. Keep each commit logically grouped.
4. Validate before committing.
5. Do not modify scoring models unless explicitly requested.
6. Do not redesign the database schema unless explicitly requested.
7. Do not start React/Next.js, SaaS, mobile, or iPad work unless explicitly requested.
8. Do not restart governance discussions unless the context spine itself is being updated.
9. Do not reopen completed intelligence tracks unless a regression is found.
10. Keep the working tree clean before session closeout.

Root Directory Hygiene Directive

Keep the repository root clean.

docs/project-tree.txt is the reference snapshot for approved root-level entries.

Agents must not add new files or directories directly under the repository root unless the entry already exists in docs/project-tree.txt or Richard explicitly approves the root-level addition.

Before creating a new artifact, dependency manifest, scratch file, export, or test output, place it inside the existing owning folder instead of the root.

If a root-level addition is truly required:

• ask Richard first
• update docs/project-tree.txt
• update intelligence/REPOSITORY-MAP.md if structure changed
• record the root-hygiene decision in the session handoff

Before session closeout, check for unintended root-level additions. Remove files you created if they are not approved by docs/project-tree.txt, or report them if they were user-created or local runtime artifacts.

Context Spine Freshness Directive

Before ending any meaningful session, agents must audit the context spine for freshness and overlap.

Use docs/CONTEXT-SPINE-STANDARD.md as the ownership guide.

Closeout audit requirements:

• Update only the file that owns the changed fact.
• Remove or avoid duplicated current-priority wording in files that do not own it.
• Keep the repository root aligned with docs/project-tree.txt unless Richard explicitly approves a root-level addition.
• Keep PROJECT-BOOTSTRAP.md current when the active state, source of truth, milestone, or immediate priority changes.
• Keep ROADMAP.md current only when strategic sequence or definition of done changes.
• Keep AGENTS.md current only when agent behaviour or closeout discipline changes.
• Keep REPOSITORY-MAP.md current only when structure, key paths, or operational file locations change.
• Keep COMPLETED-WORK.md current only when a milestone is complete and should be protected from accidental reopening.
• Keep intelligence/sessions/README.md current with the latest session pointer and lightweight state.
• Create or update a SESSION-*.md handoff that records the context spine audit outcome.

Current Do-Not-Reopen List

Do not reopen the following as active blockers unless a regression is found or Richard explicitly approves it:

• Environmental Intelligence v2
• Commercial Acquisition Strategy v1
• NGED verification
• SPEN ECR implementation
• VOA parser correction
• CSV-based dashboard logic
• Operations Dashboard v1 visual/workflow polish unless a regression is found
• scoring model redesign
• database schema redesign
• React/Next.js/SaaS/mobile app build

Insurance Underwriting Intelligence Guardrails

Insurance Underwriting Intelligence is a future evidence-readiness layer only.

Agents may help document or plan the framework when Richard explicitly asks, but must not treat it as approved implementation work.

When working on this topic, agents must not:

• quote insurance premiums
• estimate insurance pricing
• generate legal policy wording
• recommend insurance products
• claim to provide insurance advice
• replace brokers, insurers, underwriters, risk engineers, or legal advisers
• trigger a scoring-model rewrite
• redesign the database
• create a new dashboard page
• implement a jurisdiction engine
• write implementation code unless Richard explicitly approves it

Use careful language:

• say "evidence readiness", not "insurance recommendation"
• say "questions an underwriter may need answered", not "underwriting decision"
• separate official evidence, recognised third-party evidence, user-provided evidence, Kestrel-derived inference, and unknown/missing evidence

Jurisdiction awareness is a future cross-application design principle. It should not be rushed into an insurance-only implementation.

Validation Expectations

Use validation appropriate to the change.

For Python script changes:

python -m py_compile path/to/script.py

For operational source-of-truth changes:

python db/check_migration.py

For dashboard/portfolio scripts:

python automation/scripts/intelligence/portfolio_coverage.py
python automation/scripts/intelligence/due_diligence_queue.py
python automation/scripts/intelligence/opportunity_dashboard.py

For full portfolio report propagation:

bash automation/scripts/run_batch_all.sh

After generated output changes:

git status
git diff --stat

Commit Discipline

Before committing:

git status
git diff --stat

Review relevant diffs before staging.

Commit messages should be short and specific, for example:

docs: tighten roadmap context spine
fix: use PostgreSQL as source for operational dashboard scripts
chore: refresh portfolio reports from current intelligence

Do not bundle unrelated source, data, generated reports, and documentation changes unless explicitly approved.

Session Closeout Standard

Every session should end with:

git status
git log --oneline -10

If meaningful work was done, create or update a session handoff in:

intelligence/sessions/

Session handoffs should include:

• executive summary
• commits completed
• work completed
• validation performed
• context spine audit outcome
• current git state
• open risks or dirty files
• recommended next action
• do-not-do-next list
• startup commands for next session

Agent Response Style

When guiding Richard through terminal work:

• Give exact commands.
• Keep steps small.
• Ask for check outputs at commit boundaries.
• Warn before destructive commands.
• Avoid broad rewrites unless the file's purpose is being standardised.
• Prefer repo truth over chat memory.
• Be explicit when something is verified versus assumed.

Ownership Rule

This file owns agent behaviour only.

For current project state, use:

• docs/PROJECT-BOOTSTRAP.md

For strategic build sequence, use:

• docs/ROADMAP.md

For repository structure, use:

• intelligence/REPOSITORY-MAP.md

For completed work, use:

• intelligence/governance/COMPLETED-WORK.md

For session history, use:

• intelligence/sessions/